TagData

TagData enables users to select multiple categories to compare with each other in a graph or chart. It contains a label and can be used as a filter for different sources.

also known as Chip, Pill, Filter, Tag

Figma:

Ready

Responsive:

Ready

Adaptive:

N/A

A11y:

Ready

Props

Component props
Name	Type	Default
`text` Required	`string`	-
	Short text to render inside TagData.
`accessibilityRemoveIconLabel`	`string`	-
	If your app uses DefaultLabelProvider, a default value for this label will be used. Using this prop will override the default label value with a more specific label if desired. This populates the `aria-label` on the remove icon.
`baseColor`	`"primary" \| "secondary"`	`"primary"`
	The default color for TagData shown in an unselected state.
`color`	`"01" \| "02" \| "03" \| "04" \| "05" \| "06" \| "07" \| "08" \| "09" \| "10" \| "11" \| "12"`	`5`
	A color code from the data visualization palette that appears when the TagData is selected.
`disabled`	`boolean`	`false`
	Indicates if TagData should be disabled. Disabled TagDatas are inactive and cannot be interacted with. See the disabled variant to learn more.
`id`	`string`	-
	An identifier to be passed back in the `onTap` callback. It can be helpful to distinguish multiple TagDatas.
`onRemove`	`({\| event: SyntheticMouseEvent<HTMLButtonElement>, id?: string, \|}) => void`	-
	TagData can be dismissable by the "X" affordance, which triggers the `onRemove` callback. This handler should take care of state updates to no longer render the TagData.
`onTap`	`({\| event: \| SyntheticMouseEvent<HTMLDivElement> \| SyntheticKeyboardEvent<HTMLDivElement> \| SyntheticMouseEvent<HTMLAnchorElement> \| SyntheticKeyboardEvent<HTMLAnchorElement>, selected: boolean, id?: string, \|}) => void`	-
	Handler if the item selection state was changed with a click or a keyboard press.
`selected`	`boolean`	-
	Controls whether the TagData is selected or not. Use it alongside the `onTap` handler.
`showCheckbox`	`boolean`	-
	Shows a visible checkbox when Tagdata is in a selected state. See the group variant to learn more.
`size`	`"sm" \| "md" \| "lg"`	`"md"`
	Sets the size of the TagData to render. See the size variant to learn more.
`tooltip`	`{\| accessibilityLabel?: string, inline?: boolean, idealDirection?: "up" \| "right" \| "down" \| "left", text: string, zIndex?: Indexable, \|}`	-
	Adds a tooltip on hover/focus of TagData. See the with tooltip variant to learn more.

Usage guidelines

When to use

When selecting and/or comparing categories with an accompanying chart or graph view that displays at-a-glance data for a user to quickly view key metrics

When not to use

Progressing or regressing a user through a step in a flow. Use Button instead
In conjunction with TextField, TextArea, and ComboBox. Use Tag instead

Best practices

Choose the right background to help it stand out in dense data interfaces. For example, set baseColor=secondary when using TagData against a gray background.

Don't

Match TagData fill with the surrounding background color. Using the same color can make it unclear that TagData is selectable.

Use the same variants of TagData in a group, depending on the type of behavior TagData should have.

Don't

Mix TagData variants in the same group. This creates an unclear pattern for the user to understand which TagDatas are removable or not.

Use short and clear labels for easier comprehension — ideally one or two words.

Don't

Use long sentences in the text prop, since the text in TagData truncates as needed to preserve the max width.

Accessibility

Ready

Users should be able to navigate or activate TagData using a keyboard or other input modalities. Be sure to include an accessibilityRemoveIconLabel and tooltip.accessibilityLabel for the screen reader with the onRemove prop and tooltip prop.

Localization

Be sure to localize accessibilityRemoveIconLabel ,tooltip.accessibilityLabel, and text props in TagData.

When the text of TagData reaches its max width, either intentionally or through localization, the text will be truncated with ellipses as needed to preserve the max-width. Keep this in mind when selecting wording for TagData. Note that localization can lengthen text by 20 to 30 percent.

Variants

Size

TagData is available in 3 fixed sizes.
- lg has height of 48px. Text has a fixed size of 16px.
- md has height of 40px. Text has a fixed size of 14px.
- sm has height of 32px. Text has a fixed size of 14px.

import { Flex, TagData } from 'gestalt';

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
      direction="column"
      gap={2}
    >
      <TagData text="Small TagData" size="sm" showCheckbox />
      <TagData text="Medium TagData" size="md" showCheckbox />
      <TagData text="Large Tagdata" size="lg" showCheckbox />
    </Flex>
  );
}

Base Color

By default, TagData uses a light gray fill, which is suitable for placement on a white background. When used on a gray background, use baseColor="secondary" for a white fill.

import { Box, Flex, TagData } from 'gestalt';

export default function Example() {
  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
    >
      <Box
        width="50%"
        height="100%"
        display="flex"
        justifyContent="center"
        alignItems="center"
      >
        <TagData text="Small TagData" size="sm" baseColor="primary" />
      </Box>
      <Box
        width="50%"
        height="100%"
        display="flex"
        justifyContent="center"
        alignItems="center"
        color="secondary"
      >
        <TagData text="Small TagData" size="sm" baseColor="secondary" />
      </Box>
    </Flex>
  );
}

Colors

TagData is available in the colors from our data visualization color palette. Match each TagData's color to its respective data line, which will be visible when TagData is selected.

import { useState } from 'react';
import { Box, Flex, TagData } from 'gestalt';

