Menu

Anatomy

Import and assemble the component:

1import { Menu } from '@raystack/apsara'
2
3<Menu>
4  <Menu.Trigger />
5  <Menu.Content>
6    <Menu.Item />
7  </Menu.Content>
8</Menu>

Usage

Beyond the plain case, items can carry icons, sit in groups, nest into submenus, and narrow down as someone types.

Basic usage

A trigger and a list of items. The menu opens on click and closes on select, Escape, or an outside click.

1<Menu>
2  <Menu.Trigger render={<Button color="neutral" />}>Open Menu</Menu.Trigger>
3  <Menu.Content>
4    <Menu.Item>Profile</Menu.Item>
5    <Menu.Item>Settings</Menu.Item>
6    <Menu.Separator />
7    <Menu.Item>Logout</Menu.Item>
8  </Menu.Content>
9</Menu>

With icons

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

1<Menu>
2  <Menu.Trigger render={<Button color="neutral" />}>Actions</Menu.Trigger>
3  <Menu.Content>
4    <Menu.Item leadingIcon={<>📝</>}>Edit</Menu.Item>
5    <Menu.Item leadingIcon={<>📋</>} trailingIcon={<>⌘C</>}>
6      Copy
7    </Menu.Item>
8    <Menu.Separator />
9    <Menu.Item leadingIcon={<>🗑️</>}>Delete</Menu.Item>
10  </Menu.Content>
11</Menu>

With groups and labels

Organize related menu items into sections with descriptive headers.

1<Menu>
2  <Menu.Trigger render={<Button color="neutral" />}>More</Menu.Trigger>
3  <Menu.Content>
4    <Menu.Group>
5      <Menu.Label>Actions</Menu.Label>
6      <Menu.Item>New File</Menu.Item>
7      <Menu.Item>New Folder</Menu.Item>
8    </Menu.Group>
9    <Menu.Separator />
10    <Menu.Group>
11      <Menu.Label>Sort By</Menu.Label>
12      <Menu.Item>Name</Menu.Item>
13      <Menu.Item>Date</Menu.Item>
14    </Menu.Group>

Submenu

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

1<Menu>
2  <Menu.Trigger render={<Button color="neutral" />}>Basic Menu</Menu.Trigger>
3  <Menu.Content>
4    <Menu.Item>Profile</Menu.Item>
5    <Menu.Item>Settings</Menu.Item>
6    <Menu.Separator />
7    <Menu.Item>Logout</Menu.Item>
8    <Menu.Submenu>
9      <Menu.SubmenuTrigger>Sub Menu</Menu.SubmenuTrigger>
10      <Menu.SubmenuContent>
11        <Menu.Item>Sub Menu Item 1</Menu.Item>
12        <Menu.Item>Sub Menu Item 2</Menu.Item>
13        <Menu.Item>Sub Menu Item 3</Menu.Item>
14      </Menu.SubmenuContent>

Checkbox items

Use Menu.CheckboxItem for a setting that turns on or off. Clicking it toggles the check mark and keeps the menu open. Pass checked and onCheckedChange to control it.

