TagData

View source on GitHub
See recent changes on GitHub

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

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

Defines the height of the TagData to render. See the size variant to learn more.

tooltip
{
  accessibilityLabel?: string;
  inline?: boolean;
  idealDirection?: "up" | "right" | "down" | "left";
  text: string | ReadonlyArray<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

Best practices

Do

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.

Do

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.

Do

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

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 all text strings. Note that localization can lengthen text by 20 to 30 percent.

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.

Note that accessibilityRemoveIconLabel is optional as DefaultLabelProvider provides default strings. Use custom labels if they need to be more specific.

TagData depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import { useState } from 'react';
import { DefaultLabelProvider, Flex, TagData } from 'gestalt';

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

  return (
    <DefaultLabelProvider
      labels={{
        TagData: {
          accessibilityRemoveIconLabel: 'Tag entfernen',
        },
      }}
    >
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <TagData
          onRemove={() => {}}
          onTap={() => {
            setSelected((selected) => !selected);
          }}
          selected={isSelected}
          size="lg"
          text="Eindrücke"
        />
      </Flex>
    </DefaultLabelProvider>
  );
}

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
      alignItems="center"
      direction="column"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <TagData showCheckbox size="sm" text="Small TagData" />
      <TagData showCheckbox size="md" text="Medium TagData" />
      <TagData showCheckbox size="lg" text="Large Tagdata" />
    </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
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box
        alignItems="center"
        display="flex"
        height="100%"
        justifyContent="center"
        width="50%"
      >
        <TagData baseColor="primary" size="sm" text="Small TagData" />
      </Box>
      <Box
        alignItems="center"
        color="secondary"
        display="flex"
        height="100%"
        justifyContent="center"
        width="50%"
      >
        <TagData baseColor="secondary" size="sm" text="Small TagData" />
      </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',
    'neutral',
  ];

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

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

              setSelectedColors((currSelectedColors) =>
                !selected
                  ? currSelectedColors.filter((tileId) => tileId !== color)
                  : currSelectedColors.concat([color])
              );
            }}
            selected={selectedColors.includes(color)}
            showCheckbox
            text={`Color ${color}`}
          />
        ))}
      </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
      alignItems="center"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      {dataSources.map(({ id, color, tooltip, name }) => (
        <TagData
          key={id}
          color={color}
          id={id}
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

            setSelectedItems((currSelectedIds) =>
              !selected
                ? currSelectedIds.filter((tileId) => tileId !== selectedId)
                : currSelectedIds.concat([selectedId])
            );
          }}
          selected={selectedItems.includes(id)}
          showCheckbox
          text={name}
          tooltip={{ text: tooltip }}
        />
      ))}
    </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
      alignItems="center"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      {data.map(({ id, color, tooltip, name }) => (
        <TagData
          key={id}
          color={color}
          id={id}
          onRemove={({ id: selectedId }) => {
            if (!selectedId) {
              return;
            }

            setData((currData) =>
              currData.filter((tile) => tile.id !== selectedId)
            );
          }}
          onTap={({ id: selectedId, selected }) => {
            if (!selectedId) {
              return;
            }

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

Tooltip

Use tooltip to display clarifying information on hover or focus. We recommend using tooltips to provide the user additional context/details. You can also pass in a list of strings to create multi-line tooltips for TagData.

import { Flex, TagData } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={2}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <TagData
        onRemove={() => {}}
        showCheckbox
        size="lg"
        text="CPM"
        tooltip={{ text: 'Average cost per 1K paid impressions' }}
      />
      <TagData
        onRemove={() => {}}
        selected
        showCheckbox
        size="lg"
        text="MAU"
        tooltip={{
          text: [
            'Monthly Active Users',
            'The total monthly users over the last 30 days',
          ],
        }}
      />
    </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
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <TagData
        disabled
        onRemove={() => {}}
        onTap={() => {
          setSelected((selected) => !selected);
        }}
        selected={isSelected}
        showCheckbox
        size="lg"
        text="CPM"
        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