Components
Dropdown Menu
Menus that execute actions from a trigger.
DropdownMenu displays a list of commands after a trigger is pressed. Use it for actions such as
editing, duplicating, sharing, and deleting. It is not a Select: a menu executes commands, while a
Select chooses a form value.
The component is built on Base UI Menu and exported from @orkest/ui/client. Base UI owns
positioning, collision handling, dismissal, focus management, and keyboard navigation; Orkest UI owns
the visual design and public API.
Basic usage#
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuSeparator,
DropdownMenuShortcut,
DropdownMenuTrigger,
} from '@orkest/ui/client';
import { Archive, Copy, Pencil, Trash2 } from 'lucide-react';
export function Example() {
return (
<DropdownMenu>
<DropdownMenuTrigger>Actions</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem leftIcon={Pencil}>
Edit
<DropdownMenuShortcut>⌘E</DropdownMenuShortcut>
</DropdownMenuItem>
<DropdownMenuItem leftIcon={Copy}>
Duplicate
<DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem disabled leftIcon={Archive}>
Archive
</DropdownMenuItem>
<DropdownMenuItem variant="destructive" leftIcon={Trash2}>
Delete
<DropdownMenuShortcut>⇧⌘⌫</DropdownMenuShortcut>
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
);
}Use disabled to make an item inert. Disabled items keep their place in the menu, cannot be
activated, and use a lower-emphasis foreground color.
Anatomy#
DropdownMenuowns the open state and menu behavior.DropdownMenuTriggeropens the menu. It renders a secondary Button by default.DropdownMenuPortalmoves the menu to the document body.DropdownMenuContentpositions the surface, handles collisions, and scrolls long content.DropdownMenuItemexecutes an action and closes the menu.DropdownMenuGroupgroups related items;DropdownMenuLabelnames the group.DropdownMenuSeparatordivides menu sections.DropdownMenuShortcutrenders a visual keyboard hint at the end of an item.DropdownMenuLinkItemrenders navigation as an anchor.DropdownMenuCheckboxItemtoggles a setting without closing the menu.DropdownMenuRadioGroupandDropdownMenuRadioItemselect one value without closing the menu.DropdownMenuSub,DropdownMenuSubTrigger, andDropdownMenuSubContentbuild nested menus.
Use render on DropdownMenuTrigger when the trigger should be an icon button, an avatar button, or
another custom element:
<DropdownMenuTrigger render={<Button variant="ghost" aria-label="Project actions" />} />Groups, labels, and checkboxes#
import {
DropdownMenu,
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuGroup,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuLinkItem,
DropdownMenuPortal,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from '@orkest/ui/client';
import { Keyboard, Settings } from 'lucide-react';
export function Example() {
return (
<DropdownMenu>
<DropdownMenuTrigger variant="outline">View options</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuGroup>
<DropdownMenuLabel>Panels</DropdownMenuLabel>
<DropdownMenuCheckboxItem defaultChecked>
Show grid
</DropdownMenuCheckboxItem>
<DropdownMenuCheckboxItem>Show ruler</DropdownMenuCheckboxItem>
</DropdownMenuGroup>
<DropdownMenuSeparator />
<DropdownMenuGroup>
<DropdownMenuLabel>Resources</DropdownMenuLabel>
<DropdownMenuItem leftIcon={Settings}>Preferences</DropdownMenuItem>
<DropdownMenuItem leftIcon={Keyboard}>
Keyboard shortcuts
</DropdownMenuItem>
<DropdownMenuLinkItem href="/docs/components/button/">
Button documentation
</DropdownMenuLinkItem>
</DropdownMenuGroup>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
);
}DropdownMenuCheckboxItem supports both checked and defaultChecked, and it keeps the menu open
by default. Pass closeOnClick when a setting should close the menu immediately.
Radio items#
import { useState } from 'react';
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuPortal,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuTrigger,
} from '@orkest/ui/client';
export function Example() {
const [density, setDensity] = useState('comfortable');
return (
<DropdownMenu>
<DropdownMenuTrigger variant="outline">
Density: {density}
</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuRadioGroup
value={density}
onValueChange={(value) => setDensity(value)}
>
<DropdownMenuRadioItem value="compact">Compact</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="comfortable">
Comfortable
</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="spacious">Spacious</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
);
}DropdownMenuRadioGroup supports value / defaultValue / onValueChange. Radio items keep the
menu open so several settings can be adjusted in one session.
Submenus#
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
DropdownMenuSubTrigger,
DropdownMenuTrigger,
} from '@orkest/ui/client';
import { Copy, Mail, MessageSquare, Share2 } from 'lucide-react';
export function Example() {
return (
<DropdownMenu>
<DropdownMenuTrigger variant="outline">Share</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem leftIcon={Copy}>Copy link</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger leftIcon={Share2}>
Share via
</DropdownMenuSubTrigger>
<DropdownMenuSubContent>
<DropdownMenuItem leftIcon={Mail}>Email</DropdownMenuItem>
<DropdownMenuItem leftIcon={MessageSquare}>Message</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem>More options…</DropdownMenuItem>
</DropdownMenuSubContent>
</DropdownMenuSub>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
);
}DropdownMenuSubContent renders its own portal and positioner. Submenus open on hover, click, or the
right arrow key, and close with Escape or the left arrow key.
Controlled state#
import { useState } from 'react';
import { Stack, Text } from '@orkest/ui';
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from '@orkest/ui/client';
import { Copy, Pencil, Trash2 } from 'lucide-react';
export function Example() {
const [open, setOpen] = useState(false);
return (
<Stack direction="row" gap={3} wrap align="center">
<DropdownMenu open={open} onOpenChange={setOpen}>
<DropdownMenuTrigger variant="outline">Project actions</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem leftIcon={Pencil}>Rename</DropdownMenuItem>
<DropdownMenuItem leftIcon={Copy}>Duplicate</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem variant="destructive" leftIcon={Trash2}>
Delete project
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
<Text size="sm" tone="muted">
{open ? 'Status: open' : 'Status: closed'}
</Text>
</Stack>
);
}Positioning and sizing#
DropdownMenuContent places the menu on the bottom side with start alignment by default. Override
side, align, sideOffset, and alignOffset when the trigger needs a different layout. Base UI
automatically flips the menu when it would overflow the viewport.
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuLinkItem,
DropdownMenuPortal,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<DropdownMenu>
<DropdownMenuTrigger variant="outline">Sized menu</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent minWidth="18rem" maxWidth="22rem">
<DropdownMenuItem>Rename project</DropdownMenuItem>
<DropdownMenuItem>Move to folder</DropdownMenuItem>
<DropdownMenuItem>Duplicate project</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuLinkItem href="/docs/components/dropdown-menu/">
Read the documentation
</DropdownMenuLinkItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenu>
);
}Use minWidth and maxWidth for predictable surfaces, or leave them unset to let the menu grow with
its content. maxHeight controls when the menu starts scrolling; by default it is limited by the
available viewport height.
Item types#
| Type | Component | Behavior |
|---|---|---|
| Action | DropdownMenuItem | Executes an action and closes the menu |
| Link | DropdownMenuLinkItem | Renders an anchor and closes the menu after navigation |
| Destructive | DropdownMenuItem variant="destructive" | Uses the danger color for irreversible actions |
| Checkbox | DropdownMenuCheckboxItem | Toggles a setting and keeps the menu open |
| Radio | DropdownMenuRadioItem | Selects one value in a DropdownMenuRadioGroup |
| Submenu | DropdownMenuSub | Opens a nested menu |
| Shortcut | DropdownMenuShortcut | Displays a keyboard hint without changing the accessible name |
Mix icon and non-icon items with inset so labels stay aligned:
<DropdownMenuItem leftIcon={Pencil}>Edit</DropdownMenuItem>
<DropdownMenuItem inset>Preferences</DropdownMenuItem>Accessibility#
DropdownMenuContentrendersrole="menu"and items renderrole="menuitem",menuitemcheckbox, ormenuitemradioas appropriate.ArrowUpandArrowDownmove through items,HomeandEndjump to the first and last items, andEnterorSpaceactivates the highlighted item.Escapecloses the menu and restores focus to the trigger.Tabmoves focus out of the menu.- Disabled items are exposed with
aria-disabled, cannot be activated, and are skipped by arrow, Home, and End navigation. DropdownMenuShortcutis hidden from assistive technology so the accessible name stays concise.- Destructive items keep their text label; color is not the only signal.
DropdownMenuLabelis associated with its group automatically.- The menu respects
prefers-reduced-motionfor its open and close animation.
Props#
DropdownMenu#
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
| Controlled open state. | ||
defaultOpen | boolean | false |
| Initial open state for uncontrolled usage. | ||
onOpenChange | (open, eventDetails) => void | — |
| Called when the menu requests an open state change. | ||
modal | boolean | true |
| Locks page scroll and blocks outside pointer interaction while open. | ||
loopFocus | boolean | true |
| Wraps keyboard focus at the ends of the menu. | ||
orientation | 'vertical' | 'horizontal' | 'vertical' |
| Controls which arrow keys move between items. | ||
disabled | boolean | false |
| Disables the trigger and the menu. | ||
onOpenChangeComplete | (open: boolean) => void | — |
| Called after the open or close animation completes. | ||
triggerId / defaultTriggerId | string | — |
| Associates an external trigger with a controlled menu. | ||
DropdownMenuTrigger#
| Prop | Type | Default |
|---|---|---|
variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | 'secondary' |
| Visual Button variant used by the default trigger. | ||
size | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
| Button size. | ||
render | ReactElement | — |
| Replaces the default Button, for example with an icon button. | ||
openOnHover / delay / closeDelay | boolean / number / number | — |
| Opens the menu on hover with optional delays. | ||
native attributes | ButtonHTMLAttributes<HTMLButtonElement> | — |
| Disabled, type, click handlers, and refs are forwarded. | ||
DropdownMenuContent#
| Prop | Type | Default |
|---|---|---|
side | 'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end' | 'bottom' |
| Side of the trigger the menu is placed on. | ||
align | 'start' | 'center' | 'end' | 'start' |
| Alignment relative to the trigger. | ||
sideOffset | number | 6 |
| Distance between the trigger and the menu. | ||
alignOffset | number | 0 |
| Offset along the alignment axis. | ||
collisionPadding | number | Partial<Record<side, number>> | — |
| Keeps the menu away from viewport edges. | ||
minWidth / maxWidth / maxHeight | CSSProperties values | — |
| Controls surface sizing and the scrolling threshold. | ||
native attributes | Base UI Menu Popup props | — |
| Class names, data attributes, and refs are forwarded to the popup. | ||
DropdownMenuItem#
| Prop | Type | Default |
|---|---|---|
variant | 'default' | 'destructive' | 'default' |
| Marks irreversible actions with the danger color. | ||
leftIcon | LucideIcon | — |
| Decorative icon rendered before the label. | ||
inset | boolean | false |
| Aligns a label with items that use a leading icon. | ||
disabled | boolean | false |
| Prevents activation and lowers visual emphasis. | ||
closeOnClick | boolean | true |
| Closes the menu when the item is activated. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| Class names, data attributes, and refs are forwarded. | ||
DropdownMenuLinkItem#
| Prop | Type | Default |
|---|---|---|
href | string | — |
| Navigation target rendered on the anchor. | ||
closeOnClick | boolean | true |
| Closes the menu when the link is followed. | ||
leftIcon / inset / variant | LucideIcon / boolean / destructive | — |
| Shares the visual options of DropdownMenuItem. | ||
anchor attributes | AnchorHTMLAttributes<HTMLAnchorElement> | — |
| Target, rel, click handlers, and refs are forwarded. | ||
Checkbox and radio items#
| Prop | Type | Default |
|---|---|---|
DropdownMenuCheckboxItem checked / defaultChecked | boolean | — |
| Controlled and uncontrolled checked state. | ||
DropdownMenuCheckboxItem onCheckedChange | (checked, eventDetails) => void | — |
| Called when the checkbox item is toggled. | ||
DropdownMenuRadioGroup value / defaultValue | string | — |
| Controlled and uncontrolled selected value. | ||
DropdownMenuRadioGroup onValueChange | (value, eventDetails) => void | — |
| Called when the selected radio value changes. | ||
DropdownMenuRadioItem value | string | — |
| Value selected in the surrounding radio group. | ||
closeOnClick | boolean | false |
| Closes the menu when the item is toggled or selected. | ||
Submenu and shortcut#
| Prop | Type | Default |
|---|---|---|
DropdownMenuSubTrigger openOnHover | boolean | true |
| Opens the submenu when the trigger is hovered. | ||
DropdownMenuSubTrigger delay / closeDelay | number | — |
| Hover open and close delays in milliseconds. | ||
DropdownMenuSubContent | DropdownMenuContent props | — |
| Accepts the same positioning and sizing props as DropdownMenuContent. | ||
DropdownMenuShortcut | HTMLAttributes<HTMLElement> | — |
| Rendered as a hidden keyboard hint. Content is announced through the item label. | ||