SearchField

Tier: client

ImportCopy Anchor Link

import { SearchField } from '@nizivo/react/search-field';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/kbd.css
import '@nizivo/react/css/search-field.css';

Static or interactiveCopy Anchor Link

Client. It always ships its client leaf, which reads its Field through FieldScope and runs the clear button, so a page with a SearchField also loads FieldScope. The server HTML is a native <search> around an <input type="search"> that works before hydration. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

Filtering with no JavaScriptCopy Anchor Link

Put it in a <form method="get"> and give it a name. Enter submits the form, so the query lands in the URL (?q=stoneware); the server page reads it from its search params, filters, and passes it back as defaultValue. The <search> element is already the search landmark, so the form needs no role. In a client app, read onChange (or pass value and onChange) and filter as the user types.

Naming itCopy Anchor Link

Inside a Field, the Field's label names the input. Outside one, pass aria-label or aria-labelledby; with neither, the input is named "Search" (labels.label). The placeholder is not a label.

The shortcutCopy Anchor Link

shortcut="mod+k" draws the keys at the end of the field (⌘K on Apple platforms, Ctrl+K elsewhere, through Kbd and ThemeScript's data-nz-platform) and announces them with aria-keyshortcuts ("Meta+K Control+K"). The hint hides while the field has a value. As with IconButton's shortcut, the app binds the key: listen for it and call focus() on the field's ref. A shared hotkey registry comes in a later release.

Size and statesCopy Anchor Link

40 px at size="md" (Figma's 42 is off the control scale), 32 at sm, 48 at lg. pending turns the magnifier into a spinner while results load; announce the outcome where the results are. Its edge is border/control, not Figma's border/subtle, whose 1.07:1 against the top bar left the field barely visible.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { SearchField } from '@nizivo/react/search-field';

export function SearchFieldExample(): JSX.Element {
  return (
    <form method="get" style={{ maxInlineSize: 360 }}>
      <SearchField name="q" placeholder="Search orders" defaultValue="stoneware" />
    </form>
  );
}

import type { JSX } from 'react';
import { SearchField } from '@nizivo/react/search-field';

export function SearchFieldTopBarExample(): JSX.Element {
  return (
    <header
      style={{
        display: 'flex',
        alignItems: 'center',
        gap: 16,
        paddingBlock: 12,
        paddingInline: 16,
        background: 'var(--nz-bg-canvas)',
      }}
    >
      <form method="get" style={{ flex: '0 1 360px', minInlineSize: 0 }}>
        <SearchField
          name="q"
          placeholder="Search orders, products, customers"
          shortcut="mod+k"
          labels={{ label: 'Search the store' }}
        />
      </form>
    </header>
  );
}

import type { JSX } from 'react';
import { SearchField } from '@nizivo/react/search-field';

export function SearchFieldStatesExample(): JSX.Element {
  return (
    <div style={{ display: 'grid', gap: 12, maxInlineSize: 360 }}>
      <SearchField size="sm" aria-label="Search, small" placeholder="Small" />
      <SearchField aria-label="Search, medium" placeholder="Medium" />
      <SearchField size="lg" aria-label="Search, large" placeholder="Large" />
      <SearchField aria-label="Search customers" defaultValue="anna" pending />
      <SearchField aria-label="Search archived orders" placeholder="Archived orders" disabled />
    </div>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { SearchField } from '@nizivo/react/search-field';

export function SearchFieldFieldExample(): JSX.Element {
  return (
    <div style={{ display: 'grid', gap: 16, maxInlineSize: 360 }}>
      <Field label="Find a product" description="By title, SKU or barcode.">
        <SearchField name="product" placeholder="e.g. Stoneware mug" />
      </Field>
      <Field label="Order number" error="Enter at least three characters.">
        <SearchField name="order" defaultValue="10" />
      </Field>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

SearchFieldLabels type

import type { SearchFieldLabels } from '@nizivo/react/search-field'

SearchField's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
clearrequired	string	'Clear search'	The clear button's name.
labelrequired	string	'Search'	The input's name when nothing else names it: no Field, aria-label or aria-labelledby. The placeholder is not a label.

SearchFieldProps type

import type { SearchFieldProps } from '@nizivo/react/search-field'

The props of SearchField, listed above.

SearchFieldState type

import type { SearchFieldState } from '@nizivo/react/search-field'

The render state of SearchField, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-glyph-spinner, .nz-search-field, .nz-search-field-clear, .nz-search-field-control, .nz-search-field-icon, .nz-search-field-shortcut.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• search-field: draws the outline when the field inside it has focus.

KeyboardCopy Anchor Link

Source: a native <input type="search"> (search-field.client.tsx); its keydown handler clears on Escape in every engine (Firefox has no native clear), and the clear button empties the field through the native value setter and an input event, so onChange reports it. The browser lane (test/browser/search-field.spec.tsx) checks the clear button, Escape, GET submission, form.reset(), the focus outline and inline validation.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:14764
• Ghost masters: Figma node 755:888