Design system
Docs
Headless

Context Menu

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

In Nyte

Import
import { ContextMenu } from "@nyte-ai/ui/context-menu";

@nyte-ai/ui/context-menu re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

  • desktop/src/renderer/src/components/menu.tsx

The rest of this page is Base UI's documentation for @base-ui/react/context-menu, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above.

Usage guidelines

  • Use context menus as an enhancement: Don't make a context menu the only way to perform actions. Users may not discover or be able to open a context menu, especially on touch devices or with assistive technology. Always provide visible controls for the actions that are available in the context menu.

Anatomy

Import the components and place them together:

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

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

        <ContextMenu.SubmenuRoot>
          <ContextMenu.SubmenuTrigger />
        </ContextMenu.SubmenuRoot>

        <ContextMenu.Group>
          <ContextMenu.GroupLabel />
        </ContextMenu.Group>

        <ContextMenu.RadioGroup>
          <ContextMenu.RadioItem>
            <ContextMenu.RadioItemIndicator />
          </ContextMenu.RadioItem>
        </ContextMenu.RadioGroup>

        <ContextMenu.CheckboxItem>
          <ContextMenu.CheckboxItemIndicator />
        </ContextMenu.CheckboxItem>
      </ContextMenu.Popup>
    </ContextMenu.Positioner>
  </ContextMenu.Portal>
</ContextMenu.Root>;

Examples

Menu displays additional demos, many of which apply to the context menu as well.

Using with Menu

A context menu should supplement a primary way to perform the same actions. This image card exposes actions through a visible menu button and reuses them in the context menu for right-click and long-press users.

Nested menu

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

API reference

Root

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

Root Props:

PropTypeDefaultDescription
defaultOpenbooleanfalseWhether the menu is initially open. To render a controlled menu, use the open prop instead.
openboolean-Whether the menu is currently open.
onOpenChange((open: boolean, eventDetails: ContextMenu.Root.ChangeEventDetails) => void)-Event handler called when the menu is opened or closed.
highlightItemOnHoverbooleantrueWhether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.
actionsRefReact.RefObject<MenuRoot.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.
loopFocusbooleantrueWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
orientationMenuRoot.Orientation'vertical'The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
childrenReact.ReactNode--

Root.Props

Re-export of Root props.

Root.State

type ContextMenuRootState = {};

Root.Actions

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

Root.ChangeEventReason

type ContextMenuRootChangeEventReason =
  | '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 ContextMenuRootChangeEventDetails = (
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; 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;
};

Trigger

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

Trigger Props:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.Trigger.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Trigger.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
data-popup-open-Present when the corresponding context menu is open.
data-pressed-Present when the corresponding context menu is open.

Trigger.Props

Re-export of Trigger props.

Trigger.State

