Components

Menu

Headless menu primitives for command menus, selection menus, groups, separators, and nested submenus.

When to Use

Use Menu for a temporary list of commands or settings, such as Duplicate, Archive, or Show grid. Use Select or Listbox when the main job is choosing a form value, NavigationMenu for links that move around a website, and Menubar when several top-level application menus must sit in one horizontal row.

Features

• Full keyboard navigation for menu items and submenus.
• Supports controlled and uncontrolled open state.
• Supports checkbox and radio menu items.
• Supports grouped items, separators, and nested submenus.
• Supports configurable closeOnSelect, looping, escape close, side, align, and offsets.
• Stack-aware Escape dismissal when nested inside parent overlays.
• Exposes state data attributes for styling without shipping styles.

Import

import { Menu } from "@flowstack-ui/atom";

Anatomy

<Menu.Root>
  <Menu.Content>
    <Menu.Group>
      <Menu.Item />
      <Menu.CheckboxItem />
      <Menu.RadioGroup>
        <Menu.RadioItem />
      </Menu.RadioGroup>
    </Menu.Group>
    <Menu.Separator />
    <Menu.Sub>
      <Menu.SubTrigger />
      <Menu.SubContent>
        <Menu.Item />
      </Menu.SubContent>
    </Menu.Sub>
  </Menu.Content>
</Menu.Root>

API Reference

Root

Provides open state, selection defaults, item registration, and modal behavior. It does not render a DOM element; trigger primitives such as DropdownMenu and ContextMenu control it, while standalone examples can open it directly.

Content

Portals and positions the focus-managed menu surface. It restores focus when closed and locks document scrolling while a modal menu is open.

Item

Renders an actionable menu item.

CheckboxItem

Renders a menuitemcheckbox.

RadioGroup

Provides radio selection state for RadioItem.

Radio item values are scoped to their parent radio group for menu highlighting and keyboard movement, so separate groups can reuse values such as "default" inside the same menu.

RadioItem

Renders a menuitemradio.

Group

Groups related menu items with role="group".

Separator

Renders a horizontal separator between groups of related commands.

Sub

Provides controlled or uncontrolled open state for one nested submenu. It does not render a DOM element.

SubTrigger

Renders the parent menuitem that opens, closes, and labels its SubContent.

SubContent

Portals and positions the nested menu beside SubTrigger, with its own item registry, highlight state, typeahead, and nested submenu support.

Advanced compound components can use useMenuContext, useMenuRadioGroupContext, and useMenuSubContext. Their matching providers and context value types are also public exports.

Examples

Selection Menu

import { useState } from "react";
import { Menu } from "@flowstack-ui/atom";

export function ViewMenu() {
  const [grid, setGrid] = useState(true);
  const [density, setDensity] = useState("comfortable");

  return (
    <Menu.Root defaultOpen>
      <Menu.Content ariaLabel="View settings">
        <Menu.CheckboxItem
          value="grid"
          checked={grid}
          onCheckedChange={setGrid}
        >
          Show grid
        </Menu.CheckboxItem>
        <Menu.RadioGroup value={density} onValueChange={setDensity}>
          <Menu.RadioItem value="comfortable">Comfortable</Menu.RadioItem>
          <Menu.RadioItem value="compact">Compact</Menu.RadioItem>
        </Menu.RadioGroup>
      </Menu.Content>
    </Menu.Root>
  );
}

Nested Action Menu

import { Menu } from "@flowstack-ui/atom";

export function ActionsMenu() {
  return (
    <Menu.Root defaultOpen>
      <Menu.Content ariaLabel="Actions">
        <Menu.Item value="duplicate" onSelect={() => console.log("Duplicate")}>
          Duplicate
        </Menu.Item>
        <Menu.Sub>
          <Menu.SubTrigger value="move">Move to</Menu.SubTrigger>
          <Menu.SubContent>
            <Menu.Item value="archive">Archive</Menu.Item>
          </Menu.SubContent>
        </Menu.Sub>
      </Menu.Content>
    </Menu.Root>
  );
}

Accessibility

Follows the WAI-ARIA menu pattern. Content renders role="menu", items render the correct menu item roles, disabled items expose disabled semantics, and keyboard focus is managed inside the open menu. Portalled Menu content and submenu content register with a parent modal focus scope when opened inside Dialog, Drawer, or another modal primitive. Printable-character typeahead matches enabled item text; a single-character search cycles forward from the current matching item, while multi-character buffers match exact prefixes.

Changelog

See CHANGELOG.md.