TokenizedSearch

Import

import { TokenizedSearch } from '@requence/tokenized-search'

Props

Prop	Type	Default	Description
tokens	(TokenizedSearchTokenDefinition | null)[]	[]	Token key definitions
value	string	—	Controlled search value
defaultValue	string	''	Default value (uncontrolled)
onChange	(value, segments, expression) => void	—	Called on text change. expression is the parsed boolean tree
onSearch	(segments, rawText, expression) => void	—	Called on Enter submit. expression is the parsed boolean tree
autoCommit	boolean	false	Fires onSearch on every change (with the technical query, once async options resolve) instead of only on Enter/submit, and hides the submit button
complex	boolean	false	Enable boolean operators (AND, OR) and grouping parentheses. When off, they are treated as literal text. See Boolean Operators
small	boolean	false	Small variant
disabled	boolean	false	Disables editing, dropdowns, and submit; greys out the input
className	string	—	Root container class
onKeyDown	(event) => void	—	Key handler (when dropdown is closed)
ref	Ref<TokenizedSearchHandle>	—	Imperative handle
autoFocus	boolean	false	Auto-focus on mount
children	ReactNode	—	Slot sub-components for styling

Imperative Handle

interface TokenizedSearchHandle {
  submit: () => void
}

Access via ref:

const searchRef = useRef<TokenizedSearchHandle>(null)

<TokenizedSearch ref={searchRef} ... />

// Programmatic submit
searchRef.current?.submit()

Slot Components

All slots accept a className prop that is merged with internal base styles via tailwind-merge. Some slots also accept children for content.

Root-level Slots

Slot	className	children	Description
<Input>	Editor area container	Nested input slots	Wraps the TipTap editor and clear button
<ClearButton>	Button styling	Icon element	Clear button (hidden when editor is empty)
<SubmitButton>	Button styling	Icon element	Submit button (supports data-[dirty]: and aria-busy variants). Not rendered when autoCommit is set
<Dropdown>	Container styling	Nested dropdown slots	Dropdown container

Input Slots

Must be children of <Input>.

Slot	className	children	Description
<Placeholder>	Text styling	Placeholder text	Shown when editor is empty
<TokenKey>	Mark styling	—	Inline mark for token keys (e.g. Status:)
<TokenValue>	Mark styling	—	Inline mark for token values (e.g. Active)
<TokenNegation>	Mark styling	—	Inline mark for negation prefix (e.g. not:)
<TokenOperator>	Mark styling	—	Inline mark for boolean operators and parens (AND, OR, (, )). Gets data-invalid when the operator is part of a malformed expression — target with the data-[invalid]:* variant

Dropdown Slots

Must be children of <Dropdown>.

Slot	className	children	Description
<DropdownOption>	Option styling	—	Regular dropdown option (aria-selected: for highlight)
<DropdownNotOption>	Option styling	Negation label (default "not")	“Not” option for negatable tokens (aria-selected: for highlight)
<DropdownSeparator>	Border/divider styling	—	Separator between options and “Not” option
<HighlightMatch>	Text color	—	Matched substring within options
<FilterByLabel>	Text styling	Label text (e.g. “Filter by”)	Header above key suggestions
<OperationLabel>	Text styling	Label text (e.g. “Operation”)	Header above the AND / OR suggestions (complex mode)
<SuggestionIcon>	Icon wrapper styling	—	Icon container in key suggestions
<EmptyMessage>	Text styling	Message text	Shown when no options match
<Loader>	Container styling	Spinner + text	Shown while loading async options

Data Attributes

Attribute	Element	When set
aria-selected	<DropdownOption>, <DropdownNotOption>	Option is highlighted via keyboard
data-dirty	<SubmitButton>	Query text differs from last submission
aria-busy	<SubmitButton>	Async token values are being resolved (e.g. after paste)
data-resolving	<SubmitButton>	Same as aria-busy — alternative CSS hook
data-disabled, aria-disabled	Root container	The disabled prop is set — target with data-disabled:* Tailwind variants
data-invalid	Root container	The current query is a malformed boolean expression — target with data-invalid:* Tailwind variants
data-disabled	<SubmitButton>	The disabled prop is set (button also gets the native disabled attribute)