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