Experimental

Dropdown

Dropdowns present a list of options that can be used to filter existing content. variations:

Experimental Dropdown

Vanilla JS

<!--
  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)

Vanilla JS

CodePen
<!--
  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,
  });
});