---
title: Context Menu
subtitle: A menu that appears at the pointer on right click or long press.
description: A high-quality, unstyled React context menu component that appears at the pointer on right click or long press.
---
# Context Menu
A high-quality, unstyled React context menu component that appears at the pointer on right click or long press.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
import { ContextMenu } from '@base-ui/react/context-menu';
export default function ExampleMenu() {
return (
Right click here
Add to Library
Add to Playlist
Play Next
Play Last
Favorite
Share
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Trigger {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
width: 15rem;
height: 12rem;
border: 1px solid var(--color-gray-300);
color: var(--color-gray-900);
border-radius: 0.375rem;
-webkit-user-select: none;
user-select: none;
}
.Positioner {
outline: 0;
}
.Popup {
box-sizing: border-box;
padding-block: 0.25rem;
border-radius: 0.375rem;
background-color: canvas;
color: var(--color-gray-900);
transform-origin: var(--transform-origin);
transition:
transform 150ms,
opacity 150ms;
&[data-ending-style] {
opacity: 0;
}
@media (prefers-color-scheme: light) {
outline: 1px solid var(--color-gray-200);
box-shadow:
0 10px 15px -3px var(--color-gray-200),
0 4px 6px -4px var(--color-gray-200);
}
@media (prefers-color-scheme: dark) {
outline: 1px solid var(--color-gray-300);
outline-offset: -1px;
}
}
.Item {
outline: 0;
cursor: default;
user-select: none;
padding-block: 0.5rem;
padding-left: 1rem;
padding-right: 2rem;
display: flex;
font-size: 0.875rem;
line-height: 1rem;
&[data-highlighted] {
z-index: 0;
position: relative;
color: var(--color-gray-50);
}
&[data-highlighted]::before {
content: '';
z-index: -1;
position: absolute;
inset-block: 0;
inset-inline: 0.25rem;
border-radius: 0.25rem;
background-color: var(--color-gray-900);
}
}
.Separator {
margin: 0.375rem 1rem;
height: 1px;
background-color: var(--color-gray-200);
}
```
```tsx
/* index.tsx */
import { ContextMenu } from '@base-ui/react/context-menu';
import styles from './index.module.css';
export default function ExampleMenu() {
return (
Right click hereAdd to LibraryAdd to PlaylistPlay NextPlay LastFavoriteShare
);
}
```
## Anatomy
Import the components and place them together:
```jsx title="Anatomy"
import { ContextMenu } from '@base-ui/react/context-menu';
;
```
## Examples
[Menu](/react/components/menu.md) displays additional demos, many of which apply to the context menu as well.
### Nested menu
To create a submenu, create a `` inside the parent context menu. Use the `` part for the menu item that opens the nested menu.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
import * as React from 'react';
import { ContextMenu } from '@base-ui/react/context-menu';
export default function ExampleContextMenu() {
return (
Right click here
Add to Library
Add to Playlist
Get Up!
Inside Out
Night Beats
New playlist…
Play Next
Play Last
Favorite
Share
);
}
function ChevronRightIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Trigger {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
width: 15rem;
height: 12rem;
border: 1px solid var(--color-gray-300);
color: var(--color-gray-900);
border-radius: 0.375rem;
-webkit-user-select: none;
user-select: none;
}
.Positioner {
outline: 0;
}
.Popup,
.SubmenuPopup {
box-sizing: border-box;
padding-block: 0.25rem;
border-radius: 0.375rem;
background-color: canvas;
color: var(--color-gray-900);
transform-origin: var(--transform-origin);
transition:
transform 150ms,
opacity 150ms;
&[data-ending-style] {
opacity: 0;
}
@media (prefers-color-scheme: light) {
outline: 1px solid var(--color-gray-200);
box-shadow:
0 10px 15px -3px var(--color-gray-200),
0 4px 6px -4px var(--color-gray-200);
}
@media (prefers-color-scheme: dark) {
outline: 1px solid var(--color-gray-300);
outline-offset: -1px;
}
}
.SubmenuPopup {
&[data-starting-style],
&[data-ending-style] {
transform: scale(0.9);
opacity: 0;
}
}
.Arrow {
display: flex;
&[data-side='top'] {
bottom: -8px;
rotate: 180deg;
}
&[data-side='bottom'] {
top: -8px;
rotate: 0deg;
}
&[data-side='left'] {
right: -13px;
rotate: 90deg;
}
&[data-side='right'] {
left: -13px;
rotate: -90deg;
}
}
.ArrowFill {
fill: canvas;
}
.ArrowOuterStroke {
@media (prefers-color-scheme: light) {
fill: var(--color-gray-200);
}
}
.ArrowInnerStroke {
@media (prefers-color-scheme: dark) {
fill: var(--color-gray-300);
}
}
.Item,
.SubmenuTrigger {
outline: 0;
cursor: default;
user-select: none;
padding-block: 0.5rem;
padding-left: 1rem;
padding-right: 2rem;
display: flex;
font-size: 0.875rem;
line-height: 1rem;
&[data-popup-open] {
z-index: 0;
position: relative;
}
&[data-popup-open]::before {
content: '';
z-index: -1;
position: absolute;
inset-block: 0;
inset-inline: 0.25rem;
border-radius: 0.25rem;
background-color: var(--color-gray-100);
}
&[data-highlighted] {
z-index: 0;
position: relative;
color: var(--color-gray-50);
}
&[data-highlighted]::before {
content: '';
z-index: -1;
position: absolute;
inset-block: 0;
inset-inline: 0.25rem;
border-radius: 0.25rem;
background-color: var(--color-gray-900);
}
}
.SubmenuTrigger {
align-items: center;
justify-content: space-between;
gap: 1rem;
padding-right: 1rem;
}
.Separator {
margin: 0.375rem 1rem;
height: 1px;
background-color: var(--color-gray-200);
}
```
```tsx
/* index.tsx */
import * as React from 'react';
import { ContextMenu } from '@base-ui/react/context-menu';
import { Menu } from '@base-ui/react/menu';
import styles from './index.module.css';
export default function ExampleContextMenu() {
return (
Right click hereAdd to Library
Add to Playlist
Get Up!Inside OutNight BeatsNew playlist…Play NextPlay LastFavoriteShare
);
}
function ChevronRightIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
## 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:**
| 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: ContextMenu.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 | `RefObject` | - | A ref to imperative actions.\* `unmount`: When specified, the menu will not be unmounted when closed.
Instead, the `unmount` function must be called to unmount the menu manually.
Useful when the menu's animation is controlled by an external library. |
| \* `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 popover is associated with.
This is useful in conjunction with the `defaultOpen` prop to create an initially open popover. |
| handle | `Menu.Handle` | - | 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. |
| onOpenChangeComplete | `((open: boolean) => void)` | - | Event handler called after any animations complete when the menu is closed. |
| triggerId | `string \| null` | - | ID of the trigger that the popover is associated with.
This is useful in conjunction with the `open` prop to create a controlled popover.
There's no need to specify this prop when the popover is uncontrolled (i.e. 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 | `ReactNode \| PayloadChildRenderFunction` | - | The content of the popover.
This can be a regular React node or a render function that receives the `payload` of the active trigger. |
### Trigger
An area that opens the menu on right click or long press.
Renders a `
` element.
**Trigger Props:**
| Prop | Type | Default | Description |
| :-------- | :--------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | `string \| ((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. |
| style | `CSSProperties \| ((state: ContextMenu.Trigger.State) => CSSProperties \| undefined)` | - | - |
| render | `ReactElement \| ((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:**
| Attribute | Type | Description |
| :-------------- | :--- | :--------------------------------------------------- |
| data-popup-open | - | Present when the corresponding context menu is open. |
| data-pressed | - | Present when the trigger is pressed. |
### Portal
A portal element that moves the popup to a different part of the DOM.
By default, the portal element is appended to ``.
Renders a `
` element.
**Portal Props:**
| Prop | Type | Default | Description |
| :---------- | :---------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| container | `HTMLElement \| ShadowRoot \| RefObject \| 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 | `CSSProperties \| ((state: Menu.Portal.State) => CSSProperties \| undefined)` | - | - |
| 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. |
### Positioner
Positions the menu popup against the trigger.
Renders a `
` 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. |
| 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. |
| 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 \| RefObject \| (() => 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. |
| 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 | `CSSProperties \| ((state: Menu.Positioner.State) => CSSProperties \| undefined)` | - | - |
| 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. |
**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 specified side. |
| data-side | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
**Positioner CSS Variables:**
| Variable | Type | Default | Description |
| :----------------- | :------- | :------ | :------------------------------------------------------------------------------------- |
| --anchor-height | `number` | - | The anchor's height. |
| --anchor-width | `number` | - | The anchor's width. |
| --available-height | `number` | - | The available height between the trigger and the edge of the viewport. |
| --available-width | `number` | - | The available width between the trigger and the edge of the viewport. |
| --transform-origin | `string` | - | The coordinates that this element is anchored to. Used for animations and transitions. |
### Popup
A container for the menu items.
Renders a `
` element.
**Popup Props:**
| Prop | Type | Default | Description |
| :--------- | :---------------------------------------------------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------- |
| finalFocus | `boolean \| RefObject \| ((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 | `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 | `CSSProperties \| ((state: Menu.Popup.State) => CSSProperties \| undefined)` | - | \* |
| 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'` | 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 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 `
` 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 | `CSSProperties \| ((state: Menu.Arrow.State) => CSSProperties \| undefined)` | - | - |
| 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 trigger. |
### Item
An individual interactive item in the menu.
Renders a `
` 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>) => 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 `