siit-dev / better-select

A web component for a better select tag.

Better Select

Better Select is a minimal custom select, with the option to fallback to the native select on mobile devices. It offers:

• a web component for better initialization
• keyboard interaction for selecting items
• fallback to the native select on mobile (optional)

The plugin doesn't require jQuery, but it also offers a jQuery adapter if needed.

Demo

See the demo page for a live demo.

Instalation

Installing through npm

If you use npm/yarn, first install the better-select module:

npm install --save @smartimpact-it/better-select

or

yarn add @smartimpact-it/better-select

Usage as web component

The simplest method is to use the web component.

<better-select>
  <select name="select" id="select1" class="form-control">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
    <option value="4">Option 4</option>
    <option value="5">Option 5</option>
  </select>
</better-select>

In JS, you need to register the web component:

import { registerWebComponent } from '@smartimpact-it/better-select';
registerWebComponent();

or simple use the "autoRegister":

import '@smartimpact-it/better-select/autoRegisterWebComponent';

You can also include the triple-slash directive for the typescript definitions, if you use typescript.

/// <reference types="@smartimpact-it/better-select" />
import '@smartimpact-it/better-select/autoRegisterWebComponent';

Attributes for the better-select web component

The available options are:

Option	Description	Default value
no-skip-empty	don't skip options with empty value	false
placeholder	text to display when no option is selected	null
fixed-placeholder	if active, the placeholder will always be displayed, even when options are selected	false
no-native-on-mobile	display the original select "dropdown" when on mobile	false
mobile-breakpoint	window width (px) under which to be considered "mobile"	1024
wrapper-class	the class added to the wrapper element	'better-select'
trigger-class	the class added to the trigger element	'better-select__trigger'
dropdown-class	the class added to the dropdown element	'better-select__dropdown'
z-index	the z-index to be set on the custom select wrapper	decrementing from 100
scroll-selection-into-view	if true, the dropdown will scroll to the selected option when opened	true

Example:

<better-select wrapper-class="better-select2" z-index="30" no-native-on-mobile>
  <select name="select" id="select1" class="form-control">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
    <option value="4">Option 4</option>
    <option value="5">Option 5</option>
  </select>
</better-select>

Usage without the web component

import BetterSelect from '@smartimpact-it/better-select';

// Using vanilla JS
new BetterSelect(element);

// or pass some options
new BetterSelect(element, {...});

// or using jQuery
import { registerForJquery } from '@smartimpact-it/better-select';
registerForjQuery();
$('select.my-select').betterSelect({...});

// or use the autoRegister
import '@smartimpact-it/better-select/autoRegisterForJquery';
$('select.my-select').betterSelect({...});

Settings for the BetterSelect class and for the jQuery method

The available options for the BetterSelect class are:

Option	Description	Default value
skipEmpty	don't display options with empty value	true
placeholder	text to display when no option is selected	null
fixedPlaceholder	if true, the placeholder will always be displayed, even when options are selected	false
nativeOnMobile	display the original select "dropdown" when on mobile	true
mobileBreakpoint	window width (px) under which to be considered "mobile"	1024
wrapperClass	the class added to the wrapper element	'better-select'
triggerClass	the class added to the trigger element	'better-select__trigger'
dropdownClass	the class added to the dropdown element	'better-select__dropdown'
zIndex	the z-index to be set on the custom select wrapper	decrementing from 100
scrollSelectionIntoView	if true, the dropdown will scroll to the selected option when opened	true

Events

There are multiple events dispatched by the better select elements:

• better-select:init - dispatched when the better select is initialized
• better-select:open (cancelable) - dispatched when the dropdown is opened
• better-select:close (cancelable) - dispatched when the dropdown is closed
• better-select:change - dispatched when the value of the select is changed
• better-select:destroy - dispatched when the better select is destroyed
• better-select:mobileBreakpoint - dispatched when the mobile media query matches/unmatches

Methods on the BetterSelect class

The BetterSelect class exposes the following methods and getters/setters:

• updateUI() - update the UI of the custom select
• refreshOptions() - refresh the options in the dropdown
• destroy() - destroy the custom select and put back the original element
• reInit() - reinitialize the custom select
• toggle(newStatus?: boolean | null) - toggle the dropdown status
• close() - close the dropdown
• updateSettings(settings: Partial<BetterSelectSettings>) - update the settings of the custom select
• get opened(): boolean - get the status of the dropdown
• set opened(newStatus: boolean) - set the status of the dropdown
• get settings(): BetterSelectSettings - get the settings of the custom select
• set settings(settings: BetterSelectSettings) - set the settings of the custom select
• get wrapperEl(): HTMLElement | null - get the wrapper element
• get triggerEl(): HTMLAnchorElement | null - get the trigger element
• get dropdownEl(): HTMLElement | null - get the dropdown element
• get select(): HTMLSelectElement - get the original select element
• get element(): HTMLSelectElement - get the original select element
• get value(): string | number | null - get the value of the select
• set value(value: string | number | null) - set the value of the select
• isMobileAndNative(): boolean - check if the current device is mobile and the native select is used

Methods on the BetterSelect Web Component

The BetterSelect web component exposes the following methods and getters/setters:

• get betterSelect(): BetterSelect | null - get the BetterSelect instance
• getSettings(): BetterSelectSettings - get the settings of the custom select
• get value(): string - get the value of the select
• set value(value: string) - set the value of the select

Styling

The package offers an integration with Bootstrap 5, but it can be used with any other CSS framework or custom styles.

Alternatively, we offer a minimal styling for the custom select, which can be imported like this:

/* stylelint-disable-next-line scss/at-import-partial-extension */
@import '@smartimpact-it/better-select/src/scss/main.scss';

Integration with Bootstrap

To setup the styling of the custom select, the package provides an "adapter" for Bootstrap 5, which uses the styles from the default select (for the closed state) and the dropdown (for the open state). This provides a good integration with the Bootstrap variables, so that you don't need to style everything again.

To use this:

// Initialize bootstrap and its variables
@import 'bootstrap/scss/bootstrap';

// Initialize the styles for better-select, based on bootstrap.
/* stylelint-disable-next-line scss/at-import-partial-extension */
@import '@smartimpact-it/better-select/src/scss/bootstrap.scss';

Acknowledgements

The library is a continuation of the Better Select library started by Bogdan Barbu.