Headless

import { Menu } from '@base-ui/react/menu';

<Menu.Root>
  <Menu.Trigger />
  <Menu.Portal>
    <Menu.Backdrop />
    <Menu.Positioner>
      <Menu.Popup>
        <Menu.Arrow />
        <Menu.Item />
        <Menu.LinkItem />
        <Menu.Separator />

        <Menu.SubmenuRoot>
          <Menu.SubmenuTrigger />
        </Menu.SubmenuRoot>

        <Menu.Group>
          <Menu.GroupLabel />
        </Menu.Group>

        <Menu.RadioGroup>
          <Menu.GroupLabel />
          <Menu.RadioItem>
            <Menu.RadioItemIndicator />
          </Menu.RadioItem>
        </Menu.RadioGroup>

        <Menu.CheckboxItem>
          <Menu.CheckboxItemIndicator />
        </Menu.CheckboxItem>

        <Menu.Viewport />
      </Menu.Popup>
    </Menu.Positioner>
  </Menu.Portal>
</Menu.Root>;

Examples

Open on hover

To create a menu that opens on hover, add the openOnHover prop to <Menu.Trigger>. 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> or <Menu.RadioGroup>.

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

Adding a submenu

<Menu.Root>
  <Menu.Trigger />
  <Menu.Portal>
    <Menu.Positioner>
      <Menu.Popup>
        <Menu.Item />

        {/* @highlight-start */}
        {/* Submenu */}
        <Menu.SubmenuRoot>
          {/* @highlight */}
          <Menu.SubmenuTrigger />
          <Menu.Portal>
            <Menu.Positioner>
              <Menu.Popup>
                {/* prettier-ignore */}
                {/* Submenu items  */}
              </Menu.Popup>
            </Menu.Positioner>
          </Menu.Portal>
        </Menu.SubmenuRoot>
        {/* @highlight-end */}
      </Menu.Popup>
    </Menu.Positioner>
  </Menu.Portal>
</Menu.Root>

Navigate to another page

Use the <Menu.LinkItem> part to create a link.

A menu item that opens a link

<Menu.LinkItem href="/projects">Go to Projects</Menu.LinkItem>

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.

Connecting a dialog to a menu

import * as React from 'react';
import { Dialog } from '@base-ui/react/dialog';
import { Menu } from '@base-ui/react/menu';

function ExampleMenu() {
  const [dialogOpen, setDialogOpen] = React.useState(false);

  return (
    <React.Fragment>
      <Menu.Root>
        <Menu.Trigger>Open menu</Menu.Trigger>
        <Menu.Portal>
          <Menu.Positioner>
            <Menu.Popup>
              {/* @highlight-start */}
              {/* Open the dialog when the menu item is clicked */}
              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
              {/* @highlight-end */}
            </Menu.Popup>
          </Menu.Positioner>
        </Menu.Portal>
      </Menu.Root>

      {/* @highlight-start */}
      {/* Control the dialog state */}
      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
        {/* @highlight-end */}
        <Dialog.Portal>
          <Dialog.Backdrop />
          <Dialog.Popup>
            {/* prettier-ignore */}
            {/* Rest of the dialog */}
          </Dialog.Popup>
        </Dialog.Portal>
      </Dialog.Root>
    </React.Fragment>
  );
}

Detached triggers

A menu can be opened by a trigger that lives either inside or outside the <Menu.Root>. Keep the trigger inside <Menu.Root> for simple, tightly coupled layouts like the hero demo at the top of this page. When the trigger and menu content need to live in different parts of the tree (for example, in a card list that controls a menu rendered near the document root), create a handle with Menu.createHandle() and pass it to both the trigger and the root.

Note that only top-level menus can have detached triggers. Submenus must have their triggers defined within the SubmenuRoot part.

The imperative methods on the handle, such as open() and close(), require a <Menu.Root> using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

Detached triggers

const demoMenu = Menu.createHandle();

// @highlight
// @highlight-text "handle={demoMenu}"
<Menu.Trigger handle={demoMenu}>
  Actions
</Menu.Trigger>

// @highlight
// @highlight-text "handle={demoMenu}"
<Menu.Root handle={demoMenu}>
  <Menu.Portal>
    <Menu.Positioner>
      <Menu.Popup>
        <Menu.Item>Edit</Menu.Item>
        <Menu.Item>Share</Menu.Item>
      </Menu.Popup>
    </Menu.Positioner>
  </Menu.Portal>
</Menu.Root>

Multiple triggers

One menu can be opened by several triggers. You can either render multiple <Menu.Trigger> components inside the same <Menu.Root>, or attach several detached triggers to the same handle.

