Skip to content

Menu ​

An action dropdown triggered by any slotted element. Presents a list of ore-menu-item actions in a floating panel using viewport-aware positioning. Supports full keyboard navigation and accessibility semantics.

Placement ​

Control which side of the trigger the panel opens on. The menu automatically flips to avoid viewport clipping.

Full width

Items with Icons ​

Use the icon named slot on each ore-menu-item for leading icons.

Icons

These examples use ore-icon with names from the shared icon registry. The docs preview registers the full Lucide set so every name resolves; an app registers its own icons first, as described in the icon guide.

Full width

Disabled Items ​

Set disabled on a ore-menu-item to prevent selection. The item is still visible but non-interactive. Use disabled for permissions that might change rather than removing the item entirely, to signal that the action exists but is unavailable.

Full width

Disabled Menu ​

Set disabled on the ore-menu element to prevent the panel from opening at all.

Full width

Trigger with an Icon Button ​

Any element works as the trigger: including icon-only buttons. Always provide a visible label or aria-label on an icon-only trigger button so the purpose is clear to screen reader users.

Full width

Context Menu ​

Set trigger="contextmenu" to turn any element into a right-click (or long-press) target. The panel opens at the pointer instead of anchored to the trigger, and a left-click passes through to the page untouched.

Full width

Keyboard users still get the menu: Enter, Space, or ArrowDown on a focused trigger opens it anchored to the trigger element, exactly as in click mode.

Slot ore-menu-item elements into another item's submenu slot to turn it into a submenu trigger. The trigger grows a trailing chevron and flies out a nested panel on hover, ArrowRight, Enter, Space, or a click. Submenus nest to any depth — a submenu item can itself carry a submenu slot.

Full width

A submenu trigger is deliberately not selectable: it emits no select and carries no value, because its press opens the flyout rather than choosing an action. Its children stay out of the parent's arrow navigation, so the parent's rows always match what the pointer sees. Only one submenu in a sibling group stays open at a time — opening another closes its siblings, while ancestors stay open, matching native menus. Selecting a leaf closes the whole chain.

Keyboard model:

  • ArrowRight / Enter / Space on a trigger opens its flyout and moves focus into it.
  • ArrowDown / ArrowUp walk the open flyout's items.
  • Escape / ArrowLeft close the flyout and hand focus back to the trigger.
  • A hover dwell of ~120 ms opens a flyout as the pointer crosses a row; a ~300 ms grace keeps it open while the pointer crosses the gap into the flyout.

Checkable items work inside a flyout, and radio groups scope to their own panel — a submenu's radios are a separate group from the root menu's.

Separator ​

Use ore-menu-separator to add a horizontal divider between groups of related items.

Full width

Labels and End Slots ​

ore-menu-label adds a non-interactive caption above a group of items, and every ore-menu-item takes an end slot for trailing content such as shortcut hints or small indicators. Spell a shortcut as one ore-keyboard-key per pressed key wrapped in ore-keyboard-shortcut — each key gets its own cap, and the menu tightens the group's spacing so hints sit flush in the row. Captions never enter keyboard navigation (arrows walk items only) and end content never changes how an item activates, so both stay safe inside role="menu".

Full width

User Selector (Account Switcher) ​

ore-menu composes into a full user selector: any element can be the trigger, avatar rows are items with slotted content, ore-menu-label names the account group, radio items switch the active account, and the end slot carries shortcut hints.

Full width

Shortcut hints live in the end slot as display only: wrap one ore-keyboard-key per pressed key in an ore-keyboard-shortcut so each key renders its own cap with menu-tight spacing. If the shortcuts are real, register the same keys on the page so the hint stays true.

Grid Layout ​

Set layout="grid" to turn the panel into a grid of cards: icon above a centered, two-line-clamped label, equal columns, no scroller to fight. This suits a small, complete action set (three to six verbs a thumb should see at once). For longer lists, keep the default list layout. Use columns to set the row size (default 3); ore-menu-separator still works and spans the full width between clusters. The columns prop owns the column count outright: the panel's grid tracks and the arrow-key rows always read the same number.

Full width

Keyboard navigation follows the grid: ArrowLeft / ArrowRight step one card, ArrowUp / ArrowDown step one row, Home / End jump to the ends. Disabled cards are still stepped over (skipping them would desync the arrows from the visible rows) but never activated.

Checkable Items ​

Checkbox Items ​

Set type="checkbox" on a ore-menu-item to make it toggleable. Clicking or pressing Enter/Space toggles the checked attribute and emits select with checked in the event detail. The menu stays open when a checkbox item is activated.

Full width

Radio Items ​

Set type="radio" to create a group where only one item can be checked at a time. Selecting a radio item automatically unchecks all other type="radio" siblings.

Full width

Listening to Events ​

html
<ore-menu id="action-menu">
  <ore-button slot="trigger">Actions</ore-button>
  <ore-menu-item value="rename">Rename</ore-menu-item>
  <ore-menu-item value="move">Move to folder</ore-menu-item>
  <ore-menu-item value="delete">Delete</ore-menu-item>
</ore-menu>

