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)
2016-08-10 11:04:21 +02:00
A vanilla, lightweight (~15kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
2016-08-09 14:59:30 +02:00
2016-07-25 10:08:14 +02:00
[Demo ](https://joshuajohnson.co.uk/Choices/ )
2016-06-02 10:12:55 +02:00
## Setup
2016-07-11 11:25:38 +02:00
2016-06-02 10:12:55 +02:00
```html
2016-07-11 11:25:38 +02:00
<!-- 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 >
2016-06-02 10:12:55 +02:00
< script >
2016-06-22 00:06:23 +02:00
// Pass multiple elements:
2016-07-03 11:54:20 +02:00
const choices = new Choices(elements);
2016-06-22 00:06:23 +02:00
// Pass single element:
2016-07-03 11:55:48 +02:00
const choices = new Choices(element);
2016-06-22 00:06:23 +02:00
// Pass reference
2016-07-03 11:55:48 +02:00
const choices = new Choices('[data-choice']);
const choices = new Choices('.js-choice');
2016-08-01 21:00:24 +02:00
// Pass jQuery element
const choices = new Choices($('.js-choice')[0]);
2016-06-22 00:06:23 +02:00
2016-06-27 15:46:12 +02:00
// Passing options (with default options)
2016-07-03 11:54:20 +02:00
const choices = new Choices(elements, {
2016-06-02 10:12:55 +02:00
items: [],
2016-07-31 21:17:01 +02:00
choices: [],
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-08-02 22:38:00 +02:00
search: true,
flip: true,
2016-06-27 15:46:12 +02:00
regexFilter: null,
2016-08-03 20:36:37 +02:00
sortFilter: sortByAlpha,
2016-08-03 08:43:35 +02:00
sortFields: ['label', 'value'],
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-08-14 16:36:11 +02:00
noResultsText: 'No results round',
noChoicesText: 'No choices to choose from',
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-08-04 14:21:24 +02:00
callbackOnHighlightItem: (id, value, passedInput) => {},
callbackOnUnhighlightItem: (id, value, passedInput) => {},
2016-07-31 21:02:46 +02:00
callbackOnChange: (value, passedInput) => {},
2016-06-02 10:12:55 +02:00
});
< / script >
```
## Installation
2016-07-11 11:31:00 +02:00
2016-08-04 22:54:28 +02:00
`npm install choices.js --save`
2016-06-27 15:46:12 +02:00
## 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
2016-08-05 08:42:35 +02:00
2016-07-03 11:54:20 +02:00
## Configuration options
2016-06-27 15:46:12 +02:00
### items
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Array` < strong > Default:</ strong > `[]`
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
2016-06-22 00:06:23 +02:00
2016-08-06 12:15:56 +02:00
< strong > Usage:< / strong > Add pre-selected items (see terminology) to text 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-07-30 17:03:20 +02:00
### choices
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Array` < strong > Default:</ strong > `[]`
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-08-06 12:15:56 +02:00
< strong > Usage:< / strong > Add choices (see terminology) to select input.
2016-07-30 16:12:22 +02:00
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,
}]
```
2016-06-27 15:46:12 +02:00
### maxItemCount
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Number` < strong > Default:</ strong > `-1`
2016-06-27 15:46:12 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-06-27 15:46:12 +02:00
< strong > Usage:< / strong > The amount of items a user can input/select ("-1" indicates no limit).
### addItems
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-08-07 22:11:36 +02:00
< strong > Usage:< / strong > Whether a user can remove items.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### removeButton
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `false`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-08-07 22:11:36 +02:00
< strong > Usage:< / strong > Whether a button should show that, when clicked, will remove an item.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### editItems
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `false`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
2016-08-07 22:11:36 +02:00
< strong > Usage:< / strong > Whether a user can edit items. An items value can be edited by pressing the backspace.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### delimiter
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `,`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
2016-08-06 12:08:46 +02:00
< strong > Usage:</ strong > What divides each value. By default the delimited value would be `"Value 1, Value 2, Value 3"` .
2016-06-02 10:12:55 +02:00
2016-06-30 14:57:56 +02:00
### duplicates
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
< strong > Usage:< / strong > Whether a user can input a duplicate item.
2016-06-02 10:12:55 +02:00
2016-06-30 14:57:56 +02:00
### paste
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-08-07 22:11:36 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-07-30 16:12:22 +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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-08-07 22:11:36 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-08-02 22:38:00 +02:00
2016-08-07 22:11:36 +02:00
< strong > Usage:< / strong > Whether a search input should display allowing a user to filter choices.
2016-08-02 22:38:00 +02:00
### flip
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-08-02 22:38:00 +02:00
2016-08-07 22:11:36 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-07-30 16:12:22 +02:00
2016-08-07 22:11:36 +02:00
< strong > Usage:< / strong > Whether the dropdown should appear above the input if there is not enough space within the window.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### regexFilter
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Regex` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
< strong > Usage:< / strong > A filter that will need to pass for a user to successfully add an item.
2016-06-02 10:12:55 +02:00
2016-08-03 20:36:37 +02:00
### sortFilter
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > sortByAlpha
2016-08-03 20:36:37 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
< strong > Usage:< / strong > The function that will sort choices before they are displayed (unless a user is searching). By default choices are sorted by alphabetical order.
2016-08-03 20:56:57 +02:00
< strong > Example:< / strong >
```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;
},
};
```
2016-08-03 08:43:35 +02:00
### sortFields
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Array/String` < strong > Default:</ strong > `['label', 'value']`
2016-08-03 08:43:35 +02:00
< strong > Input types affected:</ strong > `select-one`, `select-multiple`
< strong > Usage:< / strong > Specify which fields should be used for sorting.
2016-06-27 15:46:12 +02:00
### placeholder
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Boolean` < strong > Default:</ strong > `true`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-08-06 12:38:06 +02:00
< strong > Usage:< / strong > Prepend a value to each item added/selected.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### appendValue
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `null`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-08-14 16:36:11 +02:00
< strong > Usage:< / strong > Append a value to each item added/selected.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### loadingText
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `String` < strong > Default:</ strong > `Loading...`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-08-14 16:36:11 +02:00
< strong > Usage:< / strong > The text that is shown whilst choices are being populated via AJAX.
### noResultsText
< strong > Type:</ strong > `String` < strong > Default:</ strong > `No results round`
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
< strong > Usage:< / strong > The text that is shown when a user's search has returned no results.
### noChoicesText
< strong > Type:</ strong > `String` < strong > Default:</ strong > `No choices to choose from`
< strong > Input types affected:</ strong > `select-multiple`
< strong > Usage:< / strong > The text that is shown when a user has selected all possible choices.
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### classNames
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Object` < strong > Default:</ strong >
2016-06-22 00:06:23 +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-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-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `() => {}`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
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-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-07-31 21:02:46 +02:00
< strong > Usage:< / strong > Function to run each time an item is added (programmatically or by the user).
2016-06-02 10:12:55 +02:00
2016-06-27 15:46:12 +02:00
### callbackOnRemoveItem
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-06-02 10:12:55 +02:00
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-07-31 21:02:46 +02:00
< strong > Usage:< / strong > Function to run each time an item is removed (programmatically or by the user).
2016-08-04 14:21:24 +02:00
### callbackOnHighlightItem
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-08-04 14:21:24 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
< strong > Usage:< / strong > Function to run each time an item is highlighted.
### callbackOnUnhighlightItem
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(id, value, passedInput) => {}`
2016-08-04 14:21:24 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
< strong > Usage:< / strong > Function to run each time an item is unhighlighted.
2016-07-31 21:02:46 +02:00
### callbackOnChange
2016-08-07 22:11:36 +02:00
< strong > Type:</ strong > `Function` < strong > Default:</ strong > `(value, passedInput) => {}`
2016-07-31 21:02:46 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
< strong > Usage:< / strong > Function to run each time an item is added/removed by a user.
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();
```
2016-08-05 08:42:35 +02:00
### destroy();
< strong > Input types affected:</ strong > `text` , `select-multiple` , `select-one`
< strong > Usage:< / strong > Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.
### init();
< strong > Input types affected:</ strong > `text` , `select-multiple` , `select-one`
< strong > Usage:< / strong > Creates a new instance of Choices, adds event listeners, creates templates and renders a Choices element to the DOM.
< strong > Note:</ strong > This is called implicitly when a new instance of Choices is created. This would be used after a Choices instance had already been destroyed (using `destroy()` ).
2016-06-27 15:46:12 +02:00
### highlightAll();
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
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();
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-06-27 15:46:12 +02:00
< 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();
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-06-27 15:46:12 +02:00
< 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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-multiple`
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Toggle dropdown between showing/hidden.
2016-07-31 22:05:17 +02:00
### setChoices(choices, value, label);
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-08-02 22:10:53 +02:00
< strong > Usage:</ strong > Set choices of select input via an array of objects, a value name and a label name. This behaves the same as passing items via the `choices` option but can be called after initialising Choices. This can also be used to add groups of choices (see example 2);
2016-07-31 22:05:17 +02:00
2016-08-02 22:10:53 +02:00
< strong > Example 1:< / strong >
2016-07-31 22:05:17 +02:00
```js
2016-08-02 22:10:53 +02:00
const example = new Choices(element);
2016-07-31 22:05:17 +02:00
2016-08-02 22:10:53 +02:00
example.setChoices([
2016-07-31 22:05:17 +02:00
{value: 'One', label: 'Label One', disabled: true},
{value: 'Two', label: 'Label Two' selected: true},
{value: 'Three', label: 'Label Three'},
], 'value', 'label');
```
2016-06-22 00:12:10 +02:00
2016-08-02 22:10:53 +02:00
< strong > Example 2:< / strong >
```js
const example = new Choices(element);
example.setChoices([{
label: 'Group one',
id: 1,
disabled: false,
choices: [
{value: 'Child One', label: 'Child One', selected: true},
{value: 'Child Two', label: 'Child Two', disabled: true},
{value: 'Child Three', label: 'Child Three'},
]
},
{
label: 'Group two',
id: 2,
disabled: false,
choices: [
{value: 'Child Four', label: 'Child Four', disabled: true},
{value: 'Child Five', label: 'Child Five'},
{value: 'Child Six', label: 'Child Six'},
]
}], 'value', 'label');
```
2016-08-02 08:45:08 +02:00
### getValue(valueOnly)
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
< strong > Usage:</ strong > Get value(s) of input (i.e. inputted items (text) or selected choices (select)). Optionally pass an argument of `true` to only return values rather than value objects.
< strong > Example:< / strong >
```js
const example = new Choices(element);
const values = example.getValue(true); // returns ['value 1', 'value 2'];
const valueArray = example.getValue(); // returns [{ active: true, choiceId: 1, highlighted: false, id: 1, label: 'Label 1', value: 'Value 1'}, { active: true, choiceId: 2, highlighted: false, id: 2, label: 'Label 2', value: 'Value 2'}];
```
2016-06-27 15:46:12 +02:00
### setValue(args);
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
2016-07-31 22:05:17 +02:00
< 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.
< strong > Example:< / strong >
```js
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'},
]);
2016-06-22 00:06:23 +02:00
2016-07-31 22:05:17 +02:00
// or via an array of strings
example.setValue(['Four','Five','Six']);
```
### setValueByChoice(value);
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
< strong > Usage:< / strong > Set value of input based on existing Choice.
< strong > Example:< / strong >
```js
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.
```
2016-06-22 00:12:10 +02:00
2016-08-03 22:51:24 +02:00
### clearStore();
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-07-30 16:12:22 +02:00
2016-08-03 22:51:24 +02:00
< strong > Usage:< / strong > Removes all items, choices and groups. Use with caution.
2016-06-22 00:06:23 +02:00
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### clearInput();
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text`
< strong > Usage:< / strong > Clear input of any user inputted text.
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-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
2016-08-02 22:14:13 +02:00
< strong > Usage:< / strong > Disables input from accepting new value/sselecting further choices.
### enable();
< strong > Input types affected:</ strong > `text` , `select-one` , `select-multiple`
< strong > Usage:< / strong > Enables input to accept new values/select further choices.
2016-06-22 00:06:23 +02:00
2016-06-22 00:12:10 +02:00
2016-06-27 15:46:12 +02:00
### ajax(fn);
2016-07-30 16:12:22 +02:00
< strong > Input types affected:</ strong > `select-one` , `select-multiple`
2016-06-22 00:06:23 +02:00
< strong > Usage:< / strong > Populate options via a callback.
2016-08-02 22:14:13 +02:00
< strong > Example:< / strong >
```js
var example = new Choices(element);
example.ajax(function(callback) {
fetch(url)
.then(function(response) {
response.json().then(function(data) {
callback(data, 'value', 'label');
});
})
.catch(function(error) {
console.log(error);
});
});
```
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
2016-08-04 18:32:08 +02:00
## Misc
2016-08-04 18:33:25 +02:00
Thanks to [@mikefrancis ](https://github.com/mikefrancis/ ) for [sending me on a hunt ](https://twitter.com/_mikefrancis/status/701797835826667520 ) for a non-jQuery solution for select boxes that eventually led to this being built!