Dropdown Menu

Use hui-menu for a short command or selection list opened from a trigger. Use a select for choosing a form value and a popover for arbitrary interactive content. Do not use a menu for long navigational lists or unrelated page content.

• Root: hui-menu
• Trigger and popup: hui-menu-trigger, hui-menu-content
• Items: hui-menu-item, hui-menu-item-checkbox, hui-menu-item-radio
• Supporting parts: hui-menu-group, hui-menu-label, hui-menu-separator

hui-menu

The root exposes data-state="open|closed" and emits hui-open-change with { open }.

Trigger and content

hui-menu-trigger renders a native button with aria-haspopup="menu", aria-expanded, and guarded aria-controls. Its disabled and accessible-name attributes are applied to the button.

hui-menu-content renders role="menu", aria-orientation="vertical", and an inline hidden attribute while closed. Open content is moved to a document-level portal so clipped ancestors cannot hide it. The content exposes data-state and data-placement. After opening, page scrolling does not reposition the content; it stays at its last document coordinates, allowing the page to carry it out of the viewport. Opening and viewport resizing still run collision-aware positioning.

During a motion-safe exit, the content keeps its mount and portal until the tokenized transition completes. It is aria-hidden, inert, and non-interactive while data-state="closed"; no-transition and reduced-motion paths apply hidden immediately.

Items

• hui-menu-item renders role="menuitem".
• hui-menu-item-checkbox renders role="menuitemcheckbox" and uses the boolean checked attribute as its source of truth.
• hui-menu-item-radio renders role="menuitemradio" and uses the boolean checked attribute. Activating one radio clears the other radio items in the same menu.
• All item types support value, disabled, and highlighted.
• When value is omitted, item identity falls back to the host id, then the item's positional index. Use explicit values for collections whose order can change.
• The highlighted item exposes data-highlighted and is the only item with tabindex="0"; other enabled items use tabindex="-1".
• Checkbox and radio items expose aria-checked and data-state.

Activating an item emits hui-select with { value }. Checkbox and radio state changes also emit hui-checked-change with { value, checked } from the menu root.

hui-menu-group renders role="group" and uses a contained hui-menu-label for aria-labelledby when no explicit group label is provided. hui-menu-separator renders role="separator".

• Trigger ArrowDown opens and focuses the first enabled item.
• Trigger ArrowUp opens and focuses the last enabled item.
• Trigger Enter, Space, and click toggle the menu.
• Menu ArrowUp/ArrowDown moves the roving tab stop, skipping disabled items.
• Home and End move to the first and last enabled items.
• Printable keys use a 500ms buffered typeahead search and skip disabled items.
• Enter and Space activate the highlighted item.
• Escape closes the menu and restores focus to the trigger.
• Tab closes the menu while preserving the browser's normal focus movement.
• Pointer activation works for all item kinds; disabled items do nothing.
• Outside pointer-down and outside focus close the menu. The dismissable-layer stack closes only the topmost open layer.

SSR renders the trigger ARIA relationship, menu roles, item states, and closed content with hidden="hidden". The server never emits portal markers. IDs are pure functions of the root ID and stable item values; id-less menus do not emit aria-controls or generated IDs. default-open serializes visible content.

Hydration re-renders component-owned template nodes while preserving projected consumer content and host attributes. The client portal is applied only when an open menu is enhanced. Without JavaScript, the trigger remains a native button and the menu content remains hidden; consumers can use default-open for a progressive visible fallback.

<hui-menu id="account-menu" aria-label="Account actions">
  <hui-menu-trigger>Account</hui-menu-trigger>
  <hui-menu-content>
    <hui-menu-item value="profile">Profile</hui-menu-item>
    <hui-menu-item value="sign-out">Sign out</hui-menu-item>
  </hui-menu-content>
</hui-menu>

<hui-menu id="playground-menu" aria-label="Account actions" placement="bottom" loop>
  <hui-menu-trigger>Account</hui-menu-trigger>
  <hui-menu-content>
    <hui-menu-item value="profile">Profile</hui-menu-item>
    <hui-menu-item value="settings">Settings</hui-menu-item>
    <hui-menu-separator></hui-menu-separator>
    <hui-menu-item value="sign-out">Sign out</hui-menu-item>
  </hui-menu-content>
</hui-menu>

• SelectChoose one or more values from a known set without free-text editing.
• PopoverAnchor supplemental interactive content to a trigger without trapping focus.
• DialogTemporarily interrupt a task with modal content and managed focus.