<script type="module">
  import '@vielzeug/refine/menu';
  import '@vielzeug/refine/button';

  const menu = document.getElementById('action-menu');

  // Fired when a menu item is selected
  menu.addEventListener('select', (e) => {
    console.log('selected:', e.detail.value, 'checked:', e.detail.checked);
    switch (e.detail.value) {
      case 'rename':
        openRenameDialog();
        break;
      case 'move':
        openMoveDialog();
        break;
      case 'delete':
        confirmDelete();
        break;
    }
  });

  menu.addEventListener('open-change', (e) => {
    console.log('menu open:', e.detail.open, e.detail.reason);
  });
</script>

Use value on each item to handle selection in a single select listener rather than per-item click handlers. Keep menu items short and action-oriented (verb + noun: "Edit post", "Delete file").

API Reference ​

ore-menu Attributes

AttributeTypeDefaultDescription
placement'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end''bottom-start'Preferred panel placement (auto-flips near viewport edges)
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'N/AColor theme
size'sm' | 'md' | 'lg''md'Size theme
disabledbooleanfalsePrevent the menu from opening
openbooleanN/AControlled panel visibility
default-openbooleanfalseInitial visibility when open is not provided
layout'list' | 'grid''list'Panel layout: rows or a grid of cards
columnsnumber3Cards per row in grid layout; sets both the tracks and the arrow-key rows
trigger'click' | 'contextmenu''click'How the menu opens: a left-click, or right-click / long-press at the pointer

ore-menu Slots

SlotDescription
triggerThe element that opens/closes the menu panel
(default)ore-menu-item elements, plus optional ore-menu-label captions and ore-menu-separator dividers

ore-menu-item Attributes

AttributeTypeDefaultDescription
valuestring''Value emitted in the select event detail
type'checkbox' | 'radio'N/AMakes the item checkable; radio items are mutually exclusive
checkedbooleanfalseWhether a checkable item is currently checked
disabledbooleanfalsePrevent the item from being selected

ore-menu-item Slots

SlotDescription
endOptional trailing content (shortcut hints, indicators)
iconOptional leading icon or decoration
submenuNested ore-menu-item elements that turn this item into a submenu trigger
(default)Item label text

Events

EventDetailDescription
select{ value: string, checked?: boolean }Emitted when a menu item is selected. checked is present for type="checkbox" and type="radio" items
open-change{ open: boolean, reason: string }Emitted whenever the panel opens or closes. Opening reports reason: "click", "contextmenu", "keyboard", or "programmatic"; closing after a plain item is chosen reports reason: "select".

CSS Custom Properties (ore-menu)

PropertyDescriptionDefault
--menu-panel-min-widthMinimum width of the panel10rem
--menu-panel-max-heightPanel height capUnset: fits the room on the opened side
--menu-panel-radiusBorder radius of the panelvar(--rounded-lg)
--menu-panel-shadowBox shadow of the panelvar(--shadow-xl)
--menu-panel-bgPanel background surfaceTheme-dependent
--menu-panel-colorPanel foreground and unchecked indicator colorTheme-dependent
--menu-panel-border-colorPanel border colorTheme-dependent
--menu-panel-blurPanel backdrop blur amountvar(--blur-md)
--menu-panel-paddingPanel paddingvar(--size-1)
--menu-panel-widthPanel width in grid layoutmin(21rem, calc(100vw - var(--size-4)))
--menu-panel-gapGap between grid cardsvar(--size-1-5)
--menu-item-card-min-heightGrid card height floorvar(--size-20)
--menu-item-card-border-colorGrid card border colorvar(--color-divider)
--menu-item-card-radiusGrid card corner radiusvar(--rounded-md)
--menu-item-card-icon-sizeIcon size inside a grid card (--ore-icon-size)var(--size-5)
--menu-item-hover-bgItem background on hoverTheme-dependent
--menu-item-focus-colorItem text color when keyboard-focusedTheme-dependent
--menu-item-focus-bgItem background when keyboard-focusedTheme-dependent
--menu-item-selection-bgBackground for checkbox/radio items (unselected)Theme-dependent
--menu-item-checked-colorItem text color when checkedTheme-dependent
--menu-item-checked-bgItem background when checkedTheme-dependent

Accessibility ​

The menu component follows WAI-ARIA Menu Button Pattern best practices.

Arrow keys move focus between items; Enter / Space activates the focused item; Escape closes the panel and returns focus to the trigger. Home / End jump to the first or last item. Opening with Enter, Space, or ArrowDown moves focus to the first usable item. Outside clicks and Tab also close the menu and restore focus to the trigger. In grid layout the arrow keys follow the two-dimensional layout instead: left/right step one card, up/down step one row.

The panel has role="menu" and aria-orientation="vertical". ore-menu-label renders with role="presentation", so the caption is visible without entering the menu's accessibility tree or keyboard flow. The trigger element receives aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu panel. Each item has role="menuitem" and aria-disabled when disabled. Checkable items automatically switch to role="menuitemcheckbox" or role="menuitemradio" with the appropriate aria-checked value.

A submenu trigger also reports aria-haspopup="menu" and aria-expanded, and its flyout is a nested role="menu". Because the trigger opens a flyout instead of choosing an action, it stays a plain role="menuitem" with no value, so assistive technology never announces it as selectable.

A trigger="contextmenu" menu suppresses the browser's native context menu on its trigger. Because a right-click is pointer-only, keep the same actions reachable by keyboard: the trigger still opens the menu with Enter / Space / ArrowDown, so give it focus (a focusable element, not a bare <p>) when the menu is the primary way to reach those actions.