jQuery SmartSelect

Basic Settings

Support both single and multiple select.

single select

single select

similar to HTML select
can only select one option
by default, closed after selection
configurable display label
stylish button through configuration

$("select#demo-1a").smartselect({
    multiple: false,
    style: {
        select: 'dropdown-toggle btn btn-info'
    },
    text: {
        selectLabel: 'Select ...'
    },
    toolbar: false
});

default values

multiple select

if multiple attribute set in <SELECT>
by default, dropdown wouldn't close after selction

default values

configurable default values
when all options deselected, plugin will be reset to default values

initial values

If original <SELECT> has options selected, plugin will be inited with these values
Initial values can also be set with options
plugin will not be reset to initial values when all options deselected

$("select#demo-1b").smartselect({
    defaultValues: [ '3', '6' ],
    toolbar: false
});

limit selections

atLeast

atLeast limits the minimum options required in the <SELECT>
user may defined a handler to listen to the atLeast event
in <OPTGROUP>, attribute 'data-atleast' can be used to set minimum required selected options in a optgroup

atMost

atMost limits the maximum options allowed in the <SELECT>
user may defined a handler to listen to the atMost event
in <OPTGROUP>, attribute 'data-atmost' can be used to set maximum selected options allowed in a optgroup

mustSelect

mustSelect contains an array of values must be selected in <SELECT>
user may defined a handler to listen to the mustSelect event
attribute data-must can used in <OPTION> to achieve same purpose

$("select#demo-1c").smartselect({
    atLeast: 2,
    atMost: 4,
    mustSelect: [ '1' ],
    toolbar: false,
    handler: {
        atLeast: function() {
            alert('at least 2 options required');
        },
        atMost: function() {
            alert('maximum 4 options exceeded');
        },
        mustSelect: function() {
            alert('must select this one');
        }
    }
});

data exclusive

data exclusive

data-exclusive and data-inclusive can be combined to achieve complex data relationships in <SELECT> or <OPTGROUP>
data-exclusive defines options exlusive with others in a multiple select situation, similar to a single select

data inclusive

data-inclusive attribute used in <OPTION> defines options can be selected together with other options in the same 'team'
data-inclusive attribute value is a space-seperated string with each non-space char indicate a different 'team'

<select id="demo-1d" multiple data-exclusive>
    <option value="1">label 1</option>
    <option value="2" data-inclusive="a b">label 2 (team a & b)</option>
    <option value="3" data-inclusive="b c">label 3 (team b & c)</option>
    <option value="4">label 4</option>
    <option value="5">label 5</option>
    <option value="6" data-inclusive="c">label 6 (team c)</option>
    <option value="7">label 7</option>
    <option value="8">label 8</option>
</select>

$("select#demo-1d").smartselect({
    showSelectedCount: 1,
    toolbar: false
});

The Toolbar

search & unfold

buttonSearch

search all options
search by 'label', 'value' or 'both'
hit RETURN in the input box to search
better use with unfold button to view unfiltered options

buttonUnfold

expanded view to show all options
in <OPTGROUP> or data-level cases, expand all groups and levels

$("select#demo-2a").smartselect({
    searchBy: 'label',
    searchCaseInsensitive: false,
    toolbar: {
        buttonSearch:   true,
        buttonAlias:    false,
        buttonView:     false,
        buttonUnfold:   true,
        buttonCancel:   false,
        buttonCheckAll: false,
        buttonUnCheck:  false
    }
});

aliases

buttonAlias

save selected options as an alias for quick access at later time
select multiple options by just clikc an alias name
different aliases must use different names
a new alias name for the same selected options will overwrite the old alias
default to close the select after click an alias
status change event 'aliasChange' triggered once an alias is added/deleted
aliases can be easily defined initially or added later

$("select#demo-2b").smartselect({
      viewAfterAlias: false,
      closeAfterAlias: false,
      handler: {
        aliasChange: function() {
          console.log('alias changed');
        }
      },
      aliases: {
          alias1: [ '1' , '2' ],
          alias2: [ '5' , '7' ]
      },
      toolbar: {
          buttonSearch:   true,
          buttonAlias:    true,
          buttonView:     false,
          buttonUnfold:   true,
          buttonCancel:   false,
          buttonCheckAll: false,
          buttonUnCheck:  false
      }
});

view & unfold

buttonView

defines a fold/unfold status when click buttonView
possible values are root, expand, level1, level2 and selected
selected can be combined with other options, like root+selected

defaultView

