# Fast select

Fastselect is lightweight browser plugin for enhanced select elements based on jQuery. Enables responsive, fast and sensible UI upgrade of select elements with features like option searching and remote dataset loading.

Fast select is not a drop-in replacement for libraries such as Select2, Chosen or Selectize. Goal is to be and remain small both in filesize and api options. As such it can be a reasonable choice for high traffic frontend or simple backend CMS solutions. It weighs less than 5KB (minified and gziped).

## Examples

### Multiple selectable options

Select elements with multiple selectable options are supported by default. Many plugin parameters can be gleaned from input data attributes which can save you from writing configuration code.

Select element with options in markup.

                    $('.multipleSelect').fastselect();

In next example options are loaded from server via ajax request. Note that in this case we are using a normal input element. Url from which options are loaded is communicated via data-url attribute.

                    $('.multipleInputDynamic').fastselect();

Options here are loaded dynamicly as well - but initial values for UI are gleaned from item markup (via data-inital-value attribute)

    $('.multipleInputDynamicWithInitialValue').fastselect();

### User provided options or tags

User can add his own custom options (tags) by supplying userOptionAllowed parameter as it is shown bellow.

    $('.tagsInput').fastselect();

### Single mode select element

Fast select plugin enhances regular select element with UI controls for searching options on the fly. When appropriate options can be loaded via ajax.

Select with options in html as usual

Select with option groups

Input with dynamically loaded options.

                    $('.singleInputDynamic').fastselect();

Input with initial value and dynamically loaded options. Upon selection item and item model are logged to console.

                    $('.singleInputDynamicWithInitialValue').fastselect({
                        onItemSelect: function($item, itemModel) {
                            console.log($item, itemModel);
                        }
                    });

## Api and options

Fast select can be instantiated via plugin facade. If there is a need to obtain fastselect object instance you can do so via jquery data utility. Alternatively you can can just use fast select constructor.

                var $select = $('select');

                // Run, fire and forget
                $select.fastselect()

                // Run via plugin facade and get instance
                var fastSelectInstance = $select.fastselect(options).data('fastselect');

                // run directly
                var fastSelectInstance = new $.Fastselect($select.get(0), options);

Plugin options / defaults are exposed in $.Fastselect.defaults namespace so you can easily adjust them globally. Full list of options is bellow.

                $.Fastselect.defaults = {

                    elementClass: 'fstElement',
                    singleModeClass: 'fstSingleMode',
                    noneSelectedClass: 'fstNoneSelected',
                    multipleModeClass: 'fstMultipleMode',
                    queryInputClass: 'fstQueryInput',
                    queryInputExpandedClass: 'fstQueryInputExpanded',
                    fakeInputClass: 'fstFakeInput',
                    controlsClass: 'fstControls',
                    toggleButtonClass: 'fstToggleBtn',
                    activeClass: 'fstActive',
                    itemSelectedClass: 'fstSelected',
                    choiceItemClass: 'fstChoiceItem',
                    choiceRemoveClass: 'fstChoiceRemove',
                    userOptionClass: 'fstUserOption',

                    resultsContClass: 'fstResults',
                    resultsOpenedClass: 'fstResultsOpened',
                    resultsFlippedClass: 'fstResultsFilpped',
                    groupClass: 'fstGroup',
                    itemClass: 'fstResultItem',
                    groupTitleClass: 'fstGroupTitle',
                    loadingClass: 'fstLoading',
                    noResultsClass: 'fstNoResults',
                    focusedItemClass: 'fstFocused',

                    matcher: null,

                    url: null,
                    loadOnce: false,
                    apiParam: 'query',
                    initialValue: null,
                    clearQueryOnSelect: true,
                    minQueryLength: 1,
                    focusFirstItem: false,
                    flipOnBottom: true,
                    typeTimeout: 150,
                    userOptionAllowed: false,
                    valueDelimiter: ',',
                    maxItems: null,

                    parseData: null,
                    onItemSelect: null,
                    onItemCreate: null,
                    onMaxItemsReached: null,

                    placeholder: 'Choose option',
                    searchPlaceholder: 'Search options',
                    noResultsText: 'No results',
                    userOptionPrefix: 'Add '

                };

## Installation

For browser usage browse dist folder - if working with build tools go with src folder. Fastselect uses Fastsearch library internaly for querying and rendering options. Download library files from github repo, get them via bower (bower install fastselect) or via npm (npm install fastselect)