--- title: "Dropdown" subtitle: "Contextual menus and action lists" description: "How to use the dropdown component for contextual menus, action lists, settings panels, and navigation." author: "Studio" section: "Design System" layer: "core" subsection: "Content" order: 5 status: "published" access: "team" client: "internal" --- 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. --- ## Tokens | Token | Default | Purpose | |-------|---------|---------| | `var(--dropdown-background)` | `var(--background-primary)` | Menu background | | `var(--dropdown-border)` | `var(--border-faded)` | Menu and divider border | | `var(--dropdown-item-hover)` | `var(--background-faded)` | Item hover background | | `var(--dropdown-item-padding-y)` | `var(--space-l)` | Item vertical padding | | `var(--dropdown-item-padding-x)` | `var(--space-m)` | Item horizontal padding | --- ## 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.
```html
``` ### Icon-only trigger For toolbars and compact contexts. No text, no chevron — the icon alone signals "click for options."
```html ``` ### Button trigger For page content where the trigger should look like a standard button.
```html ``` --- ## When to use a chevron | Scenario | Chevron? | Why | |----------|----------|-----| | Selector-style trigger (choosing a value) | Yes | Signals "pick from a list" | | Navigation dropdown (Account, Profile) | Yes | Shows the menu expands downward | | Icon-only trigger (⋯ more, settings gear) | No | The icon itself implies a menu | | Button trigger with label | Optional | Use when the button looks like a selector | --- ## Menu alignment Menus open left-aligned by default. Add `.is-right` to right-align from the trigger. ```html
``` 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.
```html ``` ### Icon-left item An icon before the text reinforces the action. Use for action verbs like Edit, Download, Delete.
```html ``` ### 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.
```html ``` ### Item with description Use `.dropdown-desc` for supporting text below the label.
```html ``` ### Avatar item For user menus showing the logged-in user's identity.
E
Erlen Masson
erlen@bydefault.studio
--- ## Section labels Use `.dropdown-label` to create non-interactive section headers that group items.
Actions
Danger zone
```html
Actions
...
Danger zone
``` --- ## Disabled item
```html ``` --- ## When to use what | Pattern | When to use | Example | |---------|-------------|---------| | Icon-left | Action verbs — the icon reinforces what the action does | Edit, Download, Delete, Settings | | Icon-right (`.dropdown-item-end`) | Trailing metadata — keyboard shortcuts, badges, status | Undo `Ctrl+Z`, Status `Active` | | No icon | Simple value selection — the text is self-explanatory | Role names, client names, sizes | | Avatar | User identification — profile menus | Account dropdown | | Description (`.dropdown-desc`) | Items that need explanation | "From template — Choose from pre-built..." | | Section label (`.dropdown-label`) | Grouping related items under a heading | "Switch Role", "Danger zone" | | Divider (`.dropdown-divider`) | Separating logical groups | Between actions and danger items | --- ## JavaScript Include `assets/js/dropdown.js` on any page. It auto-initialises all `.dropdown` elements — no setup needed. ```html ``` Clicking a `.dropdown-trigger` toggles `.is-open` on the parent `.dropdown`. Clicking outside or pressing Escape closes all open dropdowns. --- ## Keyboard interactions | Key | Action | |-----|--------| | `Enter` / `Space` | Opens the dropdown (on trigger), activates item (on item) | | `ArrowDown` | Moves focus to the next item | | `ArrowUp` | Moves focus to the previous item | | `Escape` | Closes the dropdown and returns focus to the trigger | | `Tab` | Moves focus out of the dropdown | --- ## Accessibility notes - 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 `` for link items - Dividers: `role="separator"` - Disabled items: `disabled` attribute + `aria-disabled="true"` --- ## Structure reference | Element | Class | Purpose | |---------|-------|---------| | Container | `.dropdown` | Positioning context | | Trigger | `.dropdown-trigger` | Clickable element that opens the menu | | Chevron | `.dropdown-chevron` | Rotating arrow indicator (on trigger) | | Menu | `.dropdown-menu` | The panel that appears | | Menu (right) | `.dropdown-menu .is-right` | Right-aligned from trigger | | Item | `.dropdown-item` | Clickable row | | Item (danger) | `.dropdown-item .dropdown-item--danger` | Destructive action | | Item (disabled) | `.dropdown-item .is-disabled` | Unavailable action | | Trailing content | `.dropdown-item-end` | Right-aligned metadata inside an item | | Description | `.dropdown-desc` | Supporting text under item label | | Label | `.dropdown-label` | Non-interactive section header | | Divider | `.dropdown-divider` | Separator line between groups | --- ## Do / Don't **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 `