Dropdown
Button that toggles a menu of actions or links. Uses the native Popover API for top-layer rendering and light dismiss. Menu placement, viewport-edge collision detection, and auto-flip are delegated to the popout utility (built on Floating UI) via data-popout-* attributes.
Usage
When to use
- A button needs to reveal a short list of related actions or links
- An overflow menu is required for secondary actions (
⋮trigger) - A split button combines a primary action with additional options
When not to use
- For nested site navigation - use navbar (horizontal, floating panels) or sidenav (vertical, inline expand) instead
- For selecting a single value in a form - use a
<select>control - For large menus with search or filtering - use a dedicated combobox pattern
Do
- Wire
aria-expandedon the trigger to reflect menu state - Include a visible or
aria-labelaccessible name on icon-only triggers - Return focus to the trigger when the menu closes
Don't
- Don't nest dropdowns inside dropdowns
- Don't mix link and button items without a clear reason - pick the semantic that matches the action
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
trigger | string | - | Trigger button text or HTML. |
trigger_classes | array | - | CSS classes for the trigger button. |
primary | object | - | Split button primary action as an object with text and optional url keys. |
primary_classes | array | - | CSS classes for the primary split button. |
items | array | - | Array of menu item objects. Each item supports: {text, url?} for a link or button, {type: "divider"} for a separator, {type: "header", text} for a non-interactive group header, plus is_current (boolean) and is_disabled (boolean) flags. |
trigger_label | string | - | aria-label for the trigger when it has no visible text. |
has_chevron | boolean | - | Whether to render a caret after the trigger label. Set to false for icon-only triggers. |
menu_id | string | - | Unique id for the popover menu. Auto-generated when absent. |
placement | Enum: top, right, bottom, left | bottom | Preferred side of the trigger the menu opens on. Auto-flips when that side would overflow the viewport. |
boundary | string | - | CSS selector for an ancestor that constrains auto-flip. Defaults to the viewport. |
offset | number | - | Gap between the trigger and menu in pixels. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.left | Alignment | Yes | Anchored to the left. |
.right | Alignment | - | Anchored to the right. |
.center | Alignment | - | Centered. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | - | Slight elevation. |
.elevated | Elevation | Yes | High elevation. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-dropdown | Consumer | Yes | Marks the popover menu element; the aria-expanded sync, keyboard navigation, and focus management bind to it. |
data-popout-anchor | Consumer | - | CSS selector resolved by the popout utility to pick the menu anchor when the default (preceding sibling) is not appropriate. |
Examples
Default
Menu of links and buttons triggered by a standard button.
Icon trigger
Icon-only (⋮) overflow trigger for compact toolbars.
Split button
Primary action button plus a separate toggle that reveals related actions.
With separators and headers
Menu grouped by headers and dividers.
Positioning
Placement (top, right, bottom, left) and alignment (left, right, center) variants.
Accessibility
- WCAG 2.2 AA
- Trigger is keyboard-focusable and activates on Enter or Space
- Arrow keys navigate between menu items
- Home / End jump to first / last item
- Escape closes the menu and returns focus to the trigger
- Tab exits the menu
- Menu announces as a menu with items via ARIA roles
- Focus visible on the trigger and each menu item
Dependencies
- button - trigger inherits button variants (intent, fill, size)
- Native Popover API for top-layer rendering and light dismiss
- popout - handles positioning, collision detection, and auto-flip for the menu