DROPDOWN: Custom dropdown for selecting options with rich content
VARIANTS: Simple | Scrollable | Checkable (Multi-select) | With Icons | Sizes | Borderless | Icon

Use dropdowns when there's a limited set of predefined options, options are too numerous to display directly, or when users need to make a single selection from many choices. Requires JavaScript (Stimulus controller).

Simple Dropdown

Simple Dropdown: Basic single-select dropdown with checkmark indicator on selected item. Click to open, select an option to close.

<div class="dropdown" data-controller="dropdown">...</div>

Scrollable Dropdown (Long List)

Scrollable: For long lists, add .dropdown-menu-scrollable to constrain height with overflow scroll.

<div class="dropdown-menu dropdown-menu-scrollable">...</div>

Checkable Items (Multi-select)

Multi-select: Use checkboxes for selecting multiple items. Add data-dropdown-multiple-value="true" to enable multi-select mode. The dropdown stays open after selection.

<div class="dropdown" data-dropdown-multiple-value="true">...</div>

Items with Icons

Icons: Add icons to items using .dropdown-item-icon class. Icons appear on the left side of the item text.

<svg class="dropdown-item-icon">...</svg>

Size Variants

Sizes: Use .dropdown-sm or .dropdown-lg on the container to change the size of trigger and menu items.

Small (.dropdown-sm)

Default

Large (.dropdown-lg)

<div class="dropdown dropdown-sm">...</div>
<div class="dropdown dropdown-lg">...</div>

Disabled State

Disabled: Add disabled attribute to the trigger button to disable the entire dropdown.

<button class="dropdown-trigger" disabled>...</button>

Validation States

Validation: Add .dropdown-valid or .dropdown-invalid to the container for validation feedback.

Valid

Invalid

<div class="dropdown dropdown-valid">...</div>
<div class="dropdown dropdown-invalid">...</div>

Borderless Variant

Borderless: Add .dropdown-borderless to remove the border from the trigger. Focus ring still appears on focus for accessibility.

Borderless

Borderless Small

Borderless Large

<div class="dropdown dropdown-borderless">...</div>

Icon Variant

Icon: Add .dropdown-icon to create a square icon-only trigger button (matching .btn-icon dimensions). Chevron and label are hidden automatically. Always include aria-label for accessibility. Composes with .dropdown-borderless for toolbar-style transparent triggers.

Bordered (default)

Borderless (toolbar)

Small (.dropdown-sm)

Default

Large (.dropdown-lg)

Menu right-aligned

<div class="dropdown dropdown-icon">...</div>
<div class="dropdown dropdown-icon dropdown-borderless">...</div>
<div class="dropdown dropdown-icon dropdown-sm">...</div>

Form Select Recipe

Custom select: When a native <select> or .form-select can't show rich item content (icons, disabled options, long labels), reuse the dropdown wholesale as a form field: add a hidden data-dropdown-target="value" input inside the container and the controller writes the chosen item's data-value into it on select — no new CSS class, this is the same .dropdown markup as the sections above. See docs/components/dropdown.md for the full recipe writeup (donor consulted for anatomy only: Basecoat select.js @ 6953a4adbe63).

Please select a site preference.

<div class="dropdown" data-controller="dropdown"><input type="hidden" data-dropdown-target="value" name="…">…</div>

Keyboard Navigation

Keyboard Support: Full keyboard navigation is built-in. Try these keys on any dropdown above:

Key Action
Enter / Space Open menu (if closed) or select highlighted item
Escape Close menu
↓ Arrow Down Open menu or move to next item
↑ Arrow Up Open menu or move to previous item
Home Jump to first item
End Jump to last item
Tab Close menu and move focus

Quick Reference

Container: .dropdown | .dropdown-block (full width)
Trigger: .dropdown-trigger | .dropdown-label | .dropdown-placeholder | .dropdown-chevron
Menu: .dropdown-menu | .dropdown-menu-scrollable | .dropdown-menu-end | .dropdown-menu-top
Items: .dropdown-item | .dropdown-item-icon | .dropdown-item-text | .dropdown-item-check | .dropdown-item.active
Checkable: .dropdown-check | .dropdown-check-input | .dropdown-check-label
Extras: .dropdown-divider | .dropdown-header
Sizes: .dropdown-sm | .dropdown-lg
Validation: .dropdown-valid | .dropdown-invalid
Style: .dropdown-borderless | .dropdown-icon
Stimulus: data-controller="dropdown" | data-dropdown-multiple-value="true"
Form select recipe: add data-dropdown-target="value" hidden input — no new class, see Section 10a above