2.0.0 • Published 3d ago

@ryze-digital/select-replace

Licence

MIT

Version

2.0.0

Deps

Size

91 kB

Vulns

Weekly

Summary Dependency Versions

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
labels	object	{ selectedOptions: 'selected', searchPlaceholder: 'Search options', searchNoResults: 'No results found' }	Texts used inside the component (override to translate or customize)

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 via the labels.searchPlaceholder and labels.searchNoResults options. 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.

Keywords

select replace fake select2