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
`onRemove` Required	`({\| event: SyntheticMouseEvent<HTMLButtonElement> \|}) => void`	-
	Callback fired when the user dismisses the tag. This handler should take care of state updates to no longer render the Tag.
`text` Required	`string`	-
	Short text to render inside the Tag.
`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.
`disabled`	`boolean`	`false`
	Disabled tags appear inactive and cannot be interacted with.
`type`	`"default" \| "error" \| "warning"`	`"default"`
	Communicate a "warning" or "error" state to the user, with an accompanying icon and specific background color.

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 Badge is a singular element that gives context to a specific subject.

Best Practices

Do

Use Tag to describe something that is related to more than one topic.

Don't

Use Tag as an interactive element. Tag should not be clickable or perform an action — use Button or Link instead. Tag is only intended to describe a subject.

Do

Write succinct labels for Tag — ideally two or fewer words.

Don't

Intermix removable and unremovable Tags in a group. Group or separate Tags that are removable from those that are unremovable. This creates a clear pattern to the user for which Tags can be removed and which cannot.

Do

Insert Tags directly into ComboBox, TextField or TextArea when providing an affordance to add/edit topics or categories.

Don't

Place Tags outside of the input used to add or edit Tags.

Accessibility

Ready

Localization

Be sure to localize text and accessibilityRemoveIconLabel. Be mindful of label length so that it doesn’t truncate in languages with lengthier character counts.

Variants

Dismissable

If not disabled, Tags are dismissable by the "X" affordance, which triggers the onRemove callback. If your app uses DefaultLabelProvider, a default value for this label will be used. This can be overridden with a more specific label if desired.

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));
        }}
        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 can use a no-op (e.g. () => {}).

import { Flex, Tag } from 'gestalt';

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

Error

Use type="error" to communicate an error state to the user.

import { Flex, Tag } from 'gestalt';

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

Warning

Use type="warning" to communicate a warning state to the user.

import { Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Tag onRemove={() => {}} text="Warning tag" type="warning" />
    </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={() => {}}
        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.