Base UI

A list of actions in a dropdown, enhanced with keyboard navigation.

import * as React from 'react';
import { Menu } from '@base-ui-components/react/menu';
import styles from './index.module.css';

export default function ExampleMenu() {
  return (
    <Menu.Root>
      <Menu.Trigger className={styles.Button}>
        Song <ChevronDownIcon className={styles.ButtonIcon} />
      </Menu.Trigger>
      <Menu.Portal>
        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
          <Menu.Popup className={styles.Popup}>
            <Menu.Arrow className={styles.Arrow}>
              <ArrowSvg />
            </Menu.Arrow>
            <Menu.Item className={styles.Item}>Add to Library</Menu.Item>
            <Menu.Item className={styles.Item}>Add to Playlist</Menu.Item>
            <Menu.Separator className={styles.Separator} />
            <Menu.Item className={styles.Item}>Play Next</Menu.Item>
            <Menu.Item className={styles.Item}>Play Last</Menu.Item>
            <Menu.Separator className={styles.Separator} />
            <Menu.Item className={styles.Item}>Favorite</Menu.Item>
            <Menu.Item className={styles.Item}>Share</Menu.Item>
          </Menu.Popup>
        </Menu.Positioner>
      </Menu.Portal>
    </Menu.Root>
  );
}

function ArrowSvg(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="20" height="10" viewBox="0 0 20 10" fill="none" {...props}>
      <path
        d="M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
        className={styles.ArrowFill}
      />
      <path
        d="M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z"
        className={styles.ArrowOuterStroke}
      />
      <path
        d="M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z"
        className={styles.ArrowInnerStroke}
      />
    </svg>
  );
}

function ChevronDownIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="10" height="10" viewBox="0 0 10 10" fill="none" {...props}>
      <path d="M1 3.5L5 7.5L9 3.5" stroke="currentcolor" strokeWidth="1.5" />
    </svg>
  );
}

API reference

Import the component and assemble its parts:

Anatomy

import { Menu } from '@base-ui-components/react/menu';
<Menu.Root>  <Menu.Trigger />  <Menu.Portal>    <Menu.Backdrop />    <Menu.Positioner>      <Menu.Popup>        <Menu.Arrow />        <Menu.Item />        <Menu.Separator />        <Menu.Group>          <Menu.GroupLabel />        </Menu.Group>        <Menu.RadioGroup>          <Menu.RadioItem />        </Menu.RadioGroup>        <Menu.CheckboxItem />      </Menu.Popup>    </Menu.Positioner>  </Menu.Portal></Menu.Root>

Root

Groups all parts of the menu. Doesn’t render its own HTML element.

Prop	Type	Default
`defaultOpen`	`boolean`	`false`
`open`	`boolean`	`undefined`
`onOpenChange`	`(open, event) => void`	`undefined`
`closeParentOnEsc`	`boolean`	`true`
`modal`	`boolean`	`true`
`disabled`	`boolean`	`false`
`openOnHover`	`boolean`	`undefined`
`delay`	`number`	`100`
`loop`	`boolean`	`true`
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`

Trigger

A button that opens the menu. Renders a <button> element.

Prop	Type	Default
`disabled`	`boolean`	`false`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-popup-open`	Present when the corresponding menu is open.
`data-pressed`	Present when the trigger is pressed.

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>.

Prop	Type	Default
`container`	`React.Ref \| HTMLElement \| null`	`undefined`
`keepMounted`	`boolean`	`false`

Positioner

Positions the menu popup against the trigger. Renders a <div> element.

Prop	Type	Default
`align`	`'start' \| 'center' \| 'end'`	`undefined`
`alignOffset`	`number`	`0`
`side`	`\| 'bottom' \| 'inline-end' \| 'inline-start' \| 'left' \| 'right' \| 'top'`	`undefined`
`sideOffset`	`number`	`0`
`arrowPadding`	`number`	`5`
`anchor`	`\| React.Ref \| Element \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`undefined`
`collisionBoundary`	`\| 'clipping-ancestors' \| Element \| Element[] \| Rect`	`'clipping-ancestors'`
`collisionPadding`	`number \| Rect`	`5`
`sticky`	`boolean`	`false`
`positionMethod`	`'absolute' \| 'fixed'`	`'absolute'`
`className`	`string \| (state) => string`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-open`	Present when the menu popup is open.
`data-closed`	Present when the menu popup is closed.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the menu is positioned relative to the trigger.

CSS Variable	Description
`--anchor-height`	The anchor's height.
`--anchor-width`	The anchor's width.
`--available-height`	The available height between the trigger and the edge of the viewport.
`--available-width`	The available width between the trigger and the edge of the viewport.
`--transform-origin`	The coordinates that this element is anchored to. Used for animations and transitions.

A container for the menu items. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-open`	Present when the menu is open.
`data-closed`	Present when the menu is closed.
`data-side`	Indicates which side the menu is positioned relative to the trigger.
`data-starting-style`	Present when the menu is animating in.
`data-ending-style`	Present when the menu is animating out.

Arrow

Displays an element positioned against the menu anchor. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-open`	Present when the menu popup is open.
`data-closed`	Present when the menu popup is closed.
`data-uncentered`	Present when the menu arrow is uncentered.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the menu is positioned relative to the trigger.

Item

An individual interactive item in the menu. Renders a <div> element.

Prop	Type	Default
`label`	`string`	`undefined`
`onClick`	`(event) => void`	`undefined`
`closeOnClick`	`boolean`	`true`
`disabled`	`boolean`	`false`

