DropdownMenu

Menu of actions or options, opened from a trigger. Supports nested submenus, checkbox/radio items, separators, and keyboard shortcuts. Open state is uncontrolled by default; pass open/onOpenChange to control it.

Material

Usage

import { DropdownMenu, dropdownMenuAnatomy, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "@instruments/materia-ui/components/dropdown-menu";

Best practices

Use DropdownMenu for a menu opened by clicking a trigger; a right-click / long-press menu is a ContextMenu.
It's an actions / options menu, not a form control - to choose a value use Select (styled) or Combobox (searchable), not menu rows.
Reach for DropdownMenuCheckboxItem / DropdownMenuRadioItem for stateful rows; DropdownMenuContent portals to the body.

Props

DropdownMenuCheckboxItem

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

DropdownMenuContent

Prop	Type	Description
className	`string`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`
itemRadius	`"rounded" \| "square" \| "full"`	Border radius for menu items. When "full", items become pill-shaped.
surface	`MenuSurface`	Surface density. Compact maps to the 16px-radius, 4px-padding menu surface.
contentWidth	`MenuContentWidth`	Named content widths from the design system.
overflow	`MenuOverflow`	Outer content overflow behaviour. Use hidden when a child owns scrolling.

DropdownMenuItem

Prop	Type	Description
className	`string`
inset	`boolean`
tone	`"neutral" \| "danger"`
avatar	`React.ReactNode`
dot	`boolean \| "neutral" \| "brand" \| "danger" \| "warning" \| "success" \| "info"`	Dot indicator at the start (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it.
icon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`
suffixIcon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`
kbd	`string[]`
suffix	`React.ReactNode`
active	`boolean`	Whether the item is in an active/selected state
activeIndicator	`"none" \| "dot" \| "check"`	Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active.
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row (e.g. with a link); glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

DropdownMenuLabel

Prop	Type	Default	Description
className	`string`
inset	`boolean`

DropdownMenuRadioItem

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.

DropdownMenuSeparator

Prop	Type	Default	Description
className	`string`
spacing	`"default" \| "compact"`

DropdownMenuSubContent

Prop	Type	Default	Description
className	`string`
size	`"base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xl"`

DropdownMenuSubTrigger

Prop	Type	Description
className	`string`
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`	Replace the default `<button>` row; glyph props render inside it, around `children`.
children	`string \| number \| React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Text label. Use `icon` prop for icons, not children.
inset	`boolean`
icon	`LucideIcon \| React.ComponentType<React.SVGProps<SVGSVGElement>>`

Also exports

componentDropdownMenu
constdropdownMenuAnatomy
componentDropdownMenuGroup
componentDropdownMenuPortal
componentDropdownMenuRadioGroup
componentDropdownMenuShortcut
componentDropdownMenuSub
componentDropdownMenuTrigger

Anatomy

DropdownMenu

dropdown-menu

Dropdown menu triggered by a button

DropdownMenuTrigger

dropdown-menu-trigger

Button that opens menu

DropdownMenuContent

dropdown-menu-content

Menu content container

DropdownMenuItem

dropdown-menu-item

Menu item

DropdownMenuCheckboxItem

dropdown-menu-checkbox-item

Toggleable item

DropdownMenuRadioGroup

dropdown-menu-radio-group

Exclusive selection group

DropdownMenuRadioItem

dropdown-menu-radio-item

Radio option

DropdownMenuLabel

dropdown-menu-label

Section label

DropdownMenuSeparator

dropdown-menu-separator

Visual divider

DropdownMenuSub

dropdown-menu-sub

Nested submenu

DropdownMenuSubTrigger

dropdown-menu-sub-trigger

Opens nested menu

DropdownMenuSubContent

dropdown-menu-sub-content

Nested menu container

DropdownMenuShortcut

dropdown-menu-shortcut

Keyboard shortcut

Composition

Builds on

Icon, MenuItem

Used by

DataGridColumnHeader, DataGridColumnVisibility, PageToolbar, TagSelector