Search Field

Headless Search Field; covers HTML search input, React Aria SearchField, Reka UI Primitive.


Package	`@vizejs/ui/search-field`
Maturity	stable
Own the source	`vize lib pull search-field`
Requires	controllable-state, id
Aliases	search box, search input, query field
Covers	HTML search input, React Aria SearchField, Reka UI Primitive

Usage

import { SearchField } from "@vizejs/ui/search-field";

Or copy the source into your project with vize lib pull search-field (see Source Distribution).

API

`SearchField`

Source: src/families/form/search-field/search-field.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned input id; nullish values use a deterministic fallback.
`name`	`string`	`undefined`	Native form field name.
`modelValue`	`string`	`undefined`	Controlled string value; undefined selects uncontrolled behavior.
`defaultValue`	`string`	`""`	Initial uncontrolled value and form-reset target.
`disabled`	`boolean`	`false`	Disable editing, clearing, focus, and native form submission.
`readOnly`	`boolean`	`false`	Keep focusability while preventing user editing and clearing.
`required`	`boolean`	`false`	Mark the native search input as required.
`placeholder`	`string`	`undefined`	Native placeholder text.
`autocomplete`	`string`	`undefined`	Native autocomplete hint.
`inputMode`	`SearchFieldInputMode`	`"search"`	Native virtual-keyboard input mode.
`enterKeyHint`	`SearchFieldEnterKeyHint`	`"search"`	Native virtual-keyboard enter key hint.
`showClear`	`SearchFieldClearVisibility`	`"auto"`	Clear button visibility policy.
`clearLabel`	`string`	`"Clear search"`	Accessible name for the default clear button.
`ariaLabel`	`string`	`undefined`	Accessible name when no label or aria-labelledby supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the search input.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the search input.
`ariaErrormessage`	`string`	`undefined`	Id of the validation error message used while invalid.
`ariaInvalid`	`SearchFieldAriaInvalid`	`false`	Invalid state announced to assistive technology.

Events

Event	Payload	Description
`update:modelValue`	`[value: string]`	Fired when the value requests a new controlled string.
`clear`	`[value: "", nativeEvent: MouseEvent]`	Fired after the default clear button clears the field.
`change`	`[value: string, nativeEvent: Event]`	Fired after a native change/commit with the current string and native Event.
`compositionEnd`	`[value: string, nativeEvent: CompositionEvent]`	Fired when IME composition ends.
`compositionStart`	`[value: string, nativeEvent: CompositionEvent]`	Fired when IME composition starts.
`input`	`[value: string, nativeEvent: Event]`	Fired after a native input event with the next string and native Event.
`search`	`[value: string, nativeEvent: Event]`	Fired after a native search event with the committed search string.

Slots

Slot	Slot props	Description
`clear`	`SearchFieldClearSlotState`	Replaces the default clear button contents with availability state.

Exposed

Member	Type	Description
`composing`	`boolean`	Whether the native input is currently inside IME composition.
`value`	`string`	Current controlled or uncontrolled string value.
`clear`	`() => boolean`	Clear the current value and report whether it changed.
`focus`	`(options?: FocusOptions) => void`	Move focus to the native search input.
`reset`	`() => boolean`	Restore the current default value and report whether it changed.
`select`	`() => void`	Select the current native search text.
`setValue`	`(value: string) => boolean`	Request a value update and report whether it differs.
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

Behavior

Normative state × input → outcome table for search-field.vue (@vizejs/ui/search-field). Every row is proven by the named mounted-DOM test in src/families/form/search-field/search-field.test.ts; a row without a passing test is a contract violation.

#	State	Input	Outcome	Proven by
S1	editable, native	render	`role="search"` root, native searchbox, deterministic input/clear ids, search keyboard hints, form attributes, and invalid ARIA state	`renders a named native searchbox with root landmark and accessibility attributes`
S2	uncontrolled	input / change/search	value follows the native element; emits `update:modelValue` before `input`, `change`, and `search`	`uncontrolled search field emits model before input, change, and search`
S3	controlled	native input	emits the request; the rendered value reverts to `modelValue` until the parent accepts the update	`controlled search value wins until the parent accepts the request`
S4	uncontrolled, seeded	form reset	`defaultValue` seeds the initial value and form reset restores it without request-global state	`defaultValue seeds state and native form reset restores it`
S5	clearable	default clear button	default clear emits `update:modelValue` before `clear`, empties the field, and returns focus to the searchbox	`clear button updates before clear event and returns focus to the searchbox`
S6	unavailable	render / Tab	clear availability and focus follow empty, disabled, and readonly state while preserving native input semantics	`clear visibility and availability follow empty, disabled, and readonly state`
S7	composing	IME composition	native text is not rewritten during composition; real `CompositionEvent` payloads are emitted and reconciliation happens afterward	`tracks IME composition without rewriting controlled native text`
S8	uncontrolled	exposed methods	`setValue()`, `clear()`, `select()`, `focus()`, and `reset()` update the native searchbox without bundled CSS	`exposes value mutation, clear, selection, focus, and reset controls`

The subpath remains tree-shakable and retains no packaged CSS; those package contracts are pinned by distribution.test.ts, check:size, and check:tree-shaking.