Dropdown

Preview

Installation

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

pnpm dlx @oshon-ai/cli add dropdown

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 { Dropdown } from '@oshon-ai/components';

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

<BasicField />

<div style={stackCol}>
      <p style={sectionHeading}>Enabled</p>
      <Dropdown label="Label" required tooltip description="Optional Description" options={OPTIONS} placeholder="Select…" />

      <p style={sectionHeading}>Filled</p>
      <Dropdown label="Label" required tooltip description="Optional Description" options={OPTIONS} defaultValue="react" />

      <p style={sectionHeading}>ErrorEmpty</p>
      <Dropdown label="Label" required tooltip error="Mandatory Error Description" options={OPTIONS} placeholder="Select…" />

      <p style={sectionHeading}>ErrorFilled</p>
      <Dropdown label="Label" required tooltip defaultValue="vue" error="Mandatory Error Description" options={OPTIONS} />

      <p style={sectionHeading}>DisabledEmpty</p>
      <Dropdown label="Label" required tooltip description="Optional Description" options={OPTIONS} placeholder="Select…" disabled />

      <p style={sectionHeading}>DisabledFilled</p>
      <Dropdown label="Label" required tooltip description="Optional Description" options={OPTIONS} defaultValue="svelte" disabled />
    </div>

<div style={stackCol}>
      <p style={sectionHeading}>Enabled</p>
      <Dropdown size="mobile" label="Label" required tooltip description="Optional Description" options={OPTIONS} placeholder="Select…" />
      <p style={sectionHeading}>Filled</p>
      <Dropdown size="mobile" label="Label" required tooltip description="Optional Description" options={OPTIONS} defaultValue="react" />
      <p style={sectionHeading}>ErrorFilled</p>
      <Dropdown size="mobile" label="Label" required tooltip defaultValue="vue" error="Mandatory Error Description" options={OPTIONS} />
    </div>

<SizeLadderPlayground />

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.

<Dropdown
  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-05-18

Do / Don't

<Dropdown label="Framework" placeholder="Select…" options={[{value:"react",label:"React"},{value:"vue",label:"Vue"}]} />

<Dropdown label="Region" value={region} onChange={setRegion} options={regions} />

<Dropdown label="Role" required description="Your role in the org." options={roleOptions} />

<Dropdown label="Region" error="Region is required." options={regionOptions} />

<Popover open><Dropdown options={…} /></Popover>

<Dropdown label="X" required aria-invalid />

<Dropdown label="X" description="Help" error="Bad" options={[]} />

<Dropdown options={[{value:"y",label:"Yes"},{value:"n",label:"No"}]} />

Related

• @oshon-ai/components/select
• @oshon-ai/components/menu
• @oshon-ai/components/multi-select
• @oshon-ai/components/text-field
• @oshon-ai/components/input

Design rationale

Phase 4e.3 visual fidelity refit, rewritten 2026-05-18 from a native-select wrapper to a real WAI-ARIA Combobox. The trigger doubling as the search input is the most-requested UX from users who hit the native-select wall on lists over ~10 options — typing should narrow the list, not jump character-by-character. Focus stays on the input via `aria-activedescendant`, which is the canonical APG combobox pattern; option clicks intercept mousedown to keep focus on the input across the selection. The chevron is a real `<button>` with `tabIndex=-1` so it never steals tab order. The field visual matches the previous native-select implementation exactly (same border, focus, hover, error tokens) so existing screenshots and Figma references stay accurate. Backward-compatible API: `value` / `defaultValue` / `onChange` keep the same names — `onChange` is now `(value: string) => void` instead of an event since the field is no longer a `<select>`.