Multiple triggers within the Root part

<Menu.Root>
  <Menu.Trigger>Row actions</Menu.Trigger>
  <Menu.Trigger>Quick actions</Menu.Trigger>
  {/* Rest of the menu */}
</Menu.Root>

Multiple detached triggers

const projectMenu = Menu.createHandle();

<Menu.Trigger handle={projectMenu}>Row actions</Menu.Trigger>
<Menu.Trigger handle={projectMenu}>Quick actions</Menu.Trigger>

<Menu.Root handle={projectMenu}>
  {/* Rest of the menu */}
</Menu.Root>

Menus can render different content depending on which trigger opened them. Pass a payload prop to each <Menu.Trigger> and read it via a function child on <Menu.Root>. Provide a type argument to createHandle() to strongly type the payload.

Detached triggers with payload

const menus = {
  file: ['New', 'Open', 'Save'],
  edit: ['Undo', 'Redo', 'Cut', 'Copy', 'Paste'],
}

// @highlight
const demoMenu = Menu.createHandle<{ items: string[] }>();

// @highlight
// @highlight-text "payload"
<Menu.Trigger handle={demoMenu} payload={{ items: menus.file }}>
  File
</Menu.Trigger>

// @highlight
// @highlight-text "payload"
<Menu.Trigger handle={demoMenu} payload={{ items: menus.edit }}>
  Edit
</Menu.Trigger>

<Menu.Root handle={demoMenu}>
  {({ payload }) => ( // @highlight-text "payload"
    <Menu.Portal>
      <Menu.Positioner>
        <Menu.Popup>
          <Menu.Viewport>
            {(payload?.items ?? []).map((item) => ( // @highlight-text "payload"
              <Menu.Item key={item}>{item}</Menu.Item>
            ))}
          </Menu.Viewport>
        </Menu.Popup>
      </Menu.Positioner>
    </Menu.Portal>
  )}
</Menu.Root>

Controlled mode with multiple triggers

Control a menu's open state externally with the open and onOpenChange props on <Menu.Root>. When more than one trigger can open the menu, track the active trigger with the triggerId prop on <Menu.Root> and matching id props on each <Menu.Trigger>. The onOpenChange callback receives eventDetails, which includes the DOM element that initiated the change, so you can update your triggerId state when the user activates a different trigger.

Arrow

Use the <Menu.Arrow> part inside the popup to visually connect the menu to its trigger.

When one menu is opened by multiple detached triggers, you can animate the menu as it moves between triggers. This includes animating position, size, and content.

Position and Size

To animate the menu's position, apply CSS transitions to the left, right, top, and bottom properties of the Positioner part. To animate its size, transition the width and height of the Popup part.

Content

The menu also supports content transitions. This is useful when different triggers display different content within the same menu.

To enable content animations, wrap the menu content in the <Menu.Viewport> part. This part renders a div with data-activation-direction, containing up to two space-separated tokens — a horizontal (left or right) and a vertical (up or down) value — so you can make direction-aware animations.

Inside <Menu.Viewport>, content is wrapped in divs with transition data attributes:

data-current: The currently visible content when no transitions are present or the incoming content.
data-previous: The outgoing content during a transition.

API reference

Root

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

Root Props:

