SearchField
A field for finding things: a search icon, a clear button once it holds text, and an optional shortcut that focuses it.
import { SearchField } from "@butteryui/react";Demo
When to use it
Use it for
- The app-wide search in a top bar (soft, with a / shortcut)
- Narrowing a table or list from its toolbar (outline)
- A dense toolbar, with size="sm"; a page's own search, with size="lg"
Not for
- A field in a form with a visible label: use TextField
- Picking one value from a known list: use Select
Examples
Filter list
A toolbar search that narrows a list as you type.
5 of 5 origins
Recent searches
A search whose text the page keeps in state, so a recent search can fill it in and the clear button empties it.
Recent
5 of 5 customers
Soft and outline
Soft for a top bar's search, with its / shortcut, and a small outline one for a toolbar's filter; Enter sends either.
Nothing searched yet
Top bar search
A top bar's search, soft and focused from anywhere with /, with the orders it finds listed under the bar.
3 open orders
Ethiopia Guji
Colombia Huila
Ethiopia Guji
Variants and states
Soft and outline
Soft on bg-control for a top bar, its edge showing on hover and focus; outlined for a toolbar. Type to see the clear button; Escape clears too.
Disabled
Sizes
28px for a dense toolbar, its clear button drawn at the badge height with a 28px target; 34px by default; 48px with 16px text for a page's own search.
Props
SearchField
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | "Search" | Names the field for screen readers, and shows as its placeholder unless there's one. Defaults to "Search". |
value | string | The text. Pair with onValueChange to control it. | |
defaultValue | string | The starting text when uncontrolled. | |
onValueChange | ((value: string) => void) | Called with the text on every change, and with "" when it's cleared. | |
variant | "outline" | "soft" | "outline" | "outline" (the default) with a 1px edge, as in a table's toolbar, or "soft" on bg-control, its edge
showing only on hover and while it has focus, as in a top bar. |
size | "sm" | "md" | "lg" | "md" | The field's height: "md" (34px, 30 compact, the default), "sm" (28px) for a dense toolbar, or "lg"
(48px, 40 compact, with 16px text) for a page's own search. |
shortcut | Shortcut | A key that focuses the field from anywhere outside a text field, written as useShortcut takes it, such as "/". It shows while the field is empty. | |
clearLabel | string | "Clear search" | Names the clear button. Defaults to "Clear search". |
It also takes Omit<ComponentPropsWithRef<"input">, "size" | "value" | "defaultValue" | "children" | "type">.
Accessibility
A searchbox named by its label (Search by default), which is also its placeholder. The clear button is named Clear search; Escape clears the text and keeps focus. A shortcut is announced through aria-keyshortcuts, and its keycap is hidden from screen readers.
| Keys | What they do |
|---|---|
| Escape | Clears the text, keeping focus in the field |
| Tab | Moves from the field to its clear button, once it holds text |
| Enter or Space | Clears the text from the clear button and puts focus back in the field |
| Its shortcut, such as / | Focuses the field from anywhere outside a text field |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its container's width (in an Inline, the room its siblings leave) and is 34px tall (--bt-h-control), 28px (--bt-h-sm) at size="sm" or 48px (--bt-h-cta) with 16px text at "lg", with its 16px search icon at the start. At the end sits a 28px clear button once it holds text, drawn at the badge height with a 28px target in a small field, or the shortcut's keycap while it's empty. Text too long for it scrolls inside it and ends in an ellipsis while it doesn't have focus. A press anywhere in the box but the clear button lands in the input.