beta

TagGroup

Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request.

installyarn add @react-spectrum/tag
version3.0.0-beta.2
usageimport {Item, TagGroup} from '@react-spectrum/tag'
View guidelines
Spectrum
View repository
GitHub
View package
NPM

Example#

<TagGroup aria-label="Static TagGroup items example">
  <Item>Adobe Photoshop</Item>
  <Item>Adobe InDesign</Item>
  <Item>Adobe AfterEffects</Item>
  <Item>Adobe Illustrator</Item>
  <Item>Adobe Lightroom</Item>
</TagGroup>
<TagGroup aria-label="Static TagGroup items example">
  <Item>Adobe Photoshop</Item>
  <Item>Adobe InDesign</Item>
  <Item>Adobe AfterEffects</Item>
  <Item>Adobe Illustrator</Item>
  <Item>Adobe Lightroom</Item>
</TagGroup>
<TagGroup aria-label="Static TagGroup items example">
  <Item>
    Adobe Photoshop
  </Item>
  <Item>
    Adobe InDesign
  </Item>
  <Item>
    Adobe AfterEffects
  </Item>
  <Item>
    Adobe Illustrator
  </Item>
  <Item>
    Adobe Lightroom
  </Item>
</TagGroup>

Content#

TagGroup is a component that allows users to categorize content. Basic usage of TagGroup, seen in the example above, shows the use of a static collection where the contents of the TagGroup are hard coded. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API, or update over time.

Each item has a unique key defined by the data. In the example below, the key of each row element is implicitly defined by the id property of the row object. See collections to learn more about keys in dynamic collections.

const items = [
  {id: 1, name: 'Adobe Photoshop'},
  {id: 2, name: 'Adobe XD'},
  {id: 3, name: 'Adobe InDesign'},
  {id: 4, name: 'Adobe AfterEffects'},
  {id: 5, name: 'Adobe Illustrator'},
  {id: 6, name: 'Adobe Lightroom'},
  {id: 7, name: 'Adobe Premiere Pro'},
  {id: 8, name: 'Adobe Fresco'},
  {id: 9, name: 'Adobe Dreamweaver'}
];

<Flex width={500}>
  <TagGroup items={items} aria-label="Dynamic TagGroup items example">
    {item => <Item>{item.name}</Item>}
  </TagGroup>
</Flex>
const items = [
  { id: 1, name: 'Adobe Photoshop' },
  { id: 2, name: 'Adobe XD' },
  { id: 3, name: 'Adobe InDesign' },
  { id: 4, name: 'Adobe AfterEffects' },
  { id: 5, name: 'Adobe Illustrator' },
  { id: 6, name: 'Adobe Lightroom' },
  { id: 7, name: 'Adobe Premiere Pro' },
  { id: 8, name: 'Adobe Fresco' },
  { id: 9, name: 'Adobe Dreamweaver' }
];

<Flex width={500}>
  <TagGroup
    items={items}
    aria-label="Dynamic TagGroup items example"
  >
    {(item) => <Item>{item.name}</Item>}
  </TagGroup>
</Flex>
const items = [
  {
    id: 1,
    name:
      'Adobe Photoshop'
  },
  {
    id: 2,
    name: 'Adobe XD'
  },
  {
    id: 3,
    name:
      'Adobe InDesign'
  },
  {
    id: 4,
    name:
      'Adobe AfterEffects'
  },
  {
    id: 5,
    name:
      'Adobe Illustrator'
  },
  {
    id: 6,
    name:
      'Adobe Lightroom'
  },
  {
    id: 7,
    name:
      'Adobe Premiere Pro'
  },
  {
    id: 8,
    name: 'Adobe Fresco'
  },
  {
    id: 9,
    name:
      'Adobe Dreamweaver'
  }
];

<Flex width={500}>
  <TagGroup
    items={items}
    aria-label="Dynamic TagGroup items example"
  >
    {(item) => (
      <Item>
        {item.name}
      </Item>
    )}
  </TagGroup>
