PixelDropdown

Button-triggered menu of actions with keyboard navigation, typeahead, and a compositional API for advanced layouts.

Dual API: declarative items[] sugar and compositional Root/Trigger/Content/Item parts.
Item kinds: item, separator, header, checkbox, radio, submenu (chevron affordance).
Full keyboard support: arrow navigation, Home/End, Enter/Space activation, printable-key typeahead.
Tones + destructive styling, optional shortcut kbd badges, and disabled rows skipped by focus.
Pixel and linear surfaces honored across trigger, menu, separators, and shortcut chips.

Status: stable
Category: overlays
Since: v1.0.0

import { PixelDropdown } from '@pxlkit/ui-kit';

Prop	Type	Default	Description
`label`	`string`	—	Trigger button label (legacy items[] API).
`items`	`DropdownOption[]`	—	Items to render (legacy items[] API).
`onSelect`	`(value: string) => void`	—	Called with the selected item's `value` (legacy items[] API).
`tone`	`'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink' \| 'neutral'`	`'neutral'`	Trigger tone.
`icon`	`React.ReactNode`	—	Optional icon at the right side of the trigger button. Defaults to a chevron.
`disabled`	`boolean`	`false`	Disables the trigger button.
`surface`	`'pixel' \| 'linear'`	—	Visual surface override. Falls back to nearest `<PxlKitProvider>` surface.
`ariaLabel`	`string`	—	ARIA label override when the trigger label is purely decorative.
`children`	`React.ReactNode`	—	When using compositional API, children replace items[] rendering.

ref points to <div>.

PixelDropdown.Root

Prop	Type	Default	Description
`open`	`boolean`	—	Whether the menu is open; leave unset for an uncontrolled menu.
`defaultOpen`	`boolean`	`false`	Initial open state while uncontrolled.
`onOpenChange`	`(open: boolean) => void`	—	Called with every open state the menu asks for (the trigger and its keys, Escape, a press outside, an item).
`surface`	`'pixel' \| 'linear'`	—	Surface override for the trigger and the menu; defaults to the nearest provider.
`children` (required)	`React.ReactNode`	—	The trigger and the menu (`PixelDropdown.Trigger`, `PixelDropdown.Content`).

PixelDropdown.Trigger

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Button label.
`tone`	`'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink' \| 'neutral'`	`'neutral'`	Button tone.
`icon`	`React.ReactNode`	—	Icon at the end of the button, in place of the chevron.
`disabled`	`boolean`	`false`	Disables the button.
`ariaLabel`	`string`	—	Accessible label, for a label that is only decorative.
`id`	`string`	—	Id of the button, which names the menu; generated when left out.

ref points to <button>.

PixelDropdown.Content

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	The items.
`className`	`string`	—	Extra classes on the menu.

ref points to <div>.

PixelDropdown.Item

Prop	Type	Default	Description
`value`	`string`	—	Item identity for highlight/typeahead registration (NOT the HTML form `value`).
`children` (required)	`React.ReactNode`	—	Label.
`onSelect`	`() => void`	—	Selection callback (NOT the DOM `select` event).
`disabled`	`boolean`	`false`	Skipped by the keyboard and ignores the pointer.
`destructive`	`boolean`	`false`	Visually marks the row red; equivalent to `tone="red"`.
`tone`	`'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink' \| 'neutral'`	—	Text tone.
`icon`	`React.ReactNode`	—	Icon before the label (plain items).
`shortcut`	`string`	—	Keyboard hint shown at the end of the row (display only).

Also takes the native attributes and event handlers of <button> (ButtonHTMLAttributes<HTMLButtonElement>).

ref points to <button>.

PixelDropdown.Separator

No props of its own.

PixelDropdown.Header

Prop	Type	Default	Description
`children` (required)	`React.ReactNode`	—	Text of the header row.

PixelDropdown.CheckboxItem

Prop	Type	Default	Description
`checked`	`boolean`	—	Shows the check mark, and sets `aria-checked`.
`children` (required)	`React.ReactNode`	—	Label.
`onSelect`	`() => void`	—	Selection callback (NOT the DOM `select` event).
`value`	`string`	—	Item identity for highlight/typeahead registration (NOT the HTML form `value`).
`disabled`	`boolean`	—	Skipped by the keyboard and ignores the pointer.
`tone`	`'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink' \| 'neutral'`	—	Text tone.
`destructive`	`boolean`	—	Visually marks the row red; equivalent to `tone="red"`.
`shortcut`	`string`	—	Keyboard hint shown at the end of the row (display only).

Also takes the native attributes and event handlers of <button> (ButtonHTMLAttributes<HTMLButtonElement>), except icon.

