Forms
Search Field
Search Field is a search-specific text field with leading magnifying-glass icon and optional clear action — built on shared text-input control behavior.
State × Size — 12 variants
stableReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-13
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 1.0.0
Known open questions
- No autocomplete, suggestions, or result popover in this phase.
- Escape clears the field when a value is present and showClear is enabled.
Purpose
A text input specialized for search — always includes a leading search icon and an optional clear button once text is entered.
Anatomy
SearchField = FormField + native <input type="search"> + MagnifyingGlass icon + optional clear button (accessible name "Clear search").
Variants and states
default · error · disabled
When to use
Any search/filter input, whether inline in a toolbar or as a page-level search bar.
When not to use
General free-text entry unrelated to searching/filtering — use Text Input. Selecting from a predefined option list — use Combobox.
Accessibility
Uses a native <input type="search">. The icon-only clear control ships with accessible name "Clear search". Escape clears the field when showClear is enabled and a value is present.
Keyboard behavior
Native search input behavior. Escape clears when showClear is enabled and the field has a value. Clear button is a separate focusable control.
Common mistakes
Leaving the clear button visible when the field is empty.
Properties
State × Size as variants. Value (text). Show clear icon (boolean).
Search Field vs Text Input with a leading icon
Search Field is the documented Figma component for search/filter use cases. It adds search semantics, the approved icon, and optional clear behavior without duplicating TextInput implementation.
Search Field vs Combobox
Search Field captures a free-form search query string with native search semantics — it is not a constrained option-selection model and does not present selectable suggestions. Combobox connects an editable input to a list of predefined options so users can filter and commit one option value. Use Combobox when selecting from available options; use Search Field when the query itself is the value.
Tokens used
component/radius/controlsemantic/border/defaultsemantic/icon/muted
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Visible field label via FormField. |
| showClear | boolean | true | Shows clear button when value is non-empty. |
| onValueChange | (value: string) => void | — | Controlled value change callback. |
| error | string | — | Validation message rendered through FormField. |
React example
Copy React example
import { SearchField } from "@/components/ui/SearchField";
export function Example() {
return (
<SearchField
label="Search components"
placeholder="Search the design system…"
defaultValue=""
/>
);
}