Search

Preview

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add search

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { Search } from '@oshon-ai/components';

export default function Example() {
  return <Search />;
}

<Search size="m" placeholder="Search" aria-label="Demo search" />

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'flex-start' }}>
      <div key="xs" data-story-size="xs">
        <Search size="xs" placeholder="Search" aria-label="Demo search" />
      </div>
      <div key="s" data-story-size="s">
        <Search size="s" placeholder="Search" aria-label="Demo search" />
      </div>
      <div key="m" data-story-size="m">
        <Search size="m" placeholder="Search" aria-label="Demo search" />
      </div>
      <div key="l" data-story-size="l">
        <Search size="l" placeholder="Search" aria-label="Demo search" />
      </div>
      <div key="mobile" data-story-size="mobile">
        <Search size="mobile" placeholder="Search" aria-label="Demo search" />
      </div>
    </div>

API

Every prop is documented here directly from the component's TypeScript interface. Inherited DOM attributes (aria-*, onClick, style, etc.) work as usual but are omitted from this table.

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<Search
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-04-28

Do / Don't

<Search
  suggestions={[
    { id: '1', label: 'Apple' },
    { id: '2', label: 'Banana' },
  ]}
  onSelectSuggestion={(s) => console.log(s.id)}
/>

<Search type="component" placeholder="Search records" />

<Search
  type="hero"
  segmentedLabel="All"
  onSegmentedClick={() => {}}
  helperText="Search across all product data, queries, and management tools"
  onSubmit={(q) => navigate(`/search?q=${q}`)}
/>

<Search
  size="mobile"
  value={query}
  onValueChange={setQuery}
  placeholder="Search…"
/>

<Search slotClassName={{ field: "border-[#aaaaaa]" }} />

<Search value={query} defaultValue="seed" onValueChange={setQuery} />

<Search open suggestions={[]} />

<div style={{ background: "white" }}><Search type="component" /></div>

Related

• Popup
• Popover
• Input
• TextField
• GlobalToolbar

Design rationale

Search is one of the highest-volume primitives in any product surface, so the design system needs a single component that can land on a form (field), a toolbar (component), or a dashboard (hero) without forking. The Figma source ships three named surfaces; we collapse them into a single `type` prop so the controlled-input + dropdown + clear-button + submit contract is shared. Sizes follow the standard five-axis convention: xs maps to the Component-density 24px / 10pt density (Figma's smallest published surface); s/m map to Field/Desktop 24px / 12pt; l/mobile map to Field/Mobile 34px / 14pt. Hero ignores the size axis for height (its chrome is fixed by Figma at 40×40 CTA + 16/8 inner padding) and only respects size for the helper text. The active-state dropdown intentionally reuses Popup chrome (frosted gray-300 wash + 16px backdrop-blur + drop-shadow-with-inner-highlight) so the same visual language carries across every floating surface in the system. Escape behaviour is two-stage — first press clears the typed value, second press closes the dropdown — matching the Mac OS convention users expect from Safari and Spotlight. The clear button uses `mousedown.preventDefault()` so the input focus returns to the input after the click; without that the click would blur the input and close the dropdown before the clear handler fires.