ref points to <button>.

PixelDropdown.RadioItem

Prop	Type	Default	Description
`checked`	`boolean`	—	Shows the dot, and sets `aria-checked`.
`children` (required)	`React.ReactNode`	—	Label.
`onSelect`	`() => void`	—	Selection callback (NOT the DOM `select` event).
`value`	`string`	—	Item identity for highlight/typeahead registration (NOT the HTML form `value`).
`disabled`	`boolean`	—	Skipped by the keyboard and ignores the pointer.
`tone`	`'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink' \| 'neutral'`	—	Text tone.
`destructive`	`boolean`	—	Visually marks the row red; equivalent to `tone="red"`.
`shortcut`	`string`	—	Keyboard hint shown at the end of the row (display only).

Also takes the native attributes and event handlers of <button> (ButtonHTMLAttributes<HTMLButtonElement>), except icon.

ref points to <button>.

WCAG target: 2.1 AA

menu
button

Trigger exposes aria-haspopup="menu", aria-expanded, and aria-controls wired to the menu id while the menu is open, and names the menu through aria-labelledby (its own id, or a generated one). The open menu takes focus (tabindex="-1") and points aria-activedescendant at the highlighted item, so assistive technology follows the arrows, Home/End and typeahead. Items use role="menuitem" — menuitemcheckbox and menuitemradio with aria-checked for checkbox and radio rows — with aria-disabled for skipped rows. Separators use role="separator"; headers are role="presentation". Escape, choosing an item and Tab return focus to the trigger; a press outside closes the menu and leaves focus where the pointer put it.

Keyboard

Key	Action	When
`Enter / Space`	Open the menu and move focus into it.	trigger focused
`ArrowDown`	Open the menu with focus in it, highlighting the first enabled item.	trigger focused
`ArrowUp`	Open the menu with focus in it, highlighting the last enabled item.	trigger focused
`ArrowDown`	Highlight the next enabled item; stops at the last.	menu open
`ArrowUp`	Highlight the previous enabled item; stops at the first.	menu open
`Home`	Highlight the first enabled item.	menu open
`End`	Highlight the last enabled item.	menu open
`Enter`	Activate the highlighted item, close the menu and return focus to the trigger.	menu open
`Space`	Activate the highlighted item, close the menu and return focus to the trigger.	menu open
`Escape`	Close the menu, clear the highlight and return focus to the trigger.	menu open
`Tab`	Close the menu and move focus on from the trigger to the next focusable element.	menu open
`Shift+Tab`	Close the menu and move focus back from the trigger to the previous focusable element.	menu open
`a-z / 0-9`	Typeahead — jump to the first item whose label starts with the typed prefix.	menu open

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelDropdown
      label="Actions"
      items={[
        { value: 'edit', label: 'Edit' },
        { value: 'duplicate', label: 'Duplicate' },
        { value: 'archive', label: 'Archive' },
      ]}
      onSelect={() => {}}
    />
  );
}

Examples

Default

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelDropdown
      label="Actions"
      items={[
        { value: 'edit', label: 'Edit' },
        { value: 'duplicate', label: 'Duplicate' },
        { value: 'archive', label: 'Archive' },
      ]}
      onSelect={() => {}}
    />
  );
}

Tones

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Tones() {
  return (
    <div className="flex flex-wrap items-start gap-4">
      <PixelDropdown
        label="Neutral"
        tone="neutral"
        items={[{ value: 'a', label: 'Option A' }]}
      />
      <PixelDropdown
        label="Cyan"
        tone="cyan"
        items={[{ value: 'a', label: 'Option A' }]}
      />
      <PixelDropdown
        label="Green"
        tone="green"
        items={[{ value: 'a', label: 'Option A' }]}
      />
      <PixelDropdown
        label="Red"
        tone="red"
        items={[{ value: 'a', label: 'Option A' }]}
      />
    </div>
  );
}

Surfaces

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Surfaces() {
  return (
    <div className="flex flex-wrap items-start gap-4">
      <PixelDropdown
        label="Pixel"
        surface="pixel"
        items={[
          { value: 'one', label: 'First' },
          { value: 'two', label: 'Second' },
        ]}
      />
      <PixelDropdown
        label="Linear"
        surface="linear"
        items={[
          { value: 'one', label: 'First' },
          { value: 'two', label: 'Second' },
        ]}
      />
    </div>
  );
}

Disabled trigger

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Disabled() {
  return (
    <PixelDropdown
      label="Unavailable"
      disabled
      items={[{ value: 'a', label: 'Option A' }]}
    />
  );
}

Shortcuts

import { PixelDropdown } from '@pxlkit/ui-kit';

