DropdownMenu

Dropdown menus group secondary commands behind a compact trigger.

Overview and decision boundary

Use DropdownMenu to group secondary commands behind a compact trigger.

Do not hide the primary page action inside a menu.

1import { Copy, UserPlus, X } from '@nerio-ui/adapters/icons';2import { DropdownMenu } from '@nerio-ui/ui/client';34<DropdownMenu5  trigger="Actions"6  items={[7    { group: "Collaborate", label: "Share workspace", description: "Invite people and choose access", leadingIcon: UserPlus },8    { group: "Collaborate", label: "Duplicate workspace", leadingIcon: Copy },9    { group: "Manage", label: "Archive", leadingIcon: X, destructive: true },10  ]}11/>

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm exec nerio add dropdown-menu23import { Copy, UserPlus, X } from '@nerio-ui/adapters/icons';4import { DropdownMenu } from '@nerio-ui/ui/client';

Usage

1import { Copy, UserPlus, X } from '@nerio-ui/adapters/icons';2import { DropdownMenu } from '@nerio-ui/ui/client';34<DropdownMenu5  trigger="Actions"6  items={[7    { group: "Collaborate", label: "Share workspace", description: "Invite people and choose access", leadingIcon: UserPlus },8    { group: "Collaborate", label: "Duplicate workspace", leadingIcon: Copy },9    { group: "Manage", label: "Archive", leadingIcon: X, destructive: true },10  ]}11/>

Variants

Variant	Purpose
`default`	Default variant using semantic Nerio tokens.
`grouped`	Grouped is part of the public component contract.
`destructive`	Risky action that needs explicit intent.
`description`	Description is part of the public component contract.
`leading icon`	Leading icon is part of the public component contract.
`trailing icon`	Trailing icon is part of the public component contract.
`hotkey`	Hotkey is part of the public component contract.

Anatomy

Slot	Purpose
`content`	Layered menu surface.
`group`	Labeled command cluster separated from adjacent groups.
`group-label`	Group Label slot exposed through data-slot="group-label".
`separator`	Separator slot exposed through data-slot="separator".
`item`	Command row with optional description, group, leading icon, trailing icon, hotkey, and intent.
`leading-icon`	Leading Icon slot exposed through data-slot="leading-icon".
`label`	Label slot exposed through data-slot="label".
`description`	Description slot exposed through data-slot="description".
`hotkey`	Hotkey slot exposed through data-slot="hotkey".
`trailing-icon`	Trailing Icon slot exposed through data-slot="trailing-icon".

States

State	Purpose
`Open`	Items are keyboard navigable.
`Highlighted`	Current item is ready for selection.
`Disabled`	Unavailable items stay in context without activation.

Motion

State changes should use shared motion tokens and preserve reduced-motion behavior.

Accessibility

Uses the Base UI Menu primitive.
Items are keyboard reachable and can be disabled.
Group labels and separators organize related commands without becoming menu items.
Optional descriptions are associated with their menu items through aria-describedby.
Pair the document dir attribute with Base UI DirectionProvider so menu navigation and positioned content follow LTR or RTL.
Disabled items stay visible but cannot be selected.
Use destructive tone only for irreversible or high-risk commands.
Supports controlled open, uncontrolled defaultOpen, onOpenChange, and a forwarded menu popup ref.

Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.

API

Prop	Purpose
`items`	Ordered list of label, description, group, leadingIcon, trailingIcon, hotkey, onSelect, disabled, and destructive values.
`description`	Adds visible supporting context and an accessible description to an item.
`group`	Creates labeled, separated command clusters without custom menu markup.
`disabled item`	Stays visible in context without activation.
`destructive item`	Marks risky commands without changing the whole menu tone.

Implementation contract

Contract	Value
`Registry item`	dropdown-menu installs 8 source files into the configured components directory.
`Base UI`	menu
`Registry dependencies`	button
`Package dependencies`	@base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss

Styling contract

Contract	Value
`Authoring`	`Complete, statically detectable Tailwind CSS v4 recipes own component visuals.`
`Values`	`Semantic and component --n-* variables remain the canonical customization layer.`
`Overrides`	`Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically.`
`Residual CSS`	`Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer.`

Design notes

Use DropdownMenu to group secondary commands behind a compact trigger.

Do / do not

Use for Rename, Duplicate, Archive, and similar secondary commands.

Do not