Dropdown
A menu of actions or links opened from a trigger button, such as an account menu or a row's More actions. Not for choosing a form value: use aihio-combobox for that.
Intents
menu
overlay
dismissible
Examples
Each one rendered live, over the markup that produces it.
A menu of actions
<aihio-dropdown>
<aihio-button slot="trigger" variant="outline">Open</aihio-button>
<aihio-dropdown-item>Profile</aihio-dropdown-item>
<aihio-dropdown-item>Settings</aihio-dropdown-item>
<aihio-dropdown-separator></aihio-dropdown-separator>
<aihio-dropdown-item>Logout</aihio-dropdown-item>
</aihio-dropdown>An account menu with links
An item whose child is an <a href> is a real link.
<aihio-dropdown align="end">
<aihio-button slot="trigger" variant="ghost">Account</aihio-button>
<aihio-dropdown-item><a href="/profile">Profile</a></aihio-dropdown-item>
<aihio-dropdown-item><a href="/settings">Settings</a></aihio-dropdown-item>
<aihio-dropdown-separator></aihio-dropdown-separator>
<aihio-dropdown-item value="sign-out">Sign out</aihio-dropdown-item>
</aihio-dropdown>Mistakes
Each one beside its fix, with what aihio lint says about it. The prompt fragment gives agents the
same pairs, and the build fails if the linter stops catching one or a fix stops passing.
Missing slot="trigger".
The dropdown has nothing to open it.
Don't
<aihio-dropdown>
<aihio-dropdown-item>Profile</aihio-dropdown-item>
</aihio-dropdown>aihio lint reports
-
missing-required-sloterror
Do
<aihio-dropdown>
<aihio-button slot="trigger" variant="outline">Account</aihio-button>
<aihio-dropdown-item>Profile</aihio-dropdown-item>
</aihio-dropdown>Children should be aihio-dropdown-item/separator so keyboard navigation and menuitem roles work.
Put the link inside an item: <aihio-dropdown-item><a href="/x">Link</a></aihio-dropdown-item>.
Don't
<aihio-dropdown>
<aihio-button slot="trigger">Menu</aihio-button>
<a href="/x">Link</a>
</aihio-dropdown>aihio lint reports
-
invalid-childerror
Do
<aihio-dropdown>
<aihio-button slot="trigger">Menu</aihio-button>
<aihio-dropdown-item><a href="/x">Link</a></aihio-dropdown-item>
</aihio-dropdown>API
Every attribute, property, method, and event the schema declares for aihio-dropdown.
Attributes
open-
boolean
default
false - Whether the dropdown is open
align-
one of
startenddefaultstart - Alignment of the dropdown content relative to the trigger
Methods
open(options?: { focus?: "first" | "last" | null }): void- Opens the menu in the browser top layer.
close(options?: { restoreFocus?: boolean; reason?: string }): void- Requests that the menu close.
toggle(options?: { focus?: "first" | "last" | null; restoreFocus?: boolean }): void- Toggles the menu.
Events
aihio-open- Fired after the menu opens.
aihio-close-
detail
{ reason: string } - Fired after the menu closes.
aihio-before-close-
detail
{ reason: string }cancelable - Cancelable request fired before the menu closes.
Slots
trigger- The element that opens the dropdown. Must be focusable.
default- Dropdown items and separators.
Composition
- Required slots
-
trigger - Allowed children
-
aihio-dropdown-itemaihio-dropdown-separatoraihio-button
Sub-components
Used only inside aihio-dropdown, which gives them their roles and keyboard behaviour.
<aihio-dropdown-item>
A selectable item in the dropdown. Give it a single <a href> child to make it a link.
Attributes
value- string
- Item value (defaults to text content)
disabled-
boolean
default
false
Events
aihio-select-
detail
{ value: string } - Fired when the item is selected
<aihio-dropdown-separator>
A visual separator between dropdown items
Accessibility
What you have to provide, and what the component already does. The obligations with a rule are checked by
aihio lint and by the dev build's console warnings.
Your obligations
-
error When the trigger is icon-onlyProvide aria-label on the trigger (e.g.
aria-label="Open menu").Checked as
dropdown-trigger-name
Handled for you
aria-haspopup="menu"is set on the trigger- aria-expanded is toggled on the trigger
role="menu"is set on the content panelrole="menuitem"is set on each dropdown item — or, when the item's child is<a href>, on that link, which also takes the focus- Arrow keys move focus between items; Home/End jump to first/last
- Typing a character moves to the next item whose label starts with it; a repeated letter cycles through the matches
- A link item follows itself natively on Enter (so Ctrl/Cmd+Enter and middle-click open a new tab); Space is mapped to it
- Escape closes and restores focus to the trigger
- Tab and Shift+Tab close the menu and move on through the page
- Click outside closes the menu
- The Popover API provides top-layer rendering where supported; the component handles Escape and outside-pointer dismissal so close requests remain cancelable
- The menu flips above the trigger and clamps to viewport edges when needed