npm i @ryze-digital/select-replace --save@use"@ryze-digital/select-replace";Use the provided configure mixin to define your select replace defaults.
@includeselect-replace.configure(...);List of available configuration options
| Option | Type | Default | Description |
|---|---|---|---|
| fake-select | Map | Configuration options especially for the fake select (not option list) | |
| fake-select.padding-inline-end | Number | 40px | Area where in which the arrow down icon is centered in |
| fake-select.icon | Map | The arrow down icon (aka select box indicator) | |
| fake-select.icon.color | Color | #cccccc | |
| fake-select.icon.size | Number | 9px |
Check out the actual configure mixin for better understanding.
There are seperate mixins for the replaced select and the option list.
.select-replace {
@includeselect-replace.fake-select();
}
.option-list {
@includeselect-replace.option-list();
}For accessibility reasons we do not simply hide the original <select> field, because it should remain focusable.
Therefore, our JavaScript adds a class called visually-hidden to it after it is initialized. To visually hide elements
that should still be usable by screen readers, we have a mixin in our
scss-utilities called visually-hidden.
You could either use it to create a utility class with it, to separately hide only selected <select> fields ...
.visually-hidden {
@includescss-utilities.visually-hidden();
}... or you can use it to only hide all <select> field directly, if you plan to replace them all.
select {
@includescss-utilities.visually-hidden();
}import{SelectReplace}from'@ryze-digital/select-replace';newSelectReplace({...}).init();List of available constructor parameters
| Option | Type | Default | Description |
|---|---|---|---|
| el | HTMLElement | document.querySelector('select') | Container to which the library should be bound |
| optionList | object | Configuration options especially for the option list | |
| optionList.calcWidth | boolean | true | Make option list the same width as select field |
| optionList.appendTo | HTMLElement | document.body | Container in which the option list get appended |
| classes | object | { | Selectors that are used internally or states that will be added to elements |
| search | boolean | false | Enables a search input above the option list for filtering visible options |
| labels | object | { | Texts used inside the component (override to translate or customize) |
The folloing methods can be called on an instance of SelectReplace:
init()
Calling the constructor just creates a new instance of SelectReplace and does not replace the <select> field. You
need to call init() to initiate the needed DOM modifications. This method does not have any parameters yet.
update()
After doing some modifications to the <select> field, you have to call update() to reflect these changes to the fake
select. This method does not have any parameters yet.
reposition()
You can manually call reposition() to recalculate and update the positions of the fake dropdown list. This method does
not have any parameters yet.
Pass search: true to enable a filter input above the option list. The input placeholder
and the "no results" text can be customized via the labels.searchPlaceholder and labels.searchNoResults
options. Both single select and multiple select fields can be searched.
newSelectReplace({el: document.querySelector('select'),search: true}).init();Keyboard interaction inside the search input: ArrowUp / ArrowDown move the highlight, Enter confirms
and tabs out of the dropdown, Escape closes it, and Tab / Shift+Tab advance focus to the next /
previous form field.
Native <optgroup> is rendered in the fake option list with the group's label as a non-interactive
heading. Groups with the disabled attribute (and any options inside them) are rendered as disabled and
skipped during keyboard navigation. Disabling individual <option> elements works the same way.
Checkout this repository and use the /demos folder as document root to see a running demo in the browser.