Search
Search input with debounced search callback and clear button
Category: inputs · WCAG 2.2-AA · search, input, filter, form
Sizes
- sm
- md
- lg
States
- empty
- filled
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | — | The controlled value. |
defaultValue | string | '' | The initial value when uncontrolled. |
onValueChange | (value: string) => void | — | Called with the current text on every keystroke. |
onSearch | (value: string) => void | — | Called with the query, debounced, as the user types. |
debounceMs | number | 300 | Debounce delay (ms) before onSearch fires. |
placeholder | string | Search | Placeholder text shown when the field is empty. |
size | 'sm' | 'md' | 'lg' | md | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
label | string | Search | Accessible name for the control. Rendered as a real `<label>` that is **visually hidden** by design — it changes the accessible name, not the visible UI. If you can see it, the component stylesheet did not load (import `@cascivo/react/styles.css` or the per-component CSS). |
disabled | boolean | false | When true, disables the control and removes it from the tab order. |
clearLabel | string | Clear search | Accessible label for the clear button. |
id | string | — | Id for the input, wired to the label. Auto-generated with useId when omitted — SSR-safe and stable across hydration. |
className | string | — | Additional CSS class names merged onto the root element. |
aria-labelledby | string | — | Wired automatically by a wrapping `Field` — its label id, forwarded to the focusable control so the Field's label names it. |
aria-describedby | string | — | Wired automatically by a wrapping `Field` — the ids of its hint/error text, forwarded to the focusable control so the supporting text is announced. |
aria-invalid | boolean | — | Wired automatically by a wrapping `Field` when it is in an error state. |
ariaLabel | string | — | Accessible name set through `aria-label` instead of a rendered `<label>` element. ⚠ On Search **both** props give an invisible name — `label` renders a real `<label>` the stylesheet visually hides. They differ in mechanism, not in what you see: use `ariaLabel` when a visible element outside the component already names the field, `label` otherwise. The raw DOM `aria-label` still wins over this. |
Design tokens
--cascivo-color-surface--cascivo-color-border--cascivo-color-border-strong--cascivo-color-accent--cascivo-color-text--cascivo-color-text-muted--cascivo-color-bg-subtle--cascivo-radius-input--cascivo-focus-ring--cascivo-search-width
When to use
- A query field that filters or searches content, with a built-in clear button and debounced onSearch
- Free-text search where results update as the user types (debounced) or on Enter
When not to use
- General non-search text entry — use Input
- Search that presents an inline list of suggestions/results to pick from — use Combobox
- A bounded numeric value — use NumberInput
How to build an accessible Search in React →
Examples
Basic
<Search onSearch={(q) => runQuery(q)} />Controlled
<Search value={query} onValueChange={setQuery} onSearch={runQuery} debounceMs={500} />Large
<Search size="lg" placeholder="Search products…" />