v0.5.14

Dropdown

A menu of actions or options, triggered by a button

Installation

pnpm add @wandercom/design-system-web

Usage

Built on the Base UI Menu primitive, the dropdown supports icons, keyboard shortcuts, separators, checkboxes, radio groups, and nested submenus.

21 lines
import {
  Dropdown,
  DropdownTrigger,
  DropdownContent,
  DropdownItem,
} from '@wandercom/design-system-web/ui/dropdown';

export function Example() {
  return (
    <Dropdown>
      <DropdownTrigger asChild>
        <button>Open menu</button>
      </DropdownTrigger>
      <DropdownContent>
        <DropdownItem>Profile</DropdownItem>
        <DropdownItem>Settings</DropdownItem>
        <DropdownItem>Logout</DropdownItem>
      </DropdownContent>
    </Dropdown>
  );
}

Examples

Trigger variants

The dropdown trigger supports a styled default variant matching SelectTrigger, a sm size, and an unstyled variant for custom trigger elements via asChild.

Loading example...

Basic menu

A simple dropdown menu with basic items.

Loading example...

With icons

Add icons to menu items for visual clarity.

Loading example...

With separators and labels

Group related items with separators and labels.

Loading example...

With keyboard shortcuts

Display keyboard shortcuts alongside menu items.

Loading example...

With checkbox items

Use checkboxes for togglable options.

Loading example...

With radio group

Use radio groups for mutually exclusive options.

Loading example...

With submenu

Create nested menus for hierarchical options.

Loading example...

Destructive variant

Use the destructive variant to indicate dangerous actions.

Loading example...

Inset items

Use the inset prop to align items with labels or icons.

Loading example...

Long labels

By default an item grows and wraps its label across multiple lines. Pass truncate to pin the row to a single line and ellipsize overflowing text — the full label stays available to screen readers. Truncation is intended for plain text labels; items with icons or shortcuts should use the default growing layout.

Loading example...

Scrollable menu

Long menus are capped at 500px by default and scroll, with chevron indicators showing when more items are available in either direction. Set scrollable={false} on DropdownContent to let the menu grow to the full available height instead.

Loading example...

Props

Dropdown

open?:

boolean
Controlled open state of the dropdown menu.

defaultOpen?:

boolean
Default open state for uncontrolled usage.

onOpenChange?:

(open: boolean) => void
Event handler called when the open state changes.

modal?:

boolean
Whether the dropdown menu is modal. Defaults to true.

DropdownTrigger

variant?:

'default' | 'unstyled'
Visual variant. Default renders a styled trigger matching SelectTrigger. Unstyled removes all styles for use with asChild.

size?:

'default' | 'sm'
Size of the trigger. Defaults to "default" (h-12). Use "sm" for a compact height (h-10).

asChild?:

boolean
Renders the child element directly, merging props instead of wrapping in a button. Skips variant styles when true.

nativeButton?:

boolean
Whether the rendered element is a native button. Set to false when asChild renders a non-button element. Inferred automatically in most cases.

className?:

string
Additional CSS classes to apply.

DropdownContent

className?:

string
Additional CSS classes to apply to the content container.

sideOffset?:

number
Distance in pixels from the trigger. Defaults to 4.

side?:

'top' | 'right' | 'bottom' | 'left'
Preferred side of the trigger to render against. Defaults to "bottom".

align?:

'start' | 'center' | 'end'
Alignment relative to the trigger.

alignOffset?:

number
Offset in pixels from the alignment axis.

scrollable?:

boolean
Whether the menu is capped at 500px with scroll-overflow indicators. When false, the menu grows to the full available height without indicators. Defaults to true.

container?:

HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null
The container element the portal renders into. Defaults to the container provided by PortalContainerProvider when available.

DropdownGroup

className?:

string
Additional CSS classes to apply.

DropdownItem

variant?:

'default' | 'destructive'
Visual variant. Defaults to "default".

inset?:

boolean
Adds left padding to align with labels or icons.

truncate?:

boolean
Pins the row to a single line and ellipsizes overflowing label text. By default the item grows when the label wraps. Intended for plain text labels; has no text-wrapping effect when combined with asChild or render. Defaults to false.

disabled?:

boolean
Disables the menu item.

onSelect?:

(event: Event) => void
Event handler called when the item is selected. Call event.preventDefault() to keep the menu open.

closeOnClick?:

boolean
Whether to close the menu when the item is clicked. Defaults to true.

asChild?:

boolean
Renders the child element as the item, merging props instead of wrapping in a div.

className?:

string
Additional CSS classes to apply.

DropdownCheckboxItem

checked?:

boolean
Checked state of the checkbox.

onCheckedChange?:

(checked: boolean) => void
Event handler called when the checked state changes.

disabled?:

boolean
Disables the checkbox item.

onSelect?:

(event: Event) => void
Event handler called when the item is selected.

closeOnClick?:

boolean
Whether to close the menu when the item is clicked. Defaults to false so the menu stays open while toggling.

className?:

string
Additional CSS classes to apply.

DropdownRadioGroup

value?:

string
The controlled selected value.

onValueChange?:

(value: string) => void
Event handler called when the selected value changes.

DropdownRadioItem

value:

string
The unique value of this radio item.

disabled?:

boolean
Disables the radio item.

onSelect?:

(event: Event) => void
Event handler called when the item is selected.

closeOnClick?:

boolean
Whether to close the menu when the item is clicked. Defaults to false so the menu stays open while selecting.

className?:

string
Additional CSS classes to apply.

DropdownLabel

inset?:

boolean
Adds left padding to align with inset items.

className?:

string
Additional CSS classes to apply.

DropdownSeparator

className?:

string
Additional CSS classes to apply.

DropdownShortcut

className?:

string
Additional CSS classes to apply.

DropdownSub

open?:

boolean
Controlled open state of the submenu.

defaultOpen?:

boolean
Default open state for uncontrolled usage.

onOpenChange?:

(open: boolean) => void
Event handler called when the open state changes.

DropdownSubTrigger

inset?:

boolean
Adds left padding to align with inset items.

disabled?:

boolean
Disables the submenu trigger.

className?:

string
Additional CSS classes to apply.

DropdownSubContent

sideOffset?:

number
Distance in pixels from the sub-trigger. Defaults to 13.

side?:

'top' | 'right' | 'bottom' | 'left'
Preferred side of the sub-trigger to render against. Defaults to "right".

align?:

'start' | 'center' | 'end'
Alignment relative to the sub-trigger. Defaults to "start".

alignOffset?:

number
Offset in pixels from the alignment axis.

className?:

string
Additional CSS classes to apply.

Accessibility

The dropdown is built on the Base UI Menu primitive with full accessibility support:

  • Uses semantic menu role and appropriate ARIA attributes
  • Supports keyboard navigation with arrow keys
  • Opens and closes with Enter or Space
  • Closes on Escape key press
  • Supports typeahead to jump to matching items
  • Manages focus automatically when opened and closed
  • Honors disabled state on individual items
  • Checkbox and radio items include proper ARIA state attributes
Dropdown