Tag input
Free words as removable chips — Enter or a comma adds one, a paste adds several, suggestions complete, normalize cleans and validate refuses with a reason.
Web only — React, from @krizaka/ui/tag-input. Beta: its API may still change in a minor version.
When to use
- For keywords a person invents: the tags of a video, the topics of an article.
- For a list of values typed one after the other: e-mail recipients, domains, IP addresses.
When not to use
Installation
Install
npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcssStyles
@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";Import
import { TagInput } from "@krizaka/ui/tag-input";Examples
Tags of a video
Suggestions, lower case without #, at most 10.
montrealsunset
Up to 10 tags, separated by commas.
E-mail recipients
validate refuses what is not an address; a comma or a space adds one.
ines@krizaka.com
Props
Words as removable chips — tags, keywords, e-mail recipients — with suggestions, cleaning and validation.
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | — | The visible label, passed translated (also the accessible name). |
className | string | — | Classes merged on the root. |
defaultValue | readonly string[] | [] | The tags at first, uncontrolled. |
disabled | boolean | — | Not available. |
error | string | — | An error from the app (a server refusal); validate's own errors show here too. |
hideLabel | boolean | — | Hides the label visually, keeping it as the accessible name. |
hint | string | — | A help text under the field ("Up to 10 tags, separated by commas"). |
labels | Partial<Pick<ComboboxLabels, "results" | "toggle" | "remove" | "empty" | "create">> | — | The words of the field, passed translated; English by default. |
max | number | — | Most tags; the field stops offering more past it. |
name | string | — | The name of the hidden inputs, for a plain <form> post (one per tag). |
normalize | ((tag: string) => string) | (tag) => tag.trim() | Cleans a word before it is added ((t) => t.toLowerCase().replace(/^#/, "")). An empty result is ignored. |
onValueChange | ((tags: string[]) => void) | — | Called with every tag after a change. |
placeholder | string | — | The input's placeholder, passed translated. |
separators | readonly string[] | [","] | Keys that add the word, besides Enter. Default [","]. |
suggestions | readonly string[] | [] | Words offered as the person types (their own history, a curated list). |
validate | ((tag: string, tags: readonly string[]) => string | null) | — | Refuses a word: return the reason (passed translated), shown and read as the field's error; null accepts it. |
value | readonly string[] | — | The tags (controlled). |
Accessibility
- Built on
Combobox(multiple, creatable): the same combobox pattern and announcements. - A refusal from
validateis shown under the field and read with it (aria-describedby,aria-invalid). - Each tag's remove button is named by
labels.remove(“Remove sunset”).
Keyboard
| Keys | Action |
|---|---|
| Enter / , | Add the typed word as a tag (or the active suggestion). |
| Backspace | In an empty input, remove the last tag. |
| Arrow Down / Arrow Up | Move through the suggestions. |
Best practices
- Normalise the way the product stores tags (lower case, no
#, no spaces) so “#Sunset” and “sunset” are one tag. - Say the limit and the separator in
hint(“Up to 10 tags, separated by commas”). - Offer the person's own history first in
suggestions, then a curated list. - Explain a refusal in words in
validate(“Use letters and numbers only”).
Related components
Generated from the code of @krizaka/ui 2.4.0: its meta.ts, its examples and its types.Edit this documentation on GitHub