Dropdown

Dropdowns show a contextual menu when a trigger is clicked. They are the universal menu pattern, used in the site header, sticky bars, tool toolbars, and page content. One component, same classes everywhere.

Trigger patterns

The trigger is the element that opens the dropdown. .dropdown-trigger provides built-in styling, no additional classes needed.

Icon + text + chevron

The most common trigger. The .dropdown-chevron rotates 180 degrees when the dropdown is open.

<div class="dropdown">
  <button class="dropdown-trigger" type="button" aria-haspopup="true" aria-expanded="false">
    <div class="svg-icn" data-icon="user"><!-- svg --></div>
    <span>Account</span>
    <div class="svg-icn dropdown-chevron" data-icon="chevron-down"><!-- svg --></div>
  </button>
  <div class="dropdown-menu">
    <!-- items -->
  </div>
</div>

Icon-only trigger

For toolbars and compact contexts. No text, no chevron. The icon alone signals "click for options."

<button class="dropdown-trigger" type="button" aria-haspopup="true" aria-expanded="false" aria-label="More options">
  <div class="svg-icn" data-icon="more-horizontal"><!-- svg --></div>
</button>

Button trigger

For page content where the trigger should look like a standard button.

<button class="dropdown-trigger button" data-variant="outline" type="button" ...>
  Options
  <div class="svg-icn dropdown-chevron"><!-- chevron svg --></div>
</button>

When to use a chevron

Menu alignment

Menus open left-aligned by default. Add .is-right to right-align from the trigger.

<div class="dropdown-menu is-right">

Use .is-right when the dropdown is near the right edge of the viewport to prevent overflow.

Item patterns

Text-only item

The simplest item, just a label with no icon.

<button class="dropdown-item" role="menuitem" type="button">Admin</button>

Icon-left item

An icon before the text reinforces the action. Use for action verbs like Edit, Download, Delete.

<button class="dropdown-item" role="menuitem" type="button">
  <div class="svg-icn" data-icon="settings"><!-- svg --></div>
  <span>Settings</span>
</button>

Icon-right item (trailing content)

Use .dropdown-item-end to push trailing content to the right edge. Ideal for keyboard shortcuts, badges, status indicators, or chevrons hinting at sub-menus.

<button class="dropdown-item" role="menuitem" type="button">
  <span>Undo</span>
  <span class="dropdown-item-end"><kbd>Ctrl+Z</kbd></span>
</button>

Item with description

Use .dropdown-desc for supporting text below the label.

<button class="dropdown-item" role="menuitem" type="button">
  <div>
    <div>From template</div>
    <div class="dropdown-desc">Choose from pre-built project templates</div>
  </div>
</button>

Avatar item

For user menus showing the logged-in user's identity.

Section labels

Use .dropdown-label to create non-interactive section headers that group items.

<div class="dropdown-label">Actions</div>
<button class="dropdown-item" role="menuitem" type="button">Rename</button>
...
<div class="dropdown-divider" role="separator"></div>
<div class="dropdown-label">Danger zone</div>
<button class="dropdown-item dropdown-item--danger" role="menuitem" type="button">Delete project</button>

Disabled item

<button class="dropdown-item is-disabled" role="menuitem" type="button" disabled aria-disabled="true">
  Save as...
</button>

When to use what

JavaScript

Include assets/js/dropdown.js on any page. It auto-initialises all .dropdown elements, no setup needed.

<script src="/assets/js/dropdown.js"></script>

Clicking a .dropdown-trigger toggles .is-open on the parent .dropdown. Clicking outside or pressing Escape closes all open dropdowns.

Keyboard interactions

Accessibility

• Trigger: aria-haspopup="true", aria-expanded="false" (JS updates to "true" on open)
• Icon-only triggers: add aria-label describing the action
• Menu: role="menu"
• Items: role="menuitem" on buttons, or just <a> for link items
• Dividers: role="separator"
• Disabled items: disabled attribute + aria-disabled="true"

Structure reference

Usage rules

Do:

• Use dropdowns for contextual actions and selections
• Group related items with labels and dividers
• Use icon-left for actions, icon-right for metadata
• Add aria-label on icon-only triggers
• Use .is-right near the right viewport edge

Don't:

• Don't use dropdowns for primary navigation, use tabs or links
• Don't nest dropdowns inside dropdowns
• Don't use dropdowns for form field selection, use <select> instead
• Don't put more than 10 items in a single dropdown, break into sections or use a different pattern

CSS reference

This section documents how the component is built. For usage, see the sections above.

Tokens

Selectors