Multiselect

Preview

Installation

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

pnpm dlx @oshon-ai/cli add multiselect

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

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

<InteractivePlayground />

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.

<Multiselect
  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-23

Do / Don't

const [selected, setSelected] = useState<Set<string>>(new Set());
return (
  <MultiSelect
    label="Regions"
    required
    options={[
      { id: 'na', label: 'North America', hasChildren: true },
      { id: 'us', label: 'United States', parent: 'na' },
      { id: 'ca', label: 'Canada', parent: 'na' },
      { id: 'eu', label: 'Europe', hasChildren: true },
      { id: 'uk', label: 'United Kingdom', parent: 'eu' },
    ]}
    selected={selected}
    onChange={setSelected}
    onApply={(next) => commitRegions(next)}
  />
);

<MultiSelect
  triggerVariant="chips"
  options={tags}
  selected={selected}
  onChange={setSelected}
/>

<MultiSelect
  type="page"
  title="Filter by region"
  options={regions}
  selected={selected}
  onChange={setSelected}
/>

<MultiSelect searchable options={tags} selected={selected} onChange={setSelected} />

<MultiSelect selected={new Set(['na'])} ... />

<MultiSelect onChange={(next) => setValue(next.size ? Array.from(next)[0] : null)} />

options={[{ id: 'a', hasChildren: true }, { id: 'b', parent: 'a', hasChildren: true }, { id: 'c', parent: 'b' }]}

Related

• Select
• Menu
• Popover
• Chip

Design rationale

Single component with a `type` prop instead of three (MultiSelectDropdown / MultiSelectPopup / MultiSelectPage) because the Figma source ships them as variants of one design — they share the picker body, the select-all/clear-all row, the footer, and the MultiselectItem spec. Only the chrome around the picker differs (closed field vs title vs wider panel). Making type a prop keeps the API surface small, lets callers switch without rebinding selection state, and means an a11y fix to the listbox semantics lands once for all three. The `triggerVariant: "chips"` escape hatch stacks selected chips below the closed field (Figma FilledChips 2862:32196) without a second component. Data-scale auto-shows the search bar at ≥13 leaves per `DS_SCALE_DEFAULTS.multiSelect.search`; callers force with `searchable`. Selection is controlled (Set<string>) so hosts own the source of truth; Apply/Cancel only emit events — consumers decide whether to discard or commit the live Set.