Tag Input
The Tag Input component allows users to add, remove, and manage tags dynamically, with optional suggestions.
Usage
Default
Type a tag and press Enter or comma to add. Use arrow keys to navigate suggestions; Enter to select; Escape to close. Backspace removes the last tag when the field is empty.
- react
- nextjs
const [tags, setTags] = useState(["react", "nextjs"]);
<TagInput
tags={tags}
onChange={setTags}
placeholder="Add a tag..."
/>Props
| Type | Description | |
|---|---|---|
| aria-describedby | string | References the ID of an external element that describes the tag input group. Merged with the internal accessibility description/status when provided. |
| aria-description | string | Optional screen reader description for the input behavior. This is announced through an internally rendered description element. |
| aria-label | string | Accessible label for the overall tag input group. Used when no external aria-labelledby is provided. Defaults to "Tag Input". |
| aria-labelledby | string | References the ID of an external element that labels the tag input group. Takes precedence over "aria-label" when provided. |
| data-testid | string | Optional test ID for testing frameworks. |
| debounceMs | number | Debounce time (ms) for suggestions/autocomplete fetches. |
| fetchSuggestions | ((query: string) => Promise<string[]>) | Optional function to fetch autocomplete suggestions based on input query. Should return a promise resolving to a string array. |
| idBase | string | Custom ID base for stable accessibility relationships. Can be used to generate predictable ids for label, description, listbox, input, and status elements. |
| inputAriaDescribedBy | string | References the ID of an external element that describes the text input. Merged with the internal description/status when provided. |
| inputAriaLabel | string | Optional accessible label for the text input itself. Defaults to "Add new tag". |
| inputAriaLabelledBy | string | References the ID of an external element that labels the text input. Takes precedence over inputAriaLabel when provided. |
| onChange | ((tags: string[]) => void) | Callback fired when tags change. Receives the new array of tags. |
| placeholder | string | Placeholder text displayed in the input when empty. |
| removeTagButtonLabel | string | Accessible label prefix for remove-tag buttons. Example output: "Remove tag React". Defaults to "Remove tag". |
| rounding | RoundingType | Rounding style for the input and tags. One of: "none" | "small" | "medium" | "large" | "full" |
| shadow | ShadowType | Shadow style for the input and tags. One of: "none" | "light" | "medium" | "strong" | "intense" |
| size | SizeType | Size of the input and tags. One of: "xs" | "small" | "medium" | "large" | "xl" |
| state | StateType | State of the input (for feedback/validation). One of: "success" | "error" | "warning" | "disabled" | "" |
| suggestionsAriaLabel | string | Accessible label for the suggestions listbox. Defaults to "Tag suggestions". |
| tags | string[] | Array of current tags. |
| theme | ThemeType | Theme for styling the input and tags. One of: "primary" | "secondary" | "tertiary" | "quaternary" | "clear" |