Menu

When to useLink to "When to use"

• Overflow actions for an item (a row's "more" button) or a toolbar.
• Several related commands that don't each deserve a visible button.
• View options with checkable items (kind: "checkbox" toggles, kind: "radio" picks one of a set).

Use something else when:

• the user picks a value for a form: Select
• there are only one or two actions: show Buttons
• the panel holds controls or a form: Popover
• the items navigate to pages: links in your navigation

UsageLink to "Usage"

import { IconButton, Menu } from "@arshad-shah/cynosure";
import { copy, edit, moreHorizontal, trash } from "@arshad-shah/cynosure/icons";

<Menu
  label="File actions"
  trigger={(props) => <IconButton {...props} icon={moreHorizontal} label="More actions" />}
  items={[
    { value: "edit", label: "Edit", icon: edit, shortcut: ["Ctrl", "E"] },
    { value: "copy", label: "Copy path", icon: copy },
    { label: "Danger zone", items: [{ value: "delete", label: "Delete", icon: trash, tone: "danger" }] },
  ]}
  onSelect={(value) => run(value)}
/>

trigger is a render prop: spread its props onto a Button or IconButton. Sections ({ label, items }) render as a named group after a separator.

Sections without a labelLink to "Sections without a label"

A section with no label ({ items: [...] }) is set apart by separator lines before and after it, without a group name: undo/redo, then cut/copy/paste.

SubmenusLink to "Submenus"

An item with items opens a submenu beside it instead of being chosen, nested to any depth. The entries are plain data, so a plugin can contribute them. onSelect receives the value chosen at any level, and choosing closes the whole menu.

items={[
  { value: "open", label: "Open" },
  {
    value: "move",
    label: "Move to",
    icon: folder,
    items: [
      { value: "inbox", label: "Inbox" },
      { value: "projects", label: "Projects", items: [{ value: "alpha", label: "Alpha" }] },
    ],
  },
]}

The submenu opens on the end side of its parent item, its first item level with the parent, and flips to the other side at the edge of the viewport.

Opening from elsewhereLink to "Opening from elsewhere"

open with onOpenChange controls the menu, so an app can open it from a keyboard shortcut; it opens on its first item. defaultOpen opens it on first render without controlling it.

Checkable itemsLink to "Checkable items"

Checkable items keep the menu open, so several options can be changed in one go. Keep checked in your state and update it in onSelect.

Coloured iconsLink to "Coloured icons"

Item icons are muted by default. iconTone and iconColor colour one item's icon and mean what Icon's tone and color mean: iconTone is a semantic colour (accent, neutral, danger, success, warning, info, muted), iconColor is any CSS colour and overrides it (brand draws a brand mark in its owner's colour). The highlighted item keeps the colour and a disabled item shows its icon muted.

PropsLink to "Props"

Item fields: value, label, icon, iconTone, iconColor, shortcut (keys such as ["Ctrl", "E"]), disabled, tone (neutral or danger), kind (checkbox or radio), checked, keepOpen and items (a submenu). Section fields: items and an optional label.

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: menu named by label, items as menuitem, menuitemcheckbox or menuitemradio with aria-checked, sections as named groups, unlabelled sections set apart by separators. A parent item has aria-haspopup="menu", aria-expanded and aria-controls naming its submenu, a menu named by the item's label.
• Diagonal travel: while a submenu is open, another item must hold the pointer for 300 ms before the submenu closes or switches, so moving towards the submenu across other items keeps it open. Leaving the menu cancels a pending switch.
• Shortcuts are shown with Kbd and announced through aria-keyshortcuts. The menu shows them; your app still has to handle the keys.
• Disabled items stay visible (so people learn the command exists) but can't be focused or run.
• Layers: inside a Popover or dialog, Escape closes only the menu.

TouchLink to "Touch"

Rows are at least 44px tall on coarse pointers, and a tap runs the item. Touch has no hover: a tap on a parent item opens its submenu.

ThemingLink to "Theming"

Tokens: --cy-menu-min-width, --cy-menu-max-width, --cy-menu-radius, --cy-menu-row-height and --cy-menu-offset (the gap from the trigger, also under a Menubar title).

createTheme({ components: { menu: { minWidth: "240px", radius: "10px" } } });

RelatedLink to "Related"

Popover · Select · Toolbar · Kbd