DropdownMenu

DropdownMenu displays a list of actions in a floating panel triggered by a button. Use when a set of actions share a single trigger and do not need to be persistently visible.

Basic usage

Code

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
    Actions
  </DropdownMenuTrigger>

  <DropdownMenuContent>
    <DropdownMenuGroup>
      <DropdownMenuLabel>Account</DropdownMenuLabel>

      <DropdownMenuItem>
        View details <DropdownMenuShortcut>⌘O</DropdownMenuShortcut>
      </DropdownMenuItem>

      <DropdownMenuItem>
        Edit account <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>
      </DropdownMenuItem>
    </DropdownMenuGroup>

    <DropdownMenuSeparator />

    <DropdownMenuItem variant="destructive">
      Deactivate account
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Submenu

Use a submenu when one action opens a small secondary action set.

<DropdownMenuSub>
  <DropdownMenuSubTrigger>Assign owner</DropdownMenuSubTrigger>

  <DropdownMenuSubContent>
    <DropdownMenuItem>Sales</DropdownMenuItem>
    <DropdownMenuItem>Operations</DropdownMenuItem>
  </DropdownMenuSubContent>
</DropdownMenuSub>

Selectable items

Use checkbox items for independent toggles and radio items for one-of-many choices.

Code

(() => {
  function SelectableDropdownMenuItems() {
    const [showOwner, setShowOwner] = React.useState(true);
    const [density, setDensity] = React.useState("comfortable");

    return (
      <DropdownMenu>
        <DropdownMenuTrigger render={<Button variant="outline" />}>
          View options
        </DropdownMenuTrigger>

        <DropdownMenuContent>
          <DropdownMenuGroup>
            <DropdownMenuLabel>Table columns</DropdownMenuLabel>
            <DropdownMenuCheckboxItem
              checked={showOwner}
              onCheckedChange={setShowOwner}
            >
              Owner
            </DropdownMenuCheckboxItem>
          </DropdownMenuGroup>

          <DropdownMenuSeparator />

          <DropdownMenuGroup>
            <DropdownMenuLabel>Density</DropdownMenuLabel>
            <DropdownMenuRadioGroup value={density} onValueChange={setDensity}>
              <DropdownMenuRadioItem value="compact">
                Compact
              </DropdownMenuRadioItem>
              <DropdownMenuRadioItem value="comfortable">
                Comfortable
              </DropdownMenuRadioItem>
            </DropdownMenuRadioGroup>
          </DropdownMenuGroup>
        </DropdownMenuContent>
      </DropdownMenu>
    );
  }

  return <SelectableDropdownMenuItems />;
})();

API

DropdownMenu

Name	Type/Description
actionsRef	RefObject<MenuRootActions | null> | undefined A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively.
children	ReactNode | PayloadChildRenderFunction<unknown> The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger.
closeParentOnEsc = false	boolean | undefined When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
defaultOpen = false	boolean | undefined Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
defaultTriggerId	string | null | undefined ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
handle	MenuHandle<unknown> | undefined A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.
highlightItemOnHover = true	boolean | undefined 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 = true	boolean | undefined Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
modal = true	boolean | undefined Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed.
onOpenChange	((open: boolean, eventDetails: MenuRootChangeEventDetails) => void) | undefined Event handler called when the menu is opened or closed.
onOpenChangeComplete	((open: boolean) => void) | undefined Event handler called after any animations complete when the menu is closed.
open	boolean | undefined Whether the menu is currently open.
orientation = "'vertical'"	MenuRootOrientation | undefined The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
triggerId	string | null | undefined ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).

DropdownMenuCheckboxItem

