Base UI

A menu that appears at the pointer on right click or long press.

Right click here

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

export default function ExampleMenu() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger className={styles.Trigger}>
        Right click here
      </ContextMenu.Trigger>
      <ContextMenu.Portal>
        <ContextMenu.Positioner className={styles.Positioner}>
          <ContextMenu.Popup className={styles.Popup}>
            <ContextMenu.Item className={styles.Item}>
              Add to Library
            </ContextMenu.Item>
            <ContextMenu.Item className={styles.Item}>
              Add to Playlist
            </ContextMenu.Item>
            <ContextMenu.Separator className={styles.Separator} />
            <ContextMenu.Item className={styles.Item}>Play Next</ContextMenu.Item>
            <ContextMenu.Item className={styles.Item}>Play Last</ContextMenu.Item>
            <ContextMenu.Separator className={styles.Separator} />
            <ContextMenu.Item className={styles.Item}>Favorite</ContextMenu.Item>
            <ContextMenu.Item className={styles.Item}>Share</ContextMenu.Item>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}

API reference

Import the components and place them together:

Anatomy

import { ContextMenu } from '@base-ui-components/react/context-menu';

<ContextMenu.Root>
  <ContextMenu.Trigger />
  <ContextMenu.Portal>
    <ContextMenu.Backdrop />
    <ContextMenu.Positioner>
      <ContextMenu.Popup>
        <ContextMenu.Arrow />
        <ContextMenu.Item />
        <ContextMenu.Separator />
        <ContextMenu.Group>
          <ContextMenu.GroupLabel />
        </ContextMenu.Group>
        <ContextMenu.RadioGroup>
          <ContextMenu.RadioItem />
        </ContextMenu.RadioGroup>
        <ContextMenu.CheckboxItem />
      </ContextMenu.Popup>
    </ContextMenu.Positioner>
  </ContextMenu.Portal>
</ContextMenu.Root>

Root

A component that creates a context menu activated by right clicking or long pressing. Doesn’t render its own HTML element.

Prop	Type	Default
`defaultOpen`	`boolean`	`false`
`open`	`boolean`	`undefined`
`onOpenChange`	`((open: boolean, event: Event \| undefined, reason: OpenChangeReason \| undefined) => void)`	`undefined`
`actionsRef`	`RefObject<{ unmount: () => void; }>`	`undefined`
`closeParentOnEsc`	`boolean`	`true`
`modal`	`boolean`	`true`
`onOpenChangeComplete`	`((open: boolean) => void)`	`undefined`
`disabled`	`boolean`	`false`
`openOnHover`	`boolean`	`undefined`
`delay`	`number`	`100`
`loop`	`boolean`	`true`
`orientation`	`MenuOrientation`	`'vertical'`
`children^*`	`ReactNode`	`—`

Trigger

An area that opens the menu on right click or long press. Renders a <div> element.

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

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`	`\| HTMLElement \| RefObject<HTMLElement \| null> \| null`	`undefined`
`children`	`ReactNode`	`undefined`
`keepMounted`	`boolean`	`false`

Positioner

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

Prop	Type	Default
`align`	`'center' \| 'end' \| 'start'`	`'center'`
`alignOffset`	`number \| OffsetFunction`	`0`
`side`	`Side`	`'bottom'`
`sideOffset`	`number \| OffsetFunction`	`0`
`arrowPadding`	`number`	`5`
`anchor`	`\| Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null`	`undefined`
`collisionBoundary`	`Boundary`	`'clipping-ancestors'`
`collisionPadding`	`Padding`	`5`
`sticky`	`boolean`	`false`
`positionMethod`	`'fixed' \| 'absolute'`	`'absolute'`
`trackAnchor`	`boolean`	`true`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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-align`	Indicates how the popup is aligned relative to specified side.
`data-side`	Indicates which side the popup 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
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Attribute	Description
`data-open`	Present when the menu is open.
`data-closed`	Present when the menu is closed.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-instant`	Present if animations should be instant.
`data-side`	Indicates which side the popup 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: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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-align`	Indicates how the popup is aligned relative to specified side.
`data-side`	Indicates which side the popup 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`	`MouseEventHandler<HTMLElement>`	`undefined`
`closeOnClick`	`boolean`	`true`
`disabled`	`boolean`	`false`
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

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

Group

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

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

GroupLabel

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

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

RadioGroup

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

Prop	Type	Default
`defaultValue`	`any`	`undefined`
`value`	`any`	`undefined`
`onValueChange`	`((value: any, event: Event) => void)`	`() => {}`
`disabled`	`boolean`	`false`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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`	`—`
`onClick`	`MouseEventHandler<HTMLElement>`	`undefined`
`closeOnClick`	`boolean`	`false`
`disabled`	`boolean`	`false`
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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-highlighted`	Present when the menu radio item is highlighted.
`data-disabled`	Present when the menu radio item is disabled.

RadioItemIndicator

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

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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: boolean, event: Event) => void)`	`undefined`
`onClick`	`MouseEventHandler<HTMLElement>`	`undefined`
`closeOnClick`	`boolean`	`false`
`disabled`	`boolean`	`false`
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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-highlighted`	Present when the menu checkbox item is highlighted.
`data-disabled`	Present when the menu checkbox item is disabled.

CheckboxItemIndicator

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

Prop	Type	Default
`className`	`string \| ((state: State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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`
`onClick`	`MouseEventHandler<HTMLElement>`	`undefined`
`id`	`string`	`undefined`
`children`	`ReactNode`	`undefined`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => 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
`orientation`	`Orientation`	`'horizontal'`
`className`	`string \| ((state: State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: GenericHTMLProps, state: State) => ReactElement)`	`undefined`

Examples

Advanced demos are available at the main Menu page, most of which apply to the context menu as well.

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