Menu

Trigger a list of actions. Keyboard-accessible by default.

import { Menu, MenuTrigger, MenuContent, MenuItem } from '@dashforge/tw';

<Menu>
  <MenuTrigger><Button>Actions ▾</Button></MenuTrigger>
  <MenuContent>
    <MenuItem onClick={onEdit}>Edit</MenuItem>
    <MenuItem onClick={onDuplicate}>Duplicate</MenuItem>
    <MenuItem color="danger" onClick={onDelete}>Delete</MenuItem>
  </MenuContent>
</Menu>

Quick Start

<Menu>
  <MenuTrigger><Button variant="ghost">User ▾</Button></MenuTrigger>
  <MenuContent>
    <MenuLabel>Account</MenuLabel>
    <MenuItem onClick={onProfile} icon={<User />}>Profile</MenuItem>
    <MenuItem onClick={onSettings} icon={<Settings />}>Settings</MenuItem>
    <MenuSeparator />
    <MenuItem onClick={onSignOut} icon={<LogOut />} color="danger">Sign out</MenuItem>
  </MenuContent>
</Menu>

Examples

Basic menu

Trigger + content + items, with one destructive color="danger" item:

import { Button, Menu, MenuContent, MenuItem, MenuTrigger } from '@dashforge/tw';

<Menu>
  <MenuTrigger><Button variant="ghost">Actions ▾</Button></MenuTrigger>
  <MenuContent>
    <MenuItem onClick={() => alert('Edit')}>Edit</MenuItem>
    <MenuItem onClick={() => alert('Duplicate')}>Duplicate</MenuItem>
    <MenuItem onClick={() => alert('Archive')}>Archive</MenuItem>
    <MenuItem color="danger" onClick={() => alert('Delete')}>Delete</MenuItem>
  </MenuContent>
</Menu>

MenuTrigger asChild

MenuTrigger is a Radix Slot — use asChild to render the trigger styling onto your own element. Common patterns: Button (above), IconButton (avatar dropdown), Chip, Card, etc.

<Menu>
  <MenuTrigger asChild>
    <IconButton aria-label="More options" variant="ghost">
      <MoreVertical />
    </IconButton>
  </MenuTrigger>
  <MenuContent>
    <MenuItem onClick={onEdit}>Edit</MenuItem>
    <MenuItem onClick={onArchive}>Archive</MenuItem>
  </MenuContent>
</Menu>

MenuItem variations

{/* With leading icon */}
<MenuItem icon={<Pencil />} onClick={onEdit}>Edit</MenuItem>

{/* With trailing endIcon (keyboard shortcut, badge, etc.) */}
<MenuItem onClick={onSave} endIcon={<kbd className="text-xs">⌘S</kbd>}>Save</MenuItem>

{/* Disabled */}
<MenuItem disabled icon={<Lock />}>Locked</MenuItem>

{/* Selected — toggles aria-checked */}
<MenuItem selected={view === 'grid'} onClick={() => setView('grid')}>
  Grid view
</MenuItem>

{/* Danger styling (destructive action) */}
<MenuItem color="danger" icon={<Trash2 />} onClick={onDelete}>
  Delete
</MenuItem>

MenuLabel + MenuSeparator + icons

Group related items with non-interactive labels and visual dividers; add leading icons via the icon prop:

import {
  Button, Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuTrigger,
} from '@dashforge/tw';
import { User, Settings, LogOut } from 'lucide-react';

<Menu>
  <MenuTrigger><Button variant="outline">User ▾</Button></MenuTrigger>
  <MenuContent>
    <MenuLabel>Account</MenuLabel>
    <MenuItem icon={<User size={14} />}     onClick={() => alert('Profile')}>Profile</MenuItem>
    <MenuItem icon={<Settings size={14} />} onClick={() => alert('Settings')}>Settings</MenuItem>
    <MenuSeparator />
    <MenuItem icon={<LogOut size={14} />} color="danger" onClick={() => alert('Sign out')}>
      Sign out
    </MenuItem>
  </MenuContent>
</Menu>

MenuSkeleton (loading state)

When the menu items come from an async source, swap the items with <MenuSkeleton count={...} /> while loading. Atlaskit-inspired pattern — the skeleton matches the geometry of real items so the menu doesn't reflow when content arrives.

function UserActionsMenu() {
  const { data, isLoading } = useActions();
  return (
    <Menu>
      <MenuTrigger asChild>
        <IconButton aria-label="Actions"><MoreVertical /></IconButton>
      </MenuTrigger>
      <MenuContent>
        {isLoading ? (
          <MenuSkeleton count={3} withHeading />
        ) : (
          data.map((a) => (
            <MenuItem key={a.id} icon={a.icon} onClick={() => a.run()}>
              {a.label}
            </MenuItem>
          ))
        )}
      </MenuContent>
    </Menu>
  );
}

