Skip to main content

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-expanded on the trigger to reflect menu state
  • Include a visible or aria-label accessible 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​

PropTypeDefaultDescription
triggerstring-Trigger button text or HTML.
trigger_classesarray-CSS classes for the trigger button.
primaryobject-Split button primary action as an object with text and optional url keys.
primary_classesarray-CSS classes for the primary split button.
itemsarray-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_labelstring-aria-label for the trigger when it has no visible text.
has_chevronboolean-Whether to render a caret after the trigger label. Set to false for icon-only triggers.
menu_idstring-Unique id for the popover menu. Auto-generated when absent.
placementEnum: top, right, bottom, leftbottomPreferred side of the trigger the menu opens on. Auto-flips when that side would overflow the viewport.
boundarystring-CSS selector for an ancestor that constrains auto-flip. Defaults to the viewport.
offsetnumber-Gap between the trigger and menu in pixels.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.leftAlignmentYesAnchored to the left.
.rightAlignment-Anchored to the right.
.centerAlignment-Centered.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.
.flatElevation-No elevation.
.raisedElevation-Slight elevation.
.elevatedElevationYesHigh elevation.

Attributes​

AttributeSet byRequiredDescription
data-dropdownConsumerYesMarks the popover menu element; the aria-expanded sync, keyboard navigation, and focus management bind to it.
data-popout-anchorConsumer-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
  • navbar - for nested site navigation submenus
  • select - for single-value form selection