Navigation

Dropdown

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

Displays a menu to the user, such as a set of actions or functions, triggered by a button.

Usage#

app.component.ts

import { WDS_DROPDOWN } from '@wds/angular/dropdown';

Examples#

Default#

The element in the trigger slot opens the menu. Selecting an item fires wds-select with its value and closes the menu.

Open

My Account

Profile

Billing

Settings

Log out

Show code

dropdown-default.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownLabelComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-default-demo',
  imports: [WdsDropdownComponent, WdsDropdownLabelComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Open</wds-button>
      <wds-dropdown-label>My Account</wds-dropdown-label>
      <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
      <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      <wds-dropdown-item value="settings">Settings</wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="logout">Log out</wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownDefaultDemo {}

Shortcuts#

The shortcut slot shows a keyboard shortcut on the right. It is only displayed: handle the keys yourself.

Open

My Account

Profile⇧⌘P

Billing⌘B

Settings⌘S

Log out⇧⌘Q

Show code

dropdown-shortcuts.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownLabelComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-shortcuts-demo',
  imports: [WdsDropdownComponent, WdsDropdownLabelComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Open</wds-button>
      <wds-dropdown-label>My Account</wds-dropdown-label>
      <wds-dropdown-item value="profile">Profile<span slot="shortcut">⇧⌘P</span></wds-dropdown-item>
      <wds-dropdown-item value="billing">Billing<span slot="shortcut">⌘B</span></wds-dropdown-item>
      <wds-dropdown-item value="settings">Settings<span slot="shortcut">⌘S</span></wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="logout">Log out<span slot="shortcut">⇧⌘Q</span></wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownShortcutsDemo {}

Icons#

An <svg> before the text gets the icon size and spacing.

Open

Profile

Billing

Settings

Log out

Show code

dropdown-icons.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-icons-demo',
  imports: [WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Open</wds-button>
      <wds-dropdown-item value="profile">
        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /><circle cx="12" cy="7" r="4" /></svg>
        Profile
      </wds-dropdown-item>
      <wds-dropdown-item value="billing">
        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="20" height="14" x="2" y="5" rx="2" /><path d="M2 10h20" /></svg>
        Billing
      </wds-dropdown-item>
      <wds-dropdown-item value="settings">
        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
        Settings
      </wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="logout">
        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" /><path d="m16 17 5-5-5-5" /><path d="M21 12H9" /></svg>
        Log out
      </wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownIconsDemo {}

Checkboxes#

type="checkbox" toggles checked on selection; detail.checked in wds-select is the new state. The menu closes after each change.

View

Appearance

Status Bar

Activity Bar

Panel

Status Bar: on, Panel: off

Show code

dropdown-checkboxes.ts

import { Component, signal } from '@angular/core';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_DROPDOWN } from '@wds/angular/dropdown';

@Component({
  selector: 'app-dropdown-checkboxes-demo',
  imports: [...WDS_DROPDOWN, WdsButtonComponent],
  template: `
    <div class="flex flex-col items-center gap-3">
      <wds-dropdown>
        <wds-button slot="trigger" variant="outline">View</wds-button>
        <wds-dropdown-label>Appearance</wds-dropdown-label>
        <wds-dropdown-separator />
        <wds-dropdown-item type="checkbox" [checked]="statusBar()" (wdsSelect)="statusBar.set(!!$event.checked)">Status Bar</wds-dropdown-item>
        <wds-dropdown-item type="checkbox" [checked]="activityBar()" disabled>Activity Bar</wds-dropdown-item>
        <wds-dropdown-item type="checkbox" [checked]="panel()" (wdsSelect)="panel.set(!!$event.checked)">Panel</wds-dropdown-item>
      </wds-dropdown>
      <p class="m-0 text-sm text-muted-foreground">Status Bar: {{ statusBar() ? 'on' : 'off' }}, Panel: {{ panel() ? 'on' : 'off' }}</p>
    </div>
  `,
})
export class DropdownCheckboxesDemo {
  protected readonly statusBar = signal(true);
  protected readonly activityBar = signal(false);
  protected readonly panel = signal(false);
}

Radio group#

wds-dropdown-radio-group keeps one checked type="radio" item in value and fires wds-change.

Panel Position

Top

Bottom

Right

Position: bottom

Show code

dropdown-radio-group.ts

import { Component, signal } from '@angular/core';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_DROPDOWN } from '@wds/angular/dropdown';

@Component({
  selector: 'app-dropdown-radio-group-demo',
  imports: [...WDS_DROPDOWN, WdsButtonComponent],
  template: `
    <div class="flex flex-col items-center gap-3">
      <wds-dropdown>
        <wds-button slot="trigger" variant="outline">Panel Position</wds-button>
        <wds-dropdown-label>Panel Position</wds-dropdown-label>
        <wds-dropdown-separator />
        <wds-dropdown-radio-group [value]="position()" (wdsChange)="position.set($event.value)">
          <wds-dropdown-item type="radio" value="top">Top</wds-dropdown-item>
          <wds-dropdown-item type="radio" value="bottom">Bottom</wds-dropdown-item>
          <wds-dropdown-item type="radio" value="right">Right</wds-dropdown-item>
        </wds-dropdown-radio-group>
      </wds-dropdown>
      <p class="m-0 text-sm text-muted-foreground">Position: {{ position() }}</p>
    </div>
  `,
})
export class DropdownRadioGroupDemo {
  protected readonly position = signal('bottom');
}

Destructive#

variant="destructive" marks an item with a dangerous action.

Actions

Edit

Delete

Show code

dropdown-destructive.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-destructive-demo',
  imports: [WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Actions</wds-button>
      <wds-dropdown-item value="edit">Edit</wds-dropdown-item>
      <wds-dropdown-item value="share">Share</wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="delete" variant="destructive">
        <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18" /><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6" /><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2" /></svg>
        Delete
      </wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownDestructiveDemo {}

Submenu#

A nested wds-dropdown with a wds-dropdown-item in its trigger slot is a submenu. It opens on hover, click or ArrowRight.

Open

Team

Invite users

Message

More…

New Team⌘T

Show code

dropdown-submenu.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-submenu-demo',
  imports: [WdsDropdownComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Open</wds-button>
      <wds-dropdown-item value="team">Team</wds-dropdown-item>
      <wds-dropdown>
        <wds-dropdown-item slot="trigger">Invite users</wds-dropdown-item>
        <wds-dropdown-item value="invite-email">Email</wds-dropdown-item>
        <wds-dropdown-item value="invite-message">Message</wds-dropdown-item>
        <wds-dropdown-separator></wds-dropdown-separator>
        <wds-dropdown-item value="invite-more">More…</wds-dropdown-item>
      </wds-dropdown>
      <wds-dropdown-item value="new-team">New Team<span slot="shortcut">⌘T</span></wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownSubmenuDemo {}

Complex#

Labels, groups, a submenu, shortcuts and a disabled item in one menu.

Account

My Account

Profile⇧⌘P

Billing⌘B

Settings⌘S

Keyboard shortcuts⌘K

Team

Invite users

Message

New Team⌘T

GitHub

Support

API

Log out⇧⌘Q

Show code

dropdown-complex.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownGroupComponent, WdsDropdownItemComponent, WdsDropdownLabelComponent, WdsDropdownSeparatorComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-complex-demo',
  imports: [WdsDropdownComponent, WdsDropdownLabelComponent, WdsDropdownGroupComponent, WdsDropdownItemComponent, WdsDropdownSeparatorComponent, WdsButtonComponent],
  template: `
    <wds-dropdown>
      <wds-button slot="trigger" variant="outline">Account</wds-button>
      <wds-dropdown-label>My Account</wds-dropdown-label>
      <wds-dropdown-group>
        <wds-dropdown-item value="profile">Profile<span slot="shortcut">⇧⌘P</span></wds-dropdown-item>
        <wds-dropdown-item value="billing">Billing<span slot="shortcut">⌘B</span></wds-dropdown-item>
        <wds-dropdown-item value="settings">Settings<span slot="shortcut">⌘S</span></wds-dropdown-item>
        <wds-dropdown-item value="shortcuts">Keyboard shortcuts<span slot="shortcut">⌘K</span></wds-dropdown-item>
      </wds-dropdown-group>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-group>
        <wds-dropdown-item value="team">Team</wds-dropdown-item>
        <wds-dropdown>
          <wds-dropdown-item slot="trigger">Invite users</wds-dropdown-item>
          <wds-dropdown-item value="invite-email">Email</wds-dropdown-item>
          <wds-dropdown-item value="invite-message">Message</wds-dropdown-item>
        </wds-dropdown>
        <wds-dropdown-item value="new-team">New Team<span slot="shortcut">⌘T</span></wds-dropdown-item>
      </wds-dropdown-group>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="github">GitHub</wds-dropdown-item>
      <wds-dropdown-item value="support">Support</wds-dropdown-item>
      <wds-dropdown-item value="api" disabled>API</wds-dropdown-item>
      <wds-dropdown-separator></wds-dropdown-separator>
      <wds-dropdown-item value="logout">Log out<span slot="shortcut">⇧⌘Q</span></wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownComplexDemo {}

Placement#

side and align place the panel around the trigger. It flips to the other side when there is not enough space.

Top

Profile

Billing

Right

Profile

Billing

Bottom end

Profile

Billing

Show code

dropdown-placement.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-placement-demo',
  imports: [WdsDropdownComponent, WdsDropdownItemComponent, WdsButtonComponent],
  template: `
    <div class="flex flex-wrap items-center justify-center gap-2">
      <wds-dropdown side="top">
        <wds-button slot="trigger" variant="outline">Top</wds-button>
        <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
        <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      </wds-dropdown>
      <wds-dropdown side="right">
        <wds-button slot="trigger" variant="outline">Right</wds-button>
        <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
        <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      </wds-dropdown>
      <wds-dropdown align="end">
        <wds-button slot="trigger" variant="outline">Bottom end</wds-button>
        <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
        <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      </wds-dropdown>
    </div>
  `,
})
export class DropdownPlacementDemo {}

Hover#

trigger="hover" also opens the menu when the pointer is over the trigger; a click and the keyboard still work.

Hover

Profile

Billing

Settings

Show code

dropdown-hover.ts

import { Component } from '@angular/core';
import { WdsDropdownComponent, WdsDropdownItemComponent } from '@wds/angular/dropdown';
import { WdsButtonComponent } from '@wds/angular/button';

@Component({
  selector: 'app-dropdown-hover-demo',
  imports: [WdsDropdownComponent, WdsDropdownItemComponent, WdsButtonComponent],
  template: `
    <wds-dropdown trigger="hover">
      <wds-button slot="trigger" variant="outline">Hover</wds-button>
      <wds-dropdown-item value="profile">Profile</wds-dropdown-item>
      <wds-dropdown-item value="billing">Billing</wds-dropdown-item>
      <wds-dropdown-item value="settings">Settings</wds-dropdown-item>
    </wds-dropdown>
  `,
})
export class DropdownHoverDemo {}

API References#

Dropdown menu (the WAI-ARIA menu button pattern). The panel opens in the top layer (Popover API). A nested wds-dropdown with a wds-dropdown-item in the trigger slot is a submenu.

Attributes

Attribute	Type	Default	Description
side	WdsDropdownSide \| undefined		Side of the trigger. Defaults to `bottom`, in a submenu `right`. Flips when there is not enough space.
align	WdsDropdownAlign	'start'	Alignment along the trigger.
offset	number \| undefined		Distance from the trigger in px. Defaults to 4, in a submenu 0.
trigger	WdsDropdownTrigger	'click'	`hover` opens the menu when the pointer is over the trigger (a click still works).
open	boolean	false	Whether the menu is open. Also set by `show()`, `close()` and `toggle()`.
disabled	boolean	false	Disables opening the menu.

Events

Event	Description
wds-open-changeCustomEvent<WdsDropdownOpenChangeDetail>	The menu opens or closes.
wds-selectCustomEvent<WdsDropdownSelectDetail>	An item is selected (bubbles from `wds-dropdown-item`).

Methods

Method	Description
show()	Opens the menu and moves focus to the panel.
close()	Closes the menu (with any open submenus).
toggle()	Opens or closes the menu.

Slots

Slot	Description
trigger	The element that opens the menu (e.g. `wds-button`). In a submenu: a `wds-dropdown-item`.
(default)	Content: `wds-dropdown-item`, `-label`, `-separator`, `-group`, `-radio-group`, submenus.

CSS parts (::part)

Part	Description
content	The menu panel.

CSS custom properties

Property	Description
--wds-dropdown-min-width	Minimum width of the panel (default 8rem).

A menu item. Selected with a click, Enter or Space; then the menu closes. In the trigger slot of a nested wds-dropdown it opens the submenu.

Attributes

Attribute	Type	Default	Description
type	WdsDropdownItemType	'item'	`checkbox` toggles `checked`; `radio` works in a `wds-dropdown-radio-group`.
value	string	''	Identifier passed in `wds-select` (and the value in a radio group).
checked	boolean	false	Checked state of a `checkbox` or `radio` item.
disabled	boolean	false	Disables the item: it is skipped by the arrow keys and cannot be selected.
variant	WdsDropdownItemVariant	'default'	`destructive`: the error color (e.g. "Delete").
inset	boolean	false	Indent that aligns the item with checkbox and radio items.

Events

Event	Description
wds-selectCustomEvent<WdsDropdownSelectDetail>	The item is selected.

Slots

Slot	Description
(default)	Content (text, an `<svg>` icon).
shortcut	Keyboard shortcut shown on the right, e.g. `⌘K`. It is only displayed; handle the keys yourself.

CSS parts (::part)

Part	Description
base	The row with the padding.

A heading of a menu section.

Attributes

Attribute	Type	Default	Description
inset	boolean	false	Indent that aligns the label with checkbox and radio items.

Slots

Slot	Description
(default)	Text.

CSS parts (::part)

Part	Description
base	The text with the padding.

A line between menu sections (role="separator").

CSS parts (::part)

Part	Description
base	The line.

A group of related menu items (role="group").

Slots

Slot	Description
(default)	`wds-dropdown-item` items.

A group of type="radio" items with one selected value.

Attributes

Attribute	Type	Default	Description
value	string	''	Value of the checked item.

Events

Event	Description
wds-changeCustomEvent<WdsDropdownChangeDetail>	The selected value changes.

Slots

Slot	Description
(default)	`wds-dropdown-item type="radio"` items.

Accessibility#

The trigger gets aria-haspopup="menu" and aria-expanded. The panel has role="menu"; give the trigger a text or a label that says what the menu is for.

Items have role="menuitem", or menuitemcheckbox / menuitemradio with aria-checked. Disabled items have aria-disabled="true". Groups have role="group" and separators role="separator".

wds-dropdown-label is plain text and is not linked to a group; to name a group, set aria-label on wds-dropdown-group. Give icons aria-hidden="true".

The text in the shortcut slot is part of the item name, so screen readers read it after the label.

Keyboard support#

Key	Function
EnterSpaceArrowDown	On the trigger: opens the menu and focuses the first item.
ArrowUp	On the trigger: opens the menu and focuses the last item.
ArrowDownArrowUp	Moves focus to the next or previous item, wrapping around; disabled items are skipped.
HomeEnd	Moves focus to the first or last item.
EnterSpace	Selects the focused item and closes the menu; focus returns to the trigger.
ArrowRight	On a submenu trigger: opens the submenu and focuses its first item.
ArrowLeft	In a submenu: closes it and returns focus to its trigger.
Escape	Closes the menu (or the submenu) and returns focus to its trigger.
Tab	Closes the menu and moves focus to the next element on the page.
A–Z	Moves focus to the next item whose text starts with the typed characters.

Usage#

Examples#

Default#

Shortcuts#

Icons#

Checkboxes#

Radio group#

Destructive#

Submenu#

Complex#

Placement#

Hover#

API References#

wds-dropdown#

Attributes

Events

Methods

Slots

CSS parts (::part)

CSS custom properties

wds-dropdown-item#

Attributes

Events

Slots

CSS parts (::part)

wds-dropdown-label#

Attributes

Slots

CSS parts (::part)

wds-dropdown-separator#

CSS parts (::part)

wds-dropdown-group#

Slots

wds-dropdown-radio-group#

Attributes

Events

Slots

Accessibility#

Screen reader#

Keyboard support#