TapAreaLink

View source on GitHub
; Opens a new tab
See recent changes on GitHub
; Opens a new tab

TapAreaLink is mainly used as navigational element

Props

Component props
Name
Type
Default
children
Required
React.Node
-

TapAreaLink is a wrapper around non-button components (or children) that provides clicking / touching functionality as if they were a unified button area.

href
Required
string
-

Specify a link URL.

accessibilityCurrent
"page"
| "step"
| "location"
| "date"
| "time"
| "true"
| "false"
| "section"
-

For accessibility purposes. When you have a group of related elements with one element in the group styled differently from the others to indicate that this is the current element within its group, accessibilityCurrent should be used to inform the assistive technology user what has been indicated via styling.
Accessibility: It populates aria-current.

accessibilityLabel
string
-

Supply a short, descriptive label for screen-readers to replace TapArea texts that do not provide sufficient context about the button component behavior.
Accessibility: It populates aria-label.

dataTestId
string
-

Available for testing purposes, if needed. Consider better queries before using this prop.

disabled
boolean
false

Set disabled state so TapAreaLink cannot be interacted with and actions are not available.

fullHeight
boolean
-

Set the TapAreaLink height to expand to the full height of the parent.

fullWidth
boolean
true

Set the TapAreaLink width to expand to the full width of the parent.

mouseCursor
"copy" | "grab" | "grabbing" | "move" | "noDrop" | "pointer" | "zoomIn" | "zoomOut"
"pointer"

Select a mouse cursor type to convey the TapAreaLink expected behavior

