--- title: "Dropdown" description: "A menu of links, actions and options that opens from a button, with checkbox and radio items, shortcuts and submenus. Keyboard and screen-reader friendly. The docs version switcher in the sidebar is one." url: "https://susonwaiba.github.io/htmx-ui/docs/components/dropdown" section: "Components" --- # Dropdown A menu of links, actions and options that opens from a button, with checkbox and radio items, shortcuts and submenus. Keyboard and screen-reader friendly. The docs version switcher in the sidebar is one. ```html
``` ## Markup - Wrap the trigger and menu in `.dropdown` with `data-dropdown`. - The trigger gets `data-dropdown-trigger`, `aria-haspopup="menu"` and `aria-expanded="false"`. - The menu gets `role="menu"` and starts `hidden`. Each entry is a link or button with `role="menuitem"`. - Mark the selected entry with `aria-current="true"`, and unavailable ones with `aria-disabled="true"`. - Add a `.dropdown-label` heading and `.dropdown-separator` lines (`role="separator"`) between sections as needed. The behaviour sets the rest: menu items get `tabindex="-1"` (focus moves with the arrow keys) and the trigger is linked to the menu with `aria-controls`. The same menu classes and behaviour make up each menu of a [menubar](https://susonwaiba.github.io/htmx-ui/docs/components/menubar). ## Icons and shortcuts Put an `icon()` before an item's text; icons in items are muted and sized to match. `.dropdown-shortcut` right-aligns a keyboard hint (a `.kbd` or a `.badge` sits there too). The hint is only text: the dropdown doesn't bind the key. If your page handles it, say so with `aria-keyshortcuts` on the item. ```html
``` ## Checkbox items An item with `role="menuitemcheckbox"` and `aria-checked="true"` or `"false"` toggles when chosen, showing a check in an inset slot on the left. Give plain items and labels next to them `.dropdown-item-inset` so their text lines up. ```html
``` ## Radio items Items with `role="menuitemradio"` inside a `role="group"` are a set: choosing one checks it and unchecks the rest of the group (without a group, the rest of the menu). Label the group with `aria-label`, or with `aria-labelledby` pointing at its `.dropdown-label`. ```html
``` Choosing a checkbox or radio item closes the menu like any other item. Add `data-keep-open` to an item, a group or the whole menu to keep it open instead, so several options can be set in a row: ```html
``` ## Submenus Wrap an item and a nested menu in `.dropdown-sub`. The item gets `aria-haspopup="menu"`, `aria-expanded="false"` and a `chevron-right` icon, which sits at the right edge. The submenu opens beside it on hover (after a short delay), on click, or with `→`, `Enter` or `Space`; `←` and `Esc` close it. Near the edge of the window it opens to the left or upwards instead. ```html
``` ## Destructive and disabled items `.dropdown-item-destructive` colours an item that deletes or discards something. `aria-disabled="true"` (or `disabled` on a button) fades an item out; it can't be chosen and the arrow keys skip it. ```html
``` ## Alignment The menu opens below the trigger, aligned to its left edge. Add `.dropdown-menu-end` to align it to the right edge, or `.dropdown-menu-up` to open it above the trigger. ```html
``` ## Actions with htmx Menu items can make htmx requests like any other button. The menu closes when an item is chosen. ```html
``` Checkbox and radio items fire a bubbling `menu:change` event when they change, with `detail.checked`, `detail.name` and `detail.value`. Give them a `name` (and a `value`; a checkbox item defaults to `on`) and each keeps a hidden input inside it in step, so a surrounding form submits the checked ones. This form posts on every change: ```html
``` ## Keyboard | Key | Action | | --- | --- | | `Enter` `Space` on the trigger | Open on the first item | | `↓` `↑` on the trigger | Open on the first / last item | | `↓` `↑` `Home` `End` | Next / previous / first / last item (wraps), skipping disabled ones | | Letters | Next item starting with the typed letters | | `Enter` `Space` | Choose the item (toggle a checkbox, check a radio) and close; open a submenu | | `→` `←` | Open / close a submenu | | `Esc` | Close the innermost menu and return focus to what opened it | | `Tab`, click outside | Close | With the mouse, hovering an item highlights (focuses) it, and hovering a submenu's item opens the submenu. ## Accessibility - The markup follows the [WAI-ARIA menu button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/): `menu`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, `group` and `separator` roles, with `aria-expanded`, `aria-controls` and `aria-checked` kept in step. - Name an icon-only trigger with `aria-label`, and label each radio group. - Use a dropdown for actions and navigation. For picking one value of a form field, use a [select](https://susonwaiba.github.io/htmx-ui/docs/components/select). ## Reference | Class / attribute | Description | | --- | --- | | `.dropdown` | Positioning wrapper (relative, inline-block). | | `.dropdown-menu` | The floating panel. Opens below, left-aligned. | | `.dropdown-menu-end / .dropdown-menu-up` | Align to the right edge / open above. | | `.dropdown-item` | Link or button inside the menu: role="menuitem", "menuitemcheckbox" or "menuitemradio". aria-current, aria-checked and aria-disabled are styled. | | `.dropdown-item-inset` | Indents an item or label to line up with checkbox and radio items. | | `.dropdown-item-destructive` | Danger-coloured item, for deleting or discarding. | | `.dropdown-shortcut` | Right-aligned, muted keyboard hint inside an item. | | `.dropdown-label` | Small muted heading inside the menu. | | `.dropdown-separator` | Divider line (role="separator"). | | `.dropdown-sub` | Wraps a submenu trigger (aria-haspopup="menu", aria-expanded) and its nested .dropdown-menu. | | `role="group"` | Groups radio items: checking one unchecks the others in the group. | | `data-keep-open` | On an item, group or menu: choosing an item doesn't close the menu. | | `name / value` | On checkbox and radio items: kept in a hidden input so a surrounding form submits them. | | `menu:change` | Bubbling event from a checkbox or radio item that changed; detail { checked, name, value }. | | `data-flip-x / data-flip-y` | Set on a submenu that would leave the window: it opens to the left / upwards. | | `[data-dropdown] / [data-dropdown-trigger]` | Behaviour: open/close, keyboard navigation, typeahead, submenus, checkbox and radio items, outside click. |