# Choices.js [![Build Status](https://travis-ci.org/jshjohnson/Choices.svg?branch=master)](https://travis-ci.org/jshjohnson/Choices) A vanilla, lightweight (~15kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency. [Demo](https://joshuajohnson.co.uk/Choices/) ## TL;DR * Lightweight * No jQuery dependency * Configurable sorting * Flexible styling * Fast search/filtering * Clean API * Right-to-left support * Custom templates ## Installation `npm install choices.js --save` ## Setup ```html ``` ## Terminology | Word | Definition | | ------ | ---------- | | Choice | A choice is a value a user can select. A choice would be equivelant to the `` element within a select input. | | Group | A group is a collection of choices. A group should be seen as equivalent to a `` element within a select input.| | Item | An item is an inputted value (text input) or a selected choice (select element). In the context of a select element, an item is equivelent to a selected option element: `` whereas in the context of a text input an item is equivelant to ``| ## Configuration options ### items **Type:** `Array` **Default:** `[]` **Input types affected:** `text` **Usage:** Add pre-selected items (see terminology) to text input. Pass an array of strings: `['value 1', 'value 2', 'value 3']` Pass an array of objects: ``` [{ value: 'Value 1', label: 'Label 1', id: 1 }, { value: 'Value 2', label: 'Label 2', id: 2 }] ``` ### choices **Type:** `Array` **Default:** `[]` **Input types affected:** `select-one`, `select-multiple` **Usage:** Add choices (see terminology) to select input. Pass an array of objects: ``` [{ value: 'Option 1', label: 'Option 1', selected: true, disabled: false, }, { value: 'Option 2', label: 'Option 2', selected: false, disabled: true, }] ``` ### maxItemCount **Type:** `Number` **Default:** `-1` **Input types affected:** `text`, `select-multiple` **Usage:** The amount of items a user can input/select ("-1" indicates no limit). ### addItems **Type:** `Boolean` **Default:** `true` **Input types affected:** `text` **Usage:** Whether a user can add items. ### removeItems **Type:** `Boolean` **Default:** `true` **Input types affected:** `text`, `select-multiple` **Usage:** Whether a user can remove items. ### removeItemButton **Type:** `Boolean` **Default:** `false` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Whether each item should have a remove button. ### editItems **Type:** `Boolean` **Default:** `false` **Input types affected:** `text` **Usage:** Whether a user can edit items. An item's value can be edited by pressing the backspace. ### duplicateItems **Type:** `Boolean` **Default:** `true` **Input types affected:** `text`, `select-multiple` **Usage:** Whether each inputted/chosen item should be unique. ### delimiter **Type:** `String` **Default:** `,` **Input types affected:** `text` **Usage:** What divides each value. The default delimiter seperates each value with a comma: `"Value 1, Value 2, Value 3"`. ### paste **Type:** `Boolean` **Default:** `true` **Input types affected:** `text`, `select-multiple` **Usage:** Whether a user can paste into the input. ### search **Type:** `Boolean` **Default:** `true` **Input types affected:** `select-one` **Usage:** Whether a user should be allowed to search avaiable choices. Note that multiple select boxes will always show search inputs. ### searchFloor **Type:** `Number` **Default:** `1` **Input types affected:** `select-one`, `select-multiple` **Usage:** The minimum length a search value should be before choices are searched. ### flip **Type:** `Boolean` **Default:** `true` **Input types affected:** `select-one`, `select-multiple` **Usage:** Whether the dropdown should appear above the input (rather than beneath) if there is not enough space within the window. ### regexFilter **Type:** `Regex` **Default:** `null` **Input types affected:** `text` **Usage:** A filter that will need to pass for a user to successfully add an item. ### shouldSort **Type:** `Boolean` **Default:** `true` **Input types affected:** `select-one`, `select-multiple` **Usage:** Whether choices should be sorted. If false, choices will appear in the order they were given. ### sortFilter **Type:** `Function` **Default:** sortByAlpha **Input types affected:** `select-one`, `select-multiple` **Usage:** The function that will sort choices before they are displayed (unless a user is searching). By default choices are sorted by alphabetical order. **Example:** ```js // Sorting via length of label from largest to smallest const example = new Choices(element, { sortFilter: function(a, b) { return b.label.length - a.label.length; }, }; ``` ### sortFields **Type:** `Array/String` **Default:** `['label', 'value']` **Input types affected:**`select-one`, `select-multiple` **Usage:** Specify which fields should be used for sorting when a user is searching. If a user is not searching and sorting is enabled, only the choice's label will be sorted. ### placeholder **Type:** `Boolean` **Default:** `true` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Whether the input should show a placeholder. Used in conjunction with `placeholderValue`. If `placeholder` is set to true and no value is passed to `placeholderValue`, the passed input's placeholder attribute will be used as the placeholder value. ### placeholderValue **Type:** `String` **Default:** `null` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** The value of the inputs placeholder. ### prependValue **Type:** `String` **Default:** `null` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Prepend a value to each item added/selected. ### appendValue **Type:** `String` **Default:** `null` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Append a value to each item added/selected. ### loadingText **Type:** `String` **Default:** `Loading...` **Input types affected:** `select-one`, `select-multiple` **Usage:** The text that is shown whilst choices are being populated via AJAX. ### noResultsText **Type:** `String` **Default:** `No results found` **Input types affected:** `select-one`, `select-multiple` **Usage:** The text that is shown when a user's search has returned no results. ### noChoicesText **Type:** `String` **Default:** `No choices to choose from` **Input types affected:** `select-multiple` **Usage:** The text that is shown when a user has selected all possible choices. ### itemSelectText **Type:** `String` **Default:** `Press to select` **Input types affected:** `select-multiple`, `select-one` **Usage:** The text that is shown when a user hovers over a selectable choice. ### classNames **Type:** `Object` **Default:** ``` classNames: { containerOuter: 'choices', containerInner: 'choices__inner', input: 'choices__input', inputCloned: 'choices__input--cloned', list: 'choices__list', listItems: 'choices__list--multiple', listSingle: 'choices__list--single', listDropdown: 'choices__list--dropdown', item: 'choices__item', itemSelectable: 'choices__item--selectable', itemDisabled: 'choices__item--disabled', itemOption: 'choices__item--choice', group: 'choices__group', groupHeading : 'choices__heading', button: 'choices__button', activeState: 'is-active', focusState: 'is-focused', openState: 'is-open', disabledState: 'is-disabled', highlightedState: 'is-highlighted', hiddenState: 'is-hidden', flippedState: 'is-flipped', selectedState: 'is-highlighted', } ``` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Classes added to HTML generated by Choices. By default classnames follow the [BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) notation. ### callbackOnInit **Type:** `Function` **Default:** `null` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Function to run once Choices initialises. ### callbackOnAddItem **Type:** `Function` **Default:** `null` **Arguments:** `id, value, groupValue` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Function to run each time an item is added (programmatically or by the user). **Example:** ```js const example = new Choices(element, { callbackOnAddItem: (id, value, groupValue) => { // do something creative here... }, }; ``` ### callbackOnRemoveItem **Type:** `Function` **Default:** `null` **Arguments:** `id, value, groupValue` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Function to run each time an item is removed (programmatically or by the user). ### callbackOnHighlightItem **Type:** `Function` **Default:** `null` **Arguments:** `id, value, groupValue` **Input types affected:** `text`, `select-multiple` **Usage:** Function to run each time an item is highlighted. ### callbackOnUnhighlightItem **Type:** `Function` **Default:** `null` **Arguments:** `id, value, groupValue` **Input types affected:** `text`, `select-multiple` **Usage:** Function to run each time an item is unhighlighted. ### callbackOnCreateTemplates **Type:** `Function` **Default:** `null` **Arguments:** `instance, template` **Input types affected:** `text`, `select-one`, `select-multiple` **Usage:** Function to run on template creation. Through this callback it is possible to provide custom templates for the various components of Choices (see terminology). For Choices to work with custom templates, it is important you maintain the various attributes defined [here](https://github.com/jshjohnson/Choices/blob/master/assets/scripts/src/choices.js#L1946-L2030). **Example:** ```js const example = new Choices(element, { callbackOnCreateTemplates: function (instance, template) { var classNames = instance.config.classNames; return { item: (data) => { return template(`