1 | ### SCSS
|
2 |
|
3 | #### Modifiers
|
4 |
|
5 | Use 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
|
21 | import { Dropdown } from 'carbon-components';
|
22 | ```
|
23 |
|
24 | ##### With pre-build bundle (`carbon-components.min.js`)
|
25 |
|
26 | ```javascript
|
27 | var Dropdown = CarbonComponents.Dropdown;
|
28 | ```
|
29 |
|
30 | #### Instantiating
|
31 |
|
32 | ```javascript
|
33 | // `#my-dropdown` is an element with `[data-dropdown]` attribute
|
34 | Dropdown.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
|
51 | var dropdownInstance = Dropdown.create(document.getElementById('my-dropdown'));
|
52 | // `#my-dropdown-link-1` is one of the `<a>`s with `bx--dropdown-link` class
|
53 | dropdownInstance.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
|
76 | document.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
|
86 | document.addEventListener('dropdown-selected', function(evt) {
|
87 | myAnalyticsLibrary.send({
|
88 | action: 'Dropdown item selected',
|
89 | id: evt.target.id,
|
90 | });
|
91 | });
|
92 | ```
|