Search
A search field with a magnifier, a clear button, an optional spinner and an optional keyboard shortcut, with a debounced search callback.
Overview
Search is a type="search" field built for filtering and querying. onValueChange fires on every keystroke; onSearch fires once typing pauses for debounceMs, right away on Enter, and with an empty string when the field is cleared. While loading is set, a spinner takes the place of the clear button.
shortcut shows keycaps while the field is empty and focuses the field when those keys are pressed.
Import
import { Search } from '@unflowio/ui/components/Search';Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | Controlled value |
defaultValue | string | '' | Initial value when uncontrolled |
onValueChange | (value: string) => void | — | Fired on every keystroke and when the field is cleared |
onSearch | (value: string) => void | — | Fired with the query once typing pauses for debounceMs, on Enter, and when cleared |
debounceMs | number | 250 | Delay before onSearch runs while typing. 0 runs it on every keystroke |
placeholder | string | 'Search' (translated) | Placeholder text |
label | string | the placeholder | Accessible name |
loading | boolean | — | Shows a spinner in place of the clear button |
shortcut | string[] | — | Keys that focus the field, shown as keycaps while it is empty (e.g. ['Mod', 'k']) |
listenShortcut | boolean | true | Set to false to show the shortcut keycaps without listening for them |
variant | 'outlined' | 'plain' | 'outlined' | plain drops the border and background, for toolbars and headers |
size | 'sm' | 'md' | 'md' | Field height and text size |
fullWidth | boolean | false | Stretches to fill the container |
disabled | boolean | — | Disables the field |
Other native input props (name, autoFocus, onKeyDown, ref, …) are passed to the <input>.
Basic usage
Last search: —
const [value, setValue] = useState('');
<Search
placeholder="Search projects"
value={value}
onValueChange={setValue}
onSearch={(query) => fetchResults(query)}
/>Use onValueChange for state that must follow every keystroke (the field itself, client-side filtering) and onSearch for work that should wait until typing pauses, such as a request.
Shortcut
shortcut takes the same key names as Shortcut; Mod is ⌘ on Apple platforms and Ctrl elsewhere. The keycaps show while the field is empty, and pressing the keys focuses it. Set listenShortcut={false} when something else already handles the keys and the keycaps are only a hint. The preview below does that because this site uses ⌘K for its own search.
<Search placeholder="Search" shortcut={['Mod', 'k']} />Variants, sizes and states
<Search size="sm" placeholder="Small" />
<Search placeholder="Plain" variant="plain" />
<Search placeholder="Search people" defaultValue="ana" loading />
<Search placeholder="Full width" fullWidth />
<Search placeholder="Disabled" disabled />Customization (slots & slotProps)
| Slot | Type | Description |
|---|---|---|
icon | ReactNode | Replaces the magnifier |
clearIcon | ReactNode | Replaces the clear button's icon |
startEl | ReactNode | Rendered between the icon and the field, e.g. a mode tag |
| Slot Prop | Props | Description |
|---|---|---|
input | BaseHTMLProps<HTMLInputElement> | The <input> element |
clearButton | Omit<IIconButton, 'icon' | 'onClick'> | The clear icon button |
Accessibility
- Renders a native
<input type="search">, exposed as a searchbox named bylabel, or by the placeholder when there is no label. - Clearing keeps focus in the field and calls
onSearch(''). - The clear button and spinner have translated names ("Clear search", "Searching").