## Installation [#installation]
npm
pnpm
yarn
bun
```bash
npx shadcn@latest add @dotui/token-field
```
```bash
pnpm dlx shadcn@latest add @dotui/token-field
```
```bash
yarn dlx shadcn@latest add @dotui/token-field
```
```bash
bun x shadcn@latest add @dotui/token-field
```
## About [#about]
`TokenField` is built on the TokenField primitive from React Aria's upcoming release ([adobe/react-spectrum#10318](https://github.com/adobe/react-spectrum/pull/10318)), vendored until it ships in `react-aria-components`. The primitive handles content-editable editing, IME composition, undo/redo, token-aware clipboard and drag behaviour, and screen-reader announcements.
## Usage [#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.
```tsx
import { Label } from '@/components/ui/field'
import { TokenField, TokenInput } from '@/components/ui/token-field'
```
```tsx
```
## Anatomy [#anatomy]
```tsx
```
`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 `Token`s by default; pass a render function as `TokenInput`'s children to customize them.
```tsx
{(token) => {token.text}}
```
## Value [#value]
The value is a `TokenSegmentList` — a list of plain-text and token segments. Use `defaultValue` for uncontrolled state, or `value` with `onChange` to control it; `toString()` joins the segments back into plain text.
```tsx
const [value, setValue] = React.useState(
() =>
new TokenSegmentList([
{ type: 'text', text: 'Hello ' },
{ type: 'token', text: '@sarahjones' },
]),
)
{/* ... */}
```
## Tokenization [#tokenization]
Subclass `TokenSegmentList` 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.
```tsx
class TagSegmentList extends TokenSegmentList {
protected tokenize(text: string): TokenFieldSegment[] {
// split on commas/spaces and return text + token segments
}
}
```
## Autocomplete [#autocomplete]
For trigger-based suggestions (`@`-mentions, `/`-commands) use the [Mention](/docs/components/mention) component, which wires a caret-anchored suggestions menu onto the token field.
## Examples [#examples]
## API Reference [#api-reference]
### TokenField [#tokenfield]
### TokenInput [#tokeninput]
### Token [#token]