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

Responsive:

Adaptive:

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.

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
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

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
      // $FlowExpectedError[incompatible-type] For demostration purposes
      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.