Search Field | Base Design System

A labelled search input with a leading search icon, Escape to clear, and a clear button.

SearchField is a search input with a leading search icon and a clear button that fades in once there is a value. Escape clears the field, Enter submits it. It shares its label, description, error, and filled styles with Text Field.

Variants

Variant	Use for
`filled` (default)	Search inside a form or panel, matching Text Field
`pill`	A compact, standalone search bar above a list or grid, such as a directory filter

Filled

<SearchField aria-label="Search apps" placeholder="Search" />

Pill

<SearchField variant="pill" aria-label="Search apps" placeholder="Search" />

The pill is 36px tall with a 1px border and no fill, sized for a toolbar row next to filters.

Both variants fill their container's width. Set a width on the container at the breakpoints where you want it narrower; the field never collapses to an icon, so its label stays visible at every width.

Examples

With a value

Apps

<SearchField label="Apps" defaultValue="wallet" placeholder="Search" />

The clear button appears only when the field has a value. It fades in and out over 240ms, and appears and disappears at once when the reader prefers reduced motion. Pressing it clears the value, calls onClear, and returns focus to the input.

With description

Apps

Search by name or category.

<SearchField
label="Apps"
placeholder="Search"
description="Search by name or category."
/>

Invalid

Transaction

Enter a full transaction hash.

<SearchField
label="Transaction"
defaultValue="0x12"
errorMessage="Enter a full transaction hash."
/>

A static errorMessage marks the field invalid and replaces the description.

Optional

FilterOptional

<SearchField label="Filter" isOptional placeholder="Search" />

Disabled

<SearchField label="Disabled" placeholder="Search" isDisabled />

When to use

Use SearchField when the value is a query that filters or finds results, so readers get the search role, Escape to clear, and a clear button.

Use something else when:

The value is free text that is stored, like a name or an address. Use Text Field.
The reader picks from a known set of options. Use Select or Segment.

Usage

Filter results as the reader types when the list is local, and use onSubmit for searches that need a request.

Don't

Rely on the placeholder to name the field. Pass a label, or an aria-label when the context already makes the purpose clear.

Props

Prop	Type	Default
`autoComplete` Describes the type of autocomplete functionality the input should provide if any. See	Type`string`	Default—
`autoCorrect` An attribute that takes as its value a space-separated string that describes what, if any, type	Type`string`	Default—
`className` The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the	Type`ClassNameOrFunction<SearchFieldRenderProps>`	Default—
`defaultValue` The default value (uncontrolled).	Type`string`	Default—
`description` Help text below the field, replaced by `errorMessage` when invalid.	Type`ReactNode`	Default—
`enterKeyHint` An enumerated attribute that defines what action label or icon to preset for the enter key on	Type`"search" \| "enter" \| "done" \| "go" \| "next" \| "previous" \| "send"`	Default—
`errorMessage` Error text shown below the field. A static message marks the field invalid.	Type`ChildrenOrFunction<FieldErrorRenderProps>`	Default—
`inputMode` Hints at the type of data that might be entered by the user while editing the element or its	Type`"text" \| "search" \| "url" \| "tel" \| "email" \| "none" \| "numeric" \| "decimal"`	Default—
`isDisabled` Whether the input is disabled.	Type`boolean`	Default—
`isInvalid` Whether the input value is invalid.	Type`boolean`	Default—
`isOptional` Shows "Optional" on the label row, aligned to the input's end edge.	Type`boolean`	Default—
`isReadOnly` Whether the input can be selected but not changed by the user.	Type`boolean`	Default—
`isRequired` Whether user input is required on the input before form submission.	Type`boolean`	Default—
`label` Visible label above the field. Without one, pass `aria-label`.	Type`ReactNode`	Default—
`maxLength` The maximum number of characters supported by the input. See	Type`number`	Default—
`minLength` The minimum number of characters required by the input. See	Type`number`	Default—
`pattern` Regex pattern that the value of the input must match to be valid. See	Type`string`	Default—
`placeholder`	Type`string`	Default—
`spellCheck` An enumerated attribute that defines whether the element may be checked for spelling errors.	Type`string`	Default—
`type` The type of input to render. See	Type`"text" \| "search" \| "url" \| "tel" \| "email" \| "password" \| (string & {})`	Default`'search'`
`validate` A function that returns an error message if a given value is invalid.	Type`((value: string) => true \| ValidationError \| null)`	Default—
`validationBehavior` Whether to use native HTML form validation to prevent form submission	Type`"native" \| "aria"`	Default`'native'`
`variant` `filled` matches Text Field; `pill` is a compact, rounded, bordered bar with no fill.	Type`"filled" \| "pill" \| null`	Default`filled`

Accessibility

SearchField wraps React Aria's SearchField. The input has the searchbox role and is associated with its label, description, and error message. Escape clears the value and Enter calls onSubmit.

The search icon is decorative and hidden from assistive tech. The clear button is named "Clear search", and it is left out of the tab order because Escape does the same thing from the keyboard. When a field has no visible label, pass aria-label. In development, a SearchField with no label and no aria-label logs a console warning.