</Flex>

Internationalization#

To internationalize a TagGroup, all text content within the TagGroup should be localized. This includes the aria-label provided to the TagGroup if any. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of TagGroup is automatically flipped.

Labeling#

Accessibility#

An aria-label must be provided to the TagGroup for accessibility. If the TagGroup is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Events#

Removing tags can be enabled by providing the allowsRemoving prop to the TagGroup. TagGroup will pass the key of the removed item to the onRemove handler as shown below.

function Example() {
  let defaultItems = [
    { id: 1, name: 'Adobe Photoshop' },
    { id: 2, name: 'Adobe XD' },
    { id: 3, name: 'Adobe InDesign' },
    { id: 4, name: 'Adobe AfterEffects' },
    { id: 5, name: 'Adobe Illustrator' },
    { id: 6, name: 'Adobe Lightroom' },
    { id: 7, name: 'Adobe Premiere Pro' },
    { id: 8, name: 'Adobe Fresco' },
    { id: 9, name: 'Adobe Dreamweaver' }
  ];

  let [items, setItems] = React.useState(defaultItems);

  let removeItem = (key) => {
    setItems((prevItems) => prevItems.filter((item) => key !== item.id));
  };

  return (
    <Flex width={500}>
      <TagGroup
        items={items}
        allowsRemoving
        onRemove={removeItem}
        aria-label="Removable TagGroup example"
      >
        {(item) => <Item>{item.name}</Item>}
      </TagGroup>
    </Flex>
  );
}

function Example() {
  let defaultItems = [
    { id: 1, name: 'Adobe Photoshop' },
    { id: 2, name: 'Adobe XD' },
    { id: 3, name: 'Adobe InDesign' },
    { id: 4, name: 'Adobe AfterEffects' },
    { id: 5, name: 'Adobe Illustrator' },
    { id: 6, name: 'Adobe Lightroom' },
    { id: 7, name: 'Adobe Premiere Pro' },
    { id: 8, name: 'Adobe Fresco' },
    { id: 9, name: 'Adobe Dreamweaver' }
  ];

  let [items, setItems] = React.useState(defaultItems);

  let removeItem = (key) => {
    setItems((prevItems) =>
      prevItems.filter((item) => key !== item.id)
    );
  };

  return (
    <Flex width={500}>
      <TagGroup
        items={items}
        allowsRemoving
        onRemove={removeItem}
        aria-label="Removable TagGroup example"
      >
        {(item) => <Item>{item.name}</Item>}
      </TagGroup>
    </Flex>
  );
}

function Example() {
  let defaultItems = [
    {
      id: 1,
      name:
        'Adobe Photoshop'
    },
    {
      id: 2,
      name: 'Adobe XD'
    },
    {
      id: 3,
      name:
        'Adobe InDesign'
    },
    {
      id: 4,
      name:
        'Adobe AfterEffects'
    },
    {
      id: 5,
      name:
        'Adobe Illustrator'
    },
    {
      id: 6,
      name:
        'Adobe Lightroom'
    },
    {
      id: 7,
      name:
        'Adobe Premiere Pro'
    },
    {
      id: 8,
      name:
        'Adobe Fresco'
    },
    {
      id: 9,
      name:
        'Adobe Dreamweaver'
    }
  ];

  let [items, setItems] =
    React.useState(
      defaultItems
    );

  let removeItem = (
    key
  ) => {
    setItems(
      (prevItems) =>
        prevItems.filter(
          (item) =>
            key !==
              item.id
        )
    );
  };

  return (
    <Flex width={500}>
      <TagGroup
        items={items}
        allowsRemoving
        onRemove={removeItem}
        aria-label="Removable TagGroup example"
      >
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </TagGroup>
    </Flex>
  );
}

Props#

NameTypeDefaultDescription
childrenCollectionChildren<object>—The contents of the collection.
actionLabelstring—The label to display on the action button.
keyboardDelegateTagKeyboardDelegate<object>—

