Dropdown

A dropdown groups actions that don't need to be visible all the time, behind a button. The most common case in Home Assistant is the overflow menu: the three dots button in the top right of a page, a card, or a row, with everything you can do with that item. It keeps the screen calm, while the actions stay one tap away.

Use a dropdown for:

• Actions on an item that are used less often, like Duplicate or Download
• View options, like which columns to show or the sort order
• A short list of related items in a submenu, like the areas to move something to

Don't use a dropdown for:

• The main action of a screen. If people come to a screen to save, the Save button belongs on the screen itself.
• Picking a value in a form. A dropdown is a menu, not a form field. Use a select, or a select box for a few options that need explaining.

1. Trigger: the element that opens the menu, like an icon button or a button with a caret
2. Menu: the raised surface with the items
3. Item: one action or option, with a label
4. Icon: optional, before the label of an item
5. Checkmark: on checkbox items, shows whether the option is on
6. Details: optional extra content after the label, like a keyboard shortcut
7. Submenu indicator and submenu: on an item with a submenu, an arrow at the end, and a second menu next to the item

In the frontend the trigger is often an icon button with the three dots icon, with the menu opening below it, aligned to its end. A button with a caret works too, when a label makes the menu easier to find.

Keep labels short, and start with a verb when the item runs an action: Edit, Duplicate, Download. An icon before the label helps people scan a longer menu.

Destructive actions, like Delete, use the danger variant: the label and icon turn red.

A dropdown can also hold options. Checkbox items are for settings that are on or off, like which columns to show. A selected item marks the current choice from a set, like the sort order.

Put related items in a submenu, like a list of areas to move something to, so the main menu stays short.

Disable an item when the action exists, but is not possible right now.

• Opening: selecting the trigger opens the menu, and selecting it again closes it. Opening one dropdown closes any other open dropdown. The menu scales up from 90% and fades in.
• Placement: the menu opens below the trigger, aligned to its start, by default. If there is no room, it flips to the other side, and it shifts to stay at least 10px from the edges of the screen. A long menu gets a maximum height and scrolls, and on phones it stays clear of the notch and the navigation bar.
• Hover: on devices with a pointer that can hover, an item gets the normal neutral fill. A danger item gets the normal danger fill.
• Focus: the focused item gets the same fill as on hover, and a focus ring.
• Selected: a selected item gets a quiet primary fill, a medium font weight, and the primary color for its label and icon.
• Checked: a checkbox item shows a marked checkbox icon when it is on, and an empty one when it is off.
• Disabled: a disabled item is shown at 50% opacity, and selecting it does nothing.
• Selecting: selecting an item closes the menu and moves focus back to the trigger. A checkbox item is toggled first. The page can keep the menu open in code.
• Closing: the menu also closes with Escape, with Tab, or by selecting anywhere outside of it.
• Submenus: moving the pointer from an item to its submenu keeps the submenu open, even when the pointer crosses other items on the way.

When the trigger is an icon button, it is shown as selected while the menu is open.

• Start the label of an action with a verb: Edit, Duplicate, Download.
• Put destructive actions, like Delete, at the end of the menu, with the danger variant.
• When a destructive action cannot be undone, ask for confirmation in a dialog first. See remove, delete, add, or create for picking the right word.
• Use a submenu to keep a long list of related items out of the main menu.
• Disable an item when the action exists, but is not possible right now, instead of hiding it.

Only one item at a time can take focus, so Tab doesn't walk through every item. Arrow keys move between items instead. The focused item shows a focus ring.

Each item is at least 40px high.

The menu is announced as a menu, and each item with its position, like "2 of 5". Checkbox items are announced as checked or not checked, disabled items as disabled, and items with a submenu as having one. A selected item looks selected, but is not announced as selected.

• The menu has the role menu, with a vertical orientation.
• Items have the role menuitem. Checkbox items have the role menuitemcheckbox, with aria-checked.
• Each item gets its position in the menu, with aria-posinset and aria-setsize.
• A disabled item has aria-disabled="true".
• An item with a submenu has aria-haspopup="menu", and aria-expanded while its submenu is open.
• The trigger gets aria-haspopup="menu", and aria-expanded set to true or false.
• The selected attribute changes the look of an item, but it sets no ARIA state.
• An icon button used as a trigger needs a label, which becomes its accessible name.

• Button: for the main action, and as a trigger
• Select box: picking a value in a form
• Dialog: confirming a destructive action from the menu
• UI text: how to write labels

The elements are <ha-dropdown> and <ha-dropdown-item>. They are based on the Web Awesome dropdown and dropdown item.

<ha-dropdown placement="bottom-end">
  <ha-button slot="trigger" with-caret>Actions</ha-button>
  <ha-dropdown-item value="edit">
    <ha-svg-icon slot="icon" path="..."></ha-svg-icon>
    Edit
  </ha-dropdown-item>
  <ha-dropdown-item value="delete" variant="danger">Delete</ha-dropdown-item>
</ha-dropdown>

<ha-dropdown>:

• placement: where the menu opens, relative to the trigger. bottom-start (default), bottom, bottom-end, top-start, top, top-end, left-start, left, left-end, right-start, right, or right-end. If there is no room, the menu flips to the other side.
• distance: the distance between the trigger and the menu, in pixels.
• skidding: shifts the menu along the trigger, in pixels.
• open: opens the menu.

<ha-dropdown-item>:

• value: identifies the item in the wa-select event.
• variant: default or danger.
• type: normal (default) or checkbox.
• checked: turns a checkbox item on.
• selected: marks the item as the current choice. This is an addition in Home Assistant, not part of Web Awesome.
• disabled: disables the item.
• href, target, rel, and download: turn the item into a link.

When the trigger is an <ha-icon-button>, the dropdown marks it as selected while the menu is open. You can also open the menu from another element, by setting the anchorElement property from code.

<ha-dropdown>:

• Default: the items.
• trigger: the element that opens the menu, like a button or an icon button.

<ha-dropdown-item>:

• Default: the label.
• icon: an icon before the label.
• details: extra content after the label, like a keyboard shortcut.
• submenu: the items of a submenu.

• wa-select: fires on <ha-dropdown> when people select an item. The item is in event.detail.item, so read event.detail.item.value to know which one. Checkbox items are already toggled when the event fires. Call event.preventDefault() to keep the menu open.
• wa-show and wa-after-show: fire when the menu opens, and after the animation.
• wa-hide and wa-after-hide: fire when the menu closes, and after the animation.

• --ha-dropdown-font-size: the font size of the menu. Defaults to var(--ha-font-size-m).
• --show-duration and --hide-duration: the duration of the open and close animations.

Source: src/components/ha-dropdown.ts and src/components/ha-dropdown-item.ts