custom-select
A lightweight JavaScript library for custom HTML <select>
creation and managing.
No dependencies needed.
Demos
Base
Bootstrap
Control buttons
GSAP
jQuery
Mobile Touch Devices
Install
Install with npm (recommended)
$ npm install --save custom-select
Or download the minified build file here. (jquery version is alternative, not needed!)
Use
With ES6 modules via the import
statement:
;
In CommonJs environments with the require
function:
var customSelect = default;
Note: the require().default
is necessary due to the babelify export system.
In HTML with the script
tag:
How it works
Start with a simple HTML <select>
:
Select... Foo Buz
;
You can nest the select in their label
or you can use the for
attribute on the label.
Nested will work fine but it's formally wrong due to label element specification: only a select
element can be nested in a label
tag.
Here's the HTML result:
Select... Select... Foo Buz Select... Foo Buz
Also state classes will be added and removed while plugin working.
You can use default css included in plugin release or style it by yourself. You can also use advanced techniques for using native select on Mobile/touch devices. Check the examples for inspirations.
Plugin init
Array ;
The elements parameter could be:
A DOMString selectors:
;
A instance of HTMLElement, tag SELECT:
;
A list (NodeList, HTMLCollection, Array, etc) of instances of HTMLElement, tag SELECT:
;//or;
The pluginOptions parameter is an object that overwrites some default plugin configurations.
The default config is:
containerClass: 'custom-select-container' openerClass: 'custom-select-opener' panelClass: 'custom-select-panel' optionClass: 'custom-select-option' optgroupClass: 'custom-select-optgroup' isSelectedClass: 'is-selected' hasFocusClass: 'has-focus' isDisabledClass: 'is-disabled' isOpenClass: 'is-open'
The return is an Array of customSelect instances, that contains all the public exposed methods and properties.
Style Classes
All css classes can be configured using pluginOptions, except container secondary class customSelect
which is only for internal use and should not be removed or used for styling purpose.
Structure Classes
Self explained structure classes, and relative may-have status classes:
containerClass: 'custom-select-container'
may have isDisabledClass
, isOpenClass
openerClass: 'custom-select-opener'
panelClass: 'custom-select-panel'
optionClass: 'custom-select-option'
may have isSelectedClass
, hasFocusClass
optgroupClass: 'custom-select-optgroup'
State Classes
isSelectedClass: 'is-selected'
- when the custom option is selected (as native selected attribute).
hasFocusClass: 'has-focus'
- when the custom option has current focus (mouseover, arrow navigation and keyboard autocomplete changes the focus).
isDisabledClass: 'is-disabled'
- when the select is disabled.
isOpenClass: 'is-open'
- when the panel is open.
How to get Plugin instance
Init return
const cstSel = 0; // return is an array of instances!console; // true|false
The DOM select
;const cstSel = documentcustomSelectconsole; // true|false
The DOM select container
;const cstSel = documentcustomSelectconsole; // true|false
Methods & Properties
property [readonly]
pluginOptions Get the plugin options.
cstSelpluginOptions;
property
open Get/set property.
cstSelopen = true; // open the custom selectconsole; // truecstSelopen = false; // close the custom selectconsole; // false
property
disabled Get/set property.
cstSeldisabled = true; // disable the custom selectconsole; // truecstSeldisabled = false; // enable the custom selectconsole; // false
property
value Get/set property.
Change both the native select and the custom select. Use it just like nativeSelect.value
cstSelvalue = 'foo'; // the first option with that value will be selected. If there is no option with that value the first one'll be selected.console; // return foo if there was an option with 'foo' value
method
append(elements[, target]) Append an option or an optgroup to the select.
const option = document;optiontext = 'Foo';optionvalue = 'bar';cstSel;
The elements parameter could be:
An instance of HTMLElement, tag OPTION:
const toBeAppend = document;
An instance of HTMLElement, tag OPTGROUP:
const toBeAppend = document;
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
const toBeAppend = cstSel;
The target parameter must be the select
(default) or an optgroup that is already inside the select.
method
insertBefore(elements, target) insert an option or an optgroup before the specified target.
const option = document;optiontext = 'Foo';optionvalue = 'foo';const target = cstSelselectoptions2;cstSel;
The elements parameter could be:
An instance of HTMLElement, tag OPTION:
const toBeAppend = document;
An instance of HTMLElement, tag OPTGROUP:
const toBeAppend = document;
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
const toBeAppend = cstSel;
The target parameter must be an option
or an optgroup
that is already inside the select.
method
remove(node) remove an option or an optgroup
cstSel;
method
empty() empty the select
cstSel;
method
destroy() destroy the plugin, removing custom markup, classes, and listeners.
cstSel;
property [readonly]
opener DOM Element
property [readonly]
select DOM Element
property [readonly]
panel DOM Element
property [readonly]
container DOM Element
Events
custom-select:open
Only on container
.
cstSelcontainer;
custom-select:close
Only on container
.
cstSelcontainer;
custom-select:disabled
Only on container
.
cstSelcontainer;
custom-select:enabled
Only on container
.
cstSelcontainer;
custom-select:focus-outside-panel
Fired on custom option, recommended listener on panel
.
This CustomEvent
fires when the focused option moves outside the visible part of the panel
.
It bubbles, so the listener can be placed on every ancestor of the custom options.
This event is useful for custom animations on select's autocomplete-search, when the focus moves to the found option.
By default there's no animation but a simply scrollTop
change of the panel
.
You can overwrite this behaviour by simply adding an EventListener
, with useCapture
argument set to true
and an e.stopPropagation()
statement inside you listener's callback-function.
// Example with jQuery animatecstSelpanel;
change
Only on select
.
cstSelselect;
jQuery adaptor
If you really can't live without jQuery, an adaptor was made for you 😩: download jQuery version here.
jQuery init
;
jQuery property set
;
jQuery property get
;
jQuery methods
;
That's all folks!
And now have fun ✌
Browser support
Oh wait, I was almost forgetting:
- Chrome
- Safari 7.0
- Firefox 10 (maybe also older, but come on...)
- Android 4.0
- Mobile Safari 6.0
- Internet Explorer 10