custom-select

A lightweight JavaScript library for custom HTML

:
`html

`
`js
customSelect('select');
`
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:
`html

  
    Select...
  
  
  
    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

`js
Array customSelect(elements[, pluginOptions]);
`
The elements parameter could be:A DOMString selectors:
`js
customSelect('.myForm .mySelect');
`
A instance of HTMLElement, tag SELECT:
`js
customSelect(document.getElementById('mySelect'));
`
A list (NodeList, HTMLCollection, Array, etc) of instances of HTMLElement, tag SELECT:
`js
customSelect(document.querySelector('.mySelect'));
//or
customSelect(document.getElementsByClassName('mySelect'));
`

The pluginOptions parameter is an object that overwrites some default plugin configurations.
The default config is:
`js
{
  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.
$3
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'
$3
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
`js
const cstSel = customSelect('select')[0]; // return is an array of instances!
console.log(cstSel.open); // true|false
`
The DOM select
`js
customSelect('select');
const cstSel =  document.querySelector('select').customSelect
console.log(cstSel.open); // true|false
`
The DOM select container
`js
customSelect('select');
const cstSel =  document.querySelector('.customSelect').customSelect
console.log(cstSel.open); // true|false
`
Methods & Properties
$3

Get the plugin options.
`js
cstSel.pluginOptions;
`
$3

Get/set property.
`js
cstSel.open = true; // open the custom select
console.log(cstSel.open); // true
cstSel.open = false; // close the custom select
console.log(cstSel.open); // false
`
$3

Get/set property.
`js
cstSel.disabled = true; // disable the custom select
console.log(cstSel.disabled); // true
cstSel.disabled = false; // enable the custom select
console.log(cstSel.disabled); // false
`
$3

Get/set property.  
Change both the native select and the custom select. Use it just like nativeSelect.value
`js
cstSel.value = '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.log(cstSel.value); // return foo if there was an option with 'foo' value
`
$3

Append an option or an optgroup to the select.
`js
const option = document.createElement('option');
option.text = 'Foo';
option.value = 'bar';
cstSel.append(option);
`
The elements parameter could be:An instance of HTMLElement, tag OPTION:
`js
const toBeAppend = document.createElement('option');
`
An instance of HTMLElement, tag OPTGROUP:
`js
const toBeAppend = document.createElement('optgroup');
`
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
`js
const toBeAppend = cstSel.empty();
`
The target parameter must be the select (default) or an optgroup that is already inside the select.
$3

insert an option or an optgroup before the specified target.
`js
const option = document.createElement('option');
option.text = 'Foo';
option.value = 'foo';
const target = cstSel.select.options[2];
cstSel.insertBefore(option, target);
`
The elements parameter could be:An instance of HTMLElement, tag OPTION:
`js
const toBeAppend = document.createElement('option');
`
An instance of HTMLElement, tag OPTGROUP:
`js
const toBeAppend = document.createElement('optgroup');
`
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
`js
const toBeAppend = cstSel.empty();
`
The target parameter must be an option or an optgroup that is already inside the select.
$3

remove an option or an optgroup
`js
cstSel.remove(cstSel.select.options[1]);
`
$3

empty the select
`js
cstSel.empty();
`
$3

destroy the plugin, removing custom markup, classes, and listeners.
`js
cstSel.destroy();
`
$3

DOM Element
$3

DOM Element
$3

DOM Element
$3

DOM Element

Events
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:open',
  (e) => { console.log(${e.target} is open 😊)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:close',
  (e) => { console.log(${e.target} is closed 😔)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:disabled',
  (e) => { console.log(${e.target} is disabled 👋)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:enabled',
  (e) => { console.log(${e.target} is enabled 👏)});
`
$3

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.
`js
// Example with jQuery animate
cstSel.panel.addEventListener('custom-select:focus-outside-panel',
  (e) => {
    e.stopPropagation();
    $(cstSel.panel).animate({
      scrollTop: e.target.offsetTop,
    }, 300)
  }, true);
`
$3

Only on select.
`js
cstSel.select.addEventListener('change',
  (e) => { console.log(${e.target} has changed it's value 👌)});
`
jQuery adaptor

If you really can't live without jQuery, an adaptor was made for you 😩: download jQuery version here.
$3

`js
$('#mySelect').customSelect();
`
$3

`js
$('#mySelect').customSelect('open', true);
`
$3

`js
$('#mySelect').customSelect('open');
`
$3

`js
$('#mySelect').customSelect('remove', $('#mySelect')[0].options[1]);
``
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

`custom-select`


A lightweight JavaScript library for custom HTML :
`html

`
`js
customSelect('select');
`
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:
`html

  
    Select...
  
  
  
    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

`js
Array customSelect(elements[, pluginOptions]);
`
The elements parameter could be:A DOMString selectors:
`js
customSelect('.myForm .mySelect');
`
A instance of HTMLElement, tag SELECT:
`js
customSelect(document.getElementById('mySelect'));
`
A list (NodeList, HTMLCollection, Array, etc) of instances of HTMLElement, tag SELECT:
`js
customSelect(document.querySelector('.mySelect'));
//or
customSelect(document.getElementsByClassName('mySelect'));
`

The pluginOptions parameter is an object that overwrites some default plugin configurations.
The default config is:
`js
{
  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.
$3
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'
$3
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
`js
const cstSel = customSelect('select')[0]; // return is an array of instances!
console.log(cstSel.open); // true|false
`
The DOM select
`js
customSelect('select');
const cstSel =  document.querySelector('select').customSelect
console.log(cstSel.open); // true|false
`
The DOM select container
`js
customSelect('select');
const cstSel =  document.querySelector('.customSelect').customSelect
console.log(cstSel.open); // true|false
`
Methods & Properties
$3

Get the plugin options.
`js
cstSel.pluginOptions;
`
$3

Get/set property.
`js
cstSel.open = true; // open the custom select
console.log(cstSel.open); // true
cstSel.open = false; // close the custom select
console.log(cstSel.open); // false
`
$3

Get/set property.
`js
cstSel.disabled = true; // disable the custom select
console.log(cstSel.disabled); // true
cstSel.disabled = false; // enable the custom select
console.log(cstSel.disabled); // false
`
$3

Get/set property.  
Change both the native select and the custom select. Use it just like nativeSelect.value
`js
cstSel.value = '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.log(cstSel.value); // return foo if there was an option with 'foo' value
`
$3

Append an option or an optgroup to the select.
`js
const option = document.createElement('option');
option.text = 'Foo';
option.value = 'bar';
cstSel.append(option);
`
The elements parameter could be:An instance of HTMLElement, tag OPTION:
`js
const toBeAppend = document.createElement('option');
`
An instance of HTMLElement, tag OPTGROUP:
`js
const toBeAppend = document.createElement('optgroup');
`
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
`js
const toBeAppend = cstSel.empty();
`
The target parameter must be the select (default) or an optgroup that is already inside the select.
$3

insert an option or an optgroup before the specified target.
`js
const option = document.createElement('option');
option.text = 'Foo';
option.value = 'foo';
const target = cstSel.select.options[2];
cstSel.insertBefore(option, target);
`
The elements parameter could be:An instance of HTMLElement, tag OPTION:
`js
const toBeAppend = document.createElement('option');
`
An instance of HTMLElement, tag OPTGROUP:
`js
const toBeAppend = document.createElement('optgroup');
`
A list (NodeList, HTMLCollection, Array, etc) of instance of HTMLElement, tag OPTION/OPTGROUP:
`js
const toBeAppend = cstSel.empty();
`
The target parameter must be an option or an optgroup that is already inside the select.
$3

remove an option or an optgroup
`js
cstSel.remove(cstSel.select.options[1]);
`
$3

empty the select
`js
cstSel.empty();
`
$3

destroy the plugin, removing custom markup, classes, and listeners.
`js
cstSel.destroy();
`
$3

DOM Element
$3

DOM Element
$3

DOM Element
$3

DOM Element

Events
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:open',
  (e) => { console.log(${e.target} is open 😊)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:close',
  (e) => { console.log(${e.target} is closed 😔)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:disabled',
  (e) => { console.log(${e.target} is disabled 👋)});
`
$3

Only on container.
`js
cstSel.container.addEventListener('custom-select:enabled',
  (e) => { console.log(${e.target} is enabled 👏)});
`
$3

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.
`js
// Example with jQuery animate
cstSel.panel.addEventListener('custom-select:focus-outside-panel',
  (e) => {
    e.stopPropagation();
    $(cstSel.panel).animate({
      scrollTop: e.target.offsetTop,
    }, 300)
  }, true);
`
$3

Only on select.
`js
cstSel.select.addEventListener('change',
  (e) => { console.log(${e.target} has changed it's value 👌)});
`
jQuery adaptor

If you really can't live without jQuery, an adaptor was made for you 😩: download jQuery version here.
$3

`js
$('#mySelect').customSelect();
`
$3

`js
$('#mySelect').customSelect('open', true);
`
$3

`js
$('#mySelect').customSelect('open');
`
$3

`js
$('#mySelect').customSelect('remove', $('#mySelect')[0].options[1]);
``
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