Group

Groups related menu items with the corresponding label. Renders a <div> element.

Prop	Type	Default
`children`	`React.ReactNode`	`undefined`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

RadioGroup

Groups related radio items. Renders a <div> element.

Prop	Type	Default
`defaultValue`	`any`	`undefined`
`value`	`any`	`undefined`
`onValueChange`	`(value, event) => void`	`() => {}`
`children`	`React.ReactNode`	`undefined`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

RadioItem

A menu item that works like a radio button in a given group. Renders a <div> element.

Prop	Type	Default
`label`	`string`	`undefined`
`value`	`any`	`undefined`
`onClick`	`(event) => void`	`undefined`
`closeOnClick`	`boolean`	`false`
`disabled`	`boolean`	`false`

Attribute	Description
`data-checked`	Present when the menu radio item is selected.
`data-unchecked`	Present when the menu radio item is not selected.

RadioItemIndicator

Indicates whether the radio item is selected. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-checked`	Present when the menu radio item is selected.
`data-unchecked`	Present when the menu radio item is not selected.
`data-disabled`	Present when the menu radio item is disabled.
`data-starting-style`	Present when the radio indicator is animating in.
`data-ending-style`	Present when the radio indicator is animating out.

CheckboxItem

A menu item that toggles a setting on or off. Renders a <div> element.

Prop	Type	Default
`label`	`string`	`undefined`
`defaultChecked`	`boolean`	`false`
`checked`	`boolean`	`undefined`
`onCheckedChange`	`(checked, event) => void`	`undefined`
`onClick`	`(event) => void`	`undefined`
`closeOnClick`	`boolean`	`false`
`disabled`	`boolean`	`false`

Attribute	Description
`data-checked`	Present when the menu checkbox item is checked.
`data-unchecked`	Present when the menu checkbox item is not checked.

CheckboxItemIndicator

Indicates whether the checkbox item is ticked. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-checked`	Present when the menu checkbox item is checked.
`data-unchecked`	Present when the menu checkbox item is not checked.
`data-disabled`	Present when the menu checkbox item is disabled.
`data-starting-style`	Present when the indicator is animating in.
`data-ending-style`	Present when the indicator is animating out.

SubmenuTrigger

A menu item that opens a submenu. Renders a <div> element.

Prop	Type	Default
`label`	`string`	`undefined`
`disabled`	`boolean`	`false`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-popup-open`	Present when the corresponding submenu is open.

Separator

A separator element accessible to screen readers. Renders a <div> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Examples

Open on hover

To create a menu that opens on hover, add the openOnHover prop to the Root part. You can additionally configure how quickly the menu opens on hover using the delay prop.

Checkbox items

Use the <Menu.CheckboxItem> part to create a menu item that can toggle a setting on or off.

Radio items

Use the <Menu.RadioGroup> and <Menu.RadioItem> parts to create menu items that work like radio buttons.

Close on click

Use the closeOnClick prop to change whether the menu closes when an item is clicked.

Control whether the menu closes on click

// Close the menu when a checkbox item is clicked<Menu.CheckboxItem closeOnClick />
// Keep the menu open when an item is clicked<Menu.Item closeOnClick={false} />

Group labels

Use the <Menu.GroupLabel> part to add a label to a <Menu.Group>

To create a submenu, nest another menu inside the parent menu. Use the <Menu.SubmenuTrigger> part for the menu item that opens the nested menu.

Adding a submenu

<Menu.Root>  <Menu.Trigger />  <Menu.Portal>    <Menu.Backdrop />    <Menu.Positioner>      <Menu.Popup>        <Menu.Arrow />        <Menu.Item />
        {/* Submenu */}        <Menu.Root>          <Menu.SubmenuTrigger />          <Menu.Portal>            <Menu.Positioner>              <Menu.Popup>              </Menu.Popup>            </Menu.Positioner>          </Menu.Portal>        </Menu.Root>      </Menu.Popup>    </Menu.Positioner>  </Menu.Portal></Menu.Root>

Navigate to another page

Use the render prop to compose a menu item with an anchor element.

A menu item that opens a link

<Menu.Item render={<a href="/projects">Go to Projects</a>} />

Open a dialog

In order to open a dialog using a menu, control the dialog state and open it imperatively using the onClick handler on the menu item.

Make sure to also use the dialog’s finalFocus prop to return focus back to the menu trigger.

Connecting a dialog to a menu

import * as React from 'react';import { Dialog } from '@base-ui/components/dialog';import { Menu } from '@base-ui/components/menu';
function ExampleMenu() {  const menuTriggerRef = React.useRef<HTMLButtonElement>(null);  const [dialogOpen, setDialogOpen] = React.useState(false);
  return (    <React.Fragment>      <Menu.Root>        {/* Set the trigger ref */}        <Menu.Trigger ref={menuTriggerRef}>Open menu</Menu.Trigger>        <Menu.Portal>          <Menu.Positioner>            <Menu.Popup>              {/* Open the dialog when the menu item is clicked */}              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>            </Menu.Popup>          </Menu.Positioner>        </Menu.Portal>      </Menu.Root>
      {/* Control the dialog state */}      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>        <Dialog.Portal>          <Dialog.Backdrop />          {/* Return focus to the menu trigger when the dialog is closed */}          <Dialog.Popup finalFocus={menuTriggerRef}>          </Dialog.Popup>        </Dialog.Portal>      </Dialog.Root>    </React.Fragment>  );}

Menu