Default
Show the codeHide the code
Default, code
<SearchField label="Search projects" placeholder="Project name or owner" />SearchField
A search box with a 44px clear button. Enter submits; Esc clears.
- Free core, MIT
- Version 2.0.0-rc.1
- APG pattern: Searchbox
Examples
These are the real React components. Use them with a mouse, touch or keyboard, and switch the theme and density for every example at once.
With a value
Show the codeHide the code
With a value, code
<SearchField label="Search projects" defaultValue="Northwind" />Hidden label
Show the codeHide the code
Hidden label, code
<SearchField label="Search projects" hideLabel placeholder="Search projects" />Invalid
Show the codeHide the code
Invalid, code
<SearchField
label="Search projects"
isInvalid
errorMessage="Enter at least 2 characters"
defaultValue="a"
/>Disabled
Show the codeHide the code
Disabled, code
<SearchField label="Search projects" isDisabled />With a shortcut
Show the codeHide the code
With a shortcut, code
<SearchField label="Search projects" shortcut="Control+K" placeholder="Search projects" />With a trailing action
Show the codeHide the code
With a trailing action, code
<SearchField
label="Search projects"
placeholder="Search projects"
trailing={<IconButton icon={SlidersHorizontal} label="Filters" variant="ghost" />}
/>With Cancel
Show the codeHide the code
With Cancel, code
<SearchField label="Search projects" defaultValue="Northwind" onCancel={() => {}} />Long placeholder
Show the codeHide the code
Long placeholder, code
<SearchField
label="Search projects"
placeholder="Search by project name, owner, tag or the date it was last changed"
/>Tokens
The 7 design tokens SearchField reads, with the value each has in the theme and density chosen above. Change a token and the component follows, in Figma and in code.
Show all 7 tokens
| Token | Value now | CSS variable |
|---|---|---|
| color.bg.muted | … | --sd-color-bg-muted |
| color.bg.subtle | … | --sd-color-bg-subtle |
| color.icon.default | … | --sd-color-icon-default |
| input.height | … | --sd-input-height |
| input.radius | … | --sd-input-radius |
| spacing.gap.sm | … | --sd-spacing-gap-sm |
| target.min | … | --sd-target-min |
Install
The npm package isn’t published yet. When it is, this is the install line; until then, this page runs the same build of the package (from commit fa3abf8).
Install
npm i @superduperui/react @superduperui/tokensImport
import { SearchField } from "@superduperui/react"Props
SearchField also takes the props of the React Aria component it’s built on.
| Prop | Type | What it does |
|---|---|---|
labelrequired | string | Visible label (required). Use hideLabel when a heading or the page already names the search. |
hint | string | |
errorMessage | string | ((validation: ValidationResult) => string) | |
placeholder | string | |
hideLabel | boolean | |
shortcut | string | The keyboard shortcut that focuses the field, in aria-keyshortcuts form ("Meta+K", "Control+K", "/"). It is shown as Kbd keys while the field is empty and announced through aria-keyshortcuts. SearchField binds it on the document only when it has a Control, Meta or Alt modifier (WCAG 2.1.4): bind a character-only shortcut yourself, with a way to turn it off. |
onCancel | () => void | Shows a Cancel button after the field (mobile search): it empties the field, then calls onCancel, which closes the search and moves focus. |
cancelLabel | stringDefault 'Cancel' | The Cancel button's text. Default "Cancel". |
trailing | ReactNode | One action at the end of the box (voice, scan, filters): an IconButton, 44px or `size="inline"`. |
When to use it
Use it for
- Searching or filtering a page or list
- Site or app search in a header
Use something else for
- Choosing one value from a known list: use Combobox
- A filter with fixed options: use Select or chips
Accessibility
Screen readers announce "Search projects, search text field"; the clear button "Clear search, button".
WCAG 2.2 AAA criteria the component meets in Comfortable density: 1.4.6, 1.4.9, 2.1.3, 2.3.2, 2.4.13, 2.5.5, 2.5.6.
Compact density meets AA (2.5.8, 24px targets), not AAA.
What your product still has to do
- Announce result counts politely when results update in place
- Give a character-only shortcut (like /) a way to turn it off before you bind it (2.1.4)
Shared patterns it ships with: 1.3.6 (type=search).
This release’s test results
| axe-core (WCAG A, AA, AAA and best practice) | 200 runs across every story, theme, density and width: 0 violations |
|---|---|
| Rendered text contrast | 130 text runs: 0 below 7:1, lowest 8.43:1 |
| Target size | 46 targets: 0 under 44px in Comfortable |
| Focus appearance (2.4.13) | 18 focus stops in 3 browser engines: all pass |
| Keyboard script | Chromium 3 of 3, Firefox 3 of 3, WebKit 3 of 3 |
Manual passes with VoiceOver and NVDA haven’t been done yet.
Keyboard
Each step is scripted and run in Chromium, Firefox and WebKit.
| Key | What happens |
|---|---|
| Tab | Tab reaches the search box |
| Escape | Esc clears it |
| Typing shows the clear button |
In Figma
The Figma component is SearchField, with State (Default, Hover, Focus, Disabled, Invalid); Label visibility (Visible, Hidden); Content (Placeholder, Value); Width (Medium, Small, Fill); Size (Default, Compact). The Figma library isn’t published yet.
Figma to code: State (Default, Hover, Focus, Disabled = isDisabled, Invalid = isInvalid); Label visibility → hideLabel (Visible = false, Hidden = true); Content (Placeholder, Value; preview only); Value → defaultValue; Placeholder → placeholder; Width (Medium, Small, Fill; preview only); Size (Default, Compact; preview only); Trailing → trailing when Show trailing; Show cancel → onCancel; nested Label → label; nested Hint → hint; nested FieldError → errorMessage; nested Shortcut → shortcut; nested Cancel → cancelLabel.