MenusReact

Context Menu

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

Rendered by React 19.3.1

Loading React…

import { ContextMenu } from '@hamur/react/context-menu'

const areaStyle = {
  padding: '32px 48px',
  border: '1px dashed var(--demo-border)',
  borderRadius: 12,
  color: 'var(--demo-muted)',
  fontSize: 14,
  userSelect: 'none',
  WebkitUserSelect: 'none',
} as const

export default function ContextMenuExample() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger style={areaStyle}>
        Right click here
      </ContextMenu.Trigger>
      <ContextMenu.Portal>
        <ContextMenu.Positioner>
          <ContextMenu.Popup className="menu">
            <ContextMenu.Item className="menu-item">
              Back
            </ContextMenu.Item>
            <ContextMenu.Item className="menu-item">
              Forward
            </ContextMenu.Item>
            <ContextMenu.Item className="menu-item">
              Reload
            </ContextMenu.Item>
            <ContextMenu.Item className="menu-item">
              Save as...
            </ContextMenu.Item>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  )
}

79Tests passing in React · 0 failing

71.6 KiBSize

5.00 msOpen

14.3 msClose

21.0 msOpenMutations

20.0 msCloseMutations

1.13 MiBMemory

productdevbook and 15 upstream authors10 commits · last Nov 4

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

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

// Not in this example: ContextMenu.Arrow, ContextMenu.Backdrop, ContextMenu.CheckboxItem, ContextMenu.CheckboxItemIndicator, ContextMenu.Group, ContextMenu.GroupLabel, ContextMenu.LinkItem, ContextMenu.RadioGroup, ContextMenu.RadioItem, ContextMenu.RadioItemIndicator, ContextMenu.Separator, ContextMenu.SubmenuRoot, ContextMenu.SubmenuTrigger

Examples

SubmenuRoot and SubmenuTrigger open a nested menu from an item.

ContextMenuSubmenu.tsx

import { ContextMenu } from '@hamur/react/context-menu'

export default function ContextMenuSubmenuExample() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger className="context-area">Right click here</ContextMenu.Trigger>
      <ContextMenu.Portal>
        <ContextMenu.Positioner>
          <ContextMenu.Popup className="menu">
            <ContextMenu.Item className="menu-item">Add to Library</ContextMenu.Item>
            <ContextMenu.SubmenuRoot>
              <ContextMenu.SubmenuTrigger className="menu-item">
                Add to Playlist
              </ContextMenu.SubmenuTrigger>
              <ContextMenu.Portal>
                <ContextMenu.Positioner alignOffset={-4} sideOffset={-4}>
                  <ContextMenu.Popup className="menu">
                    <ContextMenu.Item className="menu-item">Get Up!</ContextMenu.Item>
                    <ContextMenu.Item className="menu-item">Inside Out</ContextMenu.Item>
                    <ContextMenu.Item className="menu-item">Night Beats</ContextMenu.Item>
                    <ContextMenu.Separator className="menu-separator" />
                    <ContextMenu.Item className="menu-item">New playlist…</ContextMenu.Item>
                  </ContextMenu.Popup>
                </ContextMenu.Positioner>
              </ContextMenu.Portal>
            </ContextMenu.SubmenuRoot>
            <ContextMenu.Separator className="menu-separator" />
            <ContextMenu.Item className="menu-item">Play Next</ContextMenu.Item>
            <ContextMenu.Item className="menu-item">Play Last</ContextMenu.Item>
            <ContextMenu.Separator className="menu-separator" />
            <ContextMenu.Item className="menu-item">Favorite</ContextMenu.Item>
            <ContextMenu.Item className="menu-item">Share</ContextMenu.Item>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  )
}

API reference

75 props across 19 parts, in React syntax. className, style, render are listed once, under Shared props.

Arrow`ContextMenu.Arrow`

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

