useTagGroup

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

Example

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

<TagGroup
  label="Music genres"
  onAction={key => alert(`Clicked ${key}`)}
>
  <Tag id="rock">Rock</Tag>
  <Tag id="jazz">Jazz</Tag>
  <Tag id="pop">Pop</Tag>
  <Tag id="classical">Classical</Tag>
  <Tag id="edm">EDM</Tag>
</TagGroup>

API

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

useListState<T>(props: ListProps<T>): ListState<T>

useTagGroup<T>(
  props: AriaTagGroupOptions<T>,
state: ListState<T>,
ref: RefObject<HTMLElement | null>
): TagGroupAria

useTag<T>(
  props: AriaTagProps<T>,
state: ListState<T>,
ref: RefObject<FocusableElement | null>
): TagAria

ListState

Name	Type
`collection`	`Collection<Node<T>>`
A collection of items in the list.
`selectionManager`	`SelectionManager`
A selection manager to read and update multiple selection state.

`disabledKeys`	`Set<Key>`
A set of items that are disabled.

AriaTagGroupProps

Name	Type

`children`	`CollectionChildren<T>`
The contents of the collection.
`items`	`Iterable<T>`
Item objects in the collection.

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

TagGroupAria

Name	Type
`errorMessageProps`	`DOMAttributes`
Props for the tag group error message element, if any.
`descriptionProps`	`DOMAttributes`
Props for the tag group description element, if any.
`labelProps`	`DOMAttributes`
Props for the tag group's visible label (if any).
`gridProps`	`DOMAttributes`
Props for the tag grouping element.

AriaTagProps

Name	Type
`item`	`Node<T>`
An object representing the tag. Contains all the relevant information that makes up the tag.

TagAria

Name	Type
`hasAction`	`boolean`
Whether the item has an action, dependent on `onAction`, `disabledKeys`, and `disabledBehavior`. It may also change depending on the current selection state of the list (e.g. when selection is primary). This can be used to enable or disable hover styles or other visual indications of interactivity.
`allowsSelection`	`boolean`
Whether the item may be selected, dependent on `selectionMode`, `disabledKeys`, and `disabledBehavior`.
`isDisabled`	`boolean`
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`.
`isFocused`	`boolean`
Whether the item is currently focused.
`isSelected`	`boolean`
Whether the item is currently selected.
`isPressed`	`boolean`
Whether the item is currently in a pressed state.
`allowsRemoving`	`boolean`
Whether the tag can be removed.
`removeButtonProps`	`AriaButtonProps`
Props for the tag remove button.
`gridCellProps`	`DOMAttributes`
Props for the tag cell element.
`rowProps`	`DOMAttributes`
Props for the tag row element.