Dropdown Menu

A dropdown menu component for displaying a list of actions or options.

Actions

A row or card menu behind an icon button. Give an icon-only trigger an aria-label, and use start for item icons.

Groups, options, and submenus

Label titles a group. RadioGroup picks one value; CheckboxItem toggles several and shows an "only" shortcut on hover. Call event.preventDefault() in onSelect to keep the menu open while toggling. Sub nests a menu.

Button trigger

buttonWithChevron renders a small button with a chevron that flips while the menu is open. Pass the label as children and iconStart for an icon.

Usage

Dropdown.Root is non-modal by default. Inside a drawer or a modal dialog it is always modal, so a long menu can still scroll.

Use Dropdown.RadioGroup and Dropdown.RadioItem when the rows are alternatives and exactly one is chosen. The chosen row shows a check.

Nest a submenu with Dropdown.Sub, Dropdown.SubTrigger and Dropdown.SubContent.

Dropdown.Root Properties

open
boolean

Controlled open state of the dropdown

defaultOpen
boolean

Initial open state when uncontrolled

Default: false

onOpenChange
(open: boolean) => void

Called when the open state changes

modal
boolean

Traps focus and blocks the page behind the menu. Always true inside a drawer or a modal dialog

Default: false

Dropdown.Trigger Properties

asChild
boolean

Merges the trigger behavior into its child element

Default: false

buttonWithChevron
boolean

Renders the trigger as a Button with a chevron that flips while the menu is open

Default: false

fullSizeAndButtonWithChevronToTheRight
boolean

Renders a Button with a truncated label on the left and the chevron on the right

Default: false

iconStart
IconValue

Icon before the label in the two Button variants

size
'micro''small''regular''large'

Button size in the two Button variants. buttonWithChevron defaults to small

Dropdown.Content Properties

side
'top''right''bottom''left'

Preferred side of the trigger to render against

Default: bottom

align
'start''center''end'

Alignment of the content relative to the trigger

Default: center

sideOffset
number

Distance in pixels from the trigger

Default: 10

alignOffset
number

Offset in pixels along the alignment axis

Default: 0

size
number

Minimum width of the menu in pixels

Default: 249

fullWidth
boolean

Uses the trigger's width as the minimum width instead of size

Default: false

withPortal
boolean

Whether to render content in a portal

Default: true

portalContainer
HTMLElement

Container element for the portal

pinnedBottom
ReactNode

Content pinned to the bottom of the menu, with the rows above it scrolling

restoreTriggerFocus
boolean

Return focus to the trigger when the menu closes, except after an outside click

Default: false

submenusGrowUpward
boolean

Opens every nested submenu upward, so its last row lines up with the row that opened it

Default: false

Dropdown.Item Properties

start
IconValue

Icon name, descriptor, or node shown before the label

end
IconValue

Icon name, descriptor, or node shown at the end of the row

onSelect
(event: Event) => void

Called when the item is chosen. Call event.preventDefault() to keep the menu open

href
string

Renders the item as a link

target
string

Target attribute for link items

rel
string

Rel attribute for link items

disabled
boolean

Whether the item is disabled

Default: false

disabledReason
string

Tooltip on a disabled item that explains why it is disabled

disableTooltip
boolean

Turns off the tooltip that shows a truncated label in full

Default: false

tooltipSide
'top''right''bottom''left'

Side of the truncated-label tooltip

Dropdown.CheckboxItem Properties

checked
boolean'indeterminate'

Whether the row is checked

onCheckedChange
(checked: boolean) => void

Called when the row is toggled

showOnlyButton
boolean

Shows an 'only' button on hover

Default: true

onOnlyClick
() => void

Called when the 'only' button is clicked

childrenClassName
string

Classes for the label wrapper. Replaces the default truncate

Dropdown.RadioGroup and Dropdown.RadioItem Properties

value
string

On RadioGroup, the chosen value. On RadioItem, the value this row stands for (required)

onValueChange
(value: string) => void

RadioGroup only. Called with the value of the chosen row

start
IconValue

RadioItem only. Icon name, descriptor, or node shown before the label

disableTooltip
boolean

RadioItem only. Turns off the tooltip that shows a truncated label in full

Default: false

tooltipSide
'top''right''bottom''left'

RadioItem only. Side of the truncated-label tooltip

childrenClassName
string

RadioItem only. Classes for the label

Submenu Properties

Dropdown.Sub
{ open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void }

Container for a nested submenu

startIcon
IconValue

SubTrigger only. Icon shown before the label

hideChevron
boolean

SubTrigger only. Hides the trailing chevron

Default: false

pinnedBottom
ReactNode

SubContent only. Content pinned to the bottom of the submenu, with the rows above it scrolling

sideOffset
number

SubContent only. Distance in pixels from the sub-trigger

Default: 0

alignOffset
number

SubContent only. Offset in pixels along the alignment axis

Default: -4

Other Parts

Dropdown.Label
ComponentPropsWithoutRef<typeof Label>

Heading for a group of rows. Takes size: 'small' or 'medium' (default)

Dropdown.Group
ComponentPropsWithoutRef<typeof Group>

Groups related rows

Dropdown.Separator
ComponentPropsWithoutRef<typeof Separator>

Line between rows

Dropdown.Shortcut
KbdProps

Keyboard shortcut badge pinned to the end of a row

Dropdown.Portal
ComponentPropsWithoutRef<typeof Portal>

The portal Content renders into unless withPortal is false