onBlur
({|
  event: SyntheticFocusEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a TapAreaLink component loses focus

onFocus
({|
  event: SyntheticFocusEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a TapAreaLink component gets focus via keyboard navigation, mouse click (pressed), or focus method

onKeyDown
({|
  event: SyntheticKeyboardEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a keyboard key is pressed

onMouseDown
({|
  event: SyntheticMouseEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a click event begins

onMouseEnter
({|
  event: SyntheticMouseEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a mouse pointer moves onto a TapAreaLink component

onMouseLeave
({|
  event: SyntheticMouseEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a mouse pointer moves out a TapAreaLink component

onMouseUp
({|
  event: SyntheticMouseEvent<HTMLAnchorElement>,
|}) => void
-

Callback fired when a click event ends

onTap
({|
  event: SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>,
  dangerouslyDisableOnNavigation: () => void,
|}) => void
-

Callback fired when a TapAreaLink component is clicked (pressed and released) with a mouse or keyboard

rel
"none" | "nofollow"
"none"

Provides hints for SEO. See the MDN Web Docs to learn more

rounding
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | "circle" | "pill"
0

.

tabIndex
-1 | 0
0

Use "-1" to remove Button from keyboard navigation. See the Accessibility guidelines to learn more.

tapStyle
"none" | "compress"
"none"

Set a compressing behavior when the TapAreaLink is clicked / touched

  • 'none' does not compress TapArea.
  • 'compress' scales down TapArea.
target
null | "self" | "blank"
"null"

Indicates the browsing context where an href will be opened:

  • 'null' opens the anchor in the same window.
  • 'blank' opens the anchor in a new window.
  • 'self' opens an anchor in the same frame.

Localization

Localize the accessibilityLabel.

TapAreas with link role announce to assistive technologies that the link opens in a new tab when setting target to 'blank'. Localize the default label with DefaultLabelProvider. Learn more

Usage guidelines

See TapArea.

Variants

See TapArea for more variants.

Compress behavior

import { useState } from 'react';
import {
  Box,
  Flex,
  Image,
  Label,
  Mask,
  Switch,
  TapAreaLink,
  Text,
} from 'gestalt';

export default function Example() {
  const [disabled, setDisabled] = useState(false);
  const [compressed, setCompressed] = useState('compress');
  const [tabIndex, setTabIndex] = useState(false);

  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Flex alignItems="start" direction="column" gap={{ column: 6, row: 0 }}>
        <Flex gap={6} wrap>
          <TapAreaLink
            tapStyle={compressed}
            disabled={disabled}
            target="blank"
            href="https://www.pinterest.com"
            tabIndex={tabIndex ? -1 : 0}
          >
            <Box padding={3} column={12} borderStyle="lg" width={200}>
              <Mask rounding={2}>
                <Image
                  alt="Antelope Canyon"
                  naturalHeight={1}
                  naturalWidth={1}
                  src="https://i.ibb.co/DwYrGy6/stock14.jpg"
                />
              </Mask>
              <Text align="center">Visit Pinterest.com</Text>
            </Box>
          </TapAreaLink>
        </Flex>
        <Flex gap={{ column: 0, row: 2 }}>
          <Switch
            onChange={() =>
              setCompressed(compressed === 'compress' ? 'none' : 'compress')
            }
            id="compress-buttons"
            switched={compressed === 'compress'}
          />
          <Box paddingX={2} flex="grow">
            <Label htmlFor="compress-buttons">
              <Text>Compress TapArea</Text>
            </Label>
          </Box>
        </Flex>
        <Flex gap={{ column: 0, row: 2 }}>
          <Switch
            onChange={() => setDisabled(!disabled)}
            id="disable-buttons"
            switched={disabled}
          />
          <Box paddingX={2} flex="grow">
            <Label htmlFor="disable-buttons">
              <Text>Disable TapArea</Text>
            </Label>
          </Box>
        </Flex>
        <Flex gap={{ column: 0, row: 2 }}>
          <Switch
            onChange={() => setTabIndex(!tabIndex)}
            id="unreachable-buttons"
            switched={tabIndex}
          />
          <Box paddingX={2} flex="grow">
            <Label htmlFor="unreachable-buttons">
              <Text>Remove from keyboard navigation with tabIndex</Text>
            </Label>
          </Box>
        </Flex>
      </Flex>
    </Box>
  );
}

Height & width

import { Box, Flex, TapAreaLink, Text } from 'gestalt';

export default function Example() {
  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Flex gap={6} wrap maxWidth={500} height={250}>
        <Box borderStyle="sm" margin={3} width="100%" height="100%">
          <TapAreaLink
            href="www.pinterest.com"
            onTap={({ event }) => event.stopPropagation()}
            fullHeight
          >
            <Box height="100%" color="secondary">
              <Text align="center">Full parent height</Text>
            </Box>
          </TapAreaLink>
        </Box>
        <Box borderStyle="sm" margin={3} width="100%" height="100%">
          <TapAreaLink
            href="www.pinterest.com"
            onTap={({ event }) => event.stopPropagation()}
          >
            <Box height="100%" color="secondary">
              <Text align="center">Child height only</Text>
            </Box>
          </TapAreaLink>
        </Box>
      </Flex>
    </Box>
  );
}

Inline usage

import { Box, Flex, TapAreaLink, Text } from 'gestalt';

export default function Example() {
  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Box color="warningBase" height={250} padding={3} maxWidth={500}>
        <Flex direction="column" gap={{ column: 6, row: 0 }}>
          <Flex.Item>
            <Text color="inverse" inline>
              Other content
            </Text>
            <Box borderStyle="sm" margin={3} column={6}>
              <TapAreaLink
                href="www.pinterest.com"
                onTap={({ event }) => event.stopPropagation()}
              >
                <Box height="100%" color="secondary">
                  <Text align="center">Default behavior (block)</Text>
                </Box>
              </TapAreaLink>
            </Box>
          </Flex.Item>

          <Flex.Item>
            <Text color="inverse" inline>
              Other content
            </Text>
            <Box borderStyle="sm" display="inlineBlock" margin={3} column={6}>
              <TapAreaLink
                href="www.pinterest.com"
                onTap={({ event }) => event.stopPropagation()}
              >
                <Box height="100%" color="secondary">
                  <Text align="center">Inline behavior</Text>
                </Box>
              </TapAreaLink>
            </Box>
          </Flex.Item>
        </Flex>
      </Box>
    </Box>
  );
}

While TapArea doesn't provide an inline prop, this behavior can be achieved by wrapping with <Box display="inlineBlock">.

Mouse cursor

import { Box, Flex, TapAreaLink, Text } from 'gestalt';

export default function TapAreaExample() {
  return (
    <Flex wrap gap={2}>
      {[
        'copy',
        'grab',
        'grabbing',
        'move',
        'noDrop',
        'pointer',
        'zoomIn',
        'zoomOut',
      ].map((cursor) => (
        <TapAreaLink
          href="www.pinterest.com"
          onTap={({ event }) => event.stopPropagation()}
          key={cursor}
          mouseCursor={cursor}
          fullWidth={false}
        >
          <Box borderStyle="lg" padding={4} width={250} height={100}>
            <Text size="200">hover here </Text>
            <Text size="200" weight="bold">
              {`mouseCursor="${cursor}"`}
            </Text>
          </Box>
        </TapAreaLink>
      ))}
    </Flex>
  );
}

Rounding

In ordee to observe TapArea's border radius, focus on each component below navigating with the keyboard. fullWidth={false} might be required to wrap to the children component. Make the sure the children components match the rounding as well.

rounding={0}
rounding={1}
rounding={2}
rounding={3}
rounding={4}
rounding={5}
rounding={6}
rounding={7}
rounding={8}
rounding="circle"
rounding="pill"

External handlers

TapAreaLink consumes external handlers from GlobalEventsHandlerProvider.

Handlers:

See GlobalEventsHandlerProvider for more information.

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Component is not currently available in Figma.
Responsive Web
Component does not respond to changing viewport sizes in web and mobile web.

GlobalEventsHandlerProvider
GlobalEventsHandlerProvider allows external link navigation control across all children components with link behavior.
See GlobalEventsHandlerProvider to learn more about link navigation.

Edit page on GitHub
; Opens a new tab