# Token Input
Mix editable text with tokens for files, people, tags, and other references.
A token input is a text field that holds tokens alongside the text, like the people mentioned in a message or the files attached to a prompt. Each token moves, deletes and copies as one piece.
```tsx title="demo.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
TokenInput,
TokenInputEditor,
TokenInputToken,
TokenInputTokenRemove,
} from "@ui-sdk/solid/token-input"
import {
type TriggerMenuDataItem,
TriggerMenu,
TriggerMenuContent,
TriggerMenuItem,
TriggerMenuList,
} from "@ui-sdk/solid/trigger-menu"
import { For } from "solid-js"
const people = [
{ value: "hollis", label: "Hollis Grant" },
{ value: "ines", label: "Inès Moreau" },
{ value: "kofi", label: "Kofi Mensah" },
{ value: "wren", label: "Wren Takahashi" },
{ value: "tomasz", label: "Tomasz Wójcik" },
]
function Example() {
return (
Message (
{token.label}
)}
>
{(state) => (
{(item) => (
{item.label}
)}
)}
)
}
export { Example }
```
Type @ and choose a person with the arrow keys and Enter. Remove a token with Backspace, or press its remove button.
## Installation
```bash
npm install @ui-sdk/solid @ui-sdk/core
```
## Composition
Use the following composition to build a `TokenInput`:
```text
TokenInput
├── TokenInputEditor
└── TriggerMenu
```
And for each token, inside `renderToken`:
```text
TokenInputToken
└── TokenInputTokenRemove
```
`TokenInput` holds the value, and `TokenInputEditor` is the text people edit. A [Trigger Menu](/docs/solid/components/trigger-menu) inside it suggests tokens when someone types `@`, `/`, or another trigger. Pass `renderToken` to give each token your own markup.
## Usage
Import the parts and put them together:
```tsx
import {
TokenInput,
TokenInputEditor,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
const draft: TokenInputValue = [
"Explain ",
{ type: "file", value: "src/routes.ts", label: "routes.ts" },
]
function Example() {
return (
)
}
export { Example }
```
A value is an array of text and tokens. Each token has a type, a value for your app, and a label for the reader. The editor manages its own content, including tokens, selection, and undo, so let it render that content and use `renderToken` for custom token markup.
## Token Input or Trigger Menu
Token Input holds the text and tokens. [Trigger Menu](/docs/solid/components/trigger-menu) suggests what to insert when someone types a trigger character.
Use Token Input on its own when your code supplies the tokens. Add a Trigger Menu for suggestions, as in the demo above. Trigger Menu also works with ordinary inputs and textareas.
## Prompt Input
Combine file suggestions, skills, and a send action. This example marks files as pending while they load, then uses `updateToken()` to show a skill running. Enter sends; Shift+Enter adds a line. An open suggestion menu or an active input method takes precedence over sending.
```tsx title="prompt-input.tsx"
import {
createTokenInputController,
toText,
TokenInput,
TokenInputEditor,
TokenInputToken,
TokenInputTokenRemove,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
import {
type TriggerMenuDataItem,
TriggerMenu,
TriggerMenuContent,
TriggerMenuEmpty,
TriggerMenuHint,
TriggerMenuItem,
TriggerMenuList,
} from "@ui-sdk/solid/trigger-menu"
import { createSignal, For, onCleanup, Show } from "solid-js"
import { useLog } from "./log"
const files = [
{ value: "src/app.tsx", label: "app.tsx", keywords: ["src"] },
{ value: "src/routes.ts", label: "routes.ts", keywords: ["src"] },
{ value: "src/styles.css", label: "styles.css", keywords: ["src"] },
{ value: "README.md", label: "README.md" },
{ value: "package.json", label: "package.json" },
]
const skills = [
{
value: "search",
label: "search",
arguments: [{ name: "query", hint: "", required: true }],
},
{ value: "review", label: "review" },
{ value: "summarize", label: "summarize" },
]
const loadFile = () => new Promise((resolve) => setTimeout(resolve, 800))
function Example() {
const log = useLog()
const prompt = createTokenInputController()
const [running, setRunning] = createSignal(false)
let sendTimer: ReturnType | undefined
onCleanup(() => clearTimeout(sendTimer))
function send(value: TokenInputValue) {
if (running() || !prompt.getLabel().trim()) {
return
}
setRunning(true)
const skillTokens = value.filter(
(segment) => typeof segment !== "string" && segment.type === "skill"
)
for (const skill of skillTokens) {
if (typeof skill !== "string") {
prompt.updateToken(skill.id!, {
data: { ...skill.data, run: "running" },
})
}
}
sendTimer = setTimeout(() => {
for (const skill of skillTokens) {
if (typeof skill !== "string") {
prompt.updateToken(skill.id!, {
data: { ...skill.data, run: "done" },
})
}
}
log(`Sent ${toText(prompt.getValue())}`)
prompt.clear()
setRunning(false)
}, 1500)
}
return (
(
}
>
{token.type === "skill" ? `/${token.label}` : token.label}
)}
>
details.trigger === "@" ? loadFile() : undefined
}
>
No matches
{(state) => (
{(item) => (
{item.label}
)}
)}
)
}
export { Example }
```
Type @ for files or / at the start for skills. For /search, enter a query and press Enter to insert the command. Press Enter again to send, and the console logs the message.
## Deleting Tokens
Choose what Backspace does at a token with `tokenDeletion`:
- `whole` removes the token in one press.
- `select` selects it first, then removes it on the next press.
- `revert` turns it back into editable text, so the trigger menu opens on it again.
```tsx title="deletion.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
Select,
SelectContent,
SelectItem,
SelectItemIndicator,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/solid/select"
import {
TokenInput,
TokenInputEditor,
TokenInputToken,
type TokenDeletion,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
import {
type TriggerMenuDataItem,
TriggerMenu,
TriggerMenuContent,
TriggerMenuItem,
TriggerMenuList,
} from "@ui-sdk/solid/trigger-menu"
import { createSignal, For } from "solid-js"
import { useLog } from "./log"
const modes = [
{ value: "whole", label: "Whole" },
{ value: "select", label: "Select" },
{ value: "revert", label: "Revert" },
]
const files = [
{ value: "src/app.tsx", label: "app.tsx", keywords: ["src"] },
{ value: "src/routes.ts", label: "routes.ts", keywords: ["src"] },
{ value: "src/styles.css", label: "styles.css", keywords: ["src"] },
{ value: "README.md", label: "README.md" },
{ value: "package.json", label: "package.json" },
]
const draft: TokenInputValue = [
"Explain ",
{
type: "file",
value: "src/routes.ts",
label: "routes.ts",
data: { trigger: "@" },
},
" in two sentences.",
]
function Example() {
const log = useLog()
const [deletion, setDeletion] = createSignal("whole")
return (
)
}
export { Example }
```
Choose a Backspace behavior, click just after routes.ts, and press Backspace. Undo to try another behavior.
## Codec
A codec converts tokens to text for the clipboard, forms, and saved drafts. The default writes `[@label](type:value)`. Copy that text into another app and paste it back to restore the token.
Use `toText`, `fromText`, and `toLabel` to convert values yourself. Supply a custom codec for another format, as this example does for `<@hollis>`. With `copy="label"`, copying writes what people read, and pasting back into a token input still restores the tokens. The default parser accepts letters, digits, `_`, and `-` in token types; other types need a custom codec.
```tsx title="codec.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
fromText,
toText,
TokenInput,
TokenInputEditor,
type TokenCodec,
} from "@ui-sdk/solid/token-input"
import { useLog } from "./log"
const chat: TokenCodec = {
format: (token) => `<@${token.value}>`,
parse: (text) =>
text.split(/(<@[\w.-]+>)/).map((part) => {
const id = /^<@([\w.-]+)>$/.exec(part)?.[1]
return id ? { type: "mention", value: id, label: `@${id}` } : part
}),
}
const draft = fromText("Ping <@hollis> and <@ines> about the launch", chat)
function Example() {
const log = useLog()
return (
Message log(toText(value, chat))}
>
)
}
export { Example }
```
Edit the message. The console logs it in the custom format, with each mention as <@id>.
## Form
Give the input a `name` to submit its serialized text. `required`, `disabled`, and `readOnly` control form behavior. The `form` option associates it with a form elsewhere on the page, as shown here.
```tsx title="form.tsx"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/solid/checkbox"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
TokenInput,
TokenInputEditor,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
import { createSignal, createUniqueId } from "solid-js"
import { useLog } from "./log"
const draft: TokenInputValue = [
"Explain ",
{ type: "file", value: "src/routes.ts", label: "routes.ts" },
" in two sentences.",
]
function Example() {
const log = useLog()
const [disabled, setDisabled] = createSignal(false)
const [readOnly, setReadOnly] = createSignal(false)
const formId = createUniqueId()
return (
Prompt
)
}
export { Example }
```
Press Submit to log the prompt's serialized value. Try Disabled and Read-only, then Reset.
## Controlled
Pass `value` and update it in `onValueChange`. The change details include the reason, input type, and removed tokens. The input still manages its editing history.
```tsx title="controlled.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
toText,
TokenInput,
TokenInputEditor,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
import {
type TriggerMenuDataItem,
TriggerMenu,
TriggerMenuContent,
TriggerMenuItem,
TriggerMenuList,
} from "@ui-sdk/solid/trigger-menu"
import { createSignal, For } from "solid-js"
import { useLog } from "./log"
const files = [
{ value: "src/app.tsx", label: "app.tsx", keywords: ["src"] },
{ value: "src/routes.ts", label: "routes.ts", keywords: ["src"] },
{ value: "src/styles.css", label: "styles.css", keywords: ["src"] },
{ value: "README.md", label: "README.md" },
{ value: "package.json", label: "package.json" },
]
const draft: TokenInputValue = [
"Explain ",
{ type: "file", value: "src/routes.ts", label: "routes.ts" },
" in two sentences.",
]
function Example() {
const log = useLog()
const [value, setValue] = createSignal(draft)
return (
Prompt {
setValue(next)
const removed = details.removed.map((token) => token.label).join(", ")
log(
`${toText(next)} (${details.reason}${removed ? `, removed ${removed}` : ""})`
)
}}
history={{ limit: 50, groupDelay: 1000 }}
getTokenDescription={(token) =>
token.type === "file" ? "attached file" : token.type
}
>
{(state) => (
{(item) => (
{item.label}
)}
)}
)
}
export { Example }
```
Type, add a file with @, or remove a token. The console logs the value and the reason for each change.
## Controller
Use `createTokenInputController()` to insert, update, or remove tokens from code. Pass a promise as `resolve` to mark an inserted token as pending until its data is ready. Updating a token doesn't add an undo step.
```tsx title="controller.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
createTokenInputController,
TokenInput,
TokenInputEditor,
type Token,
type TokenInputValue,
} from "@ui-sdk/solid/token-input"
const draft: TokenInputValue = [
"Compare ",
{ type: "file", value: "src/routes.ts", label: "routes.ts" },
" with ",
]
const loadFile = () => new Promise((resolve) => setTimeout(resolve, 800))
function Example() {
const prompt = createTokenInputController()
const firstToken = () =>
prompt
.getValue()
.find((segment): segment is Token => typeof segment !== "string")
return (
event.preventDefault()}>
Prompt
)
}
export { Example }
```
Attach a file and watch it load. Show the first token's full path or remove it, then use Undo or Clear.
## Submit Shortcut
Set `submitShortcut` to `mod+enter` for a multiline message. Enter then inserts a line, and Command or Control+Enter submits.
```tsx title="submit-shortcut.tsx"
import { Field, FieldLabel } from "@ui-sdk/solid/field"
import {
toLabel,
TokenInput,
TokenInputEditor,
} from "@ui-sdk/solid/token-input"
import { useLog } from "./log"
function Example() {
const log = useLog()
return (
Message log(`Sent ${toLabel(value)}`)}
>
)
}
export { Example }
```
Write a message. Enter adds a line; Command+Enter on a Mac or Control+Enter elsewhere sends it to the console.
## Custom Rendering
Pass `renderToken` to render each token's content, usually a `TokenInputToken` with a `TokenInputTokenRemove` inside. It receives the token, so you can choose an icon by its type or show its `data`. Without it, each token shows its label.
Every part also takes `render`. [Parts and Composition](/docs/solid/parts-and-composition#choose-the-element) explains how props merge, and each part's state is listed under [State](#state).
## Styling
Style the editor, the tokens and their remove buttons. The editor shows `data-empty` while it holds nothing; show the placeholder with `content: attr(aria-placeholder)` on its `::before`. Tokens show `data-token-type`, `data-pending`, `data-unresolved` and `data-selected`. Without a custom token renderer, the element that holds each token, `token-input-host`, carries the same attributes, so you can style tokens without `renderToken`.
Each part has a `data-slot`, such as `token-input-token`, and shows its state through the attributes listed under [Data Attributes](#data-attributes).
## Data Attributes
### TokenInputEditor
`[data-slot="token-input-editor"]`
- `data-empty`: Present while the input holds nothing. Show the placeholder with it.
- `data-disabled`: Present when the input is disabled, by its own prop, a field or a `