DropdownMenu

A menu of actions and settings behind a button, with groups, checkbox and radio items, submenus and a destructive item.

A dropdown menu opens from a button with a list of actions, such as the actions of a table row, or settings that apply at once. It is built on Base UI's menu. For a choice that is a form value, use a select; for actions on a right click, a context menu.

Actions, a setting, a choice and a submenuClient

Last action: nothing yet · archived hidden · sorted by name

Full source examples/ui/dropdown-menu.tsx

// apps/docs/examples/ui/dropdown-menu.tsx'use client';
import {useState} from 'react';import {  CopyIcon,  MoreHorizontalIcon,  PencilIcon,  Trash2Icon,} from 'lucide-react';
import {Button} from '@workspace/active-ui/components/primitives/button';import {  DropdownMenu,  DropdownMenuCheckboxItem,  DropdownMenuContent,  DropdownMenuGroup,  DropdownMenuItem,  DropdownMenuLabel,  DropdownMenuRadioGroup,  DropdownMenuRadioItem,  DropdownMenuSeparator,  DropdownMenuSub,  DropdownMenuSubContent,  DropdownMenuSubTrigger,  DropdownMenuTrigger,} from '@workspace/active-ui/components/primitives/dropdown-menu';
/** * The actions of one row behind a button: plain items, a setting that is on * or off, one choice out of several, a submenu, and a destructive action set * apart. What each item did is printed below, because a menu only reports * the choice. */export default function DropdownMenuExample() {  const [last, setLast] = useState('nothing yet');  const [archived, setArchived] = useState(false);  const [sort, setSort] = useState('name');  return (    <div className="flex flex-col items-center gap-4">      <DropdownMenu>        <DropdownMenuTrigger          render={            <Button variant="outline" size="icon" aria-label="Scheme actions" />          }        >          <MoreHorizontalIcon aria-hidden />        </DropdownMenuTrigger>        <DropdownMenuContent className="w-56">          <DropdownMenuGroup>            <DropdownMenuLabel>Pension scheme 2026</DropdownMenuLabel>            <DropdownMenuItem onClick={() => setLast('Edit')}>              <PencilIcon aria-hidden />              Edit            </DropdownMenuItem>            <DropdownMenuItem onClick={() => setLast('Duplicate')}>              <CopyIcon aria-hidden />              Duplicate            </DropdownMenuItem>            <DropdownMenuSub>              <DropdownMenuSubTrigger>Export as</DropdownMenuSubTrigger>              <DropdownMenuSubContent>                <DropdownMenuItem onClick={() => setLast('Export as CSV')}>                  CSV                </DropdownMenuItem>                <DropdownMenuItem onClick={() => setLast('Export as PDF')}>                  PDF                </DropdownMenuItem>              </DropdownMenuSubContent>            </DropdownMenuSub>          </DropdownMenuGroup>          <DropdownMenuSeparator />          <DropdownMenuCheckboxItem            checked={archived}            onCheckedChange={setArchived}          >            Show archived versions          </DropdownMenuCheckboxItem>          <DropdownMenuSeparator />          <DropdownMenuGroup>            <DropdownMenuLabel>Sort participants by</DropdownMenuLabel>            <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>              <DropdownMenuRadioItem value="name">Name</DropdownMenuRadioItem>              <DropdownMenuRadioItem value="joined">                Date joined              </DropdownMenuRadioItem>            </DropdownMenuRadioGroup>          </DropdownMenuGroup>          <DropdownMenuSeparator />          <DropdownMenuItem            variant="destructive"            onClick={() => setLast('Delete')}          >            <Trash2Icon aria-hidden />            Delete          </DropdownMenuItem>        </DropdownMenuContent>      </DropdownMenu>      <p className="text-muted-foreground text-sm" aria-live="polite">        Last action: {last} · archived {archived ? 'shown' : 'hidden'} · sorted        by {sort}      </p>    </div>  );}

Usage#

TSX