Prop	Type	Default	Description
defaultOpen	`boolean`	`false`	Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
open	`boolean`	-	Whether the menu is currently open.
onOpenChange	`((open: boolean, eventDetails: Menu.Root.ChangeEventDetails) => void)`	-	Event handler called when the menu is opened or closed.
highlightItemOnHover	`boolean`	`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.
actionsRef	`React.RefObject<Menu.Root.Actions \| null>`	-	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.
closeParentOnEsc	`boolean`	`false`	When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
defaultTriggerId	`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.
handle	`Menu.Handle<Payload>`	-	A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.
loopFocus	`boolean`	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
modal	`boolean`	`true`	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. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal.
onOpenChangeComplete	`((open: boolean) => void)`	-	Event handler called after any animations complete when the menu is opened or closed.
triggerId	`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).
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
orientation	`Menu.Root.Orientation`	`'vertical'`	The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
children	`React.ReactNode \| PayloadChildRenderFunction<Payload>`	-	The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger.

Root.Props

Re-export of Root props.

Root.State

type MenuRootState = {};

Root.Actions

type MenuRootActions = { unmount: () => void; close: () => void };

Root.ChangeEventReason

type MenuRootChangeEventReason =
  | 'trigger-hover'
  | 'trigger-focus'
  | 'trigger-press'
  | 'outside-press'
  | 'focus-out'
  | 'list-navigation'
  | 'escape-key'
  | 'item-press'
  | 'close-press'
  | 'sibling-open'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

Root.ChangeEventDetails

type MenuRootChangeEventDetails = (
  | { reason: 'none'; event: Event }
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};

Root.Orientation

type MenuRootOrientation = 'horizontal' | 'vertical';

Trigger

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

Trigger Props:

Prop	Type	Default	Description
handle	`Menu.Handle<Payload>`	-	A handle to associate the trigger with a menu.
nativeButton	`boolean`	`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>`).
payload	`Payload`	-	A payload to pass to the menu when it is opened.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
openOnHover	`boolean`	-	Whether the menu should also open when the trigger is hovered.
delay	`number`	`100`	How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
closeDelay	`number`	`0`	How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
children	`React.ReactNode`	-	-
className	`string \| ((state: Menu.Trigger.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Trigger.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Trigger.State) => 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.

Trigger Data Attributes:

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

Trigger.Props

Re-export of Trigger props.

Trigger.State

type MenuTriggerState = {
  /** Whether the menu is currently open and was opened by this trigger. */
  open: boolean;
  /** Whether the trigger is disabled. */
  disabled: boolean;
};

Portal

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

Portal Props:

Prop	Type	Default	Description
container	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	-	A parent element to render the portal element into.
className	`string \| ((state: Menu.Portal.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Portal.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted	`boolean`	`false`	Whether to keep the portal mounted in the DOM while the popup is hidden.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Portal.State) => 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.

Portal.Props

Re-export of Portal props.

Portal.State

type MenuPortalState = {};

Backdrop

An overlay displayed beneath the menu popup. Renders a <div> element.

Backdrop Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.Backdrop.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Backdrop.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Backdrop.State) => 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.

Backdrop Data Attributes:

Attribute	Type	Description
data-open	-	Present when the menu is open.
data-closed	-	Present when the menu is closed.
data-starting-style	-	Present when the menu begins animating in.
data-ending-style	-	Present when the menu is animating out.

Backdrop.Props

Re-export of Backdrop props.

Backdrop.State

type MenuBackdropState = {
  /** Whether the menu is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Positioner

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

Positioner Props:

Prop	Type	Default	Description
disableAnchorTracking	`boolean`	`false`	Whether to disable the popup from tracking any layout shift of its positioning anchor.
align	`Align`	`'center'`	How to align the popup relative to the specified side. Submenus and menubars default to `'start'`.
alignOffset	`number \| OffsetFunction`	`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.
side	`Side`	`'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	`number \| OffsetFunction`	`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.
arrowPadding	`number`	`5`	Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
anchor	`Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`	-	An element to position the popup against. By default, the popup will be positioned against the trigger.
collisionAvoidance	`CollisionAvoidance`	-	Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`).`'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible.`'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.`'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit.`'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR).`'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR).`'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`.
collisionBoundary	`Boundary`	`'clipping-ancestors'`	An element or a rectangle that delimits the area that the popup is confined to.
collisionPadding	`Padding`	`5`	Additional space to maintain from the edge of the collision boundary.
sticky	`boolean`	`false`	Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
positionMethod	`'absolute' \| 'fixed'`	`'absolute'`	Determines which CSS `position` property to use.
className	`string \| ((state: Menu.Positioner.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Positioner.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Positioner.State) => 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.

alignOffset Prop Example:

<Positioner
  alignOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.width : anchor.height;
  }}
/>

sideOffset Prop Example:

<Positioner
  sideOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.height : anchor.width;
  }}
/>

collisionAvoidance Prop Example:

<Positioner
  collisionAvoidance={{
    side: 'shift',
    align: 'shift',
    fallbackAxisSide: 'none',
  }}
/>

Positioner Data Attributes:

Attribute	Type	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-align	`'start' \| 'center' \| 'end'`	Indicates how the popup is aligned relative to the specified side.
data-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`	Indicates which side the popup is positioned relative to the anchor.

Positioner CSS Variables:

Variable	Type	Description
`--anchor-height`	`number`	The anchor's height.
`--anchor-width`	`number`	The anchor's width.
`--available-height`	`number`	The available height between the anchor and the edge of the viewport.
`--available-width`	`number`	The available width between the anchor and the edge of the viewport.
`--positioner-height`	`number`	The height of the menu's positioner. It is important to set `height` to this value when using CSS to animate size changes.
`--positioner-width`	`number`	The width of the menu's positioner. It is important to set `width` to this value when using CSS to animate size changes.
`--transform-origin`	`string`	The coordinates that this element is anchored to. Used for animations and transitions.

Positioner.Props

Re-export of Positioner props.

