Dropdown Menu
Dropdown patterns with icons, submenus, and checkmarks. Keyboard accessible with ARIA menu semantics.
Overview
The dropdown component uses the <drop-down> web component with native <menu> elements. It provides keyboard navigation, focus management, and proper ARIA roles for accessibility.
Key features:
- Keyboard navigation with arrow keys
- Escape key closes dropdown
- Click outside closes dropdown
- Support for icons and separators
- Multiple placement options
- Nested submenus
Basic Dropdown
A simple dropdown with action items and a separator before destructive action.
<drop-down> <button data-trigger>Options</button> <menu> <li><button>Edit</button></li> <li><button>Duplicate</button></li> <li><button>Share</button></li> <li role="separator"></li> <li><button class="danger">Delete</button></li> </menu></drop-down>Dropdown with Icons
Add icons to menu items for visual context. Use an icon-only trigger with visually-hidden text for accessibility.
<drop-down> <button data-trigger> <icon-wc name="more-vertical" size="sm"></icon-wc> <span class="visually-hidden">More actions</span> </button> <menu> <li> <button> <icon-wc name="pencil" size="sm"></icon-wc> Edit </button> </li> <li> <button> <icon-wc name="copy" size="sm"></icon-wc> Duplicate </button> </li> <li role="separator"></li> <li> <button class="danger"> <icon-wc name="trash-2" size="sm"></icon-wc> Delete </button> </li> </menu></drop-down>User Account Dropdown
A common pattern for user account menus with avatar and chevron indicator.
<drop-down> <button data-trigger class="ghost"> <layout-cluster data-layout-gap="s"> <span class="avatar">JD</span> <span>John Doe</span> <icon-wc name="chevron-down" size="xs"></icon-wc> </layout-cluster> </button> <menu> <li> <button> <icon-wc name="user" size="sm"></icon-wc> Profile </button> </li> <li> <button> <icon-wc name="settings" size="sm"></icon-wc> Settings </button> </li> <li role="separator"></li> <li> <button> <icon-wc name="log-out" size="sm"></icon-wc> Sign Out </button> </li> </menu></drop-down>Configuration
The <drop-down> element accepts these attributes:
| Attribute | Values | Description |
|---|---|---|
position |
top-start top-endbottom-start bottom-endleft-start right-start |
Position of the dropdown relative to trigger. Default is bottom-start. |
Trigger Button
Mark the trigger button with data-trigger:
| Attribute | Description |
|---|---|
data-trigger |
Marks the button that opens the dropdown (required). |
Nested Submenus
Nest drop-down elements for submenus. Use position="right-start" for proper positioning.
<drop-down> <button data-trigger>Actions</button> <menu> <li><button>New File</button></li> <li><button>New Folder</button></li> <li role="separator"></li> <li> <drop-down position="right-start"> <button data-trigger> Export As <icon-wc name="chevron-right" size="xs"></icon-wc> </button> <menu> <li><button>PDF</button></li> <li><button>Word Document</button></li> <li><button>Plain Text</button></li> </menu> </drop-down> </li> </menu></drop-down>Event Handling
Listen for dropdown events to respond to user actions.
document.querySelector('drop-down').addEventListener('select', (e) => { console.log('Selected:', e.detail.value);}); dropdown.addEventListener('open', () => { console.log('Dropdown opened');}); dropdown.addEventListener('close', () => { console.log('Dropdown closed');});Usage Notes
- Accessibility: Use
visually-hiddentext for icon-only triggers - Separators: Use
<li role="separator">to group related items - Danger actions: Add
class="danger"for destructive actions - Keyboard: Arrow keys navigate, Enter/Space select, Escape closes
- Placement: The dropdown auto-adjusts if there isn't enough space
Related
Dropdown WC
Web component documentation
Modal Dialog
Modal dialog patterns