Tag

Tags can be used to categorize, classify or filter content, usually via keywords. They can appear within TextFields, TextAreas, ComboBox or as standalone components.

also known as Chip, Pill, Filter Tag

Figma:

Partially ready

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`onRemove` Required	`(arg1: { event: React.MouseEvent<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.
`size`	`"sm" \| "md" \| "lg"`	`"md"`
	Size of the Tag. Default is `md`. See size variant for more details.
`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

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.

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.

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

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

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

Tag depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more

import { DefaultLabelProvider, Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <DefaultLabelProvider
      labels={{
        TagData: {
          accessibilityRemoveIconLabel: 'Remove tag',
        },
      }}
    >
      <Flex
        alignItems="center"
        height="100%"
        justifyContent="center"
        width="100%"
      >
        <Tag
          onRemove={() => {}}
          text="Abgelaufene Kreditkarte"
          type="warning"
        />
      </Flex>
    </DefaultLabelProvider>
  );
}

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>
  );
}

Size

Tag is available in three sizes: small (24px), medium(32px), large(48px). Use the sm tag for denser surfaces.

import { Flex, Tag } from 'gestalt';

export default function Example() {
  return (
    <Flex
      direction="column"
      gap={{ column: 2, row: 0 }}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="row" gap={2}>
        <Tag onRemove={() => {}} size="sm" text="Small" />
        <Tag
          onRemove={() => {}}
          size="sm"
          text="Small Warning"
          type="warning"
        />
        <Tag onRemove={() => {}} size="sm" text="Small Error" type="error" />
      </Flex>
      <Flex gap={2}>
        <Tag onRemove={() => {}} size="md" text="Medium" />
        <Tag
          onRemove={() => {}}
          size="md"
          text="Medium Warning"
          type="warning"
        />
        <Tag onRemove={() => {}} size="md" text="Medium Error" type="error" />
      </Flex>
      <Flex gap={2}>
        <Tag onRemove={() => {}} size="lg" text="Large" />
        <Tag
          onRemove={() => {}}
          size="lg"
          text="Large Warning"
          type="warning"
        />
        <Tag onRemove={() => {}} size="lg" text="Large Error" type="error" />
      </Flex>
    </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 responds to changing viewport sizes in web and mobile web.

Edit page on GitHub