Action menu
A button with popovertarget and a popover list of real links and buttons: a click already opens, closes and activates items with no script. With JavaScript this adds the ARIA APG menu button keyboard model (roving tabindex, arrow keys, Home/End, typeahead) and a teental-staggered entrance.
quiet warm playful
Open the live demo
npx @susegad/cli add action-menu
Stands on: Core, Core: components, Tokens
The prompt
the prompt
A short list, offered at the press of a name: ruled, ink-ruled, or stamped.
A button with popovertarget and a popover list of real links and buttons. With JavaScript, the ARIA APG menu button keyboard model rides on top of behaviour the browser already gives you.
<link rel="stylesheet" href="susegad/components/action-menu/action-menu.css">
<script type="module" src="susegad/components/action-menu/action-menu.js"></script>
<sg-action-menu>
<button popovertarget="account-menu">Account</button>
<ul id="account-menu" popover role="menu">
<li role="none"><a href="/profile" role="menuitem">Profile</a></li>
<li role="none"><button type="button" role="menuitem">Sign out</button></li>
</ul>
</sg-action-menu>
The prompt
Make a menu button web component around a real [popovertarget] button and a [popover][role="menu"] list of real <a> and <button> items, so a click already opens, closes and activates it with no script. Fill in the wiring a builder left off: the panel's id, the button's popovertarget, aria-haspopup="menu" and aria-expanded, and role="menuitem" on any bare link or button inside the list. Find the trigger by searching descendants, not only direct children, since a builder may wrap it in its own theatre (a <sg-button>). Add the ARIA APG menu button keyboard model: on the closed button, ArrowDown opens the menu focused on its first item and ArrowUp on its last; inside the open menu, ArrowDown/ArrowUp move a roving tabindex (only the current item is 0, the rest -1) with wraparound, Home/End jump to the ends, a letter key jumps to the next item that starts with it (typeahead, cycling through repeats within half a second), and hovering an item moves the same roving focus a keyboard user would land on. Let Enter, Space and a click activate the focused or clicked item exactly as the browser already would (a real link navigates, a real button's own click fires); after that, close the menu and return focus to the trigger button. Tab closes the menu too, but lets Tab's own default focus change carry on, never trapping focus on the trigger. Leave Escape and outside-click alone: popover="auto" already closes the menu and returns focus on Escape, so the component adds nothing there. Stagger the list's entrance and each item's own with the teental sixteen-beat cycle (talaDelay()), and turn every entrance off under reduced motion. Place the list with CSS anchor positioning, flipped above or across when it will not fit, and stagger the items in CSS from their place in the list, keeping talaDelay() as the source of truth and the fallback. Let the list arrive and leave as a transition from its first frame.
Words to code
| When you say | Technique | What happens |
|---|---|---|
a real [popovertarget] button and a [popover][role="menu"] list | native first | Opening, closing, light-dismiss, Escape-with-focus-return, and every item's own activation are the platform's; the component only adds the keyboard model on top. |
| search descendants, not only direct children | robustness | this.querySelector('[popovertarget]'), falling back to the first button or link outside the menu, so a trigger nested in <sg-button> is still found. Menu's first draft used this.children, which missed exactly this case; fixed once the demo (which does wrap the trigger) caught it. |
a roving tabindex … with wraparound | the APG pattern | action-menu.core.js's wrap(index, delta, n) is the one piece of arithmetic; #move() sets tabindex on the old and new current item and calls .focus() on the real element, so native Enter/Space activation needs no extra code. |
| a letter key jumps to the next item … cycling through repeats | typeahead | typeaheadIndex(labels, query, from) searches forward from just after the current item and wraps once, so pressing the same letter twice moves past the first match to the next. |
| close the menu and return focus to the trigger button | closing after a real choice | #choose() calls hidePopover() then trigger.focus(), run from a click listener delegated on the menu, so it fires whether the item was reached by mouse, keyboard, or its own native activation. |
| never trapping focus on the trigger | Tab is different from Escape | #close() (Tab) only calls hidePopover(), without moving focus, so Tab's own default still lands wherever it would have; #choose() (a real selection) is the only path that pulls focus back to the trigger. |
| stagger … with the teental sixteen-beat cycle | ported timing | talaDelay(i) from packages/tokens/tokens.js sets --sg-item-delay per item; action-menu.css reads it in an animation-delay, off entirely under reduced motion. |
| fit the open list to the visual viewport, in both placement paths | a phone's innerWidth lies | visibleBox(window) and fitShift(rect, box) in action-menu.core.js; #fit() sets --sg-fit-x and action-menu.css applies it as transform: translateX(...). Never window.innerWidth. |
| place the list with CSS anchor positioning | native first, with a fallback | The same block as Popover: position-anchor: auto, top: anchor(bottom), position-try-fallbacks; action-menu.js names the anchor and drops its listeners where CSS.supports('anchor-name: --a'). |
stagger the items in CSS from their place in the list, keeping talaDelay() as the source of truth | sibling-index(), same arithmetic | action-menu.css: a registered --sg-menu-i: sibling-index() on each child of the menu, and --sg-item-delay: min(600ms, var(--sg-tala-beat) * (16 * round(down, k / 13, 1) + s + 3 * round(down, s / 8, 1))) with s = mod(k, 13): the 13 active slots skip the khali beats 8, 9 and 10. overlays.check.mjs compares all 14 delays with talaDelay(i); action-menu.js sets the inline delays only where sibling-index() is not understood. |
| the list arrives and leaves as a transition, quiet 120 ms of opacity only, warm a short rise, playful the spring | CSS @starting-style, per register | A transition from @starting-style with transition-behavior: allow-discrete on display and overlay, so it can fade out in the top layer; --_dur, --_ease and --_rise are set per [data-skin]; reduced motion removes the transition, so the first frame is the finished one. overlay.check.mjs reads the first frame of each. |
| an item is pressed: a 1 px settle in quiet, the colour shades in warm, a small give in playful | the touch contract | sg-action-menu [role=menuitem]:active answers with no transition and eases back in under 150 ms: quiet translate: 0 1px, warm an inset shade mixed toward --sg-text, playful scale: 0.97 released on --sg-ease-spring. Reduced motion keeps the shade and drops the movement; :root[data-sg-input=key] drops it for the keyboard. |
Accessibility
aria-haspopup="menu"andaria-expandedon the trigger;role="menu"androle="menuitem"on the list and its items.- Only the current item is a tab stop; arrow keys, not Tab, move through the menu while it is open, per the APG.
- Escape and outside-click close the menu and return focus to the trigger, both native.
- List border, item text and the current item's highlight hold WCAG contrast in every palette and theme (tested).
Credit
The stamped skin's dashed outline is a general block-print idiom, shared with the Wave 1 Stamp; no specific credit is owed beyond that component's own.
<sg-action-menu> wraps a button with popovertarget and a popover list of real links and buttons. A click opens and closes it, and every item is a real focusable control, with or without JavaScript. With JavaScript this adds the ARIA APG menu button keyboard model: a roving tabindex, arrow keys, Home, End and typeahead.
Use
<link rel="stylesheet" href="susegad/components/action-menu/action-menu.css">
<script type="module" src="susegad/components/action-menu/action-menu.js"></script>
<sg-action-menu>
<button popovertarget="account-menu">Account</button>
<ul id="account-menu" popover role="menu">
<li role="none"><a href="/profile" role="menuitem">Profile</a></li>
<li role="none"><button type="button" role="menuitem">Sign out</button></li>
</ul>
</sg-action-menu>
Leave id, popovertarget and role="menuitem" off and the element wires them itself. The trigger may be wrapped in its own theatre (<sg-button>, for instance); the element looks for the first [popovertarget], or the first button or link outside the menu, whichever it finds first.
Attributes and properties
| Values | Default | |
|---|---|---|
register | quiet, warm, playful | inherited |
open (property, read only) | boolean | false |
Registers
| Look | |
|---|---|
| quiet (and no JS) | a ruled list, a hairline between items |
| warm | an ink-ruled list: an accent margin, the rules and the hover/focus wash in ink |
| playful | a stamped list: a bolder frame, and a dashed stamp outline that lands on hover or focus |
The list arrives and leaves as a CSS transition from @starting-style: quiet is 120 ms of opacity and nothing else, warm adds a short rise, playful a longer one on the spring. Each item's own entrance follows the teental sixteen-beat stagger, capped so the last item of a long menu is never kept waiting past 600 ms. The stylesheet does the stagger with sibling-index() (the three khali beats stay silent); talaDelay() in packages/tokens/tokens.js is the same arithmetic and the source of truth, and the element sets the delays from it in a browser that lacks sibling-index(). Reduced motion turns every entrance off.
An item is pressed: the state answers in the same frame, with no transition, and eases back in under 150 ms. Quiet settles 1 px, warm shades the colour toward the ink, playful gives a little (scale 0.97, released on the spring). The keyboard never moves it, and under reduced motion the shade stays and the movement goes. Arrow keys do not press anything.
Positioning
Where CSS anchor positioning is supported the browser places the list: below its trigger, flipped above or across when it will not fit, with no script (a popovertarget trigger is the implicit anchor) and no scroll or resize listeners. Elsewhere the element measures and places it. Either way, the last step is fitting it to what a person can see: action-menu.js measures the open list against window.visualViewport (its visibleBox() in the core; without one, the document's clientWidth) and, if it sits outside, slides it back to 8 px inside with a --sg-fit-x custom property that the stylesheet turns into a translateX. Not window.innerWidth: mobile Chromium widens it to fit overflowing content, and an anchored panel's containing block follows, so on a phone a panel opened near the right edge used to spill past the screen. The fit runs once more in the frame after beforetoggle (so the first painted frame is already fitted, not one task later), and on resize and the visual viewport's resize and scroll. The fallback places from the trigger's top edge, never from innerHeight, which a phone widens. fitShift() is pure and tested; the phone cells of the check press it at 390 px on a clean page and on a widened one, with and without anchor positioning.
Keyboard (ARIA APG menu button)
| Key, on the closed button | Does |
|---|---|
| Enter, Space, click | Opens the menu (the platform's own popover behaviour) |
| ArrowDown | Opens the menu, focused on the first item |
| ArrowUp | Opens the menu, focused on the last item |
| Key, inside the open menu | Does |
|---|---|
| ArrowDown / ArrowUp | Moves the roving focus, wrapping at both ends |
| Home / End | Jumps to the first or last item |
| A letter | Jumps to the next item starting with it (typeahead, cycling through repeats) |
| Enter, Space, click on an item | Activates it (the item's own native behaviour), closes the menu, returns focus to the button |
| Escape | Closes the menu and returns focus to the button (the platform's own popover="auto" behaviour) |
| Tab | Closes the menu and moves focus onward, as Tab always does |
Hovering an item with a pointer moves the same roving focus a keyboard user would land on, so the two ways of using the menu always agree on which item is "current".
Accessibility
How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.
- Meets 15
- 2
- Not applicable 1
| Criterion | Status | How it was checked |
|---|---|---|
| 1.1.1 Non-text content | Meets | The warm and playful stamps behind an item are decoration drawn behind the text and are never created under reduced motion (packages/components/action-menu/action-menu.check.mjs: "reduced motion, playful: the stamp is never even created, not just paused"). Items are text. |
| 1.3.1 Info and relationships | Meets | A role="menu" list in the browser's popover layer with role="menuitem" links and buttons, and a trigger that carries aria-haspopup="menu" and aria-expanded (packages/components/action-menu/action-menu.js). action-menu.check.mjs: "no JS: Tab reaches the first real item" shows the plain popover list works with no script. |
| 1.4.1 Use of color | Meets | An item is its words; the roving item is shown by an outline and a background, and the focused item is not told apart by colour alone (packages/components/action-menu/action-menu.test.js: "every register keeps a visible focus outline on the roving item"). |
| 1.4.3 Contrast (minimum) | Meets | packages/components/action-menu/action-menu.test.js: "contrast: <palette> <theme>: the list's border, text and the focused item's background read" for every palette, light and dark. axe color-contrast is clean on the closed page and on the open menu: tools/axe.mjs --url /packages/components/action-menu/demo.html: 0 violation(s) across 6 run(s) (three registers, light and dark, desktop), 2026-10-07, and the same script run with the menu open (axe-core with the WCAG 2.2 AA tags, three registers, light): 0 violations, nothing to review. |
| 1.4.4 Resize text | Meets | Manual test, 2026-10-07: the demo with the root font size at 200 percent in three registers (1280 px wide) and the menu open, nothing clipped, nothing wider than the screen; the list is 417 to 419 px wide and 363 to 398 px tall (throwaway Playwright script). |
| 1.4.10 Reflow | Meets | Manual test at 320 CSS px with the menu open, three registers, 2026-10-07: no sideways scroll, the list 202 to 204 px wide, left edge at 16 px, inside the viewport (throwaway Playwright script). On a phone (a touch, isMobile context at 390 px, a trigger pinned to the right edge) action-menu.check.mjs "<register>, phone, <clean or widened page>[, JS fallback]: a list opened from the right edge stays inside the visual viewport" and "opening it adds no sideways scroll to the page" measure the open list against visualViewport and the page with tools/lib/overflow.mjs; before the fix the list sat past the screen on a widened page. |
| 1.4.11 Non-text contrast | Meets | The list border is --sg-rule-strong and the focus ring is --sg-focus, tested 3:1 or more on every surface for every palette and theme in packages/tokens/tokens.test.js; action-menu.test.js ("contrast: ...") tests the border and the focused item's background. |
| 1.4.12 Text spacing | Meets | Manual test, 2026-10-07: the WCAG text-spacing values (line height 1.5, letter 0.12em, word 0.16em, paragraph spacing 2em) injected with the menu open, three registers, no clipped or overlapping text (throwaway Playwright script). No check in the repository asserts it yet. |
| 1.4.13 Content on hover or focus | Not applicable | The list opens when the reader presses the trigger or an arrow key, not when the pointer hovers or focus lands. Hovering an item only moves the roving focus (action-menu.check.mjs: "hovering an item moves the roving focus to it"). |
| 2.1.1 Keyboard | Meets | packages/components/action-menu/action-menu.check.mjs: ArrowDown opens it on the first item, ArrowUp on the last, ArrowDown, ArrowUp, Home and End move (wrapping at both ends), typing a letter jumps to a matching item, Enter activates the item's own handler, Escape closes. All three registers. |
| 2.1.2 No keyboard trap | Meets | action-menu.check.mjs: "Escape closes the menu and returns focus to the trigger", "Tab closes the menu" and "Tab does not return focus to the trigger", so Tab leaves the list onward. |
| 2.1.4 Character key shortcuts | Meets | Typing a letter to jump to an item only works while focus is inside the open list (#onMenuKey in packages/components/action-menu/action-menu.js), which the criterion allows as a shortcut active only on focus. action-menu.check.mjs: "typing "p" jumps to an item starting with P". |
| 2.4.3 Focus order | Meets | action-menu.check.mjs: focus lands on the first item when the menu opens, "activating an item closes the menu" and "focus returns to the trigger". |
| 2.4.7 Focus visible | Meets | action-menu.test.js: "every register keeps a visible focus outline on the roving item", and tools/touch.check.mjs requires a focus style on the control in every register. |
| 2.4.11 Focus not obscured (minimum) | Manual test, 2026-10-07: at 320 by 640 px the menu opened and Tab pressed eight times in each register; every focused control was fully in the viewport and the element at its centre was itself (elementFromPoint). The list is in the browser's top layer, so a sticky bar of the page cannot cover it; a sticky bar can cover the trigger when it is scrolled to. | |
| 2.5.3 Label in name | Meets | Items and the trigger are named by their visible text; the component adds no aria-label (packages/components/action-menu/action-menu.js). |
| 2.5.8 Target size (minimum) | Meets | Manual test, 2026-10-07: the items are 192 px wide and 42 to 46 px tall at 320 px, and no focusable control in the open menu is under 24 by 24 CSS px, in all three registers (throwaway Playwright script). The trigger is an sg-button, 44 px tall. |
| 4.1.2 Name, role, value | The trigger carries aria-haspopup="menu" and aria-expanded that follows the list, and items are menuitems (action-menu.js). The list itself has no accessible name unless the page gives one: Manual test, 2026-10-07, Chromium: ariaSnapshot of the open warm menu reads menu: with three menuitems and no name. axe: 0 violations, closed and open. The ARIA authoring practices for a menu button name the list by pointing aria-labelledby at the trigger, which is the page author's part here. |
The page author owns:
- The items' words, in the language of the page, and
langon an item in another language (3.1.2). aria-labelledbyon therole="menu"list pointing at the trigger, so the list has a name (4.1.2).- The
role="none"on each<li>androle="menuitem"on each link or button, as the demo writes them. - Sticky headers and banners that could cover the trigger when it takes focus (2.4.11).
- The colours the page sets behind the menu, if it overrides the tokens.
How it behaves
- The trigger carries
aria-haspopup="menu"andaria-expanded. - Every item is a real
<a>or<button>; its own activation, not a synthetic one, does the work. - Only the current item is a tab stop (
tabindex="0"); the rest are-1, the APG roving-tabindex pattern. - List border, item text and the hover/focus background hold WCAG contrast in every palette and theme (tested).
Budget
Behaviour 6.7 KB (action-menu.js + action-menu.core.js); skins quiet, warm and playful are each a no-op mount, under 0.2 KB: the look is entirely in action-menu.css, keyed off [data-skin] and [data-open].