A lightweight, configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
<!-- Include base CSS (optional) -->
<link rel="stylesheet" href="assets/styles/css/base.min.css">
<!-- Include Choices CSS -->
<link rel="stylesheet" href="assets/styles/css/choices.min.css">
<!-- Include Choices JavaScript -->
<script src="/assets/scripts/dist/choices.min.js"></script>
<script>
// Pass multiple elements:
const choices = new Choices(elements);
// Pass single element:
const choices = new Choices(element);
// Pass reference
const choices = new Choices('[data-choice']);
const choices = new Choices('.js-choice');
// Pass jQuery element
const choices = new Choices($('.js-choice')[0]);
// Passing options (with default options)
const choices = new Choices(elements, {
items: [],
choices: [],
maxItemCount: -1,
addItems: true,
removeItems: true,
removeItemButton: false,
editItems: false,
duplicateItems: true,
delimiter: ',',
paste: true,
search: true,
regexFilter: null,
placeholder: true,
placeholderValue: null,
prependValue: null,
appendValue: null,
loadingText: 'Loading...',
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',
itemChoice: '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',
loadingState: 'is-loading',
},
callbackOnInit: () => {},
callbackOnAddItem: (id, value, passedInput) => {},
callbackOnRemoveItem: (id, value, passedInput) => {},
callbackOnChange: (value, passedInput) => {},
callbackOnRender: () => {},
});
</script>npm install choices.js --save-dev
| Word | Definition |
|---|---|
| Choice | A choice is a value a user can select. A choice would be equivelant to the <option></option> element within a select input. |
| Group | A group is a collection of choices. A group should be seen as equivalent to a <optgroup></optgroup> 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: <option value="Hello" selected></option> whereas in the context of a text input an item is equivelant to <input type="text" value="Hello"> |
Type: Array Default: []
Usage: Add pre-selected items (see terminology) to text input.
Input types affected: text
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
}]
Type: Array Default: []
Usage: Add choices (see terminology) to select input.
Input types affected: select-one, select-multiple
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,
}]
Type: Number Default:-1
Input types affected: text, select-multiple
Usage: The amount of items a user can input/select ("-1" indicates no limit).
Type: Boolean Default:true
Input types affected: text
Usage: Whether a user can add items to the passed input's value.
Type: Boolean Default:true
Input types affected: text, select-multiple
Usage: Whether a user can remove items (only affects text and multiple select input types).
Type: Boolean Default:false
Input types affected: text, select-multiple
Usage: Whether a button should show that, when clicked, will remove an item (only affects text and multiple select input types).
Type: Boolean Default:false
Input types affected: text
Usage: Whether a user can edit selected items (only affects text input types).
Usage: Optionally set an item limit (-1 indicates no limit).
Type: String Default:,
Input types affected: text
Usage: What divides each value.
Type: Boolean Default:true
Input types affected: text
Usage: Whether a user can input a duplicate item.
Type: Boolean Default:true
Input types affected: text, select-multiple.
Usage: Whether a user can paste into the input.
Type: Boolean Default:true
Input types affected: select-one, select-multiple.
Usage: Whether a user can filter options by searching (only affects select input types).
Type: Regex Default:null
Input types affected: text
Usage: A filter that will need to pass for a user to successfully add an item.
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.
Type: String Default:null
Input types affected: text, select-one, select-multiple
Usage: The value of the inputs placeholder.
Type: String Default:null
Input types affected: text, select-one, select-multiple
Usage: Prepend a value to each item added to input (only affects text input types).
Type: String Default:null
Input types affected: text, select-one, select-multiple
Usage: Append a value to each item added to input (only affects text input types).
Type: String Default:Loading...
Input types affected: select-one, select-multiple
Usage: The loading text that is shown when options are populated via an AJAX callback.
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 notation.
Type: Function Default:() => {}
Input types affected: text, select-one, select-multiple
Usage: Function to run once Choices initialises.
Type: Function Default:(id, value, passedInput) => {}
Input types affected: text, select-one, select-multiple
Usage: Function to run each time an item is added (programmatically or by the user).
Type: Function Default:(id, value, passedInput) => {}
Input types affected: text, select-one, select-multiple
Usage: Function to run each time an item is removed (programmatically or by the user).
Type: Function Default:(value, passedInput) => {}
Input types affected: text, select-one, select-multiple
Usage: Function to run each time an item is added/removed by a user.
Methods can be called either directly or by chaining:
// Calling a method by chaining
const choices = new Choices(element, {
addItems: false,
removeItems: false,
}).setValue(['Set value 1', 'Set value 2']).disable();
// Calling a method directly
const choices = new Choices(element, {
addItems: false,
removeItems: false,
});
choices.setValue(['Set value 1', 'Set value 2'])
choices.disable();Input types affected: text, select-multiple
Usage: Highlight each chosen item (selected items can be removed).
Input types affected: text, select-multiple
Usage: Un-highlight each chosen item.
Input types affected: text, select-multiple
Usage: Remove each item by a given value.
Input types affected: text, select-multiple
Usage: Remove each selectable item.
Input types affected: text, select-multiple
Usage: Remove each item the user has selected.
Input types affected: select-one, select-multiple
Usage: Show option list dropdown (only affects select inputs).
Input types affected: text, select-multiple
Usage: Hide option list dropdown (only affects select inputs).
Input types affected: text, select-multiple
Usage: Toggle dropdown between showing/hidden.
Input types affected: select-one, select-multiple
Usage: Set choices of select input via an array of objects, a value name and a label name. This behaves exactly the same as passing items via the choices option but can be called after initialising Choices.
Example:
const choices = new Choices(element);
choices.setChoices([
{value: 'One', label: 'Label One', disabled: true},
{value: 'Two', label: 'Label Two' selected: true},
{value: 'Three', label: 'Label Three'},
], 'value', 'label');Input types affected: text
Usage: Set value of input based on an array of objects or strings. This behaves exactly the same as passing items via the items option but can be called after initialising Choices.
Example:
const example = new Choices(element);
// via an array of objects
example.setValue([
{value: 'One', label: 'Label One'},
{value: 'Two', label: 'Label Two'},
{value: 'Three', label: 'Label Three'},
]);
// or via an array of strings
example.setValue(['Four','Five','Six']);Input types affected: select-one, select-multiple
Usage: Set value of input based on existing Choice.
Example:
const example = new Choices(element, {
choices: [
{value: 'One', label: 'Label One'},
{value: 'Two', label: 'Label Two', disabled: true},
{value: 'Three', label: 'Label Three'},
],
});
example.setValueByChoice('Two'); // Choice with value of 'Two' has now been selected.Input types affected: text
Usage: Clear value of input.
Input types affected: text
Usage: Clear input of any user inputted text.
Input types affected: text, select-one, select-multiple
Usage: Disable input from selecting further options.
Input types affected: select-one, select-multiple
Usage: Populate options via a callback.
ES5 browsers and above (http://caniuse.com/#feat=es5).
To setup a local environment: clone this repo, navigate into it's directory in a terminal window and run the following command:
npm install
| Task | Usage |
|---|---|
npm start |
Fire up local server for development |
npm run js:build |
Compile Choices to an uglified JavaScript file |
npm run css:watch |
Watch SCSS files for changes. On a change, run build process |
npm run css:build |
Compile, minify and prefix SCSS files to CSS |
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using npm scripts...bla bla bla
MIT License