import {  DropdownMenu,  DropdownMenuContent,  DropdownMenuItem,  DropdownMenuTrigger,} from '@workspace/active-ui/components/primitives/dropdown-menu';
<DropdownMenu>  <DropdownMenuTrigger render={<Button variant="outline" />}>    Actions  </DropdownMenuTrigger>  <DropdownMenuContent>    <DropdownMenuItem onClick={edit}>Edit</DropdownMenuItem>    <DropdownMenuItem variant="destructive" onClick={remove}>      Delete    </DropdownMenuItem>  </DropdownMenuContent></DropdownMenu>;

Anatomy#

DropdownMenu and DropdownMenuTrigger: the open state and the button that opens it.
DropdownMenuContent: the list, placed by side (default bottom) and align (default start). It is as wide as its trigger, at least 8rem; set a width with className.
DropdownMenuItem: an action, run by onClick; the menu closes after it. variant="destructive" colours an action that deletes. inset aligns an item without an icon with items that have one.
DropdownMenuCheckboxItem: a setting that is on or off (checked, onCheckedChange). The menu stays open after it, so several settings can be changed at once.
DropdownMenuRadioGroup with DropdownMenuRadioItem: one choice out of several (value, onValueChange).
DropdownMenuGroup with DropdownMenuLabel: a labelled group. A label belongs inside a group.
DropdownMenuSub with DropdownMenuSubTrigger and DropdownMenuSubContent: a submenu.
DropdownMenuSeparator and DropdownMenuShortcut. A shortcut only shows a key combination; binding the keys is your application's work.

What your application provides#

An accessible name for an icon-only trigger.
What each item does, and the state of checkbox and radio items.
A confirmation for a destructive item that cannot be undone, such as an alert dialog.

Accessibility and keyboard#

The trigger opens the menu with Enter, Space or ↓, and moves the focus to the first item.
↓ and ↑ move between items, typing a letter jumps to an item that starts with it, → opens a submenu and ← closes it, Enter runs the item, and Escape closes the menu and returns the focus to the trigger.
The list is a role="menu"; items are menuitem, menuitemcheckbox or menuitemradio.

API#

DropdownMenuContent#

Import from @workspace/active-ui/components/primitives/dropdown-menu

All props come from the Base UI part this component is built on.

Props

align

Type: Align
Default: 'center'

How to align the popup relative to the specified side.

Submenus and menubars default to 'start'.

alignOffset

Type: number | OffsetFunction
Default: 0

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

children

Type: ReactNode

The content of this part, in the forms its type allows.

finalFocus

Type: booleanRefObject<HTMLElement | null>(closeType) => …

Determines the element to focus when the menu is closed.

false: Do not move focus.
true: Move focus based on the default behavior (trigger or previously focused element).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.

Type: string

The id of the rendered element.

side

Type: Side
Default: 'bottom'

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

Submenus and vertical menubars default to 'inline-end'.

sideOffset

Type: number | OffsetFunction
Default: 0

Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuItem#

Import from @workspace/active-ui/components/primitives/dropdown-menu

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

closeOnClickBase UI

Type: boolean
Default: true

Whether to close the menu when the item is clicked.

disabledBase UI

Type: boolean
Default: false

Whether the component should ignore user interaction.

idBase UI

Type: string

The id of the rendered element.

inset

Type: boolean

Indents the text to line up with items that have an icon or indicator.

labelBase UI

Type: string

Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.

nativeButtonBase UI

Type: boolean
Default: false

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

variant

Type: "default""destructive"
Default: 'default'

destructive colours an item that deletes or cannot be undone.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onClickBase UI

Type: (event) => void

The click handler for the menu item.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Other parts#

DropdownMenu

All props come from the Base UI part this component is built on.

Props

open

Type: boolean

Whether the menu is currently open.

defaultOpen

Type: boolean
Default: false

Whether the menu is initially open.

To render a controlled menu, use the open prop instead.

children

Type: PayloadChildRenderFunction<…>ReactNode

The content of the menu. This can be a regular React node or a render function that receives the payload of the active trigger.

closeParentOnEsc

Type: boolean
Default: false

When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.

defaultTriggerId

Type: string | null

ID of the trigger that the menu is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open menu.

disabled

Type: boolean
Default: false

