About

Select Picker is a jQuery plugin supporting work with select boxes. It extends the default possibilities of select boxes with a new range of features. In the basic setup, it will simply mimic a basic select box, but at the same time provide you with extensive ways of styling the appearance of your select box and several more neat features.

The main area where Select Picker truly rocks is when you want to use multiple-selection select boxes. It will give you an easy way how to facilitate user's selections with a tag-like appearance solution, providing features like custom styling and search. Basic Select Picker was developed while working on project for Designeo Creative s.r.o

Examples

Basic Picker

Basic Picker mimic a standard select box. It will load first option as selected one, therefore if you want to have placeholder use first option as placeholder. Also Picker support hidden attribute, therefore if you don't want to have placeholder in list of options, use it with your placeholder option. HTML

<select name="basic" id="ex-basic">
    <option value="" disabled hidden>Select value</option>
    <option value="1">Nice</option>
    <option value="2">Very nice</option>
    <option value="3">Awesome</option>
    <option value="4">Godlike</option>
</select>

Javascript

$('#ex-basic').picker();

Multi-selection Picker

Main purpose why Picker was developed was for tag selection. You can enable this feature really easily. Picker is smart enough to detect presence of multiple attribute with select tag and then enable multiple selection. HTML

<select name="basic" id="ex-multiselect" multiple>
    <option value="1">Kind</option>
    <option value="2">Easy-going</option>
    <option value="3">Extroverts</option>
    <option value="4">Introverts</option>
    <option value="5">Ambitious</option>
    <option value="6">Loud</option>
</select>

Javascript

$('#ex-multiselect').picker();

Multi-selection Picker with limit

There is possibility to limit how much options can user choose with the multi-selection picker. HTML

<select name="basic" id="ex-multiselect-limit" multiple>
    <option value="1">Kind</option>
    <option value="2">Easy-going</option>
    <option value="3">Extroverts</option>
    <option value="4">Introverts</option>
    <option value="5">Ambitious</option>
    <option value="6">Loud</option>
</select>

Javascript

$('#ex-multiselect-limit').picker({limit: 2});

Picker with search

Since sometime you have a lot of possibilities to choose from and it might be hard to find the choice you are looking for. But don't fall in despair my friend! Exactly for this case, there is search function implemented! HTML

<select name="basic" id="ex-search" multiple>
    <option value="1">Shanghai</option>
    <option value="2">Karachi</option>
    <option value="3">Beijing</option>
    <option value="4">Tianjin</option>
    <option value="5">Istanbul</option>
    <option value="6">Lagos</option>
    <option value="7">Tokyo</option>
    <option value="8">Guangzhou</option>
    <option value="9">Mumbai</option>
    <option value="10">Moscow</option>
    <option value="11">Dhaka</option>
    <option value="12">Cairo</option>
</select>

Javascript

$('#ex-search').picker({search : true});

Data loading

With Picker there are two ways how to handle data loading - automatic and manual.
Picker will automatically load and "select" options with select attribute. This will work for either basic or multiple modes.
Or you can set your selected options manually through Picker's API via set method. More about Picker's API in Documentation section. HTML

<select name="basic" id="ex-search" multiple>
    <option value="1">Shanghai</option>
    <option value="2" selected>Karachi</option>
    <option value="3">Beijing</option>
    <option value="4" selected="selected">Tianjin</option>
    <option value="5">Istanbul</option>
    <option value="6">Lagos</option>
    <option value="7">Tokyo</option>
    <option value="8">Guangzhou</option>
    <option value="9">Mumbai</option>
    <option value="10">Moscow</option>
    <option value="11">Dhaka</option>
    <option value="12">Cairo</option>
</select><br>
<button id="ex-data-trigger">Select Cairo city</button>

Javascript

$('#ex-data-multiple').picker();
$('#ex-data-trigger').click(function () {
    $('#ex-data-multiple').picker('set', 12);
})

Coloring

Select Picker has small feature which will let you assign specific classes to specific elements based on their option's value. To enable this feature you just have to pass object where key is the desired option's and the class you want to assign to desired element.
Note that this feature applies only to selected options while multiple selection mode is selected. Also the classes are applied only to selected options.

