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: Basic single-select dropdown with checkmark indicator on selected item. Click to open, select an option to close.
<div class="tw-dropdown" data-controller="dropdown">...</div>
Scrollable: For long lists, add .dropdown-menu-scrollable to constrain height with overflow scroll.
<div class="tw-dropdown-menu tw-dropdown-menu-scrollable">...</div>
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="tw-dropdown" data-dropdown-multiple-value="true">...</div>
Icons: Add icons to items using .dropdown-item-icon class. Icons appear on the left side of the item text.
<svg class="tw-dropdown-item-icon">...</svg>
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="tw-dropdown tw-dropdown-sm">...</div><div class="tw-dropdown tw-dropdown-lg">...</div>
Disabled: Add disabled attribute to the trigger button to disable the entire dropdown.
<button class="tw-dropdown-trigger" disabled>...</button>
Validation: Add .dropdown-valid or .dropdown-invalid to the container for validation feedback.
Valid
Invalid
<div class="tw-dropdown tw-dropdown-valid">...</div><div class="tw-dropdown tw-dropdown-invalid">...</div>
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="tw-dropdown tw-dropdown-borderless">...</div>
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="tw-dropdown tw-dropdown-icon">...</div><div class="tw-dropdown tw-dropdown-icon tw-dropdown-borderless">...</div><div class="tw-dropdown tw-dropdown-icon tw-dropdown-sm">...</div>
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"