Loading…

Tags Input

A list of short values, where invalid entries stay visible instead of vanishing.

Forms
1 file
No extra npm packages
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add tags-input

No npm packages are needed beyond what Dowel already requires.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { TagsInput } from "@/components/ui/tags-input";

Examples

Every example the tests run, live and operable, side by side.

Default
With Tags
Invalid Stays Visible
Paste Multiple
At The Limit
Allowed Domains
Disabled
Animated Tags

API

Generated from the component's own types, so a prop cannot appear here without existing.

<TagsInput>

Prop	Type	Default
`label` (required) Names the field. Required — an unlabelled list of tokens is unreadable.	`string`	—
`onValueChange` (required)	`(tags: string[]) => void`	—
`value` (required)	`string[]`	—
`allowDuplicates` Rejects a tag already present. Rejections are announced, never silent.	`boolean`	`false`
`animateExit` Lets a removed tag blur and drop away before it leaves the DOM. The departing copy is `aria-hidden` and inert. Off by default, because the old token briefly remains in the markup. Tags added after mount always blur in.	`boolean`	`false`
`delimiters` Characters that commit the token being typed, besides Enter.	`string[]`	`[",", ";"]`
`disabled`	`boolean`	`false`
`inputProps`	`Omit<ComponentPropsWithRef<"input">, "value" \| "onChange" \| "disabled">`	—
`max` Refuses further tags once reached, and says so.	`number`	—
`placeholder`	`string`	—
`validate` Decides whether a tag is acceptable. An invalid tag is still added, marked, and given its reason, rather than being refused or dropped.	`TagValidator`	—

Plus every attribute of <div> except onChange, children.

Accessibility

No WAI-ARIA pattern covers a token field, and the near misses misdescribe it — these are committed values, not options being chosen, so calling the container a listbox would promise navigation that does not exist. It is a labelled group holding a list, with a remove button per token carrying the tag in its accessible name. An invalid token's reason is inside the token, so it is announced with it rather than as a detached error. Additions, removals and refusals all reach a polite live region, because a refusal that looks like nothing happening is the failure this component exists to prevent. Remove buttons sit in the natural tab order rather than behind a roving tabindex: it costs a tab stop per token, and buys a pattern every assistive technology already understands. With animateExit, a removed token lingers only as an aria-hidden, inert copy while it animates out.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

label

Names the field. Required — an unlabelled list of tokens is unreadable.

string

—

onValueChange

(tags: string[]) => void

—

value

string[]

—

allowDuplicates

Rejects a tag already present. Rejections are announced, never silent.

boolean

false

animateExit

Lets a removed tag blur and drop away before it leaves the DOM. The departing copy is aria-hidden and inert. Off by default, because the old token briefly remains in the markup. Tags added after mount always blur in.

boolean

false

delimiters

Characters that commit the token being typed, besides Enter.

string[]

[",", ";"]

disabled

boolean

false

inputProps

Omit<ComponentPropsWithRef<"input">, "value" | "onChange" | "disabled">

—

max

Refuses further tags once reached, and says so.

number

—

placeholder

string

—

validate

Decides whether a tag is acceptable. An invalid tag is still added, marked, and given its reason, rather than being refused or dropped.

TagValidator

—