Positioner.State

type MenuPositionerState = {
  /** Whether the menu is currently open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the anchor element is hidden. */
  anchorHidden: boolean;
  /** Whether the component is nested. */
  nested: boolean;
  /** Whether CSS transitions should be disabled. */
  instant: string | undefined;
};

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

Popup Props:

Prop	Type	Default	Description
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	-	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.
children	`React.ReactNode`	-	-
className	`string \| ((state: Menu.Popup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Popup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Popup.State) => 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.

Popup Data Attributes:

Attribute	Type	Description
data-open	-	Present when the menu is open.
data-closed	-	Present when the menu is closed.
data-align	`'start' \| 'center' \| 'end'`	Indicates how the popup is aligned relative to specified side.
data-instant	`'click' \| 'dismiss' \| 'group' \| 'trigger-change'`	Present if animations should be instant.
data-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`	Indicates which side the popup is positioned relative to the anchor.
data-starting-style	-	Present when the menu begins animating in.
data-ending-style	-	Present when the menu is animating out.

Popup.Props

Re-export of Popup props.

Popup.State

type MenuPopupState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the menu is currently open. */
  open: boolean;
  /** Whether the component is nested. */
  nested: boolean;
  /** Whether transitions should be skipped. */
  instant: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
};

Arrow

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

Arrow Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.Arrow.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Arrow.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Arrow.State) => 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.

Arrow Data Attributes:

Attribute	Type	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-align	`'start' \| 'center' \| 'end'`	Indicates how the popup is aligned relative to specified side.
data-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`	Indicates which side the popup is positioned relative to the anchor.

Arrow.Props

Re-export of Arrow props.

Arrow.State

type MenuArrowState = {
  /** Whether the menu is currently open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side;
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the arrow cannot be centered on the anchor. */
  uncentered: boolean;
};

Item

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

Item Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	The click handler for the menu item.
closeOnClick	`boolean`	`true`	Whether to close the menu when the item is clicked.
nativeButton	`boolean`	`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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Menu.Item.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Item.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Item.State) => 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.

Item Data Attributes:

Attribute	Type	Description
data-highlighted	-	Present when the menu item is highlighted.
data-disabled	-	Present when the menu item is disabled.

Item.Props

Re-export of Item props.

Item.State

type MenuItemState = {
  /** Whether the item should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
};

Viewport

A viewport for displaying content transitions. This component is only required if one popup can be opened by multiple triggers, its content changes based on the trigger, and switching between them is animated. Renders a <div> element.

Viewport Props:

Prop	Type	Default	Description
children	`React.ReactNode`	-	The content to render inside the transition container.
className	`string \| ((state: Menu.Viewport.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Viewport.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Viewport.State) => 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.

Viewport Data Attributes:

Attribute	Type	Description
data-activation-direction	`${'left' \| 'right' \| ''} ${'down' \| 'up' \| ''}`	Indicates the direction from which the popup was activated. This can be used to create directional animations based on how the popup was triggered. Contains space-separated values for both horizontal and vertical axes.
data-current	-	Applied to the direct child of the viewport when no transitions are present or the new content when it's entering.
data-instant	`'click' \| 'dismiss' \| 'group' \| 'trigger-change'`	Present if animations should be instant.
data-previous	-	Applied to the direct child of the viewport that contains the exiting content when transitions are present.
data-transitioning	-	Indicates that the viewport is currently transitioning between old and new content.

Viewport CSS Variables:

Variable	Type	Description
`--popup-height`	``	The height of the parent popup. This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.
`--popup-width`	``	The width of the parent popup. This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered. It can be used to freeze the dimensions of the popup when animating between different content.

Viewport.Props

Re-export of Viewport props.

Viewport.State

type MenuViewportState = {
  /** The activation direction of the transitioned content. */
  activationDirection: string | undefined;
  /** Whether the viewport is currently transitioning between contents. */
  transitioning: boolean;
  /** Present if animations should be instant. */
  instant: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
};

Group

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

Group Props:

Prop	Type	Default	Description
children	`React.ReactNode`	-	The content of the component.
className	`string \| ((state: Menu.Group.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Group.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Group.State) => 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.

Group.Props

Re-export of Group props.

Group.State

type MenuGroupState = {};

GroupLabel

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

GroupLabel Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.GroupLabel.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.GroupLabel.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.GroupLabel.State) => 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.

GroupLabel.Props

Re-export of GroupLabel props.

GroupLabel.State

type MenuGroupLabelState = {};

Separator

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

Separator Props:

Prop	Type	Default	Description
orientation	`Orientation`	`'horizontal'`	The orientation of the separator.
className	`string \| ((state: SeparatorState) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: SeparatorState) => 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.

