SearchBox
React search field built on TextInput with a magnifier, voice search, a clear button, and Enter to search. Works for live filtering and full search pages.
SearchBox builds on TextInput and adds a magnifier, a voice mic, and a clear button. onSearch fires on Enter.
When to use
Use SearchBox at the top of lists, tables, and service catalogs. Use onSearch for a submitted query and the controlled value for live filtering as the user types. Show the result count nearby so users know the search worked.
For a global command palette, use Command instead.
Examples
Props
Props declared by SearchBox. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "md" | "lg" | ||
variant | "default" | "filled-lighter" | "filled-darker" | ||
label | react.ReactNode | Visible field label, auto-associated to the input via htmlFor/id. | |
helperText | react.ReactNode | Hint shown below the field. Hidden while an error message is showing. | |
helperIcon | react.ReactNode | ||
errorMessage | react.ReactNode | Message shown below the field when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
onSearch | (value: string) => void | Fires on Enter with the current query string. | |
voiceSearch | boolean | Show the SDGA voice-search mic while the field is empty. Default true. | |
onVoiceSearch | (value: string) => void | Fires when the voice-search mic is activated, with the current query. | |
onClear | () => void | Fires when the field is cleared (clear button or Escape). | |
clearable | boolean | Show the clear (×) button while the field has a value. Default true. | |
clearLabel | string | Accessible label for the clear button. Default 'Clear search'. | |
voiceLabel | string | Accessible label for the voice-search mic. Default 'Search by voice'. |
Accessibility
The input keeps a visible label or an aria-label, and the magnifier icon is decorative. Enter runs the search and Escape clears the field. The clear and voice buttons are real buttons with accessible names.
When filtering live, announce the result count in a live region so screen reader users get feedback.