Whether the component should ignore user interaction.

handle

Type: MenuHandle<unknown>

A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.

highlightItemOnHover

Type: boolean
Default: true

Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.

loopFocus

Type: boolean
Default: true

Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.

orientation

Type: MenuRootOrientation
Default: 'vertical'

The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.

triggerId

Type: string | null

ID of the trigger that the menu is associated with. This is useful in conjunction with the open prop to create a controlled menu. There's no need to specify this prop when the menu is uncontrolled (that is, when the open prop is not set).

actionsRef

Type: RefObject<MenuRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the menu after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the menu completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the menu imperatively when called.

Events

Called by the component when something happens.

onOpenChange

Type: (open, eventDetails) => void

Event handler called when the menu is opened or closed.

onItemHighlighted

Type: (highlightedItem, eventDetails) => void

Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item element (or undefined if no item is highlighted) and details containing the reason for the change, the event, and the item's text label. The reason can be:

'keyboard': the highlight changed due to keyboard navigation.
'pointer': the highlight changed due to pointer hovering. The event may be a MouseEvent rather than a PointerEvent.
'none': the highlight changed for another reason, such as automatic highlighting while filtering, the item list changing, or the popup opening or closing.

onOpenChangeComplete

Type: (open: boolean) => void

Event handler called after any animations complete when the menu is opened or closed.

Takes only the props listed.

DropdownMenuPortal

All props come from the Base UI part this component is built on.

Props

container

Type: HTMLElementRefObject<…>ShadowRootnull

A parent element to render the portal element into.

keepMounted

Type: boolean
Default: false

Whether to keep the portal mounted in the DOM while the popup is hidden.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuTrigger

All props come from the Base UI part this component is built on.

Props

children

Type: ReactNode

The content of this part, in the forms its type allows.

closeDelay

Type: number
Default: 0

How long to wait before closing the menu that was opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

delay

Type: number
Default: 100

How long to wait before the menu may be opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

disabled

Type: boolean
Default: false

Whether the component should ignore user interaction.

handle

Type: MenuHandle<unknown>

A handle to associate the trigger with a menu.

nativeButton

Type: boolean
Default: true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

openOnHover

Type: boolean

Whether the menu should also open when the trigger is hovered.

payload

Type: unknown

A payload to pass to the menu when it is opened.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuGroup

All props come from the Base UI part this component is built on.

Props

children

Type: ReactNode

The content of the component.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuLabel

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

inset

Type: boolean

Indents the text to line up with items that have an icon or indicator.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuCheckboxItem

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

checkedBase UI

Type: boolean

Whether the checkbox item is currently ticked.

To render an uncontrolled checkbox item, use the defaultChecked prop instead.

defaultCheckedBase UI

Type: boolean
Default: false

Whether the checkbox item is initially ticked.

To render a controlled checkbox item, use the checked prop instead.

closeOnClickBase UI

Type: boolean
Default: false

Whether to close the menu when the item is clicked.

disabledBase UI

Type: boolean
Default: false

Whether the component should ignore user interaction.

idBase UI

Type: string

The id of the rendered element.

inset

Type: boolean

Indents the text to line up with items that have an icon or indicator.

labelBase UI

Type: string

Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.

nativeButtonBase UI

Type: boolean
Default: false

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onCheckedChangeBase UI

Type: (checked, eventDetails) => void

Event handler called when the checkbox item is ticked or unticked.

onClickBase UI

Type: (event) => void

The click handler for the menu item.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuRadioGroup

All props come from the Base UI part this component is built on.

Props

value

Type: any

The controlled value of the radio item that should be currently selected.

To render an uncontrolled radio group, use the defaultValue prop instead.

defaultValue

Type: any

The uncontrolled value of the radio item that should be initially selected.

To render a controlled radio group, use the value prop instead.

children

Type: ReactNode

The content of the component.

disabled

Type: boolean
Default: false

Whether the component should ignore user interaction.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onValueChange

Type: (value, eventDetails) => void

Function called when the selected value changes.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuRadioItem

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

valuerequiredBase UI

Type: any

Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected.

closeOnClickBase UI

