UNPKG

5.5 kBMarkdownView Raw
1### SCSS
2
3#### Modifiers
4
5Use these modifiers with `.bx--dropdown` class.
6
7| Name | Description |
8| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
9| `.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. |
10| `.bx--dropdown--selected` | Applies specific styles for a selected dropdown item. |
11| `.bx--dropdown--open` | Applies specific styles when the dropdown is opened |
12| `.bx--dropdown--up` | Applies style to have the dropdown slide up instead of down |
13
14### JavaScript
15
16#### Getting component class reference
17
18##### ES2015
19
20```javascript
21import { Dropdown } from 'carbon-components';
22```
23
24##### With pre-build bundle (`carbon-components.min.js`)
25
26```javascript
27var Dropdown = CarbonComponents.Dropdown;
28```
29
30#### Instantiating
31
32```javascript
33// `#my-dropdown` is an element with `[data-dropdown]` attribute
34Dropdown.create(document.getElementById('my-dropdown'));
35```
36
37#### Public Methods
38
39| Name | Params | Description |
40| ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41| `release` | | Deletes the instance |
42| `getCurrentNavigation` | | Returns the currently highlighted element |
43| `navigate` | direction: `Number` | Moves the focus up or down |
44| `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 |
45| `setCloseOnBlur` | | Sets an event handler to document for "close on blue" behavior |
46
47##### Example - Changing the active item
48
49```javascript
50// `#my-dropdown` is an element with `[data-dropdown]` attribute
51var dropdownInstance = Dropdown.create(document.getElementById('my-dropdown'));
52// `#my-dropdown-link-1` is one of the `<a>`s with `bx--dropdown-link` class
53dropdownInstance.select(document.getElementById('my-dropdown-link-1'));
54```
55
56#### Options
57
58| Option | Default Selector | Description |
59| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
60| `selectorInit` | `[data-dropdown]` | The selector to find the dropdown component |
61| `selectorItem` | `.bx--dropdown-link` | The selector to find the clickable area in the selected dropdown item |
62| `selectorItemSelected` | `.bx--dropdown--selected` | The selector to find the clickable area in the selected dropdown item |
63| `selectorItemHidden` | `[hidden],[aria-hidden="true"]` | The selector to find hidden dropdown items. Used to skip dropdown items for keyboard navigation. |
64| `classSelected` | `bx--dropdown--selected` | The class for the selected dropdown item. |
65
66#### Events
67
68| Event Name | Description |
69| ------------------------ | ----------------------------------------------------- |
70| `dropdown-beingselected` | Custom event fired before a dropdown item is selected |
71| `dropdown-selected` | Custom event fired after a dropdown item is selected |
72
73##### Example - Preventing a dropdown item from being selected in a certain condition
74
75```javascript
76document.addEventListener('dropdown-beingselected', function(evt) {
77 if (!myApplication.shouldDropdownItemBeSelected(evt.target)) {
78 evt.preventDefault();
79 }
80});
81```
82
83##### Example - Notifying events of all dropdown items being selected to an analytics library
84
85```javascript
86document.addEventListener('dropdown-selected', function(evt) {
87 myAnalyticsLibrary.send({
88 action: 'Dropdown item selected',
89 id: evt.target.id,
90 });
91});
92```