TapArea

TapArea allows components to be clickable and touchable in an accessible way

also known as Touchable

Figma:

N/A

Responsive:

Ready

Adaptive:

N/A

A11y:

Ready

Props

Component props
Name	Type	Default
`children` Required	`React.Node`	-
	TapArea is a wrapper around non-button components (or children) that provides clicking / touching functionality as if they were a unified button area.
`accessibilityControls`	`string`	-
	Specify the `id` of an associated element (or elements) whose contents or visibility are controlled by a button component so that screen reader users can identify the relationship between elements. Optional with button-role. Accessibility: It populates aria-controls.
`accessibilityExpanded`	`boolean`	-
	Indicate that a button component hides or exposes collapsible components and expose whether they are currently expanded or collapsed. Optional with button-role. Accessibility: It populates aria-expanded.
`accessibilityHaspopup`	`boolean`	-
	Indicate that a button component controls the appearance of interactive popup elements, such as menu or dialog. Optional with button-role. Accessibility: It populates aria-haspopup.
`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`	-
	Set disabled state so TapArea cannot be interacted with and actions are not available.
`fullHeight`	`boolean`	-
	Set the TapArea height to expand to the full height of the parent.
`fullWidth`	`boolean`	`true`
	Set the TapArea width to expand to the full width of the parent.
`href`	`string`	-
	Specify a link URL. Required with role=link.
`mouseCursor`	`"copy" \| "grab" \| "grabbing" \| "move" \| "noDrop" \| "pointer" \| "zoomIn" \| "zoomOut"`	`"pointer"`
	Select a mouse cursor type to convey the TapArea expected behavior .
`onBlur`	`({ event: SyntheticFocusEvent<HTMLDivElement> \| SyntheticFocusEvent<HTMLAnchorElement> }) => void`	-
	Callback fired when a TapArea component loses focus.
`onFocus`	`({ event: SyntheticFocusEvent<HTMLDivElement> \| SyntheticFocusEvent<HTMLAnchorElement> }) => void`	-
	Callback fired when a TapArea component gets focus via keyboard navigation, mouse click (pressed), or focus method
`onMouseDown`	`({ event: SyntheticMouseEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement>, {\| dangerouslyDisableOnNavigation: () => void \|}> }) => void`	-
	Callback fired when a click event begins.
`onMouseEnter`	`({ event: SyntheticMouseEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement>, {\| dangerouslyDisableOnNavigation: () => void \|}> }) => void`	-
	Callback fired when a mouse pointer moves onto a TapArea component.
`onMouseLeave`	`({ event: SyntheticMouseEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement> }) => void`	-
	Callback fired when a mouse pointer moves out a TapArea component.
`onMouseUp`	`({ event: SyntheticMouseEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement> }) => void`	-
	Callback fired when a click event ends.
`onTap`	`({ event: SyntheticMouseEvent<HTMLDivElement> \| SyntheticKeyboardEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement>, {\| dangerouslyDisableOnNavigation: () => void \|}> }) }) => void`	-
	Callback fired when a TapArea component is clicked (pressed and released) with a mouse or keyboard. Required with button-role + button-type buttons. See GlobalEventsHandlerProvider to learn more about link navigation.
`ref`	`React.Ref<"div"> \| React.Ref<"a">`	-
	Forward the ref to the underlying div or anchor element.
`rel`	`"none" \| "nofollow"`	`"none"`
	Optional with role=link.
`role`	`"button" \| "link"`	`"button"`
	Select a TapArea variant: 'button': Use for TapArea to act like buttons. The TapArea is rendered as a `<div>`. 'link': Use for TapArea to act like links. The button is rendered as an `<a>`. Required with role=link.
`rounding`	`"pill" \| "circle" \| 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8`	-
	Sets a border radius for the TapArea. Select a rounding option that aligns with its children. Options are "circle" or "pill" for fully rounded corners or 0-8 representing the radius in boints.
`tabIndex`	`-1 \| 0`	`0`
	Remove the component from sequential keyboard navigation to improve accessibility. The component is not focusable with keyboard navigation but it can be focused with Javascript or visually by clicking with the mouse. The default behaviour for the component is to be focusable in sequential keyboard navigation in the order defined by the document's source order. If component is disabled, the component is also unreachable from keyboard navigation.