defines the fold/unfold status before dropdown shows for the first time
attribute data-view can be added to <OPTGROUP> or <OPTION> to enable default fold/unfold status for specific group or level

$("select#demo-2c").smartselect({
    defaultView: 'selected',
    toolbar: {
        buttonSearch:   true,
        buttonAlias:    true,
        // view selected options only when clicked
        buttonView:     'selected',
        buttonUnfold:   true,
        buttonCancel:   false,
        buttonCheckAll: false,
        buttonUnCheck:  false
    }
});

check all

buttonCheckAll

select all options
for complex situation, simulates click group by group

buttonUnCheck

deselect all options
unless atLeast, defaultValues are set

$("select#demo-2d").smartselect({
    toolbar: {
        buttonSearch:   true,
        buttonAlias:    true,
        buttonView:     'selected',
        buttonUnfold:   true,
        buttonCancel:   false,
        buttonCheckAll: true,
        buttonUnCheck:  true
    }
});

cancel

buttonCancel

revert to the status when dropdown just showed

$("select#demo-2e").smartselect({
    viewAfterCancel: false,
    toolbar: {
        buttonSearch:   true,
        buttonAlias:    true,
        buttonView:     'selected',
        buttonUnfold:   true,
        buttonCancel:   true,
        buttonCheckAll: true,
        buttonUnCheck:  true
    }
});

toolbar position

move toolbar to left

change the style of toolbarPos
change the style of dropdown in toolbar

$("select#demo-2f").smartselect({
    style: {
        buttonDropdown: 'dropdown-menu',
        toolbarPos: 'left'
    }
});

Option Group

data-level

data-level

data-level attribute is used to indicate option level
by default, when no data-level is specified, it equals to data-level="1"
by default, click a sublevel will deselect the upper levels, vise versa.
by default, when all sublevels selected, it will revert to one level up
buttonCheckAll just select all of the level 1 under the group

$("select#demo-3a").smartselect({
    defaultView: 'expand'
});

default view

defaultView

control default fold/unfold status by using defaultView option and data-view attribute
defualtView defines overall expand level while data-view controls individual group or level
data-view="2" means expand upto 2 levels under this group/level

<optgroup label="group 1" data-view="1">
    <option value="1">label 1</option>
    <option value="1-1" data-level="2">label 1-1</option>
    <option value="1-2" data-level="2">label 1-2</option>
    <option value="2">label 2</option>
    ...

$("select#demo-3b").smartselect({
    defaultView: 'root+selected'
});

group exclusive

data-group-exclusive

when data-group-exclusive attribute set, this group will exclusive with other groups
data-group-exclusive can take a spaced string, "a b" means other groups with "a" or "b" will not be exclusive with this group
empty data-group-exclusive means data-group-exclusive="_"
when no attribute data-group-exclusiveset, equals to data-group-exclusive="."

<select id="demo-3c" multiple>
    <optgroup label="group 1" data-group-exclusive>
        <option value="1">1</option>
        <option value="2">2</option>
    </optgroup>
    <optgroup label="group a b" data-group-exclusive="a b">
        <option value="3">3</option>
        <option value="4">4</option>
    </optgroup>
    <optgroup label="group b c" data-group-exclusive="b c">
        <option value="5">5</option>
        <option value="6">6</option>
    </optgroup>
    <optgroup label="group c" data-group-exclusive="c">
        <option value="7">7</option>
        <option value="8">8</option>
    </optgroup>
    <optgroup label="group 5">
        <option value="9">9</option>
        <option value="10">10</option>
    </optgroup>
</select>

limit in group

data-atleast

set at least number of options required at group level
plugin will select the at least number of options if no default values or initial values set
status change event atLeast will be triggered if user deselect at least number of options

data-atmost

set maximum number of options allowed at group level
if default values or initial values exceend the data-atmost, event 'atMost' will be triggered

<select id="demo-3d" multiple>
    <optgroup label="group 1" data-view data-atleast="1">
        <option value="1" data-must>1</option>
        <option value="2">2</option>
        <option value="3">3</option>
    </optgroup>
    <optgroup label="group 2" data-atleast="2" data-atmost="3">
        <option value="4">4</option>
        <option value="5">5</option>
        <option value="6">6</option>
        <option value="7">7</option>
        <option value="8">8</option>
    </optgroup>
</select>

APIs

common apis

toggle, select, deselect & get

toggleDropdown() toggles the dropdown
selectOptions(array values, clear = true) select values, clear first by default
deselectOptions(array values) deselect values
getValues() get all selection values in array

click buttons below

var $ss4a = $("select#demo-4a").smartselect({
    defaultView: 'expand'
}).getsmartselect();