type ContextMenuTriggerState = {
  /** Whether the context menu is currently open. */
  open: 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:

PropTypeDefaultDescription
containerHTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null-A parent element to render the portal element into.
classNamestring | ((state: ContextMenu.Portal.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Portal.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
keepMountedbooleanfalseWhether to keep the portal mounted in the DOM while the popup is hidden.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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 ContextMenuPortalState = {};

Backdrop

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

Backdrop Props:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.Backdrop.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Backdrop.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuBackdropState = {
  /** Whether the menu is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Positioner

Positions the context menu popup against the pointer or a custom anchor. Renders a <div> element.

Positioner Props:

PropTypeDefaultDescription
disableAnchorTrackingbooleanfalseWhether to disable the popup from tracking any layout shift of its positioning anchor.
alignAlign'start'How to align the popup relative to the specified side.
alignOffsetnumber | OffsetFunction-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. Defaults to 2 for root context menus when side is not specified and align is not 'center'. Otherwise, it defaults to 0.
sideSide'bottom'Which side of the anchor element to align the popup against. May automatically change to avoid collisions. Submenus default to 'inline-end'.
sideOffsetnumber | OffsetFunction-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. Defaults to -5 for root context menus when side is not specified and align is not 'center'. Otherwise, it defaults to 0.
arrowPaddingnumber-Minimum distance to maintain between the arrow and the edges of the popup. Root context menus always use 0. Submenus default to 5.
anchorElement | VirtualElement | React.RefObject<Element | null> | (() => Element | VirtualElement | null) | null-An element to position the popup against. By default, root context menus are positioned at the pointer, and submenus are positioned against their trigger.
collisionAvoidanceCollisionAvoidance-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'.
collisionBoundaryBoundary'clipping-ancestors'An element or a rectangle that delimits the area that the popup is confined to.
collisionPaddingPadding5Additional space to maintain from the edge of the collision boundary.
stickybooleanfalseWhether to maintain the popup in the viewport after the anchor element was scrolled out of view.
classNamestring | ((state: ContextMenu.Positioner.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Positioner.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

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

sideOffset Prop Example:

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

collisionAvoidance Prop Example:

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

Positioner Data Attributes:

AttributeTypeDescription
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:

VariableTypeDescription
--anchor-heightnumberThe anchor's height.
--anchor-widthnumberThe anchor's width.
--available-heightnumberThe available height between the anchor and the edge of the viewport.
--available-widthnumberThe available width between the anchor and the edge of the viewport.
--positioner-heightnumberThe height of the menu's positioner. It is important to set height to this value when using CSS to animate size changes.
--positioner-widthnumberThe width of the menu's positioner. It is important to set width to this value when using CSS to animate size changes.
--transform-originstringThe coordinates that this element is anchored to. Used for animations and transitions.

Positioner.Props

Re-export of Positioner props.

Positioner.State

type ContextMenuPositionerState = {
  /** 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:

PropTypeDefaultDescription
finalFocusboolean | 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.
childrenReact.ReactNode--
classNamestring | ((state: ContextMenu.Popup.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Popup.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuPopupState = {
  /** 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:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.Arrow.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Arrow.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuArrowState = {
  /** 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:

PropTypeDefaultDescription
labelstring-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.
closeOnClickbooleantrueWhether to close the menu when the item is clicked.
nativeButtonbooleanfalseWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
classNamestring | ((state: ContextMenu.Item.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Item.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuItemState = {
  /** Whether the item should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
};

Group

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

Group Props:

PropTypeDefaultDescription
childrenReact.ReactNode-The content of the component.
classNamestring | ((state: ContextMenu.Group.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.Group.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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 ContextMenuGroupState = {};

GroupLabel

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

GroupLabel Props:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.GroupLabel.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.GroupLabel.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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 ContextMenuGroupLabelState = {};

Separator

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

Separator Props:

PropTypeDefaultDescription
orientationOrientation'horizontal'The orientation of the separator.
classNamestring | ((state: SeparatorState) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.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.
renderReactElement | ((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 ContextMenuSeparatorState = {
  /** The orientation of the separator. */
  orientation: Orientation;
};

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

SubmenuRoot Props:

PropTypeDefaultDescription
defaultOpenbooleanfalseWhether the menu is initially open. To render a controlled menu, use the open prop instead.
openboolean-Whether the menu is currently open.
onOpenChange((open: boolean, eventDetails: ContextMenu.SubmenuRoot.ChangeEventDetails) => void)-Event handler called when the menu is opened or closed.
highlightItemOnHoverbooleantrueWhether moving the pointer over items should highlight them. Disabling this prop allows CSS :hover to be differentiated from the :focus (data-highlighted) state.
actionsRefReact.RefObject<MenuRoot.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.
closeParentOnEscbooleanfalseWhen in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
loopFocusbooleantrueWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
orientationMenuRoot.Orientation'vertical'The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
childrenReact.ReactNode-The content of the submenu.

Re-export of SubmenuRoot props.

type ContextMenuSubmenuRootState = {};
type ContextMenuSubmenuRootChangeEventReason =
  | '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';
type ContextMenuSubmenuRootChangeEventDetails = (
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; 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;
};

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

SubmenuTrigger Props:

PropTypeDefaultDescription
labelstring-Overrides the text label to use when the item is matched during keyboard text navigation.
onClick((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)--
nativeButtonbooleanfalseWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
openOnHoverbooleantrueWhether the menu should also open when the trigger is hovered.
delaynumber100How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the openOnHover prop.
closeDelaynumber0How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the openOnHover prop.
classNamestring | ((state: ContextMenu.SubmenuTrigger.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.SubmenuTrigger.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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.

Re-export of SubmenuTrigger props.

type ContextMenuSubmenuTriggerState = {
  /** 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:

PropTypeDefaultDescription
defaultValueany-The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the value prop instead.
valueany-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: ContextMenu.RadioGroup.ChangeEventDetails) => void)-Function called when the selected value changes.
disabledbooleanfalseWhether the component should ignore user interaction.
childrenReact.ReactNode-The content of the component.
classNamestring | ((state: ContextMenu.RadioGroup.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.RadioGroup.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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 ContextMenuRadioGroupState = {
  /** Whether the component is disabled. */
  disabled: boolean;
};

RadioGroup.ChangeEventReason

type ContextMenuRadioGroupChangeEventReason =
  | '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 ContextMenuRadioGroupChangeEventDetails = (
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; 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:

PropTypeDefaultDescription
labelstring-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 ContextMenu.RadioGroup when the item is selected.
onClick((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)-The click handler for the menu item.
closeOnClickbooleanfalseWhether to close the menu when the item is clicked.
nativeButtonbooleanfalseWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
classNamestring | ((state: ContextMenu.RadioItem.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.RadioItem.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuRadioItemState = {
  /** 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:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.RadioItemIndicator.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.RadioItemIndicator.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
keepMountedbooleanfalseWhether to keep the HTML element in the DOM when the radio item is inactive.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuRadioItemIndicatorState = {
  /** 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:

PropTypeDefaultDescription
labelstring-Overrides the text label to use when the item is matched during keyboard text navigation.
defaultCheckedbooleanfalseWhether the checkbox item is initially ticked. To render a controlled checkbox item, use the checked prop instead.
checkedboolean-Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the defaultChecked prop instead.
onCheckedChange((checked: boolean, eventDetails: ContextMenu.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.
closeOnClickbooleanfalseWhether to close the menu when the item is clicked.
nativeButtonbooleanfalseWhether 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.
disabledbooleanfalseWhether the component should ignore user interaction.
classNamestring | ((state: ContextMenu.CheckboxItem.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.CheckboxItem.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuCheckboxItemState = {
  /** 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 ContextMenuCheckboxItemChangeEventReason =
  | '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 ContextMenuCheckboxItemChangeEventDetails = (
  | { reason: 'trigger-hover'; event: MouseEvent }
  | { reason: 'trigger-focus'; event: FocusEvent }
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'sibling-open'; event: Event }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; 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:

PropTypeDefaultDescription
classNamestring | ((state: ContextMenu.CheckboxItemIndicator.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.CheckboxItemIndicator.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
keepMountedbooleanfalseWhether to keep the HTML element in the DOM when the checkbox item is not checked.
renderReactElement | ((props: HTMLProps, state: ContextMenu.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:

AttributeTypeDescription
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 ContextMenuCheckboxItemIndicatorState = {
  /** 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;
};

LinkItem

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

LinkItem Props:

PropTypeDefaultDescription
labelstring-Overrides the text label to use when the item is matched during keyboard text navigation.
closeOnClickbooleanfalseWhether to close the menu when the item is clicked.
classNamestring | ((state: ContextMenu.LinkItem.State) => string | undefined)-CSS class applied to the element, or a function that returns a class based on the component's state.
styleReact.CSSProperties | ((state: ContextMenu.LinkItem.State) => React.CSSProperties | undefined)-Style applied to the element, or a function that returns a style object based on the component's state.
renderReactElement | ((props: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, state: ContextMenu.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:

AttributeTypeDescription
data-highlighted-Present when the link is highlighted.

LinkItem.Props

Re-export of LinkItem props.

LinkItem.State

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

External Types

Orientation

type Orientation = 'horizontal' | 'vertical';

Side

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

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;

Align

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

InteractionType

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

preventUnmountOnClose

type preventUnmountOnClose = () => void;

Export Groups

  • ContextMenu.Root: ContextMenu.Root, ContextMenu.Root.State, ContextMenu.Root.Props, ContextMenu.Root.Actions, ContextMenu.Root.ChangeEventReason, ContextMenu.Root.ChangeEventDetails
  • ContextMenu.Trigger: ContextMenu.Trigger, ContextMenu.Trigger.State, ContextMenu.Trigger.Props
  • ContextMenu.Backdrop: ContextMenu.Backdrop, ContextMenu.Backdrop.State, ContextMenu.Backdrop.Props
  • ContextMenu.Portal: ContextMenu.Portal, ContextMenu.Portal.State, ContextMenu.Portal.Props
  • ContextMenu.Positioner: ContextMenu.Positioner, ContextMenu.Positioner.Props, ContextMenu.Positioner.State
  • ContextMenu.Popup: ContextMenu.Popup, ContextMenu.Popup.Props, ContextMenu.Popup.State
  • ContextMenu.Arrow: ContextMenu.Arrow, ContextMenu.Arrow.State, ContextMenu.Arrow.Props
  • ContextMenu.Group: ContextMenu.Group, ContextMenu.Group.Props, ContextMenu.Group.State
  • ContextMenu.GroupLabel: ContextMenu.GroupLabel, ContextMenu.GroupLabel.Props, ContextMenu.GroupLabel.State
  • ContextMenu.Item: ContextMenu.Item, ContextMenu.Item.State, ContextMenu.Item.Props
  • ContextMenu.CheckboxItem: ContextMenu.CheckboxItem, ContextMenu.CheckboxItem.State, ContextMenu.CheckboxItem.Props, ContextMenu.CheckboxItem.ChangeEventReason, ContextMenu.CheckboxItem.ChangeEventDetails
  • ContextMenu.CheckboxItemIndicator: ContextMenu.CheckboxItemIndicator, ContextMenu.CheckboxItemIndicator.Props, ContextMenu.CheckboxItemIndicator.State
  • ContextMenu.LinkItem: ContextMenu.LinkItem, ContextMenu.LinkItem.State, ContextMenu.LinkItem.Props
  • ContextMenu.RadioGroup: ContextMenu.RadioGroup, ContextMenu.RadioGroup.Props, ContextMenu.RadioGroup.State, ContextMenu.RadioGroup.ChangeEventReason, ContextMenu.RadioGroup.ChangeEventDetails
  • ContextMenu.RadioItem: ContextMenu.RadioItem, ContextMenu.RadioItem.State, ContextMenu.RadioItem.Props
  • ContextMenu.RadioItemIndicator: ContextMenu.RadioItemIndicator, ContextMenu.RadioItemIndicator.Props, ContextMenu.RadioItemIndicator.State
  • ContextMenu.SubmenuRoot: ContextMenu.SubmenuRoot, ContextMenu.SubmenuRoot.Props, ContextMenu.SubmenuRoot.State, ContextMenu.SubmenuRoot.ChangeEventReason, ContextMenu.SubmenuRoot.ChangeEventDetails
  • ContextMenu.SubmenuTrigger: ContextMenu.SubmenuTrigger, ContextMenu.SubmenuTrigger.Props, ContextMenu.SubmenuTrigger.State
  • ContextMenu.Separator: ContextMenu.Separator, ContextMenu.Separator.Props, ContextMenu.Separator.State
  • Default: ContextMenuBackdropProps, ContextMenuBackdropState, ContextMenuPortalProps, ContextMenuPortalState, ContextMenuPopupProps, ContextMenuPopupState, ContextMenuArrowProps, ContextMenuArrowState, ContextMenuGroupProps, ContextMenuGroupState, ContextMenuGroupLabelProps, ContextMenuGroupLabelState, ContextMenuItemProps, ContextMenuItemState, ContextMenuLinkItemProps, ContextMenuLinkItemState, ContextMenuCheckboxItemProps, ContextMenuCheckboxItemState, ContextMenuCheckboxItemIndicatorProps, ContextMenuCheckboxItemIndicatorState, ContextMenuRadioGroupProps, ContextMenuRadioGroupState, ContextMenuRadioItemProps, ContextMenuRadioItemState, ContextMenuRadioItemIndicatorProps, ContextMenuRadioItemIndicatorState, ContextMenuSubmenuRootProps, ContextMenuSubmenuRootState, ContextMenuSubmenuTriggerProps, ContextMenuSubmenuTriggerState, ContextMenuRootState, ContextMenuRootProps, ContextMenuRootActions, ContextMenuRootChangeEventReason, ContextMenuRootChangeEventDetails, ContextMenuTriggerState, ContextMenuTriggerProps, ContextMenuPositionerState, ContextMenuPositionerProps

Canonical Types

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

  • ContextMenu.Root.State: ContextMenuRootState
  • ContextMenu.Root.Props: ContextMenuRootProps
  • ContextMenu.Root.Actions: ContextMenuRootActions
  • ContextMenu.Root.ChangeEventReason: ContextMenuRootChangeEventReason
  • ContextMenu.Root.ChangeEventDetails: ContextMenuRootChangeEventDetails
  • ContextMenu.Trigger.State: ContextMenuTriggerState
  • ContextMenu.Trigger.Props: ContextMenuTriggerProps
  • ContextMenu.Backdrop.State: ContextMenuBackdropState
  • ContextMenu.Backdrop.Props: ContextMenuBackdropProps
  • ContextMenu.Portal.State: ContextMenuPortalState
  • ContextMenu.Portal.Props: ContextMenuPortalProps
  • ContextMenu.Positioner.Props: ContextMenuPositionerProps
  • ContextMenu.Positioner.State: ContextMenuPositionerState
  • ContextMenu.Popup.Props: ContextMenuPopupProps
  • ContextMenu.Popup.State: ContextMenuPopupState
  • ContextMenu.Arrow.State: ContextMenuArrowState
  • ContextMenu.Arrow.Props: ContextMenuArrowProps
  • ContextMenu.Group.Props: ContextMenuGroupProps
  • ContextMenu.Group.State: ContextMenuGroupState
  • ContextMenu.GroupLabel.Props: ContextMenuGroupLabelProps
  • ContextMenu.GroupLabel.State: ContextMenuGroupLabelState
  • ContextMenu.Item.State: ContextMenuItemState
  • ContextMenu.Item.Props: ContextMenuItemProps
  • ContextMenu.CheckboxItem.State: ContextMenuCheckboxItemState
  • ContextMenu.CheckboxItem.Props: ContextMenuCheckboxItemProps
  • ContextMenu.CheckboxItemIndicator.Props: ContextMenuCheckboxItemIndicatorProps
  • ContextMenu.CheckboxItemIndicator.State: ContextMenuCheckboxItemIndicatorState
  • ContextMenu.LinkItem.State: ContextMenuLinkItemState
  • ContextMenu.LinkItem.Props: ContextMenuLinkItemProps
  • ContextMenu.RadioGroup.Props: ContextMenuRadioGroupProps
  • ContextMenu.RadioGroup.State: ContextMenuRadioGroupState
  • ContextMenu.RadioItem.State: ContextMenuRadioItemState
  • ContextMenu.RadioItem.Props: ContextMenuRadioItemProps
  • ContextMenu.RadioItemIndicator.Props: ContextMenuRadioItemIndicatorProps
  • ContextMenu.RadioItemIndicator.State: ContextMenuRadioItemIndicatorState
  • ContextMenu.SubmenuRoot.Props: ContextMenuSubmenuRootProps
  • ContextMenu.SubmenuRoot.State: ContextMenuSubmenuRootState
  • ContextMenu.SubmenuTrigger.Props: ContextMenuSubmenuTriggerProps
  • ContextMenu.SubmenuTrigger.State: ContextMenuSubmenuTriggerState