Skip to content

Dropdown Menu

A menu button (WAI-ARIA menu button pattern): a trigger opens a role="menu" of action items.

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.

<script>
import DropdownMenu from "@invisible-ui/svelte/DropdownMenu.svelte";
</script>

items takes three kinds of entry, in any order:

  • an action: { value, label } — activating it runs something.
  • a checkable item: add kind: "checkbox" or kind: "radio" plus checked. The item announces itself as menuitemcheckbox or menuitemradio and 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>

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 onSelect reports 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)}
/>
PropTypeDefaultDescription
label *string—
items *MenuEntry[]—
disabledbooleanfalse
onSelect((value: string) => void) | undefinedundefinedCalled with the chosen item's value.
  • Trigger carries aria-haspopup="menu" / aria-expanded; the popup is role="menu" with role="menuitem", role="menuitemcheckbox" or role="menuitemradio" items, role="separator" lines and role="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).
<DropdownMenu
label="Actions"
items={[
{ value: "rename", label: "Rename" },
{ value: "delete", label: "Delete" },
]}
onSelect={(v) => run(v)}
/>

Themeable via --ds-menu-*.