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.
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.
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!
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.
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.
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.
To install Select Picker through Bower run following command:
bower install select-picker --save
npm
To install Select Picker through npm run following command:
npm install select-picker --save
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
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
Type: String Default: ''
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
Type: Integer Default: none
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.
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
Type: Boolean Default: false
With this option you can control the search feature. It can be used both with
single-selection and multi-selection mode.
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.
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
Type: Integer Default: 165 (set via CSS)
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');
Parameters: none Return: original jQuery selector
This method will remove all Pickers elements and display original select box.
This method will return actually selected values of single Picker. This method has to be called from single-element selector!
$('...').picker('set', id);
Parameters: id - string Return: original jQuery selector
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);
Parameters: id - string Return: original jQuery selector
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.