Separator.Props

Re-export of Separator props.

Separator.State

type MenuSeparatorState = {
  /** The orientation of the separator. */
  orientation: Orientation;
};

SubmenuRoot

Groups all parts of a submenu. Doesn't render its own HTML element.

SubmenuRoot Props:

Prop	Type	Default	Description
defaultOpen	`boolean`	`false`	Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
open	`boolean`	-	Whether the menu is currently open.
onOpenChange	`((open: boolean, eventDetails: Menu.SubmenuRoot.ChangeEventDetails) => void)`	-	Event handler called when the menu is opened or closed.
highlightItemOnHover	`boolean`	`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.
actionsRef	`React.RefObject<Menu.Root.Actions \| null>`	-	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.
closeParentOnEsc	`boolean`	`false`	When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
loopFocus	`boolean`	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
onOpenChangeComplete	`((open: boolean) => void)`	-	Event handler called after any animations complete when the menu is opened or closed.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
orientation	`Menu.Root.Orientation`	`'vertical'`	The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
children	`React.ReactNode`	-	The content of the submenu.

SubmenuRoot.Props

Re-export of SubmenuRoot props.

SubmenuRoot.State

type MenuSubmenuRootState = {};

SubmenuRoot.ChangeEventReason

type MenuSubmenuRootChangeEventReason =
  | 'trigger-hover'
  | 'trigger-focus'
  | 'trigger-press'
  | 'outside-press'
  | 'focus-out'
  | 'list-navigation'
  | 'escape-key'
  | 'item-press'
  | 'close-press'
  | 'sibling-open'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

SubmenuRoot.ChangeEventDetails

type MenuSubmenuRootChangeEventDetails = (
  | { reason: 'none'; event: Event }
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};

SubmenuTrigger

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

SubmenuTrigger Props:

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

SubmenuTrigger Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding submenu is open.
data-highlighted	-	Present when the submenu trigger is highlighted.
data-disabled	-	Present when the submenu trigger is disabled.

SubmenuTrigger.Props

Re-export of SubmenuTrigger props.

SubmenuTrigger.State

type MenuSubmenuTriggerState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
  /** Whether the menu is currently open. */
  open: boolean;
};

RadioGroup

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

RadioGroup Props:

Prop	Type	Default	Description
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.
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.
onValueChange	`((value: any, eventDetails: Menu.RadioGroup.ChangeEventDetails) => void)`	-	Function called when the selected value changes.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
children	`React.ReactNode`	-	The content of the component.
className	`string \| ((state: Menu.RadioGroup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.RadioGroup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.RadioGroup.State) => 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.

RadioGroup.Props

Re-export of RadioGroup props.

RadioGroup.State

type MenuRadioGroupState = {
  /** Whether the component is disabled. */
  disabled: boolean;
};

RadioGroup.ChangeEventReason

type MenuRadioGroupChangeEventReason =
  | 'trigger-hover'
  | 'trigger-focus'
  | 'trigger-press'
  | 'outside-press'
  | 'focus-out'
  | 'list-navigation'
  | 'escape-key'
  | 'item-press'
  | 'close-press'
  | 'sibling-open'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

RadioGroup.ChangeEventDetails

type MenuRadioGroupChangeEventDetails = (
  | { reason: 'none'; event: Event }
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};

RadioItem

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

RadioItem Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
value*	`any`	-	Value of the radio item. This is the value that will be set in the Menu.RadioGroup when the item is selected.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	The click handler for the menu item.
closeOnClick	`boolean`	`false`	Whether to close the menu when the item is clicked.
nativeButton	`boolean`	`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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Menu.RadioItem.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.RadioItem.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.RadioItem.State) => 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.

RadioItem Data Attributes:

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

RadioItem.Props

Re-export of RadioItem props.

RadioItem.State

type MenuRadioItemState = {
  /** Whether the radio item should ignore user interaction. */
  disabled: boolean;
  /** Whether the radio item is currently highlighted. */
  highlighted: boolean;
  /** Whether the radio item is currently selected. */
  checked: boolean;
};

RadioItemIndicator

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

RadioItemIndicator Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.RadioItemIndicator.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.RadioItemIndicator.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted	`boolean`	`false`	Whether to keep the HTML element in the DOM when the radio item is inactive.
render	`ReactElement \| ((props: HTMLProps, state: Menu.RadioItemIndicator.State) => 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.

RadioItemIndicator Data Attributes:

Attribute	Type	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 begins animating in.
data-ending-style	-	Present when the radio indicator is animating out.

RadioItemIndicator.Props

Re-export of RadioItemIndicator props.

RadioItemIndicator.State

type MenuRadioItemIndicatorState = {
  /** Whether the radio item is currently selected. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

CheckboxItem

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

CheckboxItem Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
defaultChecked	`boolean`	`false`	Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead.
checked	`boolean`	-	Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
onCheckedChange	`((checked: boolean, eventDetails: Menu.CheckboxItem.ChangeEventDetails) => void)`	-	Event handler called when the checkbox item is ticked or unticked.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	The click handler for the menu item.
closeOnClick	`boolean`	`false`	Whether to close the menu when the item is clicked.
nativeButton	`boolean`	`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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Menu.CheckboxItem.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.CheckboxItem.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.CheckboxItem.State) => 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.

CheckboxItem Data Attributes:

Attribute	Type	Description
data-checked	-	Present when the menu checkbox item is checked.
data-unchecked	-	Present when the menu checkbox item is not checked.
data-highlighted	-	Present when the menu checkbox item is highlighted.
data-disabled	-	Present when the menu checkbox item is disabled.

CheckboxItem.Props

Re-export of CheckboxItem props.

CheckboxItem.State

type MenuCheckboxItemState = {
  /** Whether the checkbox item should ignore user interaction. */
  disabled: boolean;
  /** Whether the checkbox item is currently highlighted. */
  highlighted: boolean;
  /** Whether the checkbox item is currently ticked. */
  checked: boolean;
};

CheckboxItem.ChangeEventReason

type MenuCheckboxItemChangeEventReason =
  | 'trigger-hover'
  | 'trigger-focus'
  | 'trigger-press'
  | 'outside-press'
  | 'focus-out'
  | 'list-navigation'
  | 'escape-key'
  | 'item-press'
  | 'close-press'
  | 'sibling-open'
  | 'cancel-open'
  | 'imperative-action'
  | 'none';

CheckboxItem.ChangeEventDetails

type MenuCheckboxItemChangeEventDetails = (
  | { reason: 'none'; event: Event }
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};

CheckboxItemIndicator

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

CheckboxItemIndicator Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.CheckboxItemIndicator.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.CheckboxItemIndicator.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted	`boolean`	`false`	Whether to keep the HTML element in the DOM when the checkbox item is not checked.
render	`ReactElement \| ((props: HTMLProps, state: Menu.CheckboxItemIndicator.State) => 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.

CheckboxItemIndicator Data Attributes:

Attribute	Type	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 begins animating in.
data-ending-style	-	Present when the indicator is animating out.

CheckboxItemIndicator.Props

Re-export of CheckboxItemIndicator props.

CheckboxItemIndicator.State

type MenuCheckboxItemIndicatorState = {
  /** Whether the checkbox item is currently ticked. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

createHandle

Creates a new handle to connect a Menu.Root with detached Menu.Trigger components.

Return Value:

type ReturnValue = Menu.Handle<Payload>;

Handle

Controls a Menu imperatively and associates detached Menu.Trigger components with a Menu.Root. Create one with Menu.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.

Properties:

Property	Type	Modifiers	Description
isOpen	`boolean`	readonly	Whether the menu is currently open. Returns `false` while no root is attached to the handle.

Methods:

function open(triggerId: string): void;

Opens the menu and associates it with the trigger with the given id.

This method should only be called in an event handler or an effect (not during rendering).

function close(): void;

Closes the menu.

This method should only be called in an event handler or an effect (not during rendering).

LinkItem

A link in the menu that can be used to navigate to a different page or section. Renders an <a> element.

LinkItem Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
closeOnClick	`boolean`	`false`	Whether to close the menu when the item is clicked.
className	`string \| ((state: Menu.LinkItem.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.LinkItem.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, state: Menu.LinkItem.State) => 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.

LinkItem Data Attributes:

Attribute	Type	Description
data-highlighted	-	Present when the link is highlighted.

LinkItem.Props

Re-export of LinkItem props.

LinkItem.State

type MenuLinkItemState = {
  /** Whether the item is highlighted. */
  highlighted: boolean;
};

Additional Types

MenuParent

type MenuParent =
  | { type: 'menu'; store: MenuStore<unknown> }
  | { type: 'menubar'; context: MenubarContext }
  | { type: 'context-menu'; context: ContextMenuRootContext }
  | { type: 'nested-context-menu'; context: ContextMenuRootContext; menuContext: MenuRootContext }
  | { type: undefined };

External Types

Side

type Side = 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';

Align

type Align = 'start' | 'center' | 'end';

preventUnmountOnClose

type preventUnmountOnClose = () => void;

InteractionType

type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';

OffsetFunction

type OffsetFunction = (data: {
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  align: 'start' | 'center' | 'end';
  anchor: { width: number; height: number };
  positioner: { width: number; height: number };
}) => number;

PayloadChildRenderFunction

type PayloadChildRenderFunction = (arg: { payload: unknown | undefined }) => ReactNode;

Export Groups

Menu.Arrow: Menu.Arrow, Menu.Arrow.State, Menu.Arrow.Props
Menu.Backdrop: Menu.Backdrop, Menu.Backdrop.State, Menu.Backdrop.Props
Menu.CheckboxItem: Menu.CheckboxItem, Menu.CheckboxItem.State, Menu.CheckboxItem.Props, Menu.CheckboxItem.ChangeEventReason, Menu.CheckboxItem.ChangeEventDetails
Menu.CheckboxItemIndicator: Menu.CheckboxItemIndicator, Menu.CheckboxItemIndicator.Props, Menu.CheckboxItemIndicator.State
Menu.Group: Menu.Group, Menu.Group.Props, Menu.Group.State
Menu.GroupLabel: Menu.GroupLabel, Menu.GroupLabel.Props, Menu.GroupLabel.State
Menu.Item: Menu.Item, Menu.Item.State, Menu.Item.Props
Menu.LinkItem: Menu.LinkItem, Menu.LinkItem.State, Menu.LinkItem.Props
Menu.Popup: Menu.Popup, Menu.Popup.Props, Menu.Popup.State
Menu.Portal: Menu.Portal, Menu.Portal.State, Menu.Portal.Props
Menu.Positioner: Menu.Positioner, Menu.Positioner.State, Menu.Positioner.Props
Menu.RadioGroup: Menu.RadioGroup, Menu.RadioGroup.Props, Menu.RadioGroup.State, Menu.RadioGroup.ChangeEventReason, Menu.RadioGroup.ChangeEventDetails
Menu.RadioItem: Menu.RadioItem, Menu.RadioItem.State, Menu.RadioItem.Props
Menu.RadioItemIndicator: Menu.RadioItemIndicator, Menu.RadioItemIndicator.Props, Menu.RadioItemIndicator.State
Menu.Root: Menu.Root, Menu.Root.State, Menu.Root.Props, Menu.Root.Actions, Menu.Root.ChangeEventReason, Menu.Root.ChangeEventDetails, Menu.Root.Orientation
Menu.SubmenuRoot: Menu.SubmenuRoot, Menu.SubmenuRoot.Props, Menu.SubmenuRoot.State, Menu.SubmenuRoot.ChangeEventReason, Menu.SubmenuRoot.ChangeEventDetails
Menu.Trigger: Menu.Trigger, Menu.Trigger.Props, Menu.Trigger.State
Menu.Viewport: Menu.Viewport, Menu.Viewport.Props, Menu.Viewport.State
Menu.Separator: Menu.Separator, Menu.Separator.Props, Menu.Separator.State
Menu.SubmenuTrigger: Menu.SubmenuTrigger, Menu.SubmenuTrigger.Props, Menu.SubmenuTrigger.State
Menu.Handle
Menu.createHandle
Default: MenuRootState, MenuRootProps, MenuRootActions, MenuRootChangeEventReason, MenuRootChangeEventDetails, MenuRootOrientation, MenuParent, MenuArrowState, MenuArrowProps, MenuBackdropState, MenuBackdropProps, MenuCheckboxItemState, MenuCheckboxItemProps, MenuCheckboxItemChangeEventReason, MenuCheckboxItemChangeEventDetails, MenuCheckboxItemIndicatorProps, MenuCheckboxItemIndicatorState, MenuGroupLabelProps, MenuGroupLabelState, MenuGroupProps, MenuGroupState, MenuItemState, MenuItemProps, MenuLinkItemState, MenuLinkItemProps, MenuPopupProps, MenuPopupState, MenuPortalState, MenuPortalProps, MenuPositionerState, MenuPositionerProps, MenuRadioGroupProps, MenuRadioGroupState, MenuRadioGroupChangeEventReason, MenuRadioGroupChangeEventDetails, MenuRadioItemState, MenuRadioItemProps, MenuRadioItemIndicatorProps, MenuRadioItemIndicatorState, MenuSubmenuRootProps, MenuSubmenuRootState, MenuSubmenuRootChangeEventReason, MenuSubmenuRootChangeEventDetails, MenuTriggerProps, MenuTriggerState, MenuSubmenuTriggerState, MenuSubmenuTriggerProps, MenuViewportState, MenuViewportProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

Menu.Arrow.State: MenuArrowState
Menu.Arrow.Props: MenuArrowProps
Menu.Backdrop.State: MenuBackdropState
Menu.Backdrop.Props: MenuBackdropProps
Menu.CheckboxItem.State: MenuCheckboxItemState
Menu.CheckboxItem.Props: MenuCheckboxItemProps
Menu.CheckboxItem.ChangeEventReason: MenuCheckboxItemChangeEventReason
Menu.CheckboxItem.ChangeEventDetails: MenuCheckboxItemChangeEventDetails
Menu.CheckboxItemIndicator.Props: MenuCheckboxItemIndicatorProps
Menu.CheckboxItemIndicator.State: MenuCheckboxItemIndicatorState
Menu.Group.Props: MenuGroupProps
Menu.Group.State: MenuGroupState
Menu.GroupLabel.Props: MenuGroupLabelProps
Menu.GroupLabel.State: MenuGroupLabelState
Menu.Item.State: MenuItemState
Menu.Item.Props: MenuItemProps
Menu.LinkItem.State: MenuLinkItemState
Menu.LinkItem.Props: MenuLinkItemProps
Menu.Popup.Props: MenuPopupProps
Menu.Popup.State: MenuPopupState
Menu.Portal.State: MenuPortalState
Menu.Portal.Props: MenuPortalProps
Menu.Positioner.State: MenuPositionerState
Menu.Positioner.Props: MenuPositionerProps
Menu.RadioGroup.Props: MenuRadioGroupProps
Menu.RadioGroup.State: MenuRadioGroupState
Menu.RadioGroup.ChangeEventReason: MenuRadioGroupChangeEventReason
Menu.RadioGroup.ChangeEventDetails: MenuRadioGroupChangeEventDetails
Menu.RadioItem.State: MenuRadioItemState
Menu.RadioItem.Props: MenuRadioItemProps
Menu.RadioItemIndicator.Props: MenuRadioItemIndicatorProps
Menu.RadioItemIndicator.State: MenuRadioItemIndicatorState
Menu.Root.State: MenuRootState
Menu.Root.Props: MenuRootProps
Menu.Root.Actions: MenuRootActions
Menu.Root.ChangeEventReason: MenuRootChangeEventReason
Menu.Root.ChangeEventDetails: MenuRootChangeEventDetails
Menu.Root.Orientation: MenuRootOrientation
Menu.SubmenuRoot.Props: MenuSubmenuRootProps
Menu.SubmenuRoot.State: MenuSubmenuRootState
Menu.SubmenuRoot.ChangeEventReason: MenuSubmenuRootChangeEventReason
Menu.SubmenuRoot.ChangeEventDetails: MenuSubmenuRootChangeEventDetails
Menu.Trigger.Props: MenuTriggerProps
Menu.Trigger.State: MenuTriggerState
Menu.Viewport.Props: MenuViewportProps
Menu.Viewport.State: MenuViewportState
Menu.SubmenuTrigger.Props: MenuSubmenuTriggerProps
Menu.SubmenuTrigger.State: MenuSubmenuTriggerState

In Nyte

Anatomy

Examples

Open on hover

Checkbox items

Radio items

Close on click

Group labels

Nested menu

Navigate to another page

Open a dialog

Detached triggers

Multiple triggers

Controlled mode with multiple triggers

Arrow

Animating the Menu

Position and Size

Content

API reference

Root

Root.Props

Root.State

Root.Actions

Root.ChangeEventReason

Root.ChangeEventDetails

Root.Orientation

Trigger

Trigger.Props

Trigger.State

Portal

Portal.Props

Portal.State

Backdrop

Backdrop.Props

Backdrop.State

Positioner

Positioner.Props

Positioner.State

Popup

Popup.Props

Popup.State

Arrow

Arrow.Props

Arrow.State

Item

Item.Props

Item.State

Viewport

Viewport.Props

Viewport.State

Group

Group.Props

Group.State

GroupLabel

GroupLabel.Props

GroupLabel.State

Separator

Separator.Props

Separator.State

SubmenuRoot

SubmenuRoot.Props

SubmenuRoot.State

SubmenuRoot.ChangeEventReason

SubmenuRoot.ChangeEventDetails

SubmenuTrigger

SubmenuTrigger.Props

SubmenuTrigger.State

RadioGroup

RadioGroup.Props

RadioGroup.State

RadioGroup.ChangeEventReason

RadioGroup.ChangeEventDetails

RadioItem

RadioItem.Props

RadioItem.State

RadioItemIndicator

RadioItemIndicator.Props

RadioItemIndicator.State

CheckboxItem

CheckboxItem.Props