Dropdowns present a list of options that can be used to filter existing content.
variations:
Experimental 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>
Experimental 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>
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,
});
});