1(function CheckboxMenu() {
2  const [showGrid, setShowGrid] = React.useState(true);
3
4  return (
5    <Menu>
6      <Menu.Trigger render={<Button color="neutral" />}>View</Menu.Trigger>
7      <Menu.Content>
8        <Menu.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
9          Show grid
10        </Menu.CheckboxItem>
11        <Menu.CheckboxItem defaultChecked>Show rulers</Menu.CheckboxItem>
12        <Menu.CheckboxItem disabled>Show guides</Menu.CheckboxItem>
13      </Menu.Content>
14    </Menu>

Radio items

Wrap Menu.RadioItem parts in a Menu.RadioGroup. Only one item in the group is checked at a time. Clicking an item keeps the menu open.

1(function RadioMenu() {
2  const [layout, setLayout] = React.useState("list");
3
4  return (
5    <Menu>
6      <Menu.Trigger render={<Button color="neutral" />}>Layout</Menu.Trigger>
7      <Menu.Content>
8        <Menu.RadioGroup value={layout} onValueChange={setLayout}>
9          <Menu.Label>Layout</Menu.Label>
10          <Menu.RadioItem value="list">List</Menu.RadioItem>
11          <Menu.RadioItem value="board">Board</Menu.RadioItem>
12          <Menu.RadioItem value="timeline">Timeline</Menu.RadioItem>
13        </Menu.RadioGroup>
14      </Menu.Content>

Link items

Use Menu.LinkItem to navigate. It renders an <a> element. The menu stays open on click by default. Pass closeOnClick to close it, for example with client-side routing.

To use a router link, pass it to render. The item keeps its layout and icons.

1<Menu.LinkItem render={<NextLink href="/projects" />}>Projects</Menu.LinkItem>

1<Menu>
2  <Menu.Trigger render={<Button color="neutral" />}>Go to</Menu.Trigger>
3  <Menu.Content>
4    <Menu.LinkItem href="#projects">Projects</Menu.LinkItem>
5    <Menu.LinkItem href="#settings">Settings</Menu.LinkItem>
6    <Menu.LinkItem
7      href="https://github.com/raystack/apsara"
8      target="_blank"
9      rel="noreferrer"
10      closeOnClick
11    >
12      GitHub
13    </Menu.LinkItem>
14  </Menu.Content>

Autocomplete

Pass autocomplete to the Menu root. Each menu manages its own autocomplete state.

• autocompleteMode="auto" is the default. Items filter as the user types, matched against each item's value prop or its children text.
• autocompleteMode="manual" leaves filtering to you. Do it in onInputValueChange.
• Submenus opt in separately: pass autocomplete to Menu.Submenu.

1<Menu autocomplete>
2  <Menu.Trigger render={<Button color="neutral" />}>
3    Default Autocomplete
4  </Menu.Trigger>
5  <Menu.Content searchPlaceholder="Search">
6    <Menu.Group>
7      <Menu.Label>Heading</Menu.Label>
8      <Menu.Item>Assign member...</Menu.Item>
9      <Menu.Item>Subscribe...</Menu.Item>
10      <Menu.Item>Rename...</Menu.Item>
11    </Menu.Group>
12    <Menu.Separator />
13    <Menu.Group>
14      <Menu.Label>Actions</Menu.Label>

Linear inspired Menu

This is a Linear-inspired menu component that supports custom filtering and displays nested options. Users can search through all nested items using a single input field.

To closely replicate Linear-style filtering, the filtering logic should include result ranking. Using a utility like match-sorter can help achieve this by sorting filtered results based on relevance.

1(function LinearMenuDemo() {
2  const [searchQuery, setSearchQuery] = useState("");
3
4  const renderMenu = (items: MenuItem[], query: string) => {
5    const filteredItems = filterMenuItems(items, query);
6
7    if (searchQuery && filteredItems.length === 0) {
8      return <div className="no-results">No results</div>;
9    }
10
11    return filteredItems.map((item, index) => {
12      switch (item.type) {
13        case "group":
14          return (

Controlled

Pass open with onOpenChange to own the state. Do this when a keyboard shortcut or another control has to open the menu.

1(function ControlledMenu() {
2  const [open, setOpen] = React.useState(false);
3
4  return (
5    <Flex align="center" gap={5}>
6      <Menu open={open} onOpenChange={setOpen}>
7        <Menu.Trigger render={<Button variant="outline" />}>
8          Actions
9        </Menu.Trigger>
10        <Menu.Content>
11          <Menu.Item onClick={() => setOpen(false)}>Rename</Menu.Item>
12          <Menu.Item onClick={() => setOpen(false)}>Duplicate</Menu.Item>
13        </Menu.Content>
14      </Menu>

API Reference

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

Root

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

Trigger

The button that triggers the menu.

By default, the click event is not propagated. You can override this behavior by passing stopPropagation={false}.

Use the render prop to render a custom trigger element.

Content

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

Item

Individual clickable options within the menu. Built on top of Base UI Menu.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.

CheckboxItem

A menu item that toggles a setting on or off. Renders a check mark before the label when checked. Built on Base UI Menu.CheckboxItem.

RadioGroup

Groups related radio items and holds the selected value.

RadioItem

A menu item that works like a radio button in a Menu.RadioGroup. Renders a dot before the label when checked. The value prop is also used for search matching when it is a string.

LinkItem

A menu item that renders an <a> element. Built on Base UI Menu.LinkItem.

Group

A way to group related menu items together. When filtering is active, the group label is hidden.

Label

Renders a label in a menu group. This component should be wrapped with Menu.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 Menu.SubmenuTrigger and Menu.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 Menu.Content with a default sideOffset of 2.

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

Accessibility

• Built on Base UI Menu, following the WAI-ARIA Menu pattern: the trigger exposes aria-haspopup and aria-expanded, the popup uses role="menu", and items use role="menuitem".
• Arrow keys move through items, Enter activates the highlighted item, Escape closes the menu and returns focus to the trigger, and ArrowRight/ArrowLeft open and close submenus.
• With autocomplete, the popup becomes a role="dialog" containing a search input, items render as role="option", and focus stays in the input while arrow keys move the highlight, and ArrowRight or Enter opens a highlighted submenu, and Escape first closes an open submenu.
• Menu.Label must be wrapped in Menu.Group so the group is labelled via aria-labelledby.
• Menu.CheckboxItem uses role="menuitemcheckbox" and Menu.RadioItem uses role="menuitemradio", both with aria-checked. In a searchable menu they render as role="option" and keep aria-checked.
• Menu.LinkItem renders an <a> with role="menuitem", or role="option" in a searchable menu.