⌘K

dropdown component

Drop-in semantic component. See examples, sizes, variants, and source.

Custom select component for single or multi-value choices. Compose a dropdown wrapping a trigger and a menu of item rows. Layer modifiers for size (xs sm xl lg), state (disabled error success warning loading), or theme (primary positive negative warning). Opt into search with data-searchable, multi-select with data-multiple, and a clear button with data-clearable — all behavior driven by dropdown.js.

Basic Dropdown

Simple Dropdown

Select an option
Option 1
Option 2
Option 3
Option 4

With Pre-selected Value

English
English
Spanish
French
German
Italian

With Label and Help Text

Select your country
United States
United Kingdom
Canada
Australia
Germany
France

Select your country of residence

Searchable Dropdown

With Search Functionality

Type to search countries...
Afghanistan
Albania
Algeria
Andorra
Angola
Argentina
Armenia
Australia
Austria
Azerbaijan
Bahamas
Bahrain
Bangladesh
Barbados
Belarus
Belgium
Belize
Benin
Bhutan
Bolivia

Multiple Selection

Multi-Select with Checkboxes

Select multiple skills
HTML/CSS
JavaScript
React
Vue.js
Angular
Node.js
Python
Java

Select all that apply

Grouped Items

Categories with Headers

Select a product
Electronics
Laptop
Smartphone
Tablet
Accessories
Headphones
Charger
Phone Case
Services
Extended Warranty
Tech Support

Clearable Dropdown

With Clear Button

Selected Option
Selected Option
Another Option
Third Option
Fourth Option

Click × to clear selection

Color Variants

Themed Dropdowns

Primary Theme
Option 1
Option 2
Option 3
Positive Theme
Option 1
Option 2
Option 3
Negative Theme
Option 1
Option 2
Option 3
Warning Theme
Option 1
Option 2
Option 3

Form Integration

Complete Form Example

Select
Mr.
Mrs.
Ms.
Dr.
Select department
Sales
Marketing
Engineering
Human Resources
Finance
Select skills
Leadership
Communication
Technical
Creative

JavaScript API

The dropdown component provides a comprehensive JavaScript API for programmatic control and event handling.

Basic API Usage

// Get dropdown instance
const dropdown = $('.dropdown').data('bluestackDropdown');

// Methods
dropdown.getValue();                    // Get selected value(s)
dropdown.setValue('value');            // Set single value
dropdown.setValue(['val1', 'val2']);   // Set multiple values
dropdown.clearSelection();              // Clear selection
dropdown.open();                        // Open dropdown
dropdown.close();                       // Close dropdown
dropdown.toggle();                      // Toggle open/close

// Events
$('.dropdown').on('dropdown:change', function(e, value, text) {
    console.log('Selected:', value, text);
});

$('.dropdown').on('dropdown:open', function() {
    console.log('Dropdown opened');
});

$('.dropdown').on('dropdown:close', function() {
    console.log('Dropdown closed');
});

$('.dropdown').on('dropdown:clear', function() {
    console.log('Selection cleared');
});

Class API Reference

Type Class / Attribute Usage Notes
Base dropdown Required wrapper Always required
trigger Visible trigger element (shows current value) Child of dropdown
menu Floating panel of items Child of dropdown
Structure item Selectable row inside menu Add data-value="..."
selected Currently chosen item Modifier on item
placeholder Placeholder text inside trigger Replaced by selected label on change
header Group header inside menu Non-interactive label row
divider Separator between groups Inside menu
dropdown-field Wrapper that adds label + help-text For labeled form fields
Size xs 28px height — tiny Modifier on dropdown
sm 32px height — small Modifier on dropdown
(default) 40px height — medium No size class needed
xl 48px height — large Modifier on dropdown
lg 56px height — big Modifier on dropdown
States disabled Disabled — no interaction Modifier on dropdown
error Error state — red border / focus Modifier on dropdown
success Success state — green border / focus Modifier on dropdown
warning Warning state — yellow border / focus Modifier on dropdown
loading Loading — shows spinner Modifier on dropdown
open Menu is open Auto-applied by JS
Color primary Blue theme Modifier on dropdown
positive Green theme Modifier on dropdown
negative Red theme Modifier on dropdown
warning Yellow theme Modifier on dropdown
Behavior multiple Multi-select with checkboxes Class + data-multiple="true"
clearable Adds × clear button Class + data-clearable="true"
data-searchable Inject a search input at the top Attribute on dropdown
data-placeholder Default placeholder text Attribute on dropdown
data-value Value emitted on selection Attribute on item