DropdownButton

Preview

Installation

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

pnpm dlx @oshon-ai/cli add dropdownbutton

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

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

<DropdownPlayground />

<FeatureSelectedSort />

<FeatureToggleView />

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.

<DropdownButton
  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-20

Do / Don't

<ButtonHug onClick={handleSave}>Save</ButtonHug>

// Phase 4a consumers: Button is still exported as an alias for ButtonHug.
import { Button } from '@oshon-ai/components';
<Button>Save</Button>

<ButtonFill onClick={subscribe}>Subscribe</ButtonFill>

<ButtonDropdown ariaHasPopup="menu" onClick={openMenu}>Actions</ButtonDropdown>

<ButtonHug className="bg-blue-600">Save</ButtonHug>

<ButtonIconOnly icon={<BellIcon />} />

<div role="button" onClick={fn}>Save</div>

<ButtonDropdown>{isOpen && <Menu />}</ButtonDropdown>

Related

• @oshon-ai/primitives/button
• Popover
• Select
• Tooltip

Design rationale

Phase 4b fan-out from the 4a Button template per ADR-002. The shared `button-shared.tsx` module is the single source of truth for the size scale + filled surface + spinner + chevron; each variant file differs only in layout (w-full, square, two halves) and slot contract (children optional vs. required). Keeping one manifest for the family — rather than one per variant — matches the mental model consumers have ("it's all Button") and avoids 90%-duplicated manifest documents. File-level variant split is what gives tree-shaking its win; manifest-level unification is what gives docs their coherence.