Token Field

const defaultValue = /* ... */;

<TokenField allowsNewlines defaultValue={defaultValue} className="w-[320px]">
  <Label>Message</Label>
  <TokenInput />
</TokenField>

Installation

npx shadcn@latest add @dotui/token-field

About

TokenField is built on the TokenField primitive from react-aria-components. The primitive handles content-editable editing, IME composition, undo/redo, token-aware clipboard and drag behaviour, and screen-reader announcements.

Usage

Compose a TokenField with a TokenInput for the editable area, and a Label before it when you want a visible label (otherwise give the input an aria-label). Without allowsNewlines the field stays single-line.

import { Label } from '@/ui/field'
import { TokenField, TokenInput } from '@/ui/token-field'

<TokenField allowsNewlines>
  <Label>Message</Label>
  <TokenInput />
</TokenField>

Anatomy

<TokenField>
  <Label />
  <TokenInput>
    <Token />
  </TokenInput>
</TokenField>

TokenField owns the value and provides the label and description slots, TokenInput renders the text and inline tokens, and Token renders a single inline token. Tokens render as Tokens by default; pass a render function as TokenInput's children to customize them.

<TokenInput>{(token) => <Token>{token.text}</Token>}</TokenInput>

Value

The value is a TokenFieldValue — a list of plain-text and token segments, imported from react-aria-components. Use defaultValue for uncontrolled state, or value with onChange to control it; toString() joins the segments back into plain text.

import { TokenFieldValue } from 'react-aria-components'

const [value, setValue] = React.useState(
  () =>
    new TokenFieldValue([
      { type: 'text', text: 'Hello ' },
      { type: 'token', text: '@sarahjones' },
    ]),
)

<TokenField value={value} onChange={setValue}>
  {/* ... */}
</TokenField>

Tokenization

Subclass TokenFieldValue and override tokenize to convert typed text into tokens automatically — for hashtags, tag inputs, or structured search filters. tokenize receives the text of an edited region and returns the segments it should become.

class TagFieldValue extends TokenFieldValue {
  protected tokenize(text: string): TokenFieldSegment[] {
    // split on commas/spaces and return text + token segments
  }
}

Autocomplete

For trigger-based suggestions (@-mentions, /-commands) use the Mention component, which wires a caret-anchored suggestions menu onto the token field.

Examples

API Reference

TokenField

TokenInput

Token