Name	Type/Description
checked	boolean | undefined Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
className	string | ((state: MenuCheckboxItemState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
closeOnClick = false	boolean | undefined Whether to close the menu when the item is clicked.
defaultChecked = false	boolean | undefined Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
id	string | undefined @ignore
inset	boolean | undefined
label	string | undefined Overrides the text label to use when the item is matched during keyboard text navigation.
nativeButton = true	boolean | undefined 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>`).
onCheckedChange	((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void) | undefined Event handler called when the checkbox item is ticked or unticked.
onClick	((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | undefined The click handler for the menu item.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuCheckboxItemState> | undefined 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.
style	CSSProperties | ((state: MenuCheckboxItemState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuContent

Name	Type/Description
align = "start"	Align | undefined How to align the popup relative to the specified side.
alignOffset = 0	number | OffsetFunction | undefined 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. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
className	string | ((state: MenuPopupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | undefined 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.
id	string | undefined @ignore
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState> | undefined 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.
side = "bottom"	Side | undefined Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset = 4	number | OffsetFunction | undefined 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. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
style	CSSProperties | ((state: MenuPopupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuGroup

Name	Type/Description
children	ReactNode The content of the component.
className	string | ((state: MenuGroupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupState> | undefined 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.
style	CSSProperties | ((state: MenuGroupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuItem

Name	Type/Description
className	string | ((state: MenuItemState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
closeOnClick = true	boolean | undefined Whether to close the menu when the item is clicked.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
id	string | undefined @ignore
inset	boolean | undefined
label	string | undefined Overrides the text label to use when the item is matched during keyboard text navigation.
nativeButton = true	boolean | undefined 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>`).
onClick	((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | undefined The click handler for the menu item.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuItemState> | undefined 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.
style	CSSProperties | ((state: MenuItemState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.
variant = "default"	"default" | "destructive" | undefined

DropdownMenuLabel

Name	Type/Description
className	string | ((state: MenuGroupLabelState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
inset	boolean | undefined
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuGroupLabelState> | undefined 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.
style	CSSProperties | ((state: MenuGroupLabelState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuPortal

Name	Type/Description
className	string | ((state: MenuPortalState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
container	HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null | undefined A parent element to render the portal element into.
keepMounted = false	boolean | undefined Whether to keep the portal mounted in the DOM while the popup is hidden.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPortalState> | undefined 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.
style	CSSProperties | ((state: MenuPortalState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuRadioGroup

Name	Type/Description
children	ReactNode The content of the component.
className	string | ((state: MenuRadioGroupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
defaultValue	any The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
onValueChange	((value: any, eventDetails: MenuRootChangeEventDetails) => void) | undefined Function called when the selected value changes.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioGroupState> | undefined 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.
style	CSSProperties | ((state: MenuRadioGroupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.
value	any The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead.

DropdownMenuRadioItem

Name	Type/Description
className	string | ((state: MenuRadioItemState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
closeOnClick = false	boolean | undefined Whether to close the menu when the item is clicked.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
id	string | undefined @ignore
inset	boolean | undefined
label	string | undefined Overrides the text label to use when the item is matched during keyboard text navigation.
nativeButton = true	boolean | undefined 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>`).
onClick	((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | undefined The click handler for the menu item.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuRadioItemState> | undefined 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.
style	CSSProperties | ((state: MenuRadioItemState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.
value	any Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected.

DropdownMenuSeparator

Name	Type/Description
className	string | ((state: SeparatorState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
orientation = "'horizontal'"	Orientation | undefined The orientation of the separator.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState> | undefined 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.
style	CSSProperties | ((state: SeparatorState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuShortcut

No documented props

DropdownMenuSub

Name	Type/Description
actionsRef	RefObject<MenuRootActions | null> | undefined A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively.
children	ReactNode The content of the submenu.
closeParentOnEsc = false	boolean | undefined When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
defaultOpen = false	boolean | undefined Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
highlightItemOnHover = true	boolean | undefined 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 = true	boolean | undefined Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
onOpenChange	((open: boolean, eventDetails: MenuRootChangeEventDetails) => void) | undefined Event handler called when the menu is opened or closed.
onOpenChangeComplete	((open: boolean) => void) | undefined Event handler called after any animations complete when the menu is closed.
open	boolean | undefined Whether the menu is currently open.
orientation = "'vertical'"	MenuRootOrientation | undefined The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.

DropdownMenuSubContent

Name	Type/Description
align = "start"	Align | undefined How to align the popup relative to the specified side.
alignOffset = 0	number | OffsetFunction | undefined 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. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
className	string | ((state: MenuPopupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | undefined 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.
id	string | undefined @ignore
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuPopupState> | undefined 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.
side = "bottom"	Side | undefined Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset = 4	number | OffsetFunction | undefined 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. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
style	CSSProperties | ((state: MenuPopupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuSubTrigger

Name	Type/Description
className	string | ((state: MenuSubmenuTriggerState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
closeDelay = 0	number | undefined How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
delay = 100	number | undefined How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
id	string | undefined @ignore
inset	boolean | undefined
label	string | undefined Overrides the text label to use when the item is matched during keyboard text navigation.
nativeButton = true	boolean | undefined 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>`).
onClick	((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | undefined
openOnHover	boolean | undefined Whether the menu should also open when the trigger is hovered.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuSubmenuTriggerState> | undefined 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.
style	CSSProperties | ((state: MenuSubmenuTriggerState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DropdownMenuTrigger

Name	Type/Description
className	string | ((state: MenuTriggerState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
closeDelay = 0	number | undefined How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
delay = 100	number | undefined How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
disabled = false	boolean | undefined Whether the component should ignore user interaction.
handle	MenuHandle<unknown> | undefined A handle to associate the trigger with a menu.
nativeButton = true	boolean | undefined 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	boolean | undefined Whether the menu should also open when the trigger is hovered.
payload	unknown A payload to pass to the menu when it is opened.
ref	((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, MenuTriggerState> | undefined 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.
style	CSSProperties | ((state: MenuTriggerState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.