An optional keyboard delegate to handle arrow key navigation, to override the default.

allowsRemovingboolean—Whether the TagGroup allows removal of tags.
maxRowsnumber—Limit the number of rows initially shown. This will render a button that allows the user to expand to show all tags.
itemsIterable<object>—Item objects in the collection.
validationStateValidationState—Whether the input should display its "valid" or "invalid" visual styling.
isRequiredboolean—

Whether user input is required on the input before form submission. Often paired with the necessityIndicator prop to add a visual indicator to the input.

labelPositionLabelPosition'top'The label's overall position relative to the element it is labeling.
labelAlignAlignment'start'The label's horizontal alignment relative to the element it is labeling.
necessityIndicatorNecessityIndicator'icon'Whether the required state should be shown as an icon or text.
contextualHelpReactNode—A ContextualHelp element to place next to the label.
labelReactNode—The content to display as the label.
isDisabledboolean—Whether the description is displayed with lighter text.
descriptionReactNode—A description for the field. Provides a hint such as specific requirements for what to choose.
errorMessageReactNode—An error message for the field.
Events
NameTypeDefaultDescription
onAction() => void—Handler that is called when the action button is pressed.
onRemove( (key: Key )) => void—Called when the user removes a tag.
Layout
NameTypeDefaultDescription
flexResponsive<string | number | boolean>—When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>—When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>—When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<number | string>—When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'auto' | 'normal' | 'start' | 'end' | 'center' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'stretch'>—Overrides the alignItems property of a flex or grid container. See MDN.
justifySelfResponsive<'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'>—Specifies how the element is justified inside a flex or grid container. See MDN.
orderResponsive<number>—The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>—When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>—When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>—When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>—When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>—When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>—When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>—When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDefaultDescription
marginResponsive<DimensionValue>—The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>—The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>—The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>—The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>—The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>—The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>—The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDefaultDescription
widthResponsive<DimensionValue>—The width of the element. See MDN.
minWidthResponsive<DimensionValue>—The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>—The maximum width of the element. See MDN.
heightResponsive<DimensionValue>—The height of the element. See MDN.
minHeightResponsive<DimensionValue>—The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>—The maximum height of the element. See MDN.
Positioning
NameTypeDefaultDescription
positionResponsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>—Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>—The top position for the element. See MDN.
bottomResponsive<DimensionValue>—The bottom position for the element. See MDN.
leftResponsive<DimensionValue>—The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>—The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>—The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>—The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>—The stacking order for the element. See MDN.
isHiddenResponsive<boolean>—Hides the element.
Accessibility
NameTypeDefaultDescription
idstring—The element's unique identifier. See MDN.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
Advanced
NameTypeDefaultDescription
UNSAFE_classNamestring—Sets the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_styleCSSProperties—Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

With icons#

<TagGroup aria-label="TagGroup with icons example">
  <Item>
    <News />
    <Text>News</Text>
  </Item>
  <Item>
    <Airplane />
    <Text>Travel</Text>
  </Item>
  <Item>
    <Game />
    <Text>Gaming</Text>
  </Item>
  <Item>
    <ShoppingCart />
    <Text>Shopping</Text>
  </Item>
</TagGroup>
<TagGroup aria-label="TagGroup with icons example">
  <Item>
    <News />
    <Text>News</Text>
  </Item>
  <Item>
    <Airplane />
    <Text>Travel</Text>
  </Item>
  <Item>
    <Game />
    <Text>Gaming</Text>
  </Item>
  <Item>
    <ShoppingCart />
    <Text>Shopping</Text>
  </Item>
</TagGroup>
<TagGroup aria-label="TagGroup with icons example">
  <Item>
    <News />
    <Text>News</Text>
  </Item>
  <Item>
    <Airplane />
    <Text>Travel</Text>
  </Item>
  <Item>
    <Game />
    <Text>Gaming</Text>
  </Item>
  <Item>
    <ShoppingCart />
    <Text>
      Shopping
    </Text>
  </Item>
</TagGroup>