Search Field

Search Field is a text input for finding things, with a search icon, a clear button and optional shortcut hint. Use it to search or filter a library, a list of spaces or a command menu.

  • Beta
  • Accessibility
  • Figma Command Menu Search Input 82:6468 · Search your library 2801:75614
  • packages/ui/src/components/SearchField

Beta until design confirms the 48px height (Figma's search is 52), the Sub-300 border (Figma Soft-200) and the clear button's focus ring.

Preview

Type, then press Enter to search or Escape to clear. The code follows the controls.

tsx
const [query, setQuery] = useState("")

<SearchField
  aria-label="Search your library"
  placeholder="Search your library"
  shape="pill"
  value={query}
  onValueChange={setQuery}
  onSearch={runSearch}
/>

Installation

Availability

@nuton/ui and @nuton/tokens are private workspace packages and aren't published yet (D4, D12). Inside the Nuton monorepo, add them as workspace dependencies.

bash
pnpm add @nuton/ui @nuton/tokens @remixicon/react
tsx
import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

Usage

tsx
import { SearchField } from '@nuton/ui'

const [query, setQuery] = useState('')

<SearchField
  aria-label="Search your library"
  placeholder="Search your library"
  shape="pill"
  value={query}
  onValueChange={setQuery}
  onSearch={runSearch}
/>
  • Always give it a name: aria-label, aria-labelledby or a Field label. A placeholder is not a name. Without one, the field is named "Search" (labels.search).
  • Use onValueChange to filter as people type, or onSearch (Enter) when each search is expensive.
  • Wrap a page's main search in <search> or role="search" so it is a landmark.
  • Announce result counts in a role="status" region near the results.
  • shortcut only shows the hint. Bind the key in your app and pass aria-keyshortcuts.

Variants and sizes

Search Field reuses Input's two sizes and adds a pill shape, used by Figma's page search.

Sizes

Shapes

Shortcut hint

This example binds ⌘K / Ctrl+K on the page, so you can try it.

PartMeasurement
Heightlg 48, sm 36 (Input). Figma's search instances are 52 (code-only choice)
Radiusdefault: 16 (lg) / 8 (sm); pill: full (Figma "Search your library")
Inset · gap16 (lg) / 12 (sm) · 8 (Input, P1). Figma 20 · 8
Search icon24 (lg) / 20 (sm), search-2-line. Figma 20
TextParagraph/Small 14; placeholder Text/Sub-600 (C1)
Clear button20px close icon in a 24 × 24 target
ShortcutKbd: padding 2/6, radius 4, Subheading/2X Small

States and interactions

DefaultEmpty: icon Soft-400, placeholder Sub-600. No clear button.
HoverBg/Weak-50 and a Strong-950 border (Input).
FilledThe clear button appears. Focus turns the search icon State/Primary/Base (Figma Active).
InvalidError border and halo. Pair with a Field error message.
DisabledWeak-50 fill, no border, no clear button.

Figma differences (pending a decision)

  • Figma's page search is 52 tall with a Soft-200 stroke and 20px insets. Code keeps Input's 48, Sub-300 border and P1 insets so search lines up with other fields.
  • Figma has no focus ring on the clear button; code adds one.
  • Figma shows an info icon in the Command Menu input. It is not part of Search Field; add a Tooltip button next to the field if needed.

Composition examples

Filter the library as you type

Inside a Field

Press Enter to search, Escape to clear.

API reference

Props

Search Field props
PropTypeDefaultDescription
value · defaultValuestring—Controlled or uncontrolled text.
onValueChange(value: string) => void—Called on every change, and with "" when cleared.
onSearch(value: string) => void—Called with the text on Enter.
onClear() => void—Called after the clear button or Escape empties the field.
size'sm' | 'lg''lg'Input sizes: 36 or 48 tall.
shape'default' | 'pill''default'pill = fully rounded (Figma page search).
shortcutReactNode—Shortcut hint in a Kbd, e.g. "⌘K". Visual only.
iconReactNode—Replaces the search icon. Decorative.
labels{ search?: string; clear?: string }{ search: 'Search', clear: 'Clear search' }Fallback name and the clear button name.
invalidboolean—Error styling. Inside a Field, comes from error.
disabled · readOnlyboolean—Both hide the clear button.
…input propsInputHTMLAttributes—aria-label, placeholder, name, aria-keyshortcuts and others go to the <input type="search">. The ref points at it.

Accessibility

Keyboard

KeyBehaviour
EnterRuns onSearch with the current text
EscapeClears the text. When already empty, Escape passes through (e.g. to close a dialog)
TabMoves to the clear button when there is text, then on

Screen readers

A native searchbox named by its label. The clear button is named "Clear search" and controls the input. Icons and the shortcut chip are hidden; aria-keyshortcuts announces the shortcut.

Focus

The field shows Input's focus halo. Clearing with the button moves focus back to the input, so it is never lost.

Contrast and colour

Text Strong-950 and placeholder Sub-600 (6.7:1), not Figma's Soft-400 (C1). The empty search icon is decorative.

Touch and pointer

The field is 36 or 48 tall; the clear button target is 24 × 24 (WCAG 2.5.8).

You must: name the field, announce result counts, and bind any shortcut you show.

Figma mapping

Figma propertyFigma valuesCode
StateDefault · Hover · ActiveInteractive states; Active = focused with text
ShortcutBooleanshortcut
ButtonInfo icon (empty) · close button (Active)Clear button when there is text; info icon not included
Instance radius 2000Library and Spaces searchshape="pill"

Guidelines and related components

Use Search Field for

  • Searching or filtering a library, spaces or lessons
  • The input at the top of a command menu

Don't use Search Field for

  • Choosing one value from a known list (use Combobox or Select)
  • Ordinary text entry (use Input)

Do and don't

DoName the field with what it searches “Search your library” tells people, and screen readers, the scope.
Don'tRely on the placeholder as the only label Placeholders disappear when typing and are not reliable names.