Introduction
Description

UX Select

Lightweight custom select JavaScript plugin (library) created and designed for customizing and improving the native select dropdowns

ux-select description image

Features

Search

Add search by select options for improve usability

Group options

Group related options by only one data attribute

Existing markup

Work with base <select> markup without any additions

Localization

Change default localization by attributes or on instance

Lightweight

The plugin (library) weighs less than 20 kilobytes

Update

Instant update native select on user action or method usage

Styling

Customize select by replacing CSS-variables in :root element

Future additions

Many new features will be added in the future.

Examples

All examples published on StackBlitz and styled by CSS-variables.

Default

Searchable & group options

Styled options

Localization

Methods

Installation

Install from NPM

Install UX Select in your Node.js powered apps with the npm.

npm i ux-select

Use via CDN

Add CDN files from jsDelivr to your project.

<link href="https://cdn.jsdelivr.net/npm/ux-select@1.5.0/dist/ux-select.min.css" rel="stylesheet" crossorigin="anonymous"/>
<script src="https://cdn.jsdelivr.net/npm/ux-select@1.5.0/dist/ux-select.min.iife.js" crossorigin="anonymous"></script>

Download assets

Download files from GitHub and add it locally.

<link href="path/to/ux-select.min.css" rel="stylesheet" crossorigin="anonymous"/>
<script src="path/to/ux-select.min.iife.js" crossorigin="anonymous"></script>

Usage

ES module

If you prefer ES module, import plugin to your .js file.

Note: It already contains styles.
import UxSelect from "ux-select/dist/ux-select.min.js";

Initialization

After adding plugin to project, you need to initialize it on <select> element(s), where:

  • element — { HTMLSelectElement }
  • options — { Object | undefined }
const myUxSelect = new UxSelect(element, options);

Parameters

Options

Name Type Default Description
isSearchable boolean false Set `true` to add search input.
isSearchFocus boolean false Set `true` to add focus search input on open.
isGroupOptions boolean false Set `true` to add grouping options.
Note: Require data-ux-select-group attribute on option(s)
<option data-ux-select-group="groupName"></option>
optionStyle string 'default' Accept 'checkbox' and 'radio' for add styles like option(s) it checkbox or radio.

Text (localization)

Name Type Default Description
placeholder string 'Select an option' Change placeholder text
searchText string 'Search' Change placeholder text on search input
clearText string 'Clear option(s)' Change text on x-mark icon
selectedText string 'Selected:' Change text on multiple select, when user select more than 1 option

Methods

After initialize UxSelect we have its initialized instance in variable (like UxSelect) variable in example above) with helpful methods:

Name Description
myUxSelect.disable() Disable select
myUxSelect.enable() Enable select
myUxSelect.update(isTriggerChange) Update UxSelect to match with native select. Pass `false` if you don't need to trigger "change" event on native select.
myUxSelect.clear() Clear selected option(s)

Styling

Overview

UxSelect includes CSS variables in its compiled for real-time customization without transpiler.

All properties are prefixed with uxs- to avoid conflicts with third party plugins.

Variables

Here is a list of variables that you can change to customize your select
Name Default Description
--uxs-padding-x 12px X-oriented padding
--uxs-padding-y 6px Y-oriented padding
--uxs-background-color rgb(255 255 255) Select background color
--uxs-text-color rgb(34 34 34) Select text color
--uxs-font-size 16px Select font size
--uxs-line-height 1.5 Select line height
--uxs-border-width 1px Select border width
--uxs-border-radius 6px Select border radius
--uxs-border-color rgb(233 233 233) Select border color
--uxs-border-hover-color rgb(189 193 198) Select border hover color on focus/shown dropdown
--uxs-option-hover-bg-color rgb(244 244 244) Options background color on hover
--uxs-option-select-bg-color rgb(233 233 233) Options background color on select state
--uxs-option-disable-color rgb(130 130 130) Options background color on disable state
--uxs-option-styled-outline-width 1px Select styled options(checkbox/radio) outline width
--uxs-option-styled-checkbox-outline-radius 4px Select styled options(checkbox) outline radius
--uxs-option-styled-border-width 3px Select styled options(checkbox/radio) border width
--uxs-option-styled-bg 3px Select styled options(checkbox/radio) background color
--uxs-dropdown-image data:image/svg+xml Chevron-down image
--uxs-dropdown-image-disable data:image/svg+xml Chevron-down image when select disabled
--uxs-clear-image data:image/svg+xml X-mark image for clearing select
--uxs-clear-image-disable data:image/svg+xml X-mark image for clearing select when select disabled
--uxs-search-bg rgb(255 255 255) Search input background color
--uxs-search-color rgb(34 34 34) Search input text color
--uxs-search-placeholder rgb(169 169 169) Search input placeholder color
--uxs-transition-duration 0.2s Animation time duration
--uxs-transition-easing ease-in-out Animation easing
--uxs-scrollbar-track-color rgb(189 189 189) Scrollbar track color
--uxs-scrollbar-thumb-color rgb(117 117 117) Scrollbar thumb color
--uxs-scrollbar-thumb-hover-color rgb(97 97 97) Scrollbar thumb hover color