Token Search Field

"use client"

import {

The TokenSearchField component is a search input for lists such as payment history, where people narrow results with filters. Typing a known operator such as from:maya and pressing Space or Enter turns it into a token, and free text stays editable after the tokens. Use it when filters are part of the query. For a plain text search, use a search field; for a fixed set of filters, use chips or a select next to it.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/token-search-field
Copy

Usage#

Copyimport {
  TokenSearchField,
  type SearchOperator,
} from "@/components/ui/token-search-field"

Copyconst operators: SearchOperator[] = [
  { key: "from", label: "From" },
  { key: "is", label: "Status" },
]
 
<TokenSearchField label="Search payments" operators={operators} />

Features#

• Typed operators become tokens on Space or Enter when the caret is at the end
• Backspace at the start of the input moves to the last token, a second Backspace removes it
• Arrow keys move between tokens; Escape, typing, or the arrow past the last token returns to the input
• A clear button that removes the text and all tokens
• Controlled or uncontrolled tokens and text, and an onSubmit with both
• Tokens added from outside, including plain text tokens with no operator
• Polite announcements when tokens are added, removed or cleared

Operators#

Pass operators to list what the user can type before a colon. Only known operators turn into tokens; amount:5 stays text if amount is not listed.

"use client"

import {

Controlled#

Pass tokens with onTokensChange and value with onChange to own the query. onSubmit runs on Enter when there is no operator to finish and receives { text, tokens }.

"use client"

import * as React from "react"

Filters from outside#

Add tokens from your own controls, such as suggestion chips. A token without operator shows its value only.

"use client"

import * as React from "react"

Disabled#

Set isDisabled to lock the input and the tokens. The clear and remove buttons are hidden.

"use client"

import {

Accessibility#

TokenSearchField is built on React Aria SearchField and TagGroup. The input gets search semantics, Escape clears it, and the tokens are a grid of tags you move through with the arrow keys and remove with Backspace or Delete.

Label the field#

Pass label for a visible label. Without one, pass aria-label.

Copy<TokenSearchField aria-label="Search payments" operators={operators} />

Labels for the parts#

tokensLabel names the list of tokens, removeLabel starts the name of each remove button, and clearLabel names the clear button. Each remove button is named after its token, such as "Remove Status pending". Translate all three with the rest of your UI.

Announcements#

A hidden live region says "Added", "Removed" or "Cleared filters" so screen reader users hear changes that happen without a focus move.

API Reference#

TokenSearchField#

Accepts all React Aria SearchField props except children, className, onSubmit, value, defaultValue and onChange, which are replaced below.

SearchToken#

SearchOperator#