carbon-components/src/components/dropdown/README.md

Carbon Components is a component library for IBM Cloud

### SCSS

#### Modifiers

Use these modifiers with `.bx--dropdown` class.

| Name                    | Description                                           |
|-------------------------|-------------------------------------------------------|
| .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

```javascript
import { Dropdown } from 'carbon-components';
```

##### With pre-build bundle (`carbon-components.min.js`)

```javascript
var Dropdown = CarbonComponents.Dropdown;
```

#### Instantiating

```javascript
// `#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

```javascript
// `#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 |
| 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

```javascript
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

```javascript
document.addEventListener('dropdown-selected', function (evt) {
  myAnalyticsLibrary.send({
    action: 'Dropdown item selected',
    id: evt.target.id,
  });
});
```