TagGroup

A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal.

Theme

label

selectionMode

description

errorMessage

Example

TagGroup.tsx

TagGroup.css

Example

TagGroup.tsx

TagGroup.css

import {TagGroup, Tag} from './TagGroup';

<TagGroup
  label="Categories"
  selectionMode="multiple">
  <Tag>News</Tag>
  <Tag>Travel</Tag>
  <Tag>Gaming</Tag>
  <Tag>Shopping</Tag>
</TagGroup>

Content

TagGroup follows the Collection Components API, accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the items prop, and a function to render the children. Items can be removed via the onRemove event.

import {TagGroup, Tag} from './TagGroup';
import {useListData} from 'react-aria-components';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'News' },
      { id: 2, name: 'Travel' },
      { id: 3, name: 'Gaming' },
      { id: 4, name: 'Shopping' }
    ]
  });

  return (
    <TagGroup
      label="Categories"
      items={list.items}
      onRemove={(keys) => list.remove(...keys)}
      renderEmptyState={() => <div>No categories</div>}>
      {(item) => <Tag>{item.name}</Tag>}
    </TagGroup>
  );
}

Links

Use the href prop on a <Tag> to create a link. See the framework setup guide to learn how to integrate with your framework.

import {TagGroup, Tag} from './TagGroup';

<TagGroup label="Photo categories">
  <Tag href="https://en.wikipedia.org/wiki/Landscape_photography" target="_blank">Landscape</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Portrait_photography" target="_blank">Portrait</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Macro_photography" target="_blank">Macro</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Night_photography" target="_blank">Night</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Dualphotography" target="_blank">Dual</Tag>
  <Tag href="https://en.wikipedia.org/wiki/Golden_hour_(photography)" target="_blank">Golden Hour</Tag>
</TagGroup>

Selection

Use the selectionMode prop to enable single or multiple selection. The selected items can be controlled via the selectedKeys prop, matching the id prop of the items. Items can be disabled with the isDisabled prop. See the selection guide for more details.

Current selection:

selectionMode

selectionBehavior

disallowEmptySelection

import type {Selection} from 'react-aria-components';
import {TagGroup, Tag} from './TagGroup';
import {useState} from 'react';

function Example(props) {
  let [selected, setSelected] = useState<Selection>(new Set());

  return (
    <div>
      <TagGroup
        {...props}
        label="Amenities"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
      >
        <Tag id="laundry">Laundry</Tag>
        <Tag id="fitness">Fitness center</Tag>
        <Tag id="parking" isDisabled>Parking</Tag>
        <Tag id="pool">Swimming pool</Tag>
        <Tag id="breakfast">Breakfast</Tag>
      </TagGroup>
      <p>Current selection: {selected === 'all' ? 'all' : [...selected].join(', ')}</p>
    </div>
  );
}

Examples

Filterable CRUD TableTable with search, filters, column resizing, and form validation.

API

<TagGroup>
  <Label />
  <TagList>
    <Tag>
      <SelectionIndicator />
      <Button slot="remove" />
    </Tag>
  </TagList>
  <Text slot="description" />
  <Text slot="errorMessage" />
</TagGroup>

A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal.

Name	Type
`children`	`ReactNode`
The children of the component.

`selectionMode`	`SelectionMode`
The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`
How multiple selection should behave in the collection.
`selectedKeys`	`'all' \| Iterable<Key>`
The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`
The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`(keys: Selection) => void`
Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`
Whether the collection allows empty selection.
`shouldSelectOnPressUp`	`boolean`
Whether selection should occur on press up instead of press down.
`escapeKeyBehavior`	`'clearSelection' \| 'none'`
Whether pressing the escape key should clear selection in the TagGroup or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

Default className: react-aria-TagGroup

A tag list is a container for tags within a TagGroup.

Name	Type

`children`	`ReactNode \| (item: T) => ReactNode`
The contents of the collection.
`items`	`Iterable<T>`
Item objects in the collection.
`renderEmptyState`	`(props: TagListRenderProps) => ReactNode`
Provides content to display when there are no items in the tag list.
`dependencies`	`ReadonlyArray<any>`
Values that should invalidate the item cache when using dynamic collections.

Default className: react-aria-TagList

Render Prop	CSS Selector
`isEmpty`	CSS Selector: `[data-empty]`
Whether the tag list has no items and should display its empty state.
`isFocused`	CSS Selector: `[data-focused]`
Whether the tag list is currently focused.
`isFocusVisible`	CSS Selector: `[data-focus-visible]`
Whether the tag list is currently keyboard focused.
`state`	CSS Selector: `—`
State of the TagGroup.

Tag

A Tag is an individual item within a TagList.

Name	Type
`id`	`Key`
A unique id for the tag.
`textValue`	`string`
A string representation of the tags's contents, used for accessibility. Required if children is not a plain text string.
`isDisabled`	`boolean`
Whether the tag is disabled.
`children`	`ChildrenOrFunction<TagRenderProps>`
The children of the component. A function may be provided to alter the children based on component state.

Default className: react-aria-Tag

Render Prop	CSS Selector
`allowsRemoving`	CSS Selector: `[data-allows-removing]`
Whether the tag group allows items to be removed.
`isHovered`	CSS Selector: `[data-hovered]`
Whether the item is currently hovered with a mouse.
`isPressed`	CSS Selector: `[data-pressed]`
Whether the item is currently in a pressed state.
`isSelected`	CSS Selector: `[data-selected]`
Whether the item is currently selected.
`isFocused`	CSS Selector: `[data-focused]`
Whether the item is currently focused.
`isFocusVisible`	CSS Selector: `[data-focus-visible]`
Whether the item is currently keyboard focused.
`isDisabled`	CSS Selector: `[data-disabled]`
Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`selectionMode`	CSS Selector: `[data-selection-mode="single \| multiple"]`
The type of selection that is allowed in the collection.
`selectionBehavior`	CSS Selector: `—`
The selection behavior for the collection.

useTagGroup

TagGroup

Content

Links

Selection

Examples

API

TagGroup

TagList

Tag

Related pages