export function WithIconsAndShortcuts() {
  return (
    <PixelDropdown
      label="File"
      items={[
        { value: 'new', label: 'New', shortcut: 'Ctrl+N' },
        { value: 'open', label: 'Open…', shortcut: 'Ctrl+O' },
        { value: 'save', label: 'Save', shortcut: 'Ctrl+S' },
      ]}
      onSelect={() => {}}
    />
  );
}

Headers + separators

import { PixelDropdown } from '@pxlkit/ui-kit';

export function HeadersAndSeparators() {
  return (
    <PixelDropdown
      label="Account"
      items={[
        { value: 'h1', label: 'Profile', kind: 'header' },
        { value: 'view', label: 'View profile' },
        { value: 'edit', label: 'Edit profile' },
        { value: 'sep1', label: '', kind: 'separator' },
        { value: 'h2', label: 'Danger Zone', kind: 'header' },
        { value: 'delete', label: 'Delete account', tone: 'red' },
      ]}
      onSelect={() => {}}
    />
  );
}

Checkbox + radio items

import { PixelDropdown } from '@pxlkit/ui-kit';

export function CheckboxAndRadio() {
  return (
    <PixelDropdown
      label="View"
      items={[
        { value: 'g1', label: 'Show', kind: 'header' },
        { value: 'grid', label: 'Grid lines', kind: 'checkbox', checked: true },
        { value: 'ruler', label: 'Ruler', kind: 'checkbox', checked: false },
        { value: 'sep', label: '', kind: 'separator' },
        { value: 'g2', label: 'Density', kind: 'header' },
        { value: 'compact', label: 'Compact', kind: 'radio', checked: false },
        { value: 'cozy', label: 'Cozy', kind: 'radio', checked: true },
        { value: 'spacious', label: 'Spacious', kind: 'radio', checked: false },
      ]}
      onSelect={() => {}}
    />
  );
}

Disabled items

import { PixelDropdown } from '@pxlkit/ui-kit';

export function DisabledItems() {
  return (
    <PixelDropdown
      label="Edit"
      items={[
        { value: 'undo', label: 'Undo', shortcut: 'Ctrl+Z' },
        { value: 'redo', label: 'Redo', shortcut: 'Ctrl+Y', disabled: true },
        { value: 'sep', label: '', kind: 'separator' },
        { value: 'cut', label: 'Cut' },
        { value: 'copy', label: 'Copy' },
        { value: 'paste', label: 'Paste', disabled: true },
      ]}
      onSelect={() => {}}
    />
  );
}

Compositional API

import { PixelDropdown } from '@pxlkit/ui-kit';

export function Composition() {
  return (
    <PixelDropdown.Root>
      <PixelDropdown.Trigger>Menu</PixelDropdown.Trigger>
      <PixelDropdown.Content>
        <PixelDropdown.Header>Project</PixelDropdown.Header>
        <PixelDropdown.Item value="rename" onSelect={() => {}}>
          Rename
        </PixelDropdown.Item>
        <PixelDropdown.Item value="share" onSelect={() => {}} shortcut="Ctrl+E">
          Share
        </PixelDropdown.Item>
        <PixelDropdown.Separator />
        <PixelDropdown.Item value="delete" onSelect={() => {}} destructive>
          Delete
        </PixelDropdown.Item>
      </PixelDropdown.Content>
    </PixelDropdown.Root>
  );
}

Controlled open

import { useState } from 'react';
import { PixelDropdown } from '@pxlkit/ui-kit';

export function ControlledOpen() {
  const [open, setOpen] = useState(false);
  return (
    <PixelDropdown.Root open={open} onOpenChange={setOpen}>
      <PixelDropdown.Trigger>{open ? 'Close' : 'Open'} menu</PixelDropdown.Trigger>
      <PixelDropdown.Content>
        <PixelDropdown.Item value="one" onSelect={() => {}}>
          One
        </PixelDropdown.Item>
        <PixelDropdown.Item value="two" onSelect={() => {}}>
          Two
        </PixelDropdown.Item>
      </PixelDropdown.Content>
    </PixelDropdown.Root>
  );
}

PixelDropdown

API

PixelDropdown

PixelDropdown.Root

PixelDropdown.Trigger

PixelDropdown.Content

PixelDropdown.Item

PixelDropdown.Separator

PixelDropdown.Header

PixelDropdown.CheckboxItem

PixelDropdown.RadioItem

Accessibility

Keyboard

Usage

Examples

Default

Tones

Surfaces

Disabled trigger

Shortcuts

Headers + separators

Checkbox + radio items

Disabled items

Compositional API

Controlled open

Related