RYZE Digital Select Replace

Install

npm i @ryze-digital/select-replace --save

Usage

Scss

@use "@ryze-digital/select-replace";

Use the provided configure mixin to define your select replace defaults.

@include select-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 {
    @include select-replace.fake-select();
}

.option-list {
    @include select-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 {
    @include scss-utilities.visually-hidden();
}

... or you can use it to only hide all <select> field directly, if you plan to replace them all.

select {
    @include scss-utilities.visually-hidden();
}

JavaScript

import { SelectReplace } from '@ryze-digital/select-replace';

new SelectReplace({...}).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	{   fakeSelect: 'select-replace',   placeholder: 'placeholder',   optionList: 'option-list',   searchInput: 'option-list-search',   noResults: 'option-list-empty',   hideSelect: 'visually-hidden',   focussed: 'has-focus',   disabled: 'disabled',   optgroup: 'option-list-group' }	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
i18n	object		Internationalization settings
i18n.languages	array	['en', 'de']	Available translations (extend this array, if you provide more)
i18n.selectedOptions	object	{   en: 'selected',   de: 'ausgewählt' }	Translations for n selected
i18n.search.placeholder	string/object	{   en: 'Search options',   de: 'Optionen suchen' }	Placeholder text for the search field (string or per language map)
i18n.search.noResults	string/object	{   en: 'No results found',   de: 'Keine Ergebnisse gefunden' }	Text shown if no option matches the entered search
i18n.use	string	en	Fallback language to use, if document language is not available in i18n.languages

Public methods

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.

Features

Search

Pass search: true to enable a filter input above the option list. The input placeholder and the "no results" text can be customized per language via the i18n.search settings. Both single select and multiple select fields can be searched.

new SelectReplace({
    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.

Optgroups

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.

Demos

Checkout this repository and use the /demos folder as document root to see a running demo in the browser.

• Single select
• Single select with search
• Multiple select
• Multiple select fields
• Optgroup select
• Preselected options
• Disabled select and options
• Programmatic control
• Form reset
• Option list appended to custom container
• Form with select events