Skip to content

Menu

A button that opens a list of actions, with danger items last after a separator.

<div data-mount="closed"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/menu.css";
import { enhance } from "capsomer/behavior/menu";

enhance();

Usage

import { Menu } from "capsomer/react/menu";

<Menu
  label="Actions for example.org"
  items={[
    { label: "Open site", shortcut: "O", onSelect: open },
    { label: "Run checks now", onSelect: run },
    "separator",
    { label: "Archive", disabled: true, reason: "Not while a deploy runs." },
    { label: "Delete site", danger: true, onSelect: confirmDelete },
  ]}
/>
<Menu label="Site options" items={[
  { type: "group", label: "Site", items: [{ label: "Open site", icon: <OpenIcon />, shortcut: "O" }] },
  { type: "checkbox", label: "Check every minute", checked, onCheckedChange },
  { type: "radio-group", label: "Region", value, onValueChange, items: [{ value: "fra", label: "Frankfurt" }, { value: "pdx", label: "Oregon" }] },
  { type: "submenu", label: "Move to", items: [{ label: "Live sites" }, { label: "Previews" }] },
  { label: "Delete site", danger: true },
]} />
<details class="cap-menu-form" data-cap="menu-form">
  <summary class="cap-btn cap-menu-trigger">Actions for example.org <svg class="cap-icon" aria-hidden="true">...</svg></summary>
  <form class="cap-popover cap-menu" action="/admin/sites/example-org" method="post">
    <input type="hidden" name="site" value="example-org" />
    <a class="cap-option cap-menu-item" href="/sites/example-org"><span class="cap-option-label">Open site</span></a>
    <button type="submit" class="cap-option cap-menu-item" name="intent" value="archive" disabled><span class="cap-option-label">Archive</span><span class="cap-menu-reason">Not while a deploy runs.</span></button>
    <hr class="cap-listbox-separator cap-menu-separator" />
    <button type="submit" class="cap-option cap-menu-item" data-tone="crit" name="intent" value="delete"><span class="cap-option-label">Delete site</span></button>
  </form>
</details>

Examples

A form menu, closed: a details of submit buttons and links, no script needed

<details class="cap-menu-form" data-cap="menu-form" id="menu-form">
  <summary class="cap-btn cap-menu-trigger">Row actions for example.org<svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg></summary>
  <form class="cap-popover cap-menu" action="/admin/sites/example-org" method="post">
    <input type="hidden" name="site" value="example-org" />
    <a class="cap-option cap-menu-item" href="/admin/sites/example-org"><span class="cap-option-label">Open site</span></a>
    <button type="submit" class="cap-option cap-menu-item" name="intent" value="check"><span class="cap-option-label">Run checks now</span></button>
    <button type="submit" class="cap-option cap-menu-item" name="intent" value="archive" disabled><span class="cap-option-label">Archive</span><span class="cap-menu-reason">Not while a deploy runs. Try again when it ends.</span></button>
    <hr class="cap-listbox-separator cap-menu-separator" />
    <button type="submit" class="cap-option cap-menu-item" data-tone="crit" name="intent" value="delete"><span class="cap-option-label">Delete site</span></button>
  </form>
</details>

A form menu, open: a disabled item with its reason, a danger item last

<main class="specimen-page">
<details class="cap-menu-form" data-cap="menu-form" id="menu-form-open" open>
  <summary class="cap-btn cap-menu-trigger">Row actions for example.org<svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg></summary>
  <form class="cap-popover cap-menu" action="/admin/sites/example-org" method="post">
    <input type="hidden" name="site" value="example-org" />
    <a class="cap-option cap-menu-item" href="/admin/sites/example-org"><span class="cap-option-label">Open site</span></a>
    <button type="submit" class="cap-option cap-menu-item" name="intent" value="check"><span class="cap-option-label">Run checks now</span></button>
    <button type="submit" class="cap-option cap-menu-item" name="intent" value="archive" disabled><span class="cap-option-label">Archive</span><span class="cap-menu-reason">Not while a deploy runs. Try again when it ends.</span></button>
    <hr class="cap-listbox-separator cap-menu-separator" />
    <button type="submit" class="cap-option cap-menu-item" data-tone="crit" name="intent" value="delete"><span class="cap-option-label">Delete site</span></button>
  </form>