`tapStyle`	`none \| "compress"`	`"none"`
	Set a compressing behavior when the TapArea is clicked / touched. 'none' does not compress TapArea. 'compress' scales down TapArea.
`target`	`null \| "self" \| "blank"`	`"null"`
	Define the frame or window to open the anchor defined on `href`: 'null' opens the anchor in the same window. 'blank' opens the anchor in a new window. 'self' opens an anchor in the same frame. Optional with role=link.

Accessibility

Ready

Localization

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

Variants

Basic TapArea

import { Avatar, Box, TapArea, Text } from 'gestalt';

export default function TapAreaExample() {
  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Box rounding={4} borderStyle="sm" width={170}>
        <TapArea rounding={4}>
          <Box
            alignItems="center"
            direction="column"
            display="flex"
            padding={3}
          >
            <Avatar
              name="Alberto"
              size="xl"
              src="https://i.ibb.co/NsK2w5y/Alberto.jpg"
              verified
            />
            <Text weight="bold">Alberto&apos;s Profile</Text>
          </Box>
        </TapArea>
      </Box>
    </Box>
  );
}

TapArea with Link/Button

import { useState } from 'react';
import { Box, Image, Link, Mask, TapArea, Text } from 'gestalt';

export default function TapAreaExample() {
  const [touches, setTouches] = useState(0);

  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Box width={200}>
        <TapArea onTap={() => setTouches(touches + 1)} rounding={2}>
          <Box color="selected" rounding={4} borderStyle="sm">
            <Mask rounding={2}>
              <Image
                alt="Antelope Canyon"
                naturalHeight={1}
                naturalWidth={1}
                src="https://i.ibb.co/DwYrGy6/stock14.jpg"
              />
            </Mask>
            <Box paddingY={2}>
              <Link
                href="https://www.pinterest.com/search/pins/?rs=ac&len=2&q=antelope%20canyon%20arizona&eq=Antelope%20Canyon"
                onClick={({ event }) => event.stopPropagation()}
                rounding="pill"
                target="blank"
              >
                <Text align="center" color="inverse">
                  Find More on Pinterest
                </Text>
              </Link>
            </Box>
          </Box>
        </TapArea>
        <Box paddingY={2}>
          <Text color="subtle" align="center">
            Touched {touches} {touches === 1 ? 'time' : 'times'}
          </Text>
        </Box>
      </Box>
    </Box>
  );
}

If you have a Link or Button inside of TapArea, you can apply e.stopPropagation() so the onTap doesn't get triggered.

TapArea with link interaction can be paired with GlobalEventsHandlerProvider. See GlobalEventsHandlerProvider to learn more about link navigation.

Roles & compress behavior

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

export default function Example() {
  const [disabled, setDisabled] = useState(false);
  const [compressed, setCompressed] = useState('compress');
  const [touches, setTouches] = useState(0);
  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>
          <Tooltip text="Default TapArea">
            <TapArea
              tapStyle={compressed}
              disabled={disabled}
              onTap={() => setTouches(touches + 1)}
              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">
                  Touched {touches} {touches === 1 ? 'time' : 'times'}
                </Text>
              </Box>
            </TapArea>
          </Tooltip>
          <Tooltip text="Link TapArea">
            <TapArea
              tapStyle={compressed}
              disabled={disabled}
              role="link"
              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>
            </TapArea>
          </Tooltip>
        </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, TapArea, 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%">
          <TapArea fullHeight>
            <Box height="100%" color="secondary">
              <Text align="center">Full parent height</Text>
            </Box>
          </TapArea>
        </Box>
        <Box borderStyle="sm" margin={3} width="100%" height="100%">
          <TapArea>
            <Box height="100%" color="secondary">
              <Text align="center">Child height only</Text>
            </Box>
          </TapArea>
        </Box>
      </Flex>
    </Box>
  );
}

Inline usage

