/ui/elements/dropdown
The dropdown elements module exports the dropdown method to create a dropdown element group from a params argument.
- Source
Requires
Methods
(inner) dropdown(params) → {HTMLElement}
The dropdown method returns a dropdown element created from the params argument.
| Name | Type | Description |
|---|---|---|
params | Object | Parameter for the creation of the dropdown element. |
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
params.entries | Array | Array of entry objects. Expected format: [{title: 'Title for Option 1', option: 'option1'}, ...]. | ||
params.callback | function | <optional> | Called on selection. Multi select: callback(e, [...selectedOptions], entry). Single select: callback(e, entry). With pills or search the callback is called with the array of selected options. | |
params.placeholder | string | <optional> | '' | The placeholder for the list of options. |
params.span | string | <optional> | Fallback for the placeholder if not provided. | |
params.multi | boolean | <optional> | Allow multiple choice if true. | |
params.multiple | boolean | <optional> | Allow multiple choice if true using classic select with native multiple flag. This changes dropdown select into a scrollable list. | |
params.search | boolean | <optional> | Replace the select with a search input and datalist of the entries. | |
params.pills | boolean | <optional> | Add selected entries as pills to a pills element above the dropdown. | |
params.field | string | <optional> | The field used to create a unique datalist id for the search input. | |
params.keepPlaceholder | boolean | <optional> | set this flag to | |
params.data_id | string | <optional> | 'dropdown' | The data-id attribute for the select element. |
- Source
The dropdown node with the pills container [optional] and either the search input or select element.
- Type:
- HTMLElement
(inner) onSearchInput(e, params)
The input event handler for the search input element.
Typed keystrokes are ignored to prevent an exact match being selected while typing, e.g. selecting 1 before 10 can be entered. Only the selection of a datalist option [inputType undefined or 'insertReplacementText'] is processed.
The entry with a title matching the input value is toggled, added to or removed from the selected sets and pills. The input value is cleared. The callback is called with the array of selected options if no pills element is assigned; otherwise the pills element calls the callback.
| Name | Type | Description |
|---|---|---|
e | Event | The input event from the search element. |
params | Object | The dropdown element object. |
| Name | Type | Attributes | Description |
|---|---|---|---|
params.entries | Array | The entries available to the dropdown. | |
params.selectedTitles | Set | A set of titles from currently selected dropdown items. | |
params.selectedOptions | Set | A set of options from currently selected dropdown items. | |
params.pills | Object | <optional> | The pills element. |
params.callback | function | <optional> | The callback method for the selection. |
- Source
(inner) optionElements(params) → {Array.<HTMLElement>}
Creates an option element for each entry and assigns the element as entry.li property. Entries flagged as selected get the selected class and are added to the selected sets and pills.
| Name | Type | Description |
|---|---|---|
params | Object | The dropdown element object. |
| Name | Type | Attributes | Description |
|---|---|---|---|
params.entries | Array | The entries available to the dropdown. | |
params.selectedTitles | Set | A set of titles from currently selected dropdown items. | |
params.selectedOptions | Set | A set of options from currently selected dropdown items. | |
params.pills | Object | <optional> | The pills element. |
- Source
Array of option elements.
- Type:
- Array.<HTMLElement>
(inner) pillsElement(params)
Assign a pills element to the params.pills property. Removing a pill unselects the matching entry and option element.
| Name | Type | Description |
|---|---|---|
params | Object | The dropdown element object. |
| Name | Type | Attributes | Description |
|---|---|---|---|
params.pills | boolean | <optional> | The pills element will be assigned to the flag property. |
params.entries | Array | The entries available to the dropdown. | |
params.options | Array | The option elements including the placeholder option at index 0. | |
params.selectedTitles | Set | A set of titles from currently selected dropdown items. | |
params.selectedOptions | Set | A set of options from currently selected dropdown items. | |
params.callback | function | <optional> | Called with the array of pills when a pill is added or removed. |
- Source
(inner) searchInput(params) → {HTMLElement}
Assign a search input with a datalist of the entries to the params.search property.
| Name | Type | Description |
|---|---|---|
params | Object | The dropdown element object. |
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
params.search | boolean | <optional> | The search element will be assigned to the flag property. | |
params.entries | Array | The entries available to the dropdown. | ||
params.field | string | <optional> | The field used to create a unique datalist id. | |
params.placeholder | string | <optional> | 'Enter search term...' | The placeholder for the search input. |
- Source
The search input and its datalist. Undefined if params.search is falsy.
- Type:
- HTMLElement
(inner) selectKeyDown(e, params)
The keydown event handler for the select element.
The native select type-ahead selects the first option beginning with a typed character and fires a change event. This would toggle an entry in a multi select dropdown. The default is prevented for printable characters in a multi select dropdown. The space key is allowed to open the select.
| Name | Type | Description |
|---|---|---|
e | KeyboardEvent | The keydown event from the select element. |
params | Object | The dropdown element object. |
| Name | Type | Attributes | Description |
|---|---|---|---|
params.multi | boolean | <optional> | Allow multiple choice if true. |
- Source
(inner) selectOnChange(e, params)
The change event handler for the select element.
The selectedIndex is reset to the placeholder option. Entries in a multi select dropdown are toggled, added to or removed from the selected sets and pills, and the callback is called with the array of selected options and the entry. The placeholder text is updated with the selected titles unless pills or keepPlaceholder are set.
Single select entries can not be unselected. The callback is called with the selected entry.
| Name | Type | Description |
|---|---|---|
e | Event | The change event from the select element. |
params | Object | The dropdown element object. |
| Name | Type | Attributes | Description |
|---|---|---|---|
params.entries | Array | The entries available to the dropdown. | |
params.options | Array | The option elements including the placeholder option at index 0. | |
params.multi | boolean | <optional> | Allow multiple choice if true. |
params.pills | Object | <optional> | The pills element. |
params.keepPlaceholder | boolean | <optional> | Keep the original placeholder after an option is selected. |
params.placeHolderOption | HTMLElement | The placeholder option element. | |
params.callback | function | <optional> | The callback method for the selection. |
- Source
(inner) selectReset(e)
Resets the selectedIndex of the select element to the placeholder option on focus and blur.
| Name | Type | Description |
|---|---|---|
e | Event | The focus or blur event from the select element. |
- Source