Type: boolean
Default: false

Whether to close the menu when the item is clicked.

disabledBase UI

Type: boolean
Default: false

Whether the component should ignore user interaction.

idBase UI

Type: string

The id of the rendered element.

inset

Type: boolean

Indents the text to line up with items that have an icon or indicator.

labelBase UI

Type: string

Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.

nativeButtonBase UI

Type: boolean
Default: false

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onClickBase UI

Type: (event) => void

The click handler for the menu item.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuSeparator

All props come from the Base UI part this component is built on.

Props

orientation

Type: Orientation
Default: 'horizontal'

The orientation of the separator.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuSub

All props come from the Base UI part this component is built on.

Props

open

Type: boolean

Whether the menu is currently open.

defaultOpen

Type: boolean
Default: false

Whether the menu is initially open.

To render a controlled menu, use the open prop instead.

children

Type: ReactNode

The content of the submenu.

closeParentOnEsc

Type: boolean
Default: false

When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.

disabled

Type: boolean
Default: false

Whether the component should ignore user interaction.

highlightItemOnHover

Type: boolean
Default: true

Whether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.

loopFocus

Type: boolean
Default: true

Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.

orientation

Type: MenuRootOrientation
Default: 'vertical'

The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.

actionsRef

Type: RefObject<MenuRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the menu after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the menu completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the menu imperatively when called.

Events

Called by the component when something happens.

onOpenChange

Type: (open, eventDetails) => void

Event handler called when the menu is opened or closed.

onItemHighlighted

Type: (highlightedItem, eventDetails) => void

'keyboard': the highlight changed due to keyboard navigation.
'pointer': the highlight changed due to pointer hovering. The event may be a MouseEvent rather than a PointerEvent.
'none': the highlight changed for another reason, such as automatic highlighting while filtering, the item list changing, or the popup opening or closing.

onOpenChangeComplete

Type: (open: boolean) => void

Event handler called after any animations complete when the menu is opened or closed.

Takes only the props listed.

DropdownMenuSubTrigger

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

closeDelayBase UI

Type: number
Default: 0

How long to wait before closing the menu that was opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

delayBase UI

Type: number
Default: 100

How long to wait before the menu may be opened on hover. Specified in milliseconds.

Requires the openOnHover prop.

disabledBase UI

Type: boolean
Default: false

Whether the component should ignore user interaction.

idBase UI

Type: string

The id of the rendered element.

inset

Type: boolean

Indents the text to line up with items that have an icon or indicator.

labelBase UI

Type: string

Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.

nativeButtonBase UI

Type: boolean
Default: false

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

openOnHoverBase UI

Type: boolean
Default: true

Whether the menu should also open when the trigger is hovered.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Events

Called by the component when something happens.

onClickBase UI

Type: (event) => void

Called when the element is clicked.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

DropdownMenuSubContent

All props come from the Base UI part this component is built on.

Props

align

Type: Align
Default: 'center'

How to align the popup relative to the specified side.

Submenus and menubars default to 'start'.

alignOffset

Type: number | OffsetFunction
Default: 0

Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

children

Type: ReactNode

The content of this part, in the forms its type allows.

finalFocus

Type: booleanRefObject<HTMLElement | null>(closeType) => …

Determines the element to focus when the menu is closed.

false: Do not move focus.
true: Move focus based on the default behavior (trigger or previously focused element).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing.

Type: string

The id of the rendered element.

side

Type: Side
Default: 'bottom'

Which side of the anchor element to align the popup against. May automatically change to avoid collisions.

Submenus and vertical menubars default to 'inline-end'.

sideOffset

Type: number | OffsetFunction
Default: 0

Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.

The function takes a data object parameter with the following properties:

data.anchor: the dimensions of the anchor element with properties width and height.
data.positioner: the dimensions of the positioner element with properties width and height.
data.side: which side of the anchor element the positioner is aligned against.
data.align: how the positioner is aligned relative to the specified side.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Parts that take only their element’s attributes

DropdownMenuShortcut: the attributes of a <span>, with className and ref.

Based on shadcn/ui

This page adapts the Dropdown Menu documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.