Usage

1import { ContextMenu } from '@raystack/apsara'

API Reference

The ContextMenu component is composed of several parts, each with their own props.

Root

The root element is the parent component that holds the context menu. Using the autocomplete prop, you can enable search functionality.

Trigger

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

Content

The container that holds the menu items. When autocomplete is enabled, renders an inline search input inside the popup.

Item

Individual clickable options within the menu. Built on top of Base UI ContextMenu.Item.

Renders as a role='option' when used in an autocomplete menu. By default, the item's children text content is used for matching, which can be overridden by passing a value prop.

Group

A way to group related menu items together. When filtering is active, the group wrapper is removed and items are rendered flat.

Label

Renders a label in a menu group. This component should be wrapped with ContextMenu.Group so the aria-labelledby is correctly set on the group element. Hidden when filtering is active.

Separator

Visual divider between menu items or groups. Hidden when filtering is active.

EmptyState

Placeholder content when there are no menu items to display.

Submenu

Wraps a submenu root. Use with ContextMenu.SubmenuTrigger and ContextMenu.SubmenuContent to create nested menus.

Supports its own autocomplete prop to enable search functionality within the submenu independently from the parent menu.

SubmenuTrigger

The trigger item for a submenu. Renders with a trailing chevron icon by default. Accepts leadingIcon and trailingIcon props.

When inside a searchable parent menu, the value prop can be used for autocomplete matching.

SubmenuContent

The content container for a submenu. Shares the same API as ContextMenu.Content with a default sideOffset of 2.

Examples

Basic Usage

A simple context menu with basic functionality. Right-click the trigger area to open.

1<ContextMenu>
2  <ContextMenu.Trigger
3    style={{
4      padding: "2em 4em",
5      border: "1px dashed var(--rs-color-border-base-primary)",
6      borderRadius: "var(--rs-radius-2)",
7    }}
8  >
9    <Text>Right click here</Text>
10  </ContextMenu.Trigger>
11  <ContextMenu.Content>
12    <ContextMenu.Item>Profile</ContextMenu.Item>
13    <ContextMenu.Item>Settings</ContextMenu.Item>
14    <ContextMenu.Separator />
15    <ContextMenu.Item>Logout</ContextMenu.Item>

With Icons

You can add icons to the menu items. Supports both leading and trailing icons.

1<ContextMenu>
2  <ContextMenu.Trigger
3    style={{
4      padding: "2em 4em",
5      border: "1px dashed var(--rs-color-border-base-primary)",
6      borderRadius: "var(--rs-radius-2)",
7    }}
8  >
9    <Text>Right click here</Text>
10  </ContextMenu.Trigger>
11  <ContextMenu.Content>
12    <ContextMenu.Item leadingIcon={<>📝</>}>Edit</ContextMenu.Item>
13    <ContextMenu.Item leadingIcon={<>📋</>} trailingIcon={<>⌘C</>}>
14      Copy
15    </ContextMenu.Item>

With Groups and Labels

Organize related menu items into sections with descriptive headers.

1<ContextMenu>
2  <ContextMenu.Trigger
3    style={{
4      padding: "2em 4em",
5      border: "1px dashed var(--rs-color-border-base-primary)",
6      borderRadius: "var(--rs-radius-2)",
7    }}
8  >
9    <Text>Right click here</Text>
10  </ContextMenu.Trigger>
11  <ContextMenu.Content>
12    <ContextMenu.Group>
13      <ContextMenu.Label>Actions</ContextMenu.Label>
14      <ContextMenu.Item>New File</ContextMenu.Item>
15      <ContextMenu.Item>New Folder</ContextMenu.Item>

Submenu

Use ContextMenu.Submenu, ContextMenu.SubmenuTrigger, and ContextMenu.SubmenuContent to create nested menus with multiple levels.

1<ContextMenu>
2  <ContextMenu.Trigger
3    style={{
4      padding: "2em 4em",
5      border: "1px dashed var(--rs-color-border-base-primary)",
6      borderRadius: "var(--rs-radius-2)",
7    }}
8  >
9    <Text>Right click here</Text>
10  </ContextMenu.Trigger>
11  <ContextMenu.Content>
12    <ContextMenu.Item>Profile</ContextMenu.Item>
13    <ContextMenu.Item>Settings</ContextMenu.Item>
14    <ContextMenu.Separator />
15    <ContextMenu.Item>Logout</ContextMenu.Item>

Autocomplete

To enable autocomplete, pass the autocomplete prop to the ContextMenu root element. Each menu instance will manage its own autocomplete behavior.

By default (autocompleteMode="auto"), items are automatically filtered as the user types. The filter matches against the item's value prop or its children text content.

For submenus, you can independently enable autocomplete by passing autocomplete to ContextMenu.Submenu.

1<ContextMenu autocomplete>
2  <ContextMenu.Trigger
3    style={{
4      padding: "2em 4em",
5      border: "1px dashed var(--rs-color-border-base-primary)",
6      borderRadius: "var(--rs-radius-2)",
7    }}
8  >
9    <Text>Right click here</Text>
10  </ContextMenu.Trigger>
11  <ContextMenu.Content searchPlaceholder="Search">
12    <ContextMenu.Group>
13      <ContextMenu.Label>Heading</ContextMenu.Label>
14      <ContextMenu.Item>Assign member...</ContextMenu.Item>
15      <ContextMenu.Item>Subscribe...</ContextMenu.Item>