<select name="basic" id="ex-search" multiple>
    <option value="1">Shanghai</option>
    <option value="2" selected>Karachi</option>
    <option value="3">Beijing</option>
    <option value="4" selected="selected">Tianjin</option>
    <option value="5">Istanbul</option>
</select><br>

Javascript

var classes = {
    2 : 'orange',
    4 : 'blue',
    5 : 'orange'
};

$('#ex-coloring').picker({coloring: classes});

Events

Select Picker has basic support for events. Attach your event listeners to the original select element. HTML

<select name="basic" id="ex-events" multiple>
    <option value="1">Kind</option>
    <option value="2">Easy-going</option>
    <option value="3">Extroverts</option>
    <option value="4">Introverts</option>
    <option value="5">Ambitious</option>
    <option value="6">Loud</option>
</select>

JavaScript

var $elem = $('#ex-events');
$elem.picker();
$elem.on('sp-change', function(){
    alert('Great! Thanks for letting me know!');
});

Installation

You can install Select Picker in three ways - directly, through Bower and through npm.

Directly

To install Select Picker directly download ZIP archive from here, unzip it and copy files css/picker.min.css and js/picker.min.js in to your project structure.

<link rel="stylesheet" href="path/to/file/picker.min.css">
<script type="text/javascript" src="path/to/file/picker.min.js"></script>

Bower

To install Select Picker through Bower run following command:

npm

To install Select Picker through npm run following command:

Documentation

To start using Select Picker, first you have to include required files in your HTML page. Basic way is to include in your head tag following part, of course with modifying the path to the files

<link rel="stylesheet" href="css/picker.css">
<script type="text/javascript" src="js/picker.js"></script>

Then only thing you need to do is initialize Picker!

<script type="text/javascript">
    $(document).ready(function(){
        $('#your-selector').picker();
    });
</script>

Parameters

Picker bring you several parameters with which you can customize your Picker.

autofocusScrollOffset

If you need to modify the position to which the window is scrolled to, you can set a offset from the Picker, by specifying autofocusScrollOffset.

coloring

If you want to customize each selected option, during multi-selection mode, you can do it by creating object, where key value is option's value and the value of pair is the class you want to assign and pass this object through coloring parameter.
Check the example to understand it better.

containerClass

Through containerClass parameter you can specify what class should be added to whole Picker wrapping element. It is mostly to be used for specific styling purposes.

containerWidth

With containerWidth parameter you can set the width of whole container. This comes handy especially in multiple-selection mode, when the selected options could be outstretching the container and cause some layout problems.

limit

If you want to limit, how much options can user select in the multi-selection mode, can use limit parameter. After reaching the limit, the dropdown will be hidden and will be shown again only when user will remove some of the options.

search

With this option you can control the search feature. It can be used both with single-selection and multi-selection mode.

searchAutofocus

When you enable the search feature, you can also enhance the user's experience, with automatic focus to search field. At the same time when the focus is put to search field, window is scrolled to the Picker.

texts

If you want to modify the Picker's messages you can modify it by passing object with modified texts. Just please remember that you have to use same key values as default object.

width

When you have a long option's text, Picker's drop-down list will break the text when it will reached default width. With this option you can override the default width.

API

Select Picker has also basic API to modify already initialized Picker.
Methods which do not return any value can be called with jQuery selector which contains more than one elements. Methods which returns some values have to be called through single element selector.

$('.multiple-used-class').picker(); // Will work
$('.multiple-used-class').picker('set', 2); // Will work
$('.multiple-used-class').picker('get'); // Won't work

$('...').picker('destroy');

This method will remove all Pickers elements and display original select box.

$('...').picker('get');

This method will return actually selected values of single Picker.
This method has to be called from single-element selector!

$('...').picker('set', id);

This method will allow you to manually set value as selected. Parameter id is value of option element. In case of multi-selection mode, it will add option as another selected one.

$('...').picker('remove', id);

This method will allow you to manually remove value as selected. Parameter id is value of option element. This method works only while multi-selection mode.

Events

Select Picker has currently basic support for events. Any suggestions for extending currently supported events will be very much welcomed.

Name of event	Description
sp-change	Triggered when some element is chosen (in single mode) or add/removed (in multiple mode).
sp-open	Triggered when is the dropdown menu opened.
sp-close	Triggered when is the dropdown menu closed.