Menu

Menus expose compact sets of application actions.

When to use

Use a menu for a compact set of commands or selection actions opened by a trigger. Use the navigation-disclosure example for ordinary destination links, and a Popover for rich content or form fields.

Action menu

Use action menus for related commands. The static preview includes icons, descriptions, shortcuts, disabled and destructive states.

Selection states

Use menuitemcheckbox or menuitemradio only for checked choices, always with aria-checked. Group radios with data-menu-group; selection closes the menu and restores trigger focus.

End alignment and viewport edges

An end-aligned menu stays anchored to the trigger’s logical end edge.

A navigation dropdown is not an action menu. Use native details/summary, links in a labelled nav and no menu roles. .menu-align-end provides CSS-only alignment.

This static preview shows the navigation surface.

Interactive

Combine [data-menu], a button trigger and role="menu". The Showcase runtime manages aria-expanded, focus and keys.

HTML
<div class="menu" data-menu>
	<button
		class="btn menu-trigger"
		type="button"
		id="actions-trigger"
		aria-haspopup="menu"
		aria-expanded="false"
		aria-controls="actions-menu"
		popovertarget="actions-menu"
		data-menu-trigger>
		Actions
	</button>
	<div
		class="menu-popup"
		id="actions-menu"
		role="menu"
		aria-labelledby="actions-trigger"
		popover="manual"
		hidden
		data-menu-popup>
		<a class="menu-item" role="menuitem" href="/records/42">View details</a>
		<button class="menu-item" type="button" role="menuitem">Duplicate</button>
		<button class="menu-item" type="button" role="menuitem" disabled>Move</button>
		<hr class="menu-separator" role="separator" />
		<button class="menu-item menu-item-destructive" type="button" role="menuitem">
			Delete
		</button>
	</div>
</div>

Keyboard and lifecycle contract

  • Enter, Space or Arrow Down opens at the first enabled item; Arrow Up opens at the last.
  • Arrow keys wrap; Home/End jump to an edge; typing searches items.
  • Escape closes and restores trigger focus. Activation closes; button and selection actions restore focus. Tab, focus departure or outside pointer input closes without moving focus.
  • Only one menu stays open; initialization is idempotent after Astro page swaps.

The package ships styles only; applications implement this behavior. The Showcase uses native Popover when available and a hidden fallback that cannot escape clipping. Nested submenus are unsupported; use a flat menu or dialog.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--menu-min-width12remMinimum width..menu
--menu-max-width22remMaximum width..menu
--menu-max-height20remMaximum height..menu
--menu-available-heightcalc(100vh - 1rem)Runtime height limit updated by the Showcase positioner..menu-popup (runtime)
--menu-offsetvar(--spacer-2)Gap between the trigger and popup; use a resolvable length..menu
--menu-viewport-insetvar(--spacer-2)Minimum viewport clearance for the Showcase positioner; use a resolvable length..menu
--menu-padding-yvar(--spacer-1)Top and bottom padding..menu
--menu-padding-xvar(--spacer-1)Left and right padding..menu
--menu-gapvar(--spacer-1)Space between child elements..menu
--menu-bg-colorvar(--bg-surface)Background color..menu
--menu-colorvar(--text-color)Text and icon color..menu
--menu-border-widthvar(--border-width)Border thickness..menu
--menu-border-colorvar(--border-color)Border color..menu
--menu-border-radiusvar(--border-radius)Corner radius..menu
--menu-box-shadowvar(--shadow-lg)Outer shadow..menu
--menu-z-indexvar(--z-index-tooltip)Stacking order..menu
--menu-item-padding-yvar(--spacer-2)Item top and bottom padding..menu
--menu-item-padding-xvar(--spacer-3)Item left and right padding..menu
--menu-item-gapvar(--spacer-2)Space between item icon, label and shortcut..menu
--menu-item-border-radiusvar(--border-radius-sm)Item corner radius..menu
--menu-item-hover-bg-colorvar(--bg-surface-hover)Item background on hover or keyboard focus..menu
--menu-item-active-bg-colorvar(--bg-active)Item background while pressed..menu
--menu-item-current-colorvar(--action-color)Text color for current or active items..menu
--menu-item-destructive-colorvar(--error)Text color for destructive actions..menu
--menu-item-disabled-colorvar(--disabled-text-color)Text color for disabled items..menu (disabled)
--menu-item-description-colorvar(--text-muted)Supporting item text color..menu
--menu-item-shortcut-colorvar(--text-muted)Keyboard shortcut text color..menu
--menu-group-label-colorvar(--text-muted)Group heading text color..menu
--menu-separator-colorvar(--border-color)Divider line color..menu
--menu-transition-durationvar(--transition-duration-fast)Duration of visual state transitions..menu
--menu-transition-easingvar(--transition-easing)Timing curve for visual state transitions..menu