@smartimpact-it/better-select
TypeScript icon, indicating that this package has built-in type declarations

1.2.13 • Public • Published

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.

Package Sidebar

Install

npm i @smartimpact-it/better-select

Weekly Downloads

5

Version

1.2.13

License

MIT

Unpacked Size

125 kB

Total Files

45

Last publish

Collaborators

  • bogdanbeniaminb
  • smartimpact