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.

also known as Chip, Pill, Filter Tag

Figma:

Partially ready

Web:

iOS:

Android:

A11y:

Props

Component props
Name	Type	Default
`text` Required	`string`	-
	Short text to render inside the tag.
`disabled`	`boolean`	`false`
	Set a disabled state so the tag looks inactive and cannot be interacted with.
`errorMessage`	`string`	-
	Set an error state on the tag. The message is used as an accessibility label for the error icon. Keep it short so it doesn't overwhelm the user.
`onRemove`	`({\| event: SyntheticMouseEvent<> \|}) => void`	-
	Callback fired when the tag is removed. Should handle state updates to stop rendering the component. Required unless the tag is in a disabled state.
`removeIconAccessibilityLabel`	`string`	-
	Accessibility label for the icon button to remove the tag, ideally something like "Remove [Tag Name] Tag". Required unless the tag is in a disabled state.

Usage guidelines

When to use

In conjunction with TextField, TextArea, and ComboBox, or as a standalone element to display selected options.

When not to use

As a replacement for the Badge, as the Badge is a singular element that gives context to a specific subject.

Accessibility

Ready

Variants

Dismissable

If not disabled, Tags are dismissable by the "X" affordance, which triggers the onRemove callback. Be sure to provide removeIconAccessibilityLabel!

import { Fragment, useState } from 'react';
import { Box, Button, Flex, Tag } from 'gestalt';

export default function Example() {
  const [tags, setTags] = useState([generateTag()]);

  function generateTag() {
    return (
      <Tag
        onRemove={() => {
          setTags((currTags) => currTags.slice(0, currTags.length - 1));
        }}
        removeIconAccessibilityLabel="Remove tag"
        text="Tag"
      />
    );
  }

  return (
    <Box padding={2}>
      <Flex direction="column" gap={3}>
        <Button
          onClick={() => {
            setTags((currTags) => [...currTags, generateTag()]);
          }}
          text="Add tag"
        />

        <Flex
          alignItems="center"
          gap={2}
          height="100%"
          justifyContent="center"
          width="100%"
          wrap
        >
          {tags.map((item, index) => (
            <Fragment key={index}>{item}</Fragment>
          ))}
        </Flex>
      </Flex>
    </Box>
  );
}

Disabled

When disabled, Tags are visible but cannot be removed.

If this condition is constant (not determined dynamically), onRemove and removeIconAccessibilityLabel can be omitted.

import { Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Tag disabled text="Disabled tag" />
    </Flex>
  );
}

Error

Use the errorMessage to communicate an error state to the user.

Note that the message is only available to screen readers. You should indicate the error in the surrounding UI, including how to correct it.

import { Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Tag
        errorMessage="There is an error!"
        onRemove={() => {}}
        removeIconAccessibilityLabel="Remove tag"
        text="Error tag"
      />
    </Flex>
  );
}

Max width

Tag has a maximum width of 300px. Longer text will be truncated, but can be seen by hovering over the Tag.

import { Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Tag
        onRemove={() => {}}
        removeIconAccessibilityLabel="Remove tag"
        text="The quick brown fox jumps over the lazy dog"
      />
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Partially ready	Component is live in Figma, however may not be available for all platforms.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.