</details>
</main>

Open

<main class="specimen-page"><div data-mount="open"></div></main>

An item highlighted

<main class="specimen-page"><div data-mount="highlighted"></div></main>

A disabled item with its reason

<main class="specimen-page"><div data-mount="disabled"></div></main>

A danger item, last, after a separator

<main class="specimen-page"><div data-mount="danger"></div></main>

Checkbox and radio items, a submenu, group labels, an icon

<main class="specimen-page"><div data-mount="rich"></div></main>

Comfortable density

<main class="specimen-page"><div data-mount="comfortable"></div></main>

API reference

Menu

PropTypeRequiredDoes
labelReactNodeYesThe trigger's visible label: what the menu acts on ("Actions", "More for capsid").
aria-labelstringNeeded when the label is not plain text, for example an icon-only trigger.
itemsMenuEntry[]Yes
disabledboolean
containerHTMLElement | nullWhere the popup is portaled. Inside a modal <dialog> pass the dialog.
defaultOpenbooleanFor specimens and tests: open on mount.
chevronbooleanThe trigger's down chevron; false for an icon trigger that says what it opens (the player's).

FormMenu

PropTypeRequiredDoes
labelReactNodeYesThe summary's visible text: what the menu acts on ("Actions for example.org").
aria-labelstring
actionstringWhere the form posts, and its method (post unless a GET filter is meant). Not needed with form.
formstringThe id of a form elsewhere on the page that the items submit (a card inside a list whose one form carries the row's fields): the menu renders no form of its own, and each item's button names that form. hidden is then not sent; the outer form carries its fields.
size"sm"The trigger's size: "sm" in a dense row or a card.
method"post" | "get"
itemsFormMenuItem[]Yes
namestringThe field the button's value goes in. intent unless the server expects another name.
hiddenRecord<string, string>Fields every item sends with it: the row's id, a return address.

Functions

FunctionSignatureDoes
stepIndex(count: number, from: number, dir: 1 | -1): numberMoves to the next or previous button, wrapping; from is the focused one, or -1.
enhance(root?: ParentNode): () => void

CSS variables

VariableDefault
--anchor-width0px
--available-heightset by the page
--available-widthset by the page

Parts and data attributes

ClassIs
.cap-menuthe root
.cap-menu-chevrona part
.cap-menu-forma part
.cap-menu-itema part
.cap-menu-positionera part
.cap-menu-reasona part
.cap-menu-triggera part
AttributeValues
data-instantpresent or absent
data-popup-openpresent or absent
data-submenupresent or absent
data-tonecrit
StateRead from
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[open]an attribute

Accessibility

KeyDoes
Enter, Space or ArrowDown on the triggerOpens the menu with its first item focused
ArrowDown, ArrowUpMove between items, skipping separators, wrapping at the ends
ArrowRight on a submenu itemOpens the submenu on its first item
ArrowLeft, or Esc, in a submenuCloses the submenu; focus returns to its item
Space or Enter on a checkbox or radio itemToggles or chooses it
A letterMoves to the next item that starts with it
Enter or Space on an itemRuns it and closes the menu; focus returns to the trigger
EscCloses the menu; focus returns to the trigger
TabCloses the menu and moves on
  • The menu is named by its trigger (aria-labelledby, from Base UI). Checkbox and radio items are menuitemcheckbox and menuitemradio with aria-checked; a submenu item has aria-haspopup="menu"; a group is named by its label.
  • Disabled items carry aria-disabled="true" and stay focusable (Base UI's focusableWhenDisabled), so the reason is heard.
  • Forced colors: the highlighted item gets a Highlight outline, the separator a CanvasText rule.
  • Inside a modal dialog, pass the dialog as container, or the popup renders under the top layer, out of sight.