// toggle dropdown
$("#btn-4aa").click(function() {
    $ss4a.toggleDropdown();
});

// set values without clear
$("#btn-4ab").click(function() {
    $ss4a.selectOptions([ '3', '4' ], false);
});

// unset values
$("#btn-4ac").click(function() {
    $ss4a.deselectOptions([ '3' ]);
});

// get values
$("#btn-4ad").click(function() {
    alert($ss4a.getValues());
});

// clear all values
$("#btn-4ae").click(function() {
    $ss4a.selectOptions([ ]);
});

disable & enable

disable & enable

disableOptions(array values) disable options base on given values, if no values provided, disable all options
enableOptions(array values) enable options base on given values. If no values provided, enable all disabled options
disableSelect() disables the select entirely
enableSelect() enables the select

click buttons below

var $ss4b = $("select#demo-4b").smartselect({
                defaultView: 'expand'
            }).getsmartselect();

// toggle dropdown
$("#btn-4ba").click(function() {
    $ss4b.toggleDropdown();
});

// disable values
$("#btn-4bb").click(function() {
    $ss4b.disableOptions();
});


// enable values
$("#btn-4bc").click(function() {
    $ss4b.enableOptions([ '3', '4' ]);
});

// enable all
$("#btn-4bd").click(function() {
    $ss4b.enableOptions();
});

// get values
$("#btn-4be").click(function() {
    alert($ss4b.getValues());
});

// disable select
$("#btn-4bf").click(function() {
    $ss4b.disableSelect();
});

// enable select
$("#btn-4bg").click(function() {
    $ss4b.enableSelect();
});

add & remove options

addOption(info, after, parent)

'info' is an object has 'info.label' and 'info.value' set.
'after' is an option value, DOM or jQuery object.
'parent' can be an option value, DOM, jQuery object or a group name to match

removeOption(value)

'value' can be an option value, DOM or jQuery object.

click buttons below

var $ss4c = $("select#demo-4c").smartselect({
                defaultView: 'expand'
            }).getsmartselect();

// add 9 after 8
$("#btn-4ca").click(function() {
    $ss4c.toggleDropdown(false);
    $ss4c.addOption({
        label: '9',
        value: '9'
    }, '8');
});

// add 10 under 8
$("#btn-4cb").click(function() {
    $ss4c.addOption({
        label: '10',
        value: '10'
    }, false, '8');
});

// just add to the group 1
$("#btn-4cc").click(function() {
    $ss4c.addOption({
        label: '11',
        value: '11'
    }, false, $ss4c.getGroup('group 1'));
});

// just add to the root end
$("#btn-4cd").click(function() {
    $ss4c.addOption({
        label: '12',
        value: '12'
    });
});

$(document).on('optionDuplicated.pa.smartselect', function(e) {
    $ss4c.removeOption(e.target);
});

// get values
$("#btn-4ch").click(function() {
    alert($ss4c.getValues());
});

work with alias

addAlias(name, value)

'name' is a string.
'value' is an array of values.

removeAlias(name)

'name' is a string.

click buttons below

var $ss4d = $("select#demo-4d").smartselect({
                defaultView: 'expand',
                closeAfterAlias: false
            }).getsmartselect();

// add alias 'test'
function xx() {
    $ss4d.$buttonAlias.find('button').trigger('click');
}

$("#btn-4da").click(function() {
    $ss4d.toggleDropdown();
    setTimeout(xx, 100);
    $ss4d.addAlias('test', [ '3', '5' ]);
});

$("#btn-4db").click(function() {
    $ss4d.selectAlias('test');
    setTimeout(xx, 100);
});

$("#btn-4dc").click(function() {
    $ss4d.removeAlias('test');
});

Events

status events

status change events

signal a status change
no 'on' prefix in the event name, like 'atLeast', 'atMost' etc.
handlers can be defined outside with fullname like 'atLeast.pa.smartselect'
handlers can also be defined in initial options, with shortname like 'atLeast'
status change events triggered on related jQ object
or when no object to be associated with, triggered on this.$element

$(document).on('aliasChange.pa.smartselect', function() {
    alert('handler defined outside');
});
var $ss5a = $('select#demo-5a').smartselect({
                aliases: {
                    test: [ '3', '4' ]
                },
                handler: {
                    aliasChange: function(e) {
                        alert('handler defined in options');
                    }
                }
            }).getsmartselect();

var removeIt = function() {
    $ss5a.removeAlias('test');
};