Arrow data attributes
Data attribute	Description
`data-open`	Present when the menu popup is open.
`data-closed`	Present when the menu popup is closed.
`data-side`	Indicates which side the popup is positioned relative to the anchor.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-uncentered`	Present when the menu arrow is uncentered.

Backdrop`ContextMenu.Backdrop`

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

Backdrop data attributes
Data attribute	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.

CheckboxItem`ContextMenu.CheckboxItem`

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

CheckboxItem props
Prop	Type	Default
`label`Overrides the text used for keyboard text navigation and filtering.	`string`	`—`
`defaultChecked`Whether the checkbox item is initially ticked.	`boolean`	`false`
`checked`Whether the checkbox item is currently ticked.	`boolean`	`—`
`onCheckedChange`Event handler called when the checkbox item is ticked or unticked.	`((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void)`	`—`
`onClick`The click handler for the menu item.	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	`—`
`closeOnClick`Whether to close the menu when the item is clicked.	`boolean`	`false`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`

CheckboxItem data attributes
Data 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-highlighted`	Present when the menu checkbox item is highlighted.

CheckboxItemIndicator`ContextMenu.CheckboxItemIndicator`

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

CheckboxItemIndicator props
Prop	Type	Default
`keepMounted`Whether to keep the HTML element in the DOM when the checkbox item is not checked.	`boolean`	`false`

CheckboxItemIndicator data attributes
Data 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 begins animating in.
`data-ending-style`	Present when the indicator is animating out.

Group`ContextMenu.Group`

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

Group props
Prop	Type	Default
`children`The content of the component.	`React.ReactNode`	`—`

GroupLabel`ContextMenu.GroupLabel`

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

Item`ContextMenu.Item`

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

Item props
Prop	Type	Default
`label`Overrides the text used for keyboard text navigation and filtering.	`string`	`—`
`onClick`The click handler for the menu item.	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	`—`
`closeOnClick`Whether to close the menu when the item is clicked.	`boolean`	`true`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`

Item data attributes
Data attribute	Description
`data-highlighted`	Present when the menu item is highlighted.
`data-disabled`	Present when the menu item is disabled.

LinkItem`ContextMenu.LinkItem`

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

LinkItem props
Prop	Type	Default
`label`Overrides the text used for keyboard text navigation and filtering.	`string`	`—`
`closeOnClick`Whether to close the menu when the item is clicked.	`boolean`	`false`

LinkItem data attributes
Data attribute	Description
`data-highlighted`	Present when the link is highlighted.

Popup`ContextMenu.Popup`

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

Popup props
Prop	Type	Default
`finalFocus`Determines the element to focus when the menu is closed.	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	`—`
`children`	`React.ReactNode`	`—`

Popup data attributes
Data attribute	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.
`data-side`	Indicates which side the popup is positioned relative to the anchor.
`data-align`	Indicates how the popup is aligned relative to specified side.
`data-instant`	Present if animations should be instant.

Portal`ContextMenu.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>.

Portal props
Prop	Type	Default
`container`A parent element to render the portal element into.	`HTMLElement \| ShadowRoot \| React.RefObject<HTMLElement \| ShadowRoot \| null> \| null`	`—`
`keepMounted`Whether to keep the portal mounted in the DOM while the popup is hidden.	`boolean`	`false`

Positioner`ContextMenu.Positioner`

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

Positioner props
Prop	Type	Default
`disableAnchorTracking`Whether to disable the popup from tracking any layout shift of its positioning anchor.	`boolean`	`false`
`align`How to align the popup relative to the specified side.	`Align`	`'start'`
`alignOffset`Additional offset along the alignment axis in pixels.	`number \| OffsetFunction`	`—`
`side`Which side of the anchor element to align the popup against.	`Side`	`'bottom'`
`sideOffset`Distance between the anchor and the popup in pixels.	`number \| OffsetFunction`	`—`
`arrowPadding`Minimum distance to maintain between the arrow and the edges of the popup.	`number`	`—`
`anchor`An element to position the popup against.	`Element \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`	`—`
`collisionAvoidance`Determines how to handle collisions when positioning the popup.	`CollisionAvoidance`	`—`
`collisionBoundary`An element or a rectangle that delimits the area that the popup is confined to.	`Boundary`	`'clipping-ancestors'`
`collisionPadding`Additional space to maintain from the edge of the collision boundary.	`Padding`	`5`
`sticky`Whether to maintain the popup in the viewport after	`boolean`	`false`

Positioner data attributes
Data attribute	Description
`data-open`	Present when the menu popup is open.
`data-closed`	Present when the menu popup is closed.
`data-anchor-hidden`	Present when the anchor is hidden.
`data-side`	Indicates which side the popup is positioned relative to the anchor.
`data-align`	Indicates how the popup is aligned relative to the specified side.

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

RadioGroup`ContextMenu.RadioGroup`

Groups related radio items. Renders a <div>.

RadioGroup props
Prop	Type	Default
`defaultValue`The uncontrolled value of the radio item that should be initially selected.	`any`	`—`
`value`The controlled value of the radio item that should be currently selected.	`any`	`—`
`onValueChange`Function called when the selected value changes.	`((value: any, eventDetails: MenuRootChangeEventDetails) => void)`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`children`The content of the component.	`React.ReactNode`	`—`

RadioItem`ContextMenu.RadioItem`

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

RadioItem props
Prop	Type	Default
`label`Overrides the text used for keyboard text navigation and filtering.	`string`	`—`
`value`requiredValue of the radio item.	`any`	`—`
`onClick`The click handler for the menu item.	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	`—`
`closeOnClick`Whether to close the menu when the item is clicked.	`boolean`	`false`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`

RadioItem data attributes
Data 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-highlighted`	Present when the menu radio item is highlighted.

RadioItemIndicator`ContextMenu.RadioItemIndicator`

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

RadioItemIndicator props
Prop	Type	Default
`keepMounted`Whether to keep the HTML element in the DOM when the radio item is inactive.	`boolean`	`false`

RadioItemIndicator data attributes
Data 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 begins animating in.
`data-ending-style`	Present when the radio indicator is animating out.

Root`ContextMenu.Root`

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

Root props
Prop	Type	Default
`defaultOpen`Whether the menu is initially open.	`boolean`	`false`
`open`Whether the menu is currently open.	`boolean`	`—`
`onOpenChange`Event handler called when the menu is opened or closed.	`((open: boolean, eventDetails: ContextMenuRootChangeEventDetails) => void)`	`—`
`highlightItemOnHover`Whether moving the pointer over items should highlight them.	`boolean`	`true`
`actionsRef`A ref to imperative actions.	`React.RefObject<MenuRootActions \| null>`	`—`
`loopFocus`Whether to loop keyboard focus back to the first item	`boolean`	`true`
`onItemHighlighted`Callback fired when an item is highlighted or unhighlighted.	`((highlightedItem: HTMLElement \| undefined, eventDetails: MenuRootHighlightEventDetails) => void)`	`—`
`onOpenChangeComplete`Event handler called after any animations complete when the menu is opened or closed.	`((open: boolean) => void)`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`orientation`The visual orientation of the menu.	`MenuRootOrientation`	`'vertical'`
`children`	`React.ReactNode`	`—`

Separator`ContextMenu.Separator`

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

Separator props
Prop	Type	Default
`orientation`The orientation of the separator.	`Orientation`	`'horizontal'`

Separator data attributes
Data attribute	Description
`data-orientation`	Indicates the orientation of the separator.

SubmenuRoot`ContextMenu.SubmenuRoot`

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

SubmenuRoot props
Prop	Type	Default
`defaultOpen`Whether the menu is initially open.	`boolean`	`false`
`open`Whether the menu is currently open.	`boolean`	`—`
`onOpenChange`Event handler called when the menu is opened or closed.	`((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)`	`—`
`highlightItemOnHover`Whether moving the pointer over items should highlight them.	`boolean`	`true`
`actionsRef`A ref to imperative actions.	`React.RefObject<MenuRootActions \| null>`	`—`
`closeParentOnEsc`When in a submenu, determines whether pressing the Escape key	`boolean`	`false`
`loopFocus`Whether to loop keyboard focus back to the first item	`boolean`	`true`
`onItemHighlighted`Callback fired when an item is highlighted or unhighlighted.	`((highlightedItem: HTMLElement \| undefined, eventDetails: MenuRootHighlightEventDetails) => void)`	`—`
`onOpenChangeComplete`Event handler called after any animations complete when the menu is opened or closed.	`((open: boolean) => void)`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`orientation`The visual orientation of the menu.	`MenuRootOrientation`	`'vertical'`
`children`The content of the submenu.	`React.ReactNode`	`—`

SubmenuTrigger`ContextMenu.SubmenuTrigger`

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

SubmenuTrigger props
Prop	Type	Default
`label`Overrides the text used for keyboard text navigation and filtering.	`string`	`—`
`onClick`	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	`—`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`openOnHover`Whether the menu should also open when the trigger is hovered.	`boolean`	`true`
`delay`How long to wait before the menu may be opened on hover.	`number`	`100`
`closeDelay`How long to wait before closing the menu that was opened on hover.	`number`	`0`

SubmenuTrigger data attributes
Data attribute	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.

Trigger`ContextMenu.Trigger`

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

Trigger data attributes
Data attribute	Description
`data-popup-open`	Present when the corresponding context menu is open.
`data-pressed`	Present when the corresponding context menu is open.

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`ShiftTab`	Closes the menu and returns focus to the area it was opened on	Popup

Accessibility

What the parts set
Part	Sets	So that
Popup	`role="menu"`	the popup is announced as a menu
Item	`role="menuitem"`	each action is read as a menu item
CheckboxItem	`role="menuitemcheckbox"`, `aria-checked`	a setting is read with its on or off state
RadioItem	`role="menuitemradio"`, `aria-checked`	the chosen option of a set is read
Group	`role="group"`, `aria-labelledby` to its GroupLabel	related items are read under their label
SubmenuTrigger	`aria-controls` to the submenu	a screen reader knows the item opens another menu
Separator	`role="separator"`	groups are divided for screen readers too
Arrow	`aria-hidden="true"`	the decorative arrow is not read

Focus order

Opening moves focus into Popup.
Arrow keys move between items; Tab and Shift+Tab close the menu.
Closing returns focus to where it was before the menu opened.

Installation

Anatomy

Examples

Submenu

API reference

ArrowContextMenu.Arrow

BackdropContextMenu.Backdrop

CheckboxItemContextMenu.CheckboxItem

CheckboxItemIndicatorContextMenu.CheckboxItemIndicator

GroupContextMenu.Group

GroupLabelContextMenu.GroupLabel

ItemContextMenu.Item

LinkItemContextMenu.LinkItem

PopupContextMenu.Popup

PortalContextMenu.Portal

PositionerContextMenu.Positioner

RadioGroupContextMenu.RadioGroup

RadioItemContextMenu.RadioItem

RadioItemIndicatorContextMenu.RadioItemIndicator

RootContextMenu.Root

SeparatorContextMenu.Separator

SubmenuRootContextMenu.SubmenuRoot

SubmenuTriggerContextMenu.SubmenuTrigger

TriggerContextMenu.Trigger