Skip to content

Search Field

A search input with a leading icon and a clear button; Escape clears and Enter submits.

betaReact AriaSource

Installation

pnpm add @syntara/react @syntara/tokens
import { SearchField } from '@syntara/react';

Usage

import { SearchField } from '@syntara/react';

export function Search() {
  return <SearchField aria-label="Search transactions" placeholder="Search transactions" onSubmit={(q) => search(q)} />;
}

Examples

With label and description

Press Enter to search, Escape to clear.

In a toolbar

Same height as buttons at every density.

Accessibility

KeysAction
EnterCalls onSubmit.
EscapeClears the field (focus stays in the input).
TabMoves focus to the input; the clear button is not a tab stop.
  • The input has role searchbox.
  • The clear button is hidden while the field is empty but keeps its space, so text never shifts.
  • The search icon is decorative (aria-hidden).

Guidelines

Do

  • Say what can be searched in the placeholder or label.
  • Use aria-label only when a visible label would be redundant, e.g. a search above a table.

Don’t

  • Don't hide results behind Enter when filtering a short list; filter on change.
  • Don't put other buttons inside the field; place them beside it.

API reference

SearchField

label
ReactNode

Visible label. Optional; without it, aria-label or aria-labelledby is required (enforced by the type).

aria-label
string

Accessible name when there is no visible label.

description
ReactNode

Help text, linked with aria-describedby.

errorMessage
string | ((validation: ValidationResult) => string)

Shown with an icon when invalid.

placeholder
string

Hint text, e.g. what can be searched.

value / defaultValue
string

Controlled / uncontrolled value.

onChange
(value: string) => void

Called on every edit.

onSubmit
(value: string) => void

Called on Enter.

onClear
() => void

Called when cleared with Escape or the clear button.

clearLabel
string

Accessible name of the clear button. Defaults to React Aria's localized "Clear search".

isDisabled
boolean

Disables the field.

Default false

inputRef
Ref<HTMLInputElement>

Ref to the underlying input.

size
  • sm
  • mddefault
  • lg

Height of the box: md is the density's control height, sm one 8px step shorter, lg two steps taller. Height, corner radius and inline inset match a Button of the same size, so a field and a button in one row line up.

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour9
focus.ringtext.defaulttext.disabledtext.subtleborder.defaultborder.strongsurface.defaultsurface.sunkensurface.canvas
Type2
font.size.smfont.tracking.sm
Space and size6
control-heightspace.1space.2space.4space.6control-padding-inline
Shape1
radius.field
Motion4
motion.duration.fastmotion.duration.springmotion.easingmotion.spring