Dropdown Menu

Dropdown patterns with icons, submenus, and checkmarks. Keyboard accessible with ARIA menu semantics.

Overview

The dropdown component uses the <dropdown-wc> 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.

 <dropdown-wc> <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> </dropdown-wc>

Dropdown with Icons

Add icons to menu items for visual context. Use an icon-only trigger with visually-hidden text for accessibility.

 <dropdown-wc> <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> </dropdown-wc>

User Account Dropdown

A common pattern for user account menus with avatar and chevron indicator.

 <dropdown-wc> <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> </dropdown-wc>

Configuration

The <dropdown-wc> element accepts these data attributes:
Attribute Values Description
data-position top-start top-end
bottom-start bottom-end
left-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 dropdown-wc elements for submenus. Use data-position="right-start" for proper positioning.

 <dropdown-wc> <button data-trigger>Actions</button> <menu> <li><button>New File</button></li> <li><button>New Folder</button></li> <li role="separator"></li> <li> <dropdown-wc data-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> </dropdown-wc> </li> </menu> </dropdown-wc>

Event Handling

Listen for dropdown events to respond to user actions.

 document.querySelector('dropdown-wc').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-hidden text 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