export default function Example() {
  const allColors = [
    '01',
    '02',
    '03',
    '04',
    '05',
    '06',
    '08',
    '09',
    '10',
    '11',
    '12',
  ];

  const [selectedColors, setSelectedColors] = useState(allColors);

  return (
    <Box overflow="scrollY" height="90%" padding={2}>
      <Flex gap={4} wrap justifyContent="center">
        {allColors.map((color) => (
          <TagData
            id={color}
            key={color}
            color={color}
            selected={selectedColors.includes(color)}
            onTap={({ id: selectedId, selected }) => {
              if (!selectedId) {
                return;
              }

              setSelectedColors((currSelectedColors) =>
                !selected
                  ? currSelectedColors.filter((tileId) => tileId !== color)
                  : currSelectedColors.concat([color])
              );
            }}
            text={`Color ${color}`}
            showCheckbox
          />
        ))}
      </Flex>
    </Box>
  );
}

Group

Use TagData's showCheckbox prop to display a checkbox. This is useful when presenting the user with a multi-select experience.

import { useState } from 'react';
import { Flex, TagData } from 'gestalt';

export default function Example() {
  const dataSources = [
    {
      id: 'data-1',
      name: 'Monthly Active',
      color: '01',
      tooltip: 'Monthly active users',
    },
    {
      id: 'data-2',
      name: 'Weekly Active',
      color: '02',
      tooltip: 'Weekly active users',
    },
    {
      id: 'data-3',
      name: 'Daily Active',
      color: '03',
      tooltip: 'Daily active users',
    },
  ];

  const allIds = dataSources.map(({ id }) => id);

  const [selectedItems, setSelectedItems] = useState(allIds);

  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
      gap={2}
    >
      {dataSources.map(({ id, color, tooltip, name }) => (
        <TagData
          key={id}
          id={id}
          showCheckbox
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

            setSelectedItems((currSelectedIds) =>
              !selected
                ? currSelectedIds.filter((tileId) => tileId !== selectedId)
                : currSelectedIds.concat([selectedId])
            );
          }}
          selected={selectedItems.includes(id)}
          color={color}
          tooltip={{ text: tooltip }}
          text={name}
        />
      ))}
    </Flex>
  );
}

Dismissible

Provide an onRemove callback to make TagData dismissible. Tags are dismissible by the "X" affordance, which triggers the onRemove callback. onRemove should be used to update the external state that is keeping track of TagDatas. If your app uses DefaultLabelProvider, a default accessibility label for the remove icon will be used. This can be overridden with a more specific label if desired.

import { useState } from 'react';
import { Flex, TagData } from 'gestalt';

export default function Example() {
  const dataSources = [
    {
      id: 'data-1',
      name: 'Monthly Active',
      color: '01',
      tooltip: 'Monthly active users',
    },
    {
      id: 'data-2',
      name: 'Weekly Active',
      color: '02',
      tooltip: 'Weekly active users',
    },
    {
      id: 'data-3',
      name: 'Daily Active',
      color: '03',
      tooltip: 'Daily active users',
    },
  ];

  const allIds = dataSources.map(({ id }) => id);

  const [data, setData] = useState(dataSources);

  const [selectedItems, setSelectedItems] = useState(allIds);

  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
      gap={2}
    >
      {data.map(({ id, color, tooltip, name }) => (
        <TagData
          key={id}
          id={id}
          color={color}
          showCheckbox
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

            setSelectedItems((currSelectedIds) =>
              !selected
                ? currSelectedIds.filter((tileId) => tileId !== selectedId)
                : currSelectedIds.concat([selectedId])
            );
          }}
          onRemove={({ id: selectedId }) => {
            if (!selectedId) {
              return;
            }

            setData((currData) =>
              currData.filter((tile) => tile.id !== selectedId)
            );
          }}
          selected={selectedItems.includes(id)}
          tooltip={{ text: tooltip }}
          text={name}
        />
      ))}
    </Flex>
  );
}

Use tooltip to display clarifying information on hover or focus. We recommend using tooltips to provide the user additional context/details.

import { useState } from 'react';
import { Flex, TagData } from 'gestalt';

export default function Example() {
  const [isSelected, setSelected] = useState(false);

  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
    >
      <TagData
        showCheckbox
        text="CPM"
        size="lg"
        selected={isSelected}
        onTap={() => {
          setSelected((selected) => !selected);
        }}
        onRemove={() => {}}
        tooltip={{ text: 'Average cost per 1K paid impressions' }}
      />
    </Flex>
  );
}

Disabled

Disabled TagData cannot be interacted with using the mouse or keyboard. This is commonly used to disable interaction when there are pending permissions or data prerequisites have not been met.

import { useState } from 'react';
import { Flex, TagData } from 'gestalt';

export default function Example() {
  const [isSelected, setSelected] = useState(true);

  return (
    <Flex
      justifyContent="center"
      alignItems="center"
      height="100%"
      width="100%"
    >
      <TagData
        disabled
        text="CPM"
        size="lg"
        onRemove={() => {}}
        showCheckbox
        selected={isSelected}
        onTap={() => {
          setSelected((selected) => !selected);
        }}
        tooltip={{ text: 'Average cost per 1K paid impressions' }}
      />
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Ready	Component is available in Figma for web and mobile web.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.

Tag
Tags are objects that hold text and have a delete icon to remove them. They can appear within TextFields, TextAreas, ComboBox or as standalone components.

TileData
TileData is a flexible, visually rich component that can be used as single or multiple selections on should be only used with data visualizations.

Edit page on GitHub

; Opens a new tab

TagData

also known as Chip, Pill, Filter, Tag

Props

Usage guidelines

Best practices

Accessibility

Localization

Variants

Size

Base Color

Colors

Group

Dismissible

Tooltip

Disabled

Component quality checklist

Related