import { Box, Flex, TapArea, 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}>
              <TapArea>
                <Box height="100%" color="secondary">
                  <Text align="center">Default behavior (block)</Text>
                </Box>
              </TapArea>
            </Box>
          </Flex.Item>

          <Flex.Item>
            <Text color="inverse" inline>
              Other content
            </Text>
            <Box borderStyle="sm" display="inlineBlock" margin={3} column={6}>
              <TapArea>
                <Box height="100%" color="secondary">
                  <Text align="center">Inline behavior</Text>
                </Box>
              </TapArea>
            </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

mouseCursor="copy"

copy

mouseCursor="grab"

grab

mouseCursor="grabbing"

grabbing

mouseCursor="move"

move

mouseCursor="noDrop"

noDrop

mouseCursor="pointer"

pointer

mouseCursor="zoomIn"

zoomIn

mouseCursor="zoomOut"

zoomOut

Rounding

rounding={0}

rounding={1}

rounding={2}

rounding={3}

rounding={4}

rounding={5}

rounding={6}

rounding={7}

rounding={8}

rounding="circle"

circle

rounding="pill"

pill

Ref

import { useRef, useState } from 'react';
import { Box, Button, Flex, TapArea, Text } from 'gestalt';

export default function TapAreaRefExample() {
  const ref = useRef(null);
  const [focus, setFocus] = useState(0);

  return (
    <Box
      padding={4}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Flex gap={{ column: 4, row: 2 }} direction="column" alignItems="center">
        <Button text="Focus the TapArea" onClick={() => ref.current?.focus()} />
        <TapArea ref={ref} rounding="pill" onFocus={() => setFocus(focus + 1)}>
          <Box borderStyle="sm" padding={2} rounding="pill">
            <Text>TapArea is focused {focus} times</Text>
          </Box>
        </TapArea>
      </Flex>
    </Box>
  );
}

import { Fragment, useRef, useState } from 'react';
import { Box, Flex, Image, Layer, Mask, Popover, TapArea, Text } from 'gestalt';

export default function MenuButtonExample() {
  const [selected, setSelected] = useState(false);
  const anchorRef = useRef(null);

  return (
    <Box
      padding={8}
      height="100%"
      display="flex"
      alignItems="center"
      justifyContent="center"
    >
      <Fragment>
        <TapArea
          accessibilityLabel="Open the options menu"
          accessibilityControls="menu"
          accessibilityExpanded={selected}
          accessibilityHaspopup
          onTap={() => setSelected(!selected)}
        >
          <Box
            ref={anchorRef}
            borderStyle="sm"
            display="inlineBlock"
            alignItems="center"
            rounding={1}
            padding={2}
          >
            <Flex gap={{ column: 0, row: 2 }}>
              <Box height={50} width={50}>
                <Mask rounding={1}>
                  <Image
                    alt="Antelope Canyon"
                    naturalHeight={1}
                    naturalWidth={1}
                    src="https://i.ibb.co/FY2MKr5/stock6.jpg"
                  />
                </Mask>
              </Box>
              <Text weight="bold" align="center">
                Menu
              </Text>
            </Flex>
          </Box>
        </TapArea>
        {selected && (
          <Layer>
            <Popover
              anchor={anchorRef.current}
              idealDirection="down"
              onDismiss={() => setSelected(false)}
              positionRelativeToAnchor={false}
              size="md"
            >
              <Box id="menu" direction="column" display="flex" padding={2}>
                <Box padding={2}>
                  <Text weight="bold">Option 1</Text>
                </Box>
                <Box padding={2}>
                  <Text weight="bold">Option 2</Text>
                </Box>
              </Box>
            </Popover>
          </Layer>
        )}
      </Fragment>
    </Box>
  );
}

External handlers

TapArea consumes external handlers from GlobalEventsHandlerProvider.

Handlers:

onNavigation: executed when TapArea role="link" is clicked

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	Ready	Component responds to changing viewport sizes in web and mobile web.

GlobalEventsHandlerProvider
GlobalEventsHandlerProvider allows external link navigation control across all children components with link behavior.

Edit page on GitHub

; Opens a new tab

TapArea

also known as Touchable

Props

Accessibility

Localization

Variants

Basic TapArea

TapArea with Link/Button

Roles & compress behavior

Height & width

Inline usage

Mouse cursor

Rounding

Ref

Accessibility: label, controls, expanded, & popup

External handlers

Component quality checklist

Related