Dropdowns present a list of options that can be used to filter existing content.
variations:
Dropdown
<!--
Copyright IBM Corp. 2016, 2018
This source code is licensed under the Apache-2.0 license found in the
LICENSE file in the root directory of this source tree.
-->
<ul data-dropdown data-value
class="bx--dropdown"
tabindex="0">
<li class="bx--dropdown-text">
Dropdown label <svg class="bx--dropdown__arrow" width="10" height="5" viewBox="0 0 10 5" fill-rule="evenodd">
<path d="M10 0L5 5 0 0z"></path>
</svg>
</li>
<li>
<ul class="bx--dropdown-list">
<li data-option data-value="all" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 1</a>
</li>
<li data-option data-value="cloudFoundry" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 2</a>
</li>
<li data-option data-value="staging" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 3</a>
</li>
<li data-option data-value="dea" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 4</a>
</li>
<li data-option data-value="router" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 5</a>
</li>
</ul>
</li>
</ul>
<br>
Dropdown (Up)
<!--
Copyright IBM Corp. 2016, 2018
This source code is licensed under the Apache-2.0 license found in the
LICENSE file in the root directory of this source tree.
-->
<ul data-dropdown data-value
class="bx--dropdown bx--dropdown--up"
tabindex="0">
<li class="bx--dropdown-text">
Dropdown label <svg class="bx--dropdown__arrow" width="10" height="5" viewBox="0 0 10 5" fill-rule="evenodd">
<path d="M10 0L5 5 0 0z"></path>
</svg>
</li>
<li>
<ul class="bx--dropdown-list">
<li data-option data-value="all" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 1</a>
</li>
<li data-option data-value="cloudFoundry" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 2</a>
</li>
<li data-option data-value="staging" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 3</a>
</li>
<li data-option data-value="dea" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 4</a>
</li>
<li data-option data-value="router" class="bx--dropdown-item">
<a class="bx--dropdown-link" href="javascript:void(0)" tabindex="-1">Option 5</a>
</li>
</ul>
</li>
</ul>
<br>
Multi-select Dropdown
This component is currently only available in our React library.
Inline Multi-select Dropdown
This component is currently only available in our React library.
Filter Dropdown
This component is currently only available in our React library.
Documentation
SCSS
Modifiers
Use these modifiers with .bx--dropdown
class.
Name | Description |
---|---|
.bx--dropdown--auto-width |
Allows the width of the dropdown to be equal to the width of the content inside it instead of being 100% width of the container. |
.bx--dropdown--selected |
Applies specific styles for a selected dropdown item. |
.bx--dropdown--open |
Applies specific styles when the dropdown is opened |
.bx--dropdown--up |
Applies style to have the dropdown slide up instead of down |
JavaScript
Getting component class reference
ES2015
import { Dropdown } from 'carbon-components';
With pre-build bundle (carbon-components.min.js
)
var Dropdown = CarbonComponents.Dropdown;
Instantiating
// `#my-dropdown` is an element with `[data-dropdown]` attribute
Dropdown.create(document.getElementById('my-dropdown'));
Public Methods
Name | Params | Description |
---|---|---|
release |
Deletes the instance | |
getCurrentNavigation |
Returns the currently highlighted element | |
navigate |
direction: Number |
Moves the focus up or down |
select |
itemToSelect: Object |
Handles clicking on the dropdown options, doing the following: Changing text to selected option, removing selected option from options when selected, and emitting custom events |
setCloseOnBlur |
Sets an event handler to document for "close on blue" behavior |
Example - Changing the active item
// `#my-dropdown` is an element with `[data-dropdown]` attribute
var dropdownInstance = Dropdown.create(document.getElementById('my-dropdown'));
// `#my-dropdown-link-1` is one of the `<a>`s with `bx--dropdown-link` class
dropdownInstance.select(document.getElementById('my-dropdown-link-1'));
Options
Option | Default Selector | Description |
---|---|---|
selectorInit |
[data-dropdown] |
The selector to find the dropdown component |
selectorItem |
.bx--dropdown-link |
The selector to find the clickable area in the selected dropdown item |
selectorItemSelected |
.bx--dropdown--selected |
The selector to find the clickable area in the selected dropdown item |
selectorItemHidden |
[hidden],[aria-hidden="true"] |
The selector to find hidden dropdown items. Used to skip dropdown items for keyboard navigation. |
classSelected |
bx--dropdown--selected |
The class for the selected dropdown item. |
Events
Event Name | Description |
---|---|
dropdown-beingselected |
Custom event fired before a dropdown item is selected |
dropdown-selected |
Custom event fired after a dropdown item is selected |
Example - Preventing a dropdown item from being selected in a certain condition
document.addEventListener('dropdown-beingselected', function(evt) {
if (!myApplication.shouldDropdownItemBeSelected(evt.target)) {
evt.preventDefault();
}
});
Example - Notifying events of all dropdown items being selected to an analytics library
document.addEventListener('dropdown-selected', function(evt) {
myAnalyticsLibrary.send({
action: 'Dropdown item selected',
id: evt.target.id,
});
});