> Native Solid 2 fork. Original documentation and designs © WorkOS; historical posts retain their original context.
# Context Menu
Displays a menu located at the pointer, triggered by a right click or a long press.
## Features
- Supports submenus with configurable reading direction.
- Supports items, labels, groups of items.
- Supports checkable items (single or multiple) with optional indeterminate state.
- Supports modal and non-modal modes.
- Customize side, alignment, offsets, collision handling.
- Focus is fully managed.
- Full keyboard navigation.
- Typeahead support.
- Dismissing and layering behavior is highly customizable.
- Triggers with a long press on touch devices
## Anatomy
Import all parts and piece them together.
```jsx
import { ContextMenu } from "@radix-solid/primitives";
export default () =>
;
```
## API Reference
Adheres to the [Menu WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu) and uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/menu-button/menu-button-actions.html) to manage focus movement among menu items.
### Root
Contains all the parts of a context menu.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `dir`The reading direction of submenus when applicable. If omitted, inherits globally from `DirectionProvider` or assumes LTR (left-to-right) reading mode. | `enum` | — |
| `open`The controlled open state of the context menu. Must be used in conjunction with `onOpenChange`. This is intended for reading the open state and closing the menu programmatically—we discourage opening the menu programmatically, since opening it depends on user interaction to position the menu. | `boolean` | — |
| `onOpenChange`Event handler called when the open state of the context menu changes. | `function` | — |
| `modal`The modality of the context menu. When set to `true`, interaction with outside elements will be disabled and only menu content will be visible to screen readers. | `boolean` | `true` |
### Trigger
The area that opens the context menu. Wrap it around the target you want the context menu to open from when right-clicking (or using the relevant keyboard shortcuts).
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `disabled`When `true`, the context menu won't open when right-clicking. Note that this will also restore the native context menu. | `boolean` | `false` |
| Data attribute | Values |
| -------------- | -------------------- |
| `[data-state]` | `"open" \| "closed"` |
### Portal
When used, portals the content part into the `body`.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------- |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. If used on this part, it will be inherited by `ContextMenu.Content` and `ContextMenu.SubContent` respectively. | `boolean` | — |
| `container`Specify a container element to portal the content into. | `HTMLElement` | `document.body` |
### Content
The component that pops out in an open context menu.
| Prop | Type | Default |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | `false` |
| `onCloseAutoFocus`Event handler called when focus moves back after closing. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onEscapeKeyDown`Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onPointerDownOutside`Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onFocusOutside`Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onInteractOutside`Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. It inherits from `ContextMenu.Portal`. | `boolean` | — |
| `alignOffset`The vertical distance in pixels from the anchor. | `number` | `0` |
| `avoidCollisions`When `true`, overrides the `side` and`align` preferences to prevent collisions with boundary edges. | `boolean` | `true` |
| `collisionBoundary`The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Boundary` | `[]` |
| `collisionPadding`The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`. | `number \| Padding` | `0` |
| `sticky`The sticky behavior on the align axis. `"partial"` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `"always"` will keep the content in the boundary regardless. | `enum` | `"partial"` |
| `hideWhenDetached`Whether to hide the content when the trigger becomes fully occluded. | `boolean` | `false` |
| Data attribute | Values |
| -------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"` |
| `[data-side]` | `"left" \| "right" \| "bottom" \| "top"` |
| `[data-align]` | `"start" \| "end" \| "center"` |
| CSS Variable | Description |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `--radix-context-menu-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets |
| `--radix-context-menu-content-available-width` | The remaining width between the trigger and the boundary edge |
| `--radix-context-menu-content-available-height` | The remaining height between the trigger and the boundary edge |
| `--radix-context-menu-trigger-width` | The width of the trigger |
| `--radix-context-menu-trigger-height` | The height of the trigger |
### Arrow
An optional arrow element to render alongside a submenu. This can be used to help visually link the trigger item with the `ContextMenu.Content`. Must be rendered inside `ContextMenu.Content`.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `width`The width of the arrow in pixels. | `number` | `10` |
| `height`The height of the arrow in pixels. | `number` | `5` |
### Item
The component that contains the context menu items.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the context menu from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | ------------------------ |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### Group
Used to group multiple `ContextMenu.Item`s.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### Label
Used to render a label. It won't be focusable using arrow keys.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### CheckboxItem
An item that can be controlled and rendered like a checkbox.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `checked`The controlled checked state of the item. Must be used in conjunction with `onCheckedChange`. | `boolean \| 'indeterminate'` | — |
| `onCheckedChange`Event handler called when the checked state changes. | `function` | — |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the context menu from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | --------------------------------------------- |
| `[data-state]` | `"checked" \| "unchecked" \| "indeterminate"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### RadioGroup
Used to group multiple `ContextMenu.RadioItem`s.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value`The value of the selected item in the group. | `string` | — |
| `onValueChange`Event handler called when the value changes. | `function` | — |
### RadioItem
An item that can be controlled and rendered like a radio.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value*`The unique value of the item. | `string` | — |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the context menu from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | --------------------------------------------- |
| `[data-state]` | `"checked" \| "unchecked" \| "indeterminate"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### ItemIndicator
Renders when the parent `ContextMenu.CheckboxItem` or `ContextMenu.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. | `boolean` | — |
| Data attribute | Values |
| -------------- | --------------------------------------------- |
| `[data-state]` | `"checked" \| "unchecked" \| "indeterminate"` |
### Separator
Used to visually separate items in the context menu.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### Sub
Contains all the parts of a submenu.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `defaultOpen`The open state of the submenu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | — |
| `open`The controlled open state of the submenu. Must be used in conjunction with `onOpenChange`. | `boolean` | — |
| `onOpenChange`Event handler called when the open state of the submenu changes. | `function` | — |
### SubTrigger
An item that opens a submenu. Must be rendered inside `ContextMenu.Sub`.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | ------------------------ |
| `[data-state]` | `"open" \| "closed"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### SubContent
The component that pops out when a submenu is open. Must be rendered inside `ContextMenu.Sub`.
| Prop | Type | Default |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | `false` |
| `onEscapeKeyDown`Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault` | `function` | — |
| `onPointerDownOutside`Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onFocusOutside`Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onInteractOutside`Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. It inherits from `ContextMenu.Portal`. | `boolean` | — |
| `sideOffset`The distance in pixels from the trigger. | `number` | `0` |
| `align`The direction the submenu appears from its anchor item. May change when collisions occur. | `enum` | `"start"` |
| `alignOffset`An offset in pixels from the `"start"` or `"end"` alignment options. | `number` | `0` |
| `avoidCollisions`When `true`, overrides the `side` and`align` preferences to prevent collisions with boundary edges. | `boolean` | `true` |
| `collisionBoundary`The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Boundary` | `[]` |
| `collisionPadding`The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`. | `number \| Padding` | `0` |
| `arrowPadding`The padding between the arrow and the edges of the content. If your content has `border-radius`, this will prevent it from overflowing the corners. | `number` | `0` |
| `sticky`The sticky behavior on the align axis. `"partial"` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `"always"` will keep the content in the boundary regardless. | `enum` | `"partial"` |
| `hideWhenDetached`Whether to hide the content when the trigger becomes fully occluded. | `boolean` | `false` |
| Data attribute | Values |
| -------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"` |
| `[data-side]` | `"left" \| "right" \| "bottom" \| "top"` |
| `[data-align]` | `"start" \| "end" \| "center"` |
| CSS Variable | Description |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `--radix-context-menu-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets |
| `--radix-context-menu-content-available-width` | The remaining width between the trigger and the boundary edge |
| `--radix-context-menu-content-available-height` | The remaining height between the trigger and the boundary edge |
| `--radix-context-menu-trigger-width` | The width of the trigger |
| `--radix-context-menu-trigger-height` | The height of the trigger |
## Examples
### With submenus
You can create submenus by using `ContextMenu.Sub` in combination with its parts.
```jsx
…
…
…
Sub menu →
Sub menu item
Sub menu item
…
```
### With disabled items
You can add special styles to disabled items via the `data-disabled` attribute.
```jsx
// index.tsx
import { ContextMenu } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.ContextMenuItem[data-disabled] {
color: gainsboro;
}
```
### With separators
Use the `Separator` part to add a separator between items.
```jsx
…
…
…
…
```
### With labels
Use the `Label` part to help label a section.
```jsx
…
Label
…
…
…
```
### With checkbox items
Use the `CheckboxItem` part to add an item that can be checked.
```jsx
import { createSignal } from "solid-js";
import { CheckIcon } from "@radix-solid/icons";
import { ContextMenu } from "@radix-solid/primitives";
export default () => {
const [checked, setChecked] = createSignal(true);
return
…
…
…
Checkbox item
;
};
```
### With radio items
Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others.
```jsx
import { createSignal } from "solid-js";
import { CheckIcon } from "@radix-solid/icons";
import { ContextMenu } from "@radix-solid/primitives";
export default () => {
const [color, setColor] = createSignal("blue");
return
…
Red
Blue
Green
;
};
```
### With complex items
You can add extra decorative elements in the `Item` parts, such as images.
```jsx
import { ContextMenu } from "@radix-solid/primitives";
export default () =>
…
Adolfo Hess
Miyah Myles
;
```
### Constrain the content/sub-content size
You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport.
We expose several CSS custom properties such as `--radix-context-menu-trigger-width` and `--radix-context-menu-content-available-height` to support this. Use them to constrain the content dimensions.
```jsx
// index.tsx
import { ContextMenu } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.ContextMenuContent {
width: var(--radix-context-menu-trigger-width);
max-height: var(--radix-context-menu-content-available-height);
}
```
### Origin-aware animations
We expose a CSS custom property `--radix-context-menu-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions.
```jsx
// index.tsx
import { ContextMenu } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.ContextMenuContent {
transform-origin: var(--radix-context-menu-content-transform-origin);
animation: scaleIn 0.5s ease-out;
}
@keyframes scaleIn {
from {
opacity: 0;
transform: scale(0);
}
to {
opacity: 1;
transform: scale(1);
}
}
```
### Collision-aware animations
We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.
```jsx
// index.tsx
import { ContextMenu } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.ContextMenuContent {
animation-duration: 0.6s;
animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.ContextMenuContent[data-side="top"] {
animation-name: slideUp;
}
.ContextMenuContent[data-side="bottom"] {
animation-name: slideDown;
}
@keyframes slideUp {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideDown {
from {
opacity: 0;
transform: translateY(-10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
```
## Accessibility
Uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items.
### Keyboard Interactions
| Key | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `Space` | Activates the focused item. |
| `Enter` | Activates the focused item. |
| `ArrowDown` | Moves focus to the next item. |
| `ArrowUp` | Moves focus to the previous item. |
| `ArrowRight``ArrowLeft` | When focus is on `ContextMenu.SubTrigger`, opens or closes the submenu depending on reading direction. |
| `Esc` | Closes the context menu |