Skip to contentKino
Skip to Content

Token input

Text with tokens in it, such as a message that mentions people and attaches files, where each token is deleted, selected and copied as one piece.

npx shadcn add https://kinoui.com/r/token-input.json
Share on

Examples

March close

Ledger · 3 people

  1. MC

    Maya Chen 9:41

    The March close is ready for review. @Priya Raman can you check the accruals before Thursday? Notes are in march-close.pdf.

  2. PR

    Priya Raman 10:02

    On it. Two vendors are still missing invoices, so I’ll flag them in the sheet.

Default

A reply that mentions people and attaches files. Type @ for suggestions from a Trigger menu inside it; the buttons insert at the caret through actionsRef.

Token deletion

tokenDeletion sets what Backspace does beside a token: removes it, selects it first, or turns it back into its text.

Loading and unresolved

A token’s status: pending shows a spinner after 200ms, and unresolved a dashed edge until someone says which one it is.

Submit shortcut

With submitShortcut="mod+enter", Enter starts a new line and ⌘ Enter or Ctrl Enter calls onSubmit.

Write a note before you send it.

In a form

In a Field, its label names the field and an invalid field marks it. name sends the value in the codec’s text, such as [@Maya Chen](mention:maya).

Read only

readOnly keeps the text and its tokens as they are; they can still be selected and copied.

Installation

npx shadcn@latest add https://kinoui.com/r/token-input.json
Files
lib/reduce-motion.tslib/scroll.tslib/refs.tslib/resize.tslib/swap.tsxlib/popup.tslib/glide.tsxcomponents/kino/tooltip.tsxlib/cut.tsxcomponents/kino/spinner.tsxcomponents/kino/button.tsxlib/trigger-editor.tsxlib/chip.tsxlib/field-control.tsxlib/run-progress.tslib/highlight.tslib/flow.tslib/announce.tsxcomponents/kino/input.tsxcomponents/kino/textarea.tsxcomponents/kino/token-input.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

TokenInput

PropTypeDefaultDescription
defaultValue(string | Token)[][]The text and tokens at first, when you leave the state to the field.
value(string | Token)[]NoneThe text and tokens, when you hold the state. A token is { type, value, label }, with an optional status, text it reverts to, and data for its drawing.
onValueChange(value, { reason, added, removed }) => voidNonereason says what changed it, such as input, paste, undo or remove-press; added and removed are the tokens that came and went.
renderToken(token) => ReactNode<TokenInputToken />Draws a token: TokenInputToken with what it holds, such as an avatar.
onSubmit(value) => voidNoneCalled on the submit key. Without it, the key submits the form around the field, if there is one.
submitShortcut'enter''mod+enter''enter'Which key sends: Enter, with Shift+Enter for a new line, or ⌘/Ctrl+Enter, with Enter for a new line.
tokenDeletion'whole''select''revert''whole'What Backspace or Delete does to the token beside the caret: removes it, selects it first, or turns it back into its text.
copy'codec''label''codec'What a copy puts in plain text for other apps: tokens in the codec’s form, or their labels. A paste back into a token input restores them either way.
codec{ stringify, parse }`[@label](type:value)`How the value is written as plain text, for a form and the clipboard, and read back from it.
getTokenDescription(token) => string“Ada Okafor, mention”What a screen reader says for a token, and in the announcement when one is added or removed.
actionsRefRefObject<TokenInputActions>Noneinsert(content, { resolve }) at the caret, as one undo step: a token given resolve is pending until the promise settles, takes what it gives, and goes if it fails. Also updateToken, removeToken, undo, redo, clear and focus.
readOnlybooleanfalseKeeps the value as it is; it can still be selected and copied.
disabledbooleanfalseOut of the tab order, and nothing can be changed.
requiredbooleanfalseFails the form’s check while the field is empty.
namestringNoneThe form field the value is sent as, in the codec’s text.
formstringNoneThe id of a form outside the field that the value is sent with.

Data attributes

AttributeOnDescription
data-selectedTokenInputTokenThe token is inside the selection.
data-pendingTokenInputTokenThe token is still loading.
data-unresolvedTokenInputTokenSomeone has to say which one the token is.
data-token-typeTokenInputTokenThe token’s type, to style one kind apart.
data-emptyTokenInputEditorNothing is written.

Accessibility

  • The field is a multiline textbox. Name it with a Field and its label, which focuses it, or with aria-label.
  • A token is one character to the caret: the arrow keys step over it, Shift+arrow selects it, and Backspace or Delete acts on it whole.
  • A screen reader reads each token’s label with its description, such as “Maya Chen, mentioned”, and hears each token added or removed, and an upload that finishes.
  • Undo and redo are the field’s own, so tokens come back whole: ⌘Z or Ctrl+Z, and ⌘⇧Z or Ctrl+Y.
  • A read-only field is announced as read only, and ⌘A or Ctrl+A selects its text to copy.
  • When the system asks for less motion, tokens fade in and out without scaling.