2016-07-02 15:48:20 +02:00
# Choices.js [![Build Status](https://travis-ci.org/jshjohnson/Choices.svg?branch=master)](https://travis-ci.org/jshjohnson/Choices)
A lightweight, configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
2016-06-02 10:12:55 +02:00
## Setup
```html
< script src = "/assets/js/dist/choices.min.js" > < / script >
< script >
2016-06-22 00:06:23 +02:00
// Pass multiple elements:
var choices = new Choices(elements);
// Pass single element:
var choice = new Choices(element);
// Pass reference
var choice = new Choices('[data-choice']);
var choice = new Choices('.js-choice');
2016-06-27 15:46:12 +02:00
// Passing options (with default options)
2016-06-22 00:06:23 +02:00
var choices = new Choices(elements, {
2016-06-02 10:12:55 +02:00
items: [],
2016-06-27 15:46:12 +02:00
maxItemCount: -1,
2016-06-02 10:12:55 +02:00
addItems: true,
removeItems: true,
2016-06-27 15:46:12 +02:00
removeItemButton: false,
2016-06-02 10:12:55 +02:00
editItems: false,
2016-06-27 15:46:12 +02:00
duplicateItems: true,
2016-06-02 10:12:55 +02:00
delimiter: ',',
2016-06-27 15:46:12 +02:00
paste: true,
2016-07-02 14:04:38 +02:00
search: true,
2016-06-27 15:46:12 +02:00
regexFilter: null,
2016-06-02 10:12:55 +02:00
placeholder: true,
2016-06-27 15:46:12 +02:00
placeholderValue: null,
prependValue: null,
appendValue: null,
2016-06-02 10:12:55 +02:00
loadingText: 'Loading...',
2016-06-27 15:46:12 +02:00
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',
2016-06-30 14:57:56 +02:00
itemChoice: 'choices__item--choice',
2016-06-27 15:46:12 +02:00
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',
2016-06-30 15:11:09 +02:00
loadingState: 'is-loading',
2016-06-27 15:46:12 +02:00
},
callbackOnInit: () => {},
callbackOnAddItem: (id, value, passedInput) => {},
callbackOnRemoveItem: (id, value, passedInput) => {},
2016-07-02 12:13:48 +02:00
callbackOnRender: () => {},
2016-06-02 10:12:55 +02:00
});
< / script >
```
## Installation
2016-06-27 15:46:12 +02:00
To install via NPM, run `npm install --save-dev choices.js`
## Terminology
| 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.|
2016-07-01 10:54:59 +02:00
| 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">` |
2016-06-02 10:12:55 +02:00
## Options
2016-06-27 15:46:12 +02:00
### items
< strong > Type:</ strong > < strong > Default:</ strong > `[]`
2016-06-02 10:12:55 +02:00
2016-06-22 00:08:28 +02:00
< strong > Usage:< / strong > Add pre-selected items to input.
2016-06-22 00:06:23 +02:00
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
}]
```
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### maxItemCount
< strong > Type:</ strong > `Number` < strong > Default:</ strong > `-1`
< strong > Usage:< / strong > The amount of items a user can input/select ("-1" indicates no limit).
### addItems
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
< strong > Usage:< / strong > Whether a user can add items to the passed input's value.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### removeItems
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a user can remove items (only affects text and multiple select input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### removeButton
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `false`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a button should show that, when clicked, will remove an item (only affects text and multiple select input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### editItems
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `false`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a user can edit selected items (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
< strong > Usage:< / strong > Optionally set an item limit (`-1` indicates no limit).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### delimiter
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `,`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > What divides each value (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-30 14:57:56 +02:00
### duplicates
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a user can input a duplicate item (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-30 14:57:56 +02:00
### paste
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a user can paste into the input.
2016-06-02 10:12:55 +02:00
2016-06-30 14:57:56 +02:00
### search
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Whether a user can filter options by searching (only affects select input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### regexFilter
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Regex` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > A filter that will need to pass for a user to successfully add an item (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### placeholder
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:</ strong > 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.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### placeholderValue
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > The value of the inputs placeholder.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### prependValue
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Prepend a value to each item added to input (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### appendValue
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Append a value to each item added to input (only affects text input types).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### loadingText
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `Loading...`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > The loading text that is shown when options are populated via an AJAX callback.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### classNames
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Object` < strong > Default:</ strong >
```
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',
2016-06-27 15:57:33 +02:00
itemOption: 'choices__item--choice',
2016-06-22 00:06:23 +02:00
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',
2016-06-30 14:57:56 +02:00
selectedState: 'is-highlighted',
2016-06-22 00:06:23 +02:00
}
```
2016-06-02 10:12:55 +02:00
2016-07-02 12:11:16 +02:00
< strong > Usage:</ strong > 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.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### callbackOnInit
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `() => {}`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Function to run once Choices initialises.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### callbackOnAddItem
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Function to run each time an item is added.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### callbackOnRemoveItem
2016-06-22 00:06:23 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-06-02 10:12:55 +02:00
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Function to run each time an item is removed.
2016-06-02 10:12:55 +02:00
## Methods
2016-06-27 15:46:12 +02:00
Methods can be called either directly or by chaining:
```js
// 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
2016-07-01 10:56:33 +02:00
const choices = new Choices(element, {
addItems: false,
removeItems: false,
});
2016-06-27 15:46:12 +02:00
choices.setValue(['Set value 1', 'Set value 2'])
choices.disable();
```
### highlightAll();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Highlight each chosen item (selected items can be removed).
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### unhighlightAll();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Un-highlight each chosen item.
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### removeItemsByValue(value);
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Remove each item by a given value.
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### removeActiveItems(excludedId);
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Remove each selectable item.
2016-06-22 00:12:10 +02:00
2016-06-30 14:57:56 +02:00
### removeHighlightedItems();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Remove each item the user has selected.
2016-06-27 15:46:12 +02:00
### showDropdown();
< strong > Usage:< / strong > Show option list dropdown (only affects select inputs).
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### hideDropdown();
< strong > Usage:< / strong > Hide option list dropdown (only affects select inputs).
2016-06-22 00:06:23 +02:00
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### toggleDropdown();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Toggle dropdown between showing/hidden.
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### setValue(args);
< strong > Usage:</ strong > 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 on an text input (only affects text inputs).
2016-06-22 00:06:23 +02:00
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### clearValue();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Clear value of input.
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### clearInput();
< strong > Usage:< / strong > Clear input of any user inputted text (only affects text inputs).
2016-06-22 00:06:23 +02:00
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### disable();
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Disable input from selecting further options.
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### ajax(fn);
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Populate options via a callback.
2016-06-02 10:12:55 +02:00
## Browser compatibility
2016-06-22 00:06:23 +02:00
ES5 browsers and above (http://caniuse.com/#feat=es5).
2016-06-02 10:12:55 +02:00
## Development
To setup a local environment: clone this repo, navigate into it's directory in a terminal window and run the following command:
2016-06-22 00:06:23 +02:00
```npm install```
2016-06-02 10:12:55 +02:00
### NPM tasks
2016-06-27 15:46:12 +02:00
| 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 |
2016-06-02 10:12:55 +02:00
## Contributions
2016-06-22 00:06:23 +02:00
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
2016-06-02 10:12:55 +02:00
## License
2016-06-23 11:06:35 +02:00
MIT License