TapAreaLink

View source on GitHub
See recent changes on GitHub
Consult PDocs for this component

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.

focusColor
"lightBackground" | "darkBackground"
"lightBackground"

Indicates whether this component is hosted in a light or dark container.
Used for improving focus ring color contrast.

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.

innerFocusColor
"default" | "inverse"
-

Indicates whether this component presents a light ('default') or dark ('inverse') inner focus border when focused.
Used for improving focus ring color contrast.

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

Select a mouse cursor type to convey the TapAreaLink expected behavior

onBlur
(arg1: { event: React.FocusEvent<HTMLAnchorElement> }) => void
-

Callback fired when a TapAreaLink component loses focus

onFocus
(arg1: { event: React.FocusEvent<HTMLAnchorElement> }) => void
-

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

onKeyDown
(arg1: { event: React.KeyboardEvent<HTMLAnchorElement> }) => void
-

Callback fired when a keyboard key is pressed

onMouseDown
(arg1: { event: React.MouseEvent<HTMLAnchorElement> }) => void
-

Callback fired when a click event begins

onMouseEnter
(arg1: { event: React.MouseEvent<HTMLAnchorElement> }) => void
-

Callback fired when a mouse pointer moves onto a TapAreaLink component

onMouseLeave
(arg1: { event: React.MouseEvent<HTMLAnchorElement> }) => void
-

Callback fired when a mouse pointer moves out a TapAreaLink component

onMouseUp
(arg1: { event: React.MouseEvent<HTMLAnchorElement> }) => void
-

Callback fired when a click event ends

onTap
(arg1: {
  event: React.MouseEvent<HTMLAnchorElement> | React.KeyboardEvent<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.

Usage guidelines

See TapArea.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

TapAreaLink depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import {
  Box,
  DefaultLabelProvider,
  Flex,
  Image,
  Mask,
  TapAreaLink,
  Text,
} from 'gestalt';

export default function Example() {
  return (
    <DefaultLabelProvider
      labels={{
        Link: {
          accessibilityNewTabLabel: 'Öffnet eine neue Browser-Registerkarte.',
          accessibilityDownloadLabel: 'Es lädt eine Datei herunter.',
        },
      }}
    >
      <Flex alignItems="center" height="100%" justifyContent="center">
        <TapAreaLink
          fullWidth={false}
          href="#"
          onTap={({ event }) => event.preventDefault()}
          target="blank"
        >
          <Box borderStyle="lg" column={12} padding={3} 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">Besuchen Sie Pinterest.com</Text>
          </Box>
        </TapAreaLink>
      </Flex>
    </DefaultLabelProvider>
  );
}

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
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex alignItems="start" direction="column" gap={{ column: 6, row: 0 }}>
        <Flex gap={6} wrap>
          <TapAreaLink
            disabled={disabled}
            href="https://www.pinterest.com"
            tabIndex={tabIndex ? -1 : 0}
            tapStyle={compressed}
            target="blank"
          >
            <Box borderStyle="lg" column={12} padding={3} 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
            id="compress-buttons"
            onChange={() =>
              setCompressed(compressed === 'compress' ? 'none' : 'compress')
            }
            switched={compressed === 'compress'}
          />
          <Box flex="grow" paddingX={2}>
            <Label htmlFor="compress-buttons">
              <Text>Compress TapArea</Text>
            </Label>
          </Box>
        </Flex>
        <Flex gap={{ column: 0, row: 2 }}>
          <Switch
            id="disable-buttons"
            onChange={() => setDisabled(!disabled)}
            switched={disabled}
          />
          <Box flex="grow" paddingX={2}>
            <Label htmlFor="disable-buttons">
              <Text>Disable TapArea</Text>
            </Label>
          </Box>
        </Flex>
        <Flex gap={{ column: 0, row: 2 }}>
          <Switch
            id="unreachable-buttons"
            onChange={() => setTabIndex(!tabIndex)}
            switched={tabIndex}
          />
          <Box flex="grow" paddingX={2}>
            <Label htmlFor="unreachable-buttons">
              <Text>Remove from keyboard navigation with tabIndex</Text>
            </Label>
          </Box>
        </Flex>
      </Flex>
    </Box>
  );
}

Focus style

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

export default function TapAreaLinkExample() {
  return (
    <Box padding={8} width="100%">
      <Flex gap={6} width="100%">
        <Flex direction="column" gap={6} width="100%">
          <Box
            alignItems="center"
            borderStyle="sm"
            color="light"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="lightBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="dark" size="100">
                  focusColor=lightBackground
                </Text>
              </Box>
            </TapAreaLink>
          </Box>

          <Box
            alignItems="center"
            borderStyle="sm"
            color="dark"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="darkBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="light" size="100">
                  focusColor=darkBackground
                </Text>
              </Box>
            </TapAreaLink>
          </Box>
        </Flex>
        <Flex direction="column" gap={6} width="100%">
          <Box
            alignItems="center"
            borderStyle="sm"
            color="light"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="lightBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              innerFocusColor="default"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="dark" size="100">
                  focusColor=lightBackground & innerFocusColor=default
                </Text>
              </Box>
            </TapAreaLink>
          </Box>

          <Box
            alignItems="center"
            borderStyle="sm"
            color="dark"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="darkBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              innerFocusColor="default"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="light" size="100">
                  focusColor=darkBackground & innerFocusColor=default
                </Text>
              </Box>
            </TapAreaLink>
          </Box>
        </Flex>
        <Flex direction="column" gap={6} width="100%">
          <Box
            alignItems="center"
            borderStyle="sm"
            color="light"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="lightBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              innerFocusColor="inverse"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="dark" size="100">
                  focusColor=lightBackground & innerFocusColor=inverse
                </Text>
              </Box>
            </TapAreaLink>
          </Box>

          <Box
            alignItems="center"
            borderStyle="sm"
            color="dark"
            display="flex"
            height={150}
            justifyContent="center"
            width={150}
          >
            <TapAreaLink
              focusColor="darkBackground"
              fullHeight={false}
              fullWidth={false}
              href="www.pinterest.com"
              innerFocusColor="inverse"
              onTap={({ event }) => event.preventDefault()}
            >
              <Box height={100} width={100}>
                <Text color="light" size="100">
                  focusColor=darkBackground & innerFocusColor=inverse
                </Text>
              </Box>
            </TapAreaLink>
          </Box>
        </Flex>
      </Flex>
    </Box>
  );
}

Height & width

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

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

          <Flex.Item>
            <Text color="inverse" inline>
              Other content
            </Text>
            <Box borderStyle="sm" column={6} display="inlineBlock" margin={3}>
              <TapAreaLink
                href="www.pinterest.com"
                onTap={({ event }) => event.stopPropagation()}
              >
                <Box color="secondary" height="100%">
                  <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 gap={2} wrap>
      {[
        'copy',
        'grab',
        'grabbing',
        'move',
        'noDrop',
        'pointer',
        'zoomIn',
        'zoomOut',
      ].map((cursor) => (
        <TapAreaLink
          key={cursor}
          fullWidth={false}
          href="www.pinterest.com"
          mouseCursor={cursor}
          onTap={({ event }) => event.stopPropagation()}
        >
          <Box borderStyle="lg" height={100} padding={4} width={250}>
            <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.

Internal documentation

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