Dropdown Menu
A menu button (WAI-ARIA menu button pattern): a trigger opens a role="menu" of
action items.
Dropdown Menu or Select?
Section titled “Dropdown Menu or Select?”Same popup mechanics, different semantics: a Dropdown Menu’s items run commands — verbs like Rename, Delete, Share — and nothing stays selected, while a Select picks a value that persists and submits with the form. If “what’s in the field right now?” makes sense, you want the Select.
Import
Section titled “Import”<script> import DropdownMenu from "@invisible-ui/svelte/DropdownMenu.svelte";</script><script setup> import { DropdownMenu } from "@invisible-ui/vue";</script>import { DropdownMenu } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-dropdown-menu></ds-dropdown-menu>What a menu can hold
Section titled “What a menu can hold”items takes three kinds of entry, in any order:
- an action:
{ value, label }— activating it runs something. - a checkable item: add
kind: "checkbox"orkind: "radio"pluschecked. The item announces itself asmenuitemcheckboxormenuitemradioand always states whether it is on. The menu reports the activation; the application decides the new state, as everywhere else here. - a separator:
{ type: "separator" }— a line, never a focus stop. - a group:
{ type: "group", label, items }— its items are announced as a named set. Arrow keys walk through grouped items as if they were flat.
<DropdownMenu label="View" items={[ { type: "group", label: "Sort by", items: [ { value: "name", label: "Name", kind: "radio", checked: sort === "name" }, { value: "date", label: "Date", kind: "radio", checked: sort === "date" }, ], }, { type: "separator" }, { value: "compact", label: "Compact rows", kind: "checkbox", checked: compact }, ]} onSelect={(v) => apply(v)}/>In Elements, assign the entries through the items property and listen for
select. The event fires after the menu closes:
<ds-dropdown-menu label="Actions"></ds-dropdown-menu><script type="module"> import "@invisible-ui/elements/define";
const menu = document.querySelector("ds-dropdown-menu"); menu.items = [ { value: "rename", label: "Rename" }, { type: "separator" }, { value: "delete", label: "Delete" }, ]; menu.addEventListener("select", (event) => run(event.detail.value));</script>Submenus
Section titled “Submenus”A submenu entry, { type: "submenu", value, label, items }, is an item that
opens a nested menu beside it. The React menus render submenus; the Svelte,
Vue and Elements menus render one level.
- Enter, Space or the arrow toward the inline end opens a submenu and focuses its first item; the arrow toward the inline start and Escape close one level; Tab and an outside press close every level. The arrows follow right-to-left text.
- The pointer resting 100 ms on a submenu item opens it. Moving diagonally toward the submenu across other items keeps it open; a tap opens it on touch.
- Space on a checkable item changes it and keeps the menu open, so several options can be set in a row. Enter and a press close every level, then report.
- Values are unique across the whole tree, and
onSelectreports the item’s value only. One level of submenu is recommended.
In React:
<DropdownMenu label="Actions" items={[ { value: "rename", label: "Rename" }, { type: "submenu", value: "share", label: "Share", items: [ { value: "email", label: "Email" }, { value: "link", label: "Copy link" }, ], }, { type: "separator" }, { value: "delete", label: "Delete" }, ]} onSelect={(value) => run(value)}/>| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | |
items * | MenuEntry[] | — | |
disabled | boolean | false | |
onSelect | ((value: string) => void) | undefined | undefined | Called with the chosen item's value. |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | The trigger button's visible label. |
items * | MenuEntry[] | — | |
disabled | boolean | false | |
onSelect | (value: string) => void | undefined | Called with the chosen item's value. |
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible text of the trigger, and the menu's accessible name. |
items * | MenuEntry[] | — | Items, separators, groups and submenus, in the order shown. |
disabled | boolean | false | |
onSelect | (value: string) => void | — | Called with the chosen item's value, after every level has closed. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | |
disabled | yes |
Reactive attributes re-render the element when they change after the first render.
Properties: items (MenuEntry[]).
Emits: bubbling select CustomEvent with detail.value, after the menu closes.
Accessibility
Section titled “Accessibility”- Trigger carries
aria-haspopup="menu"/aria-expanded; the popup isrole="menu"withrole="menuitem",role="menuitemcheckbox"orrole="menuitemradio"items,role="separator"lines androle="group"sets named by their label. - Open with Enter / Space / ArrowDown (ArrowUp opens to the last item); arrow / Home / End move, typeahead jumps, Enter/click activates, Escape / Tab / outside-pointer close. DOM focus moves into the menu and returns to the trigger on close.
- Popup positioning (flip/shift, stays attached on scroll) via
@floating-ui/dom. - Under a coarse pointer every item keeps a hit area of at least 44 by 44
(
--ds-metrics-density-touch-min-target-size).
Example
Section titled “Example”<DropdownMenu label="Actions" items={[ { value: "rename", label: "Rename" }, { value: "delete", label: "Delete" }, ]} onSelect={(v) => run(v)}/>Themeable via --ds-menu-*.