Search docs

Menu

A list of actions that opens from a button.

Menu follows the Menu Button WAI-ARIA design pattern.

import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Menu } from '@leve-ui/menu';
import { LuChevronDown } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);
  const last = useSignal('Nothing yet');
  const select$ = $((action: string) => {
    last.value = action;
  });

  return (
    <div class="menu-default">
      <Menu.Root>
        <Menu.Trigger class="menu-default-trigger">
          Actions
          <LuChevronDown class="menu-default-chevron" aria-hidden="true" />
        </Menu.Trigger>
        <Menu.Content sideOffset={4} class="menu-default-content">
          <Menu.Item onSelect$={() => select$('New file')} class="menu-default-item">
            New file <span class="menu-default-shortcut">⌘N</span>
          </Menu.Item>
          <Menu.Item onSelect$={() => select$('Duplicate')} class="menu-default-item">
            Duplicate <span class="menu-default-shortcut">⌘D</span>
          </Menu.Item>
          <Menu.Item disabled class="menu-default-item">
            Paste <span class="menu-default-shortcut">⌘V</span>
          </Menu.Item>
          <Menu.Separator class="menu-default-separator" />
          <Menu.Group>
            <Menu.GroupLabel class="menu-default-label">Share</Menu.GroupLabel>
            <Menu.Item onSelect$={() => select$('Copy link')} class="menu-default-item">
              Copy link
            </Menu.Item>
            <Menu.Item onSelect$={() => select$('Email')} class="menu-default-item">
              Email
            </Menu.Item>
          </Menu.Group>
        </Menu.Content>
      </Menu.Root>
      <p class="menu-default-status">Last action: {last.value}</p>
    </div>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/menu

Anatomy#

import { Menu } from '@leve-ui/menu'; // or '@leve-ui/core'

<Menu.Root>
  <Menu.Trigger />
  <Menu.Content>
    <Menu.Item />
    <Menu.Separator />
    <Menu.Group>
      <Menu.GroupLabel />
      <Menu.Item />
    </Menu.Group>
    <Menu.CheckboxItem>
      <Menu.ItemIndicator />
    </Menu.CheckboxItem>
    <Menu.RadioGroup>
      <Menu.RadioItem>
        <Menu.ItemIndicator />
      </Menu.RadioItem>
    </Menu.RadioGroup>
    <Menu.Sub>
      <Menu.SubTrigger />
      <Menu.SubContent>
        <Menu.Item />
      </Menu.SubContent>
    </Menu.Sub>
    <Menu.Arrow />
  </Menu.Content>
</Menu.Root>
PartElementDescription
Menu.Root<div>Wraps the parts and holds the open state.
Menu.Trigger<button>The button that opens the menu. Use as to render another element or component.
Menu.Content<div>The menu, a popover="manual" element in the top layer.
Menu.Item<div>An action. Use as to render <a>, Qwik City's <Link>, or another component.
Menu.Group<div>A group of items, named by its GroupLabel.
Menu.GroupLabel<div>The name of a group. Not an item.
Menu.CheckboxItem<div>An item that is turned on or off.
Menu.RadioGroup<div>A set of RadioItems where one is selected.
Menu.RadioItem<div>An item of a RadioGroup.
Menu.ItemIndicator<span>The check mark of a CheckboxItem or RadioItem, hidden while unchecked.
Menu.Sub<div>Wraps a submenu and holds its open state.
Menu.SubTrigger<div>The item that opens a submenu.
Menu.SubContent<div>The submenu, placed next to its SubTrigger.
Menu.Separator<div>A line between items.
Menu.Arrow<div>Optional. An arrow pointing at the Trigger, drawn with CSS.

Use as on Menu.Item or Menu.Trigger to render another element or component. A component passed to as must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

Examples#

Pass <a> or a router link component such as Qwik City's <Link> to as on Menu.Item so items navigate while keeping role="menuitem", keyboard navigation, and menu closing.

Checkbox and Radio Items#

Menu.CheckboxItem turns an option on or off, and Menu.RadioItem selects one value of a Menu.RadioGroup. Both take bind: signals like the other controls. Space changes them without closing the menu; a click or Enter changes them and closes it.

Menu.Sub nests a menu. ArrowRight, Enter or Space on the Menu.SubTrigger opens it and focuses its first item; ArrowLeft and Escape close only the submenu. Hovering the SubTrigger opens it and keeps focus on the SubTrigger. Selecting an item in the submenu closes the whole menu.

Context Menu#

Menu.ContextTrigger opens the menu at the pointer on right click, Shift + F10 or long press, instead of from a button. See Context Menu.

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; content?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

Whether the menu is open initially (uncontrolled). It opens when the page resumes.

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the menu opens or closes by a user interaction.

loopfalseboolean

Whether ArrowDown on the last item moves to the first one, and ArrowUp on the first to the last.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menuAlways present
data-state"open" | "closed"

Trigger#

PropDefaultType
as'button'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <button>. A component must spread the props it receives onto one element.

Also accepts all <button> attributes.

Data attributeValue
data-leve-menu-triggerAlways present
data-state"open" | "closed"

Content#

PropDefaultType
side'bottom''top' | 'right' | 'bottom' | 'left'

The side of the Trigger (or the pointer of a context menu) to place the menu on. It flips when there is no room.

align'start''start' | 'center' | 'end'

The alignment along that side.

sideOffset0number

The distance from the Trigger in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the menu to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

arrowPadding0number

The padding between the arrow and the corners of the menu, in px.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping: "top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS variableValue
--leve-menu-anchor-widthThe width of the Trigger, for example to make the menu at least as wide
--leve-menu-anchor-heightThe height of the Trigger
--leve-menu-available-widthThe width available in the viewport
--leve-menu-available-heightThe height available in the viewport, for example for max-height

The Content gets inline position, top and left while it is open. Set display only on :popover-open, since on the Content itself it would override the browser's display: none of the closed popover.

Item#

PropDefaultType
as'div'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <div>. A component must spread the props it receives onto one element.

disabledfalseboolean

Disables the item: it cannot be selected and arrow keys skip it.

onSelect$–QRL<() => void>

Called when the item is selected with a click, Enter or Space.

closeOnSelecttrueboolean

Whether selecting the item closes the menu.

textValue–string

The text used by typeahead, when the item's text content is not suitable.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-itemAlways present
data-disabledPresent when disabled
data-text-valueThe textValue, when set

The focused item is the highlighted one: arrow keys, typeahead and the pointer move focus, so style it with :focus.

CheckboxItem#

PropDefaultType
defaultCheckedfalseboolean

Whether the item is checked initially (uncontrolled).

bind:checked–Signal<boolean>

A signal with the checked state (controlled).

onCheckedChange$–QRL<(checked: boolean) => void>

Called when the user checks or unchecks the item.

disabledfalseboolean

Disables the item: it cannot be changed and arrow keys skip it.

closeOnSelecttrueboolean

Whether a click or Enter closes the menu. Space never closes it (APG).

textValue–string

The text used by typeahead, when the item's text content is not suitable.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-checkbox-itemAlways present
data-state"checked" | "unchecked"
data-disabledPresent when disabled

RadioGroup#

PropDefaultType
defaultValuenullstring | null

The value selected initially (uncontrolled).

bind:value–Signal<string | null>

A signal with the selected value (controlled).

onValueChange$–QRL<(value: string) => void>

Called when the user selects a value.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-radio-groupAlways present

RadioItem#

PropDefaultType
value (required)–string

The value of this item.

disabledfalseboolean

Disables the item: it cannot be selected and arrow keys skip it.

closeOnSelecttrueboolean

Whether a click or Enter closes the menu. Space never closes it (APG).

textValue–string

The text used by typeahead, when the item's text content is not suitable.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-radio-itemAlways present
data-state"checked" | "unchecked"
data-disabledPresent when disabled

ItemIndicator#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-menu-item-indicatorAlways present
data-state"checked" | "unchecked"

The indicator has the hidden attribute while its item is unchecked.

Sub#

PropDefaultType
defaultOpenfalseboolean

Whether the submenu is open initially (uncontrolled).

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the submenu opens or closes by a user interaction.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-subAlways present
data-state"open" | "closed"

SubTrigger#

PropDefaultType
disabledfalseboolean

Disables the item: it cannot open the submenu and arrow keys skip it.

textValue–string

The text used by typeahead, when the item's text content is not suitable.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-sub-triggerAlways present
data-state"open" | "closed"
data-disabledPresent when disabled

SubContent#

PropDefaultType
side'right''top' | 'right' | 'bottom' | 'left'

The side of the SubTrigger to place the submenu on. It flips when there is no room.

align'start''start' | 'center' | 'end'

The alignment along that side.

sideOffset0number

The distance from the SubTrigger in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the menu to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

arrowPadding0number

The padding between the arrow and the corners of the menu, in px.

Also accepts all <div> attributes.

Data attributeValue
data-leve-menu-sub-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping
data-align"start" | "center" | "end"

The submenu exposes the same CSS variables as the Content with the --leve-menu-sub- prefix.

Group#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-menu-groupAlways present

GroupLabel#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-menu-group-labelAlways present

Separator#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-menu-separatorAlways present

Arrow#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-menu-arrowAlways present
data-sideThe final side of the Content

Accessibility#

Complies with the Menu Button WAI-ARIA design pattern.

  • Menu.Trigger renders aria-haspopup="menu", aria-expanded and aria-controls. Menu.Content renders role="menu" and is named by the Trigger with aria-labelledby.
  • Items render role="menuitem" and tabindex="-1": focus moves between them with the keyboard (roving focus), and the menu is one tab stop.
  • Disabled items render aria-disabled="true". They are announced but cannot be selected, and arrow keys skip them.
  • Menu.Group renders role="group", named by its Menu.GroupLabel.
  • Menu.SubTrigger renders role="menuitem" with aria-haspopup="menu", aria-expanded and aria-controls; Menu.SubContent renders role="menu", named by its SubTrigger.
  • Menu.CheckboxItem and Menu.RadioItem render role="menuitemcheckbox" / role="menuitemradio" with aria-checked. Menu.RadioGroup renders role="group"; name it with aria-label, or place it in a Menu.Group with a label. Menu.ItemIndicator is hidden from assistive technologies, since aria-checked conveys the state.

Keyboard Interactions#

KeyDescription
Enter / Space / ArrowDownOn the Trigger, opens the menu and focuses the first item.
ArrowUpOn the Trigger, opens the menu and focuses the last item.
ArrowDown / ArrowUpMoves focus to the next / previous enabled item. Wraps around when loop is set.
Home / EndMoves focus to the first / last enabled item.
A characterMoves focus to the next item that starts with the typed characters.
Enter / SpaceOn an item, selects it and closes the menu.
SpaceOn a checkbox or radio item, changes it without closing the menu.
EnterOn a checkbox or radio item, changes it and closes the menu.
ArrowRight / Enter / SpaceOn a SubTrigger, opens the submenu and focuses its first item.
ArrowLeftIn a submenu, closes it and returns focus to its SubTrigger.
EscapeCloses the submenu, or the menu, and returns focus to the SubTrigger or the Trigger.
TabCloses the menu and moves focus on.