Selected state (toggle pattern)

Pass selected to toggle aria-checked for toggle / multi-select patterns:

import { useState } from 'react';
import { Button, Menu, MenuContent, MenuItem, MenuTrigger } from '@dashforge/tw';

function ViewPicker() {
  const [view, setView] = useState<'grid' | 'list' | 'compact'>('grid');
  return (
    <Menu>
      <MenuTrigger><Button variant="outline">View: {view} ▾</Button></MenuTrigger>
      <MenuContent>
        {['grid', 'list', 'compact'].map((v) => (
          <MenuItem key={v} selected={view === v} onClick={() => setView(v as any)}>
            {v}
          </MenuItem>
        ))}
      </MenuContent>
    </Menu>
  );
}

For true multi-select UX (where clicking does NOT close the menu), set closeOnItemClick={false} on the parent <Menu>.

Per-item bridge integration

access and visibleWhen are on MenuItem (not on Menu — the menu container has no behavior to gate). Hide individual destructive actions from non-privileged users, or toggle items based on engine state:

<MenuContent>
  <MenuItem onClick={onEdit}>Edit</MenuItem>
  <MenuItem onClick={onArchive}>Archive</MenuItem>
  <MenuSeparator />
  <MenuItem
    color="danger"
    onClick={onDelete}
    access={{ requires: 'workspace.delete', when: 'denied:hide' }}
  >
    Delete workspace
  </MenuItem>
</MenuContent>

A MenuItem that returns null (via visibleWhen or access hide) is invisible — separators around it stay intact in the visual flow.

Controlled open state

function MyMenu() {
  const [open, setOpen] = useState(false);
  return (
    <Menu open={open} onOpenChange={setOpen}>
      <MenuTrigger asChild><Button>Toggle</Button></MenuTrigger>
      <MenuContent>...</MenuContent>
    </Menu>
  );
}

Theme defaults

Configure <Menu> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Menu: {
      defaults: { closeOnItemClick: true, modal: false },
    },
  },
});

Configurable axes (MenuVariantProps):

children and the compound sub-components (MenuTrigger, MenuContent, MenuItem, …) are structural — not theme-configurable. access / visibleWhen on MenuItem are per-instance semantics.

Precedence chain (lowest → highest):

1. Built-in defaults (closeOnItemClick: true, modal: false).
2. theme.components.Menu.defaults (application-wide).
3. Instance prop (<Menu closeOnItemClick={false} />) — wins over theme.

TypeScript: theme.components.Menu.defaults autocompletes to the two axes above.

Reactivity: useComponentDefaults('Menu') subscribes to the theme store — patchTheme re-renders the Menu with the new axes.

Note: the documented placement and sideOffset props on <Menu> are not yet wired through to <MenuContent> — a Sprint 4.4-bis follow-up. Until then, pass side / align / sideOffset on <MenuContent> directly.

API

<Menu> props

<MenuTrigger> props

<MenuContent> props

<MenuItem> props

<MenuLabel> props

children: ReactNode — non-interactive heading text.

<MenuSeparator>

No props. Visual divider.

<MenuSkeleton> props

Slots & slotProps

<Menu> is a compound API — instead of a slotProps bag, it exposes each region as a named sub-component that you compose in JSX. Style each region by passing utility classes via className / sx to the sub-component you render:

This "explicit sub-component" pattern is Menu's chosen shape over slotProps because menus are visually compositional (the consumer decides which sub-components appear and in what order) rather than a fixed anatomy like <DataGrid> or <Autocomplete>.

A11y

• Full WAI-ARIA Menu pattern via Radix. Keyboard: ↑ ↓ move focus, Home / End jump to first/last, type-ahead by first letter, Esc closes, Tab returns focus to trigger.
• Lazy portal mount: no DOM cost while closed.
• MenuItem memoization: each item is React.memo-wrapped (Atlaskit-style perf). Sibling re-renders don't re-render unchanged items.

Notes

• Architecture switch from the Sprint 4.4 plan: the original plan was to build Menu on the Popover from Sprint 3 (same pattern as <RowActionsMenu>). We switched to @radix-ui/react-dropdown-menu because the WAI-ARIA menu pattern (roles menu / menuitem / separator, type-ahead, focus management, return-focus to trigger) is non-trivial to reimplement on a plain Popover. The Radix component adds one new peer dep but ships the full a11y story for free.
• Per-item bridge (access + visibleWhen on <MenuItem>, not <Menu>): the container has no behavior to gate. Putting the bridge on each item lets you mix gated and ungated items in the same menu.
• For an imperative confirmation dialog (e.g. before a destructive onDelete), pair MenuItem with <ConfirmDialog>.