$('#btn-5aa').click(function() {
    $ss5a.toggleDropdown(false).$buttonAlias.find('button').trigger('click');
    setTimeout(removeIt, 900);
});

procedural events

procedural events

events triggered in procedures
'on' prefix in the event name, like 'onPluginLoaded' etc.
procedural events normally come in pairs like 'onOptionChange' (before) and 'onOptionChanged' (after)
callbacks can defined in initial options
callbacks can also be added later on with API 'addCallback()'
callbacks are required to return true or false base on execution status.
if a before-procedure callback returns false, the whole procedure will stop

var d3 = function($target, event) {
    if ($target.attr('data-value') === '3') {
        alert('you can not select 3');
        return false;
    }
    return true;
};

var $ss5b = $('select#demo-5b').smartselect({
                callback: {
                    onOptionSelect: [ d3 ]
                },
                toolbar: false
            }).getsmartselect();

$('#btn-5ba').click(function() {
    $ss5b.toggleDropdown(false);
    $ss5b.selectOption('3');
});

$('#btn-5bb').click(function() {
    $ss5b.toggleDropdown(false);
    $ss5b.selectOption('2');
});

$ss5b.addCallback('onOptionSelected', function($target, event) {
    alert('you selected ' + $target.attr('data-value'));
});

callback example 1

onOptionSelected

triggered after option sucessfully selected

onOptionDeselected

triggered after option sucessfully deselected

var addButton = function($target, event) {
    var self = this;
    var html = '<button type="button" class="btn btn-sm btn-info" data-value="' +
        $target.attr('data-value') + '">' + $target.text() +
        '<i class="fa fa-times"></i></button>';
    $('#pool').append(html);

    $('#pool').find('button').off().on('click', function(e) {
        var v = $(e.target).closest('button').attr('data-value');
        self.deselectOptions([ v ]);
    });
    return true;
};

var removeButton = function($target, event) {
    $('#pool').find('button').each(function() {
        if ($(this).attr('data-value') === $target.attr('data-value')) {
            $(this).remove();
            return false;
        }
    });
    return true;
};

$('select#demo-5c').smartselect({
    defaultView: 'expand',
    toolbar: false,
    callback: {
        onOptionSelected: [ addButton ],
        onOptionDeselected: [ removeButton ]
    }
});

callback example 2

Disable options base on selection

on option select, call predefined callbacks.

var exOne = function($target, event) {
    var val = $target.attr('data-value');
    if (val === 'male') {
        // always enable first
        this.enableOptions([ 'decathlon' ]);
        this.disableOptions([ 'heptathlon', 'synchronized Swimming' ]);
    }
    if (val === 'female') {
        this.enableOptions([ 'heptathlon', 'synchronized Swimming' ]);
        this.disableOptions([ 'decathlon' ]);
    }
    return true;
};

$('select#demo-5d').smartselect({
    defaultView: 'expand',
    toolbar: false,
    callback: {
        onOptionSelect: [ exOne ]
    }
});

Advanced

special options

input box as an option

all kinds of components can be used as an option
As long as the option is marked as data-special
and three callbacks getSpecialValue(), setSpecialValue(), getSpecialLabel() defined.
class ss-nobubble to disable click event bubble up to <li>

$(document).ready(function() {
    var $ss6a = $('#demo-6a').smartselect({
        defaultView: 'level1+selected',
        initialValues: [ '1//testInput', '2-1' ],
        specialValueSeperator: '//',
        aliases: {
            'Special Option': [ '1//testInput', '2-1' ]
        },
        callback: {
            onOptionSelect: [
                // if inputbox has no value, disable select
                function($target, event) {
                    if ($target.find('input').val() === '') return false;
                    return true;
                }
            ]
        },
        data: [
            { group: true, label: 'Group One' },
                { value: '1',
                  'data-special': true,
                  html: '<label class="ss-nobubble"><input type="text" placeholder="Please type" id="test6" class="form-control input-sm"></label>'
                },
                { value: '2', label: '2' },
                { value: '2-1', label: '2-1', level: 2 },
                { value: '3', label: '3'  },
            { group: true, label: 'Group Two' },
                { value: '4', label: '4' },
                { value: '5', label: '5' },
                { value: '6', label: '6' }
        ]}).getsmartselect();

    // select if inputbox has value, unselect if inputbox empty
    $("#test6").on("focusout", function(e) {
        var $jq = $(this);
        var val = $jq.val();
        if (val === "") {
            $ss6a.deselectOptions([ '1' ]);
        } else {
            $ss6a.selectOption([ '1' ]);
        }
    });
});