The Tag Group component is a focusable container that holds and manages multiple Tag elements, with built-in support for keyboard navigation, selection, and removal.
- Manage sets of related tags where users need to view, select, or remove multiple items (e.g., active filters, selected keywords, categorized content).
- Provide unified keyboard navigation and focus management across tags.
- Display dynamic or static collections requiring accessibility features like roving focus.
- Removable filter pills: Tags representing active filters with individual close buttons.
- Selectable tags: Tags that support single or multiple selection (e.g., for categorization or multi-select inputs).
- Static tag lists: Non-interactive or non-removable tags with keyboard navigation for screen readers.
- For a single tag; use the Tag component instead.
- For simple non-interactive displays without keyboard navigation needs; use a basic container.
- When tags require independent focus management outside a unified group.
| Variant | Use Case |
|---|
| None (default) | Display tags with optional individual removal |
| Single | Allow selection of exactly one tag |
| Multiple | Allow selection of one or more tags |
| Element | Description |
|---|
| Container | Focusable wrapper managing the overall group. |
| Label | Accessible name for the group (visible or via aria-label). |
| Tag List | Layout container for the collection of Tag items. |
| Tags | Individual Tag components within the group. |
| Description | Optional helper text below the tag list. |
| Error Message | Optional validation error text. |
| State | Description | Visual Indicators |
|---|
| Empty | No tags present | Render empty state content if provided |
| Focused | Keyboard focus (visible on Tab or arrow key navigation) | High-contrast focus ring on active tag |
| Error | Validation error state | Error message displayed, potential red styling |
- Provide a clear, concise label describing the group’s purpose (e.g., “Selected filters” or “Keywords”).
- Ensure individual tag labels remain concise and consistent with Tag guidelines.
- For empty states, use neutral messaging like “No items selected”.
- Always provide an accessible label via visible text or
aria-label/aria-labelledby.
- For selectable variants: Use
role="listbox" with aria-multiselectable="true" for multiple selection.
- For non-selectable: Use
role="group" or appropriate list structure.
- Ensure each tag has a
textValue for non-text content and unique keys for dynamic collections.
- Support roving tabindex for keyboard focus movement across tags.
- Announce changes (e.g., removal, selection) dynamically if needed.
Support standard keyboard navigation
- Tab: Focus the group; subsequent arrows move focus internally.
- Arrow Left/Right: Move focus between tags (roving focus).
- Home/End: Jump to first/last tag.
- Space/Enter: Toggle selection on focused tag (in selectable variants).
- Delete/Backspace: Remove focused tag (if removal allowed).
- Escape: Optionally clear selection (configurable behavior).
- Type-ahead: Jump to tags matching typed characters.
