Dropdown menu

OverviewCopy Anchor Link

An independent dropdown with nested actions, checkboxes, keyboard navigation, and interruptible motion. Change its appearance and behavior through typed arguments, or let an agent supply those arguments at runtime.

Use it for a short list of commands behind a button: file actions, row actions, or view settings. For choosing a form value, use a select instead.

InstallationCopy Anchor Link

Uthereal UI is currently a private source package. From a checkout of this repository, create a package archive:

npm pack

Install that archive in your React application:

npm install /path/to/uthereal-ui-0.1.0.tgz

Use React 19.2.3 or later and a bundler that handles TypeScript and CSS Modules, such as Next.js or Vite. The package installs Zag, Motion, and Zod as dependencies. Component styles are imported with the component.

UsageCopy Anchor Link

import { DropdownMenu } from '@uthereal/ui/dropdown-menu'

export function FileActions() {
  return (
    <DropdownMenu
      label="Actions"
      items={[
        { kind: 'action', id: 'rename', label: 'Rename', action: 'rename' },
        {
          kind: 'action',
          id: 'duplicate',
          label: 'Duplicate',
          action: 'duplicate',
        },
        { kind: 'separator', id: 'separator' },
        {
          kind: 'checkbox',
          id: 'preview',
          label: 'Show preview',
          defaultChecked: true,
        },
      ]}
      onAction={(action, itemId) => console.log(action, itemId)}
    />
  )
}

The component emits named actions. Your application implements what those actions do.

ExamplesCopy Anchor Link

Nested actionsCopy Anchor Link

A submenu is an item with its own items array. Item IDs must be unique across the whole menu.

const items = [
  {
    kind: 'submenu',
    id: 'export',
    label: 'Export',
    items: [
      { kind: 'action', id: 'pdf', label: 'PDF document', action: 'exportPdf' },
      {
        kind: 'action',
        id: 'csv',
        label: 'CSV spreadsheet',
        action: 'exportCsv',
      },
    ],
  },
] satisfies import('@uthereal/ui').MenuItem[]

Controlled stateCopy Anchor Link

Keep checkbox selections in your application when they must survive a remount. Omit these props to let the component manage its own state.

const [checked, setChecked] = useState({ preview: true })

<DropdownMenu
  items={items}
  checked={checked}
  onCheckedChange={setChecked}
/>

API referenceCopy Anchor Link

These serializable arguments and defaults come directly from the component schema.

React integrationCopy Anchor Link

Keyboard & accessibilityCopy Anchor Link

Zag supplies focus management, menu semantics, typeahead, and collision handling. Disabled items are skipped. Use clear labels for destructive actions; color alone does not communicate their effect.

MotionCopy Anchor Link

subtle is the default. expressive adds a more pronounced spring; none removes animation. Pointer highlights animate between items, while keyboard highlights respond immediately. System reduced-motion preferences always take precedence.

Override individual settings while retaining the preset's remaining defaults:

<DropdownMenu
  items={items}
  motion="expressive"
  motionOptions={{
    transition: { type: 'spring', damping: 38 },
    enter: { offset: 6 },
    chevronDuration: 180,
  }}
/>

All durations are milliseconds. Explore the motion controls and complete reference.

ThemingCopy Anchor Link

Choose light or dark mode, an accent, and optional design tokens. The same typed settings apply to the trigger and every portalled submenu, and are available to agents.

<DropdownMenu
  items={items}
  theme={{
    mode: 'dark',
    accent: 'violet',
    tokens: { popupRadius: 8, fontSize: 14, itemHeight: 36 },
  }}
/>

Recipe and size supply defaults for omitted tokens. Geometry uses pixels. Explore all 30 tokens in the theming reference, or open Customize in the preview above. Appearance edits preserve existing checkbox selections and open-menu state.