choices.js
v11.1.0TypeScript
A vanilla JS customisable text input/select box plugin
0/weekUpdated 11 months agoMITUnpacked: 1.9 MB
Published by Josh Johnson
npm install choices.jsChoices.js   
A vanilla, lightweight (~20kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
TL;DR
- Lightweight
- No jQuery dependency
- Configurable sorting
- Flexible styling
- Fast search/filtering
- Clean API
- Right-to-left support
- Custom templates
---
$3
$3
---
Table of Contents
- Installation
- Setup
- Terminology
- Input Types
- Configuration Options
- Callbacks
- Events
- Methods
- Development
- License
Installation
With NPM:
``zsh`
npm install choices.js
With Yarn:
`zsh`
yarn add choices.js
From a CDN:
Note: There is sometimes a delay before the latest version of Choices is reflected on the CDN.
`html
href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/base.min.css"
/>
href="https://cdn.jsdelivr.net/npm/choices.js@9.0.1/public/assets/styles/base.min.css"
/>
href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/choices.min.css"
/>
href="https://cdn.jsdelivr.net/npm/choices.js@9.0.1/public/assets/styles/choices.min.css"
/>
`
Or include Choices directly:
`html`
$3
The use of import of css/scss is supported from webpack.
In .scss:
`scss`
@import "choices.js/src/styles/choices";
In .js/.ts:
`javascript`
import "choices.js/public/assets/styles/choices.css";
Setup
Note: If you pass a selector which targets multiple elements, the first matching element will be used. Versions prior to 8.x.x would return multiple Choices instances.
`js
// Pass single element
const element = document.querySelector('.js-choice');
const choices = new Choices(element);
// Pass reference
const choices = new Choices('[data-trigger]');
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(element, {
silent: false,
items: [],
choices: [],
renderChoiceLimit: -1,
maxItemCount: -1,
closeDropdownOnSelect: 'auto',
singleModeForMultiSelect: false,
addChoices: false,
addItems: true,
addItemFilter: (value) => !!value && value !== '',
removeItems: true,
removeItemButton: false,
removeItemButtonAlignLeft: false,
editItems: false,
allowHTML: false,
allowHtmlUserInput: false,
duplicateItemsAllowed: true,
delimiter: ',',
paste: true,
searchEnabled: true,
searchChoices: true,
searchFloor: 1,
searchResultLimit: 4,
searchFields: ['label', 'value'],
position: 'auto',
resetScrollPosition: true,
shouldSort: true,
shouldSortItems: false,
sorter: () => {...},
shadowRoot: null,
placeholder: true,
placeholderValue: null,
searchPlaceholderValue: null,
prependValue: null,
appendValue: null,
renderSelectedChoices: 'auto',
loadingText: 'Loading...',
noResultsText: 'No results found',
noChoicesText: 'No choices to choose from',
itemSelectText: 'Press to select',
uniqueItemText: 'Only unique values can be added',
customAddItemText: 'Only values matching specific conditions can be added',
addItemText: (value) => {
return Press Enter to add "${value}";Remove item
},
removeItemIconText: () => ,Remove item: ${value}
removeItemLabelText: (value) => ,Only ${maxItemCount} values can be added
maxItemText: (maxItemCount) => {
return ;`
},
valueComparer: (value1, value2) => {
return value1 === value2;
},
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'],
description: ['choices__description'],
placeholder: ['choices__placeholder'],
group: ['choices__group'],
groupHeading: ['choices__heading'],
button: ['choices__button'],
activeState: ['is-active'],
focusState: ['is-focused'],
openState: ['is-open'],
disabledState: ['is-disabled'],
highlightedState: ['is-highlighted'],
selectedState: ['is-selected'],
flippedState: ['is-flipped'],
loadingState: ['is-loading'],
notice: ['choices__notice'],
addChoice: ['choices__item--selectable', 'add-choice'],
noResults: ['has-no-results'],
noChoices: ['has-no-choices'],
},
// Choices uses the great Fuse library for searching. You
// can find more options here: https://fusejs.io/api/options.html
fuseOptions: {
includeScore: true
},
labelId: '',
callbackOnInit: null,
callbackOnCreateTemplates: null,
appendGroupInSearch: false,
});
Terminology
| Word | Definition |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choice | A choice is a value a user can select. A choice would be equivalent 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 equivalent to a selected option element: whereas in the context of a text input an item is equivalent to |
Input Types
Choices works with the following input types, referenced in the documentation as noted.
| HTML Element | Documentation "Input Type" |
| -------------------------------------------------------------------------------------------------------| -------------------------- |
| | text |
|
Configuration Options
$3
Type: Boolean Default: false
Input types affected: text, select-one, select-multiple
Usage: Optionally suppress console errors and warnings.
$3
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,
customProperties: {
random: 'I am a custom property'
}
}]
$3
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,
customProperties: {
description: 'Custom description about Option 2',
random: 'Another random custom property'
},
},
{
label: 'Group 1',
choices: [{
value: 'Option 3',
label: 'Option 4',
selected: true,
disabled: false,
},
{
value: 'Option 2',
label: 'Option 2',
selected: false,
disabled: true,
customProperties: {
description: 'Custom description about Option 2',
random: 'Another random custom property'
}
}]
}]
$3
Type: Number Default: -1
Input types affected: select-one, select-multiple
Usage: The amount of choices to be rendered within the dropdown list ("-1" indicates no limit). This is useful if you have a lot of choices where it is easier for a user to use the search area to find a choice.
$3
Type: Number Default: -1
Input types affected: text, select-multiple
Usage: The amount of items a user can input/select ("-1" indicates no limit).
$3
Type: Boolean | 'auto' Default: auto
Input types affected: select-one, select-multiple
Usage: Control how the dropdown closes after making a selection for select-one or select-multiple.
- 'auto' defaults based on backing-element type:
- select-one: true
- select-multiple: false
$3
Type: Boolean Default: false
Input types affected: select-one, select-multiple
Usage: Make select-multiple with a max item count of 1 work similar to select-one does. Selecting an item will auto-close the dropdown and swap any existing item for the just selected choice. If applied to a select-one, it functions as above and not the standard select-one.
$3
Type: Boolean
Default: falseInput types affected:
, select-oneUsage: Whether a user can add choices dynamically.
Note:
must also be true$3
Type:
Default: trueInput types affected:
Usage: Whether a user can add items.
$3
Type:
Default: trueInput types affected:
, select-multipleUsage: Whether a user can remove items.
$3
Type:
Default: falseInput types affected:
, select-one, select-multipleUsage: Whether each item should have a remove button.
$3
Type:
Default: falseInput types affected:
, select-one, select-multipleUsage: Align item remove button left vs right
$3
Type:
Default: falseInput types affected:
Usage: Whether a user can edit items. An item's value can be edited by pressing the backspace.
$3
Type:
Default: falseInput types affected:
, select-one, select-multipleUsage: Whether HTML should be rendered in all Choices elements. If
, all elements (placeholder, items, etc.) will be treated as plain text. If true, this can be used to perform XSS scripting attacks if you load choices from a remote source.$3
Type:
Boolean Default: falseInput types affected:
, select-one, select-multipleUsage: Whether HTML should be escaped on input when
or addChoices is true. If false, user input will be treated as plain text. If true, this can be used to perform XSS scripting attacks if you load choices from a remote source.$3
Type:
Boolean Default: trueInput types affected:
, select-multiple, select-oneUsage: Whether duplicate inputted/chosen items are allowed
$3
Type:
Default: ,Input types affected:
Usage: What divides each value. The default delimiter separates each value with a comma:
.$3
Type:
Boolean Default: trueInput types affected:
, select-multipleUsage: Whether a user can paste into the input.
$3
Type:
Default: trueInput types affected:
, select-multipleUsage: Whether a search area should be shown.
$3
Type:
Default: trueInput types affected:
Usage: Whether choices should be filtered by input or not. If
, the search event will still emit, but choices will not be filtered.$3
Type:
Array/String Default: ['label', 'value']Input types affected:
, select-multipleUsage: Specify which fields should be used when a user is searching. If you have added custom properties to your choices, you can add these values thus:
.$3
Type:
Number Default: 1Input types affected:
, select-multipleUsage: The minimum length a search value should be before choices are searched.
$3
Type:
Default: 4Input types affected:
, select-multipleUsage: The maximum amount of search results to show ("-1" indicates no limit).
$3
Type: Document Element Default: null
Input types affected:
, select-multipleUsage: You can pass along the shadowRoot from your application like so.
js
var shadowRoot = document
.getElementById('wrapper')
.attachShadow({ mode: 'open' });
...
var el = shadowRoot.querySelector(...);
var choices = new Choices(el, {
shadowRoot: shadowRoot,
});
`$3
Type:
Default: autoInput types affected:
, select-multipleUsage: Whether the dropdown should appear above (
) or below (bottom) the input. By default, if there is not enough space within the window the dropdown will appear above the input, otherwise below it.$3
Type:
Boolean Default: trueInput types affected:
Usage: Whether the scroll position should reset after adding an item.
$3
Type:
Default: nullInput types affected:
Usage: A RegExp or string (will be passed to RegExp constructor internally) or filter function that will need to return
for a user to successfully add an item.Example:
`js
// Only adds items matching the text test
new Choices(element, {
addItemFilter: (value) => {
return ['orange', 'apple', 'banana'].includes(value);
};
});// only items ending to
-red
new Choices(element, {
addItemFilter: '-red$';
});$3
Type:
Default: trueInput types affected:
, select-multipleUsage: Whether choices and groups should be sorted. If false, choices/groups will appear in the order they were given.
$3
Type:
Default: falseInput types affected:
, select-multipleUsage: Whether items should be sorted. If false, items will appear in the order they were selected.
$3
Type:
Default: sortByAlphaInput types affected:
select-one, select-multipleUsage: The function that will sort choices and items before they are displayed (unless a user is searching). By default choices and items are sorted by alphabetical order.
Example:
js
// Sorting via length of label from largest to smallest
const example = new Choices(element, {
sorter: function(a, b) {
return b.label.length - a.label.length;
},
};
`$3
Type:
Default: trueInput types affected:
Usage: Whether the input should show a placeholder. Used in conjunction with
. 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.Note: For select boxes, the recommended way of adding a placeholder is as follows:
`html
`For backward compatibility,
and are also supported.$3
Type:
String Default: nullInput types affected:
Usage: The value of the inputs placeholder.
$3
Type:
Default: nullInput types affected:
Usage: The value of the search inputs placeholder.
$3
Type:
Default: nullInput types affected:
, select-one, select-multipleUsage: Prepend a value to each item added/selected.
$3
Type:
Default: nullInput types affected:
, select-one, select-multipleUsage: Append a value to each item added/selected.
$3
Type:
Default: autoInput types affected:
Usage: Whether selected choices should be removed from the list. By default choices are removed when they are selected in multiple select box. To always render choices pass
.$3
Type:
String Default: Loading...Input types affected:
, select-multipleUsage: The text that is shown whilst choices are being populated via AJAX.
$3
Type:
Default: No results foundInput types affected:
, select-multipleUsage: The text that is shown when a user's search has returned no results. Optionally pass a function returning a string.
$3
Type:
Default: No choices to choose fromInput types affected:
, select-oneUsage: The text that is shown when a user has selected all possible choices, or no choices exist. Optionally pass a function returning a string.
$3
Type:
Default: Press to selectInput types affected:
, select-oneUsage: The text that is shown when a user hovers over a selectable choice. Set to empty to not reserve space for this text.
$3
Type:
Default: Press Enter to add "${value}"Input types affected:
, select-one, select-multipleUsage: The text that is shown when a user has inputted a new item but has not pressed the enter key. To access the current input value, pass a function with a
argument (see the default config for an example), otherwise pass a string.Return type must be safe to insert into HTML (ie use the 1st argument which is sanitised)
$3
Type:
String/Function Default: Remove item"Input types affected:
, select-one, select-multipleUsage: The text/icon for the remove button. To access the item's value, pass a function with a
argument (see the default config [https://github.com/jshjohnson/Choices#setup] for an example), otherwise pass a string.Return type must be safe to insert into HTML (ie use the 1st argument which is sanitised)
$3
Type:
String/Function Default: Remove item: ${value}"Input types affected:
, select-one, select-multipleUsage: The text for the remove button's aria label. To access the item's value, pass a function with a
argument (see the default config [https://github.com/jshjohnson/Choices#setup] for an example), otherwise pass a string.Return type must be safe to insert into HTML (ie use the 1st argument which is sanitised)
$3
Type:
String/Function Default: Only ${maxItemCount} values can be addedInput types affected:
Usage: The text that is shown when a user has focus on the input but has already reached the max item count. To access the max item count, pass a function with a
argument (see the default config for an example), otherwise pass a string.$3
Type:
Function Default: strict equalityInput types affected:
, select-multipleUsage: A custom compare function used when finding choices by value (using
).Example:
`js
const example = new Choices(element, {
valueComparer: (a, b) => value.trim() === b.trim(),
};
`$3
Type:
Default: Input types affected:
, select-multipleUsage: The labelId improves accessibility. If set, it will add aria-labelledby to the choices element.
$3
Type:
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'],
itemChoice: ['choices__item--choice'],
description: ['choices__description'],
placeholder: ['choices__placeholder'],
group: ['choices__group'],
groupHeading: ['choices__heading'],
button: ['choices__button'],
activeState: ['is-active'],
focusState: ['is-focused'],
openState: ['is-open'],
disabledState: ['is-disabled'],
highlightedState: ['is-highlighted'],
selectedState: ['is-selected'],
flippedState: ['is-flipped'],
loadingState: ['is-loading'],
notice: ['choices__notice'],
addChoice: ['choices__item--selectable', 'add-choice'],
noResults: ['has-no-results'],
noChoices: ['has-no-choices'],
}
Input types affected:
, select-one, select-multipleUsage: Classes added to HTML generated by Choices. By default classnames follow the BEM notation.
Callbacks
Note: For each callback,
refers to the current instance of Choices. This can be useful if you need access to methods (this.disable()) or the config object (this.config).$3
Type:
Function Default: nullInput types affected:
, select-one, select-multipleUsage: Function to run once Choices initialises.
$3
Type:
Default: null Arguments: strToEl, escapeForTemplateInput types affected:
, select-one, select-multipleUsage: 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 data attributes defined here.
If you want just extend a little original template then you may use
to get access to
original template function.Templates receive the full Choices config as the first argument to any template, which allows you to conditionally display things based on the options specified.
@note For each callback,
this refers to the current instance of Choices. This can be useful if you need access to methods (this.disable()).Example:
`js
const example = new Choices(element, {
callbackOnCreateTemplates: (strToEl, escapeForTemplate, getClassNames) => ({
input: (...args) =>
Object.assign(Choices.defaults.templates.input.call(this, ...args), {
type: 'email',
}),
}),
});
`or more complex:
js
const example = new Choices(element, {
callbackOnCreateTemplates: function(strToEl, escapeForTemplate, getClassNames) {
return {
item: ({ classNames }, data) => {
return template(data.active ? 'aria-selected="true"' : ''
} ${data.disabled ? 'aria-disabled="true"' : ''}>
★ ${escapeForTemplate(data.label)}
);
},
choice: ({ classNames }, data) => {
return template(data.disabled
? 'data-choice-disabled aria-disabled="true"'
: 'data-choice-selectable'
} data-id="${data.id}" data-value="${escapeForTemplate(data.value)}" ${
data.groupId > 0 ? 'role="treeitem"' : 'role="option"'
}>
★ ${escapeForTemplate(data.label)}
);
},
};
},
});
`Events
Note: Events fired by Choices behave the same as standard events. Each event is triggered on the element passed to Choices (accessible via
. Arguments are accessible within the event.detail object.Example:
`js
const element = document.getElementById('example');
const example = new Choices(element);element.addEventListener(
'addItem',
function(event) {
// do something creative here...
console.log(event.detail.id);
console.log(event.detail.value);
console.log(event.detail.label);
console.log(event.detail.customProperties);
console.log(event.detail.groupValue);
},
false,
);
// or
const example = new Choices(document.getElementById('example'));
example.passedElement.element.addEventListener(
'addItem',
function(event) {
// do something creative here...
console.log(event.detail.id);
console.log(event.detail.value);
console.log(event.detail.label);
console.log(event.detail.customProperties);
console.log(event.detail.groupValue);
},
false,
);
`$3
Payload:
Input types affected:
, select-one, select-multipleUsage: Triggered each time an item is added (programmatically or by the user).
$3
Payload:
Input types affected:
, select-one, select-multipleUsage: Triggered each time an item is removed (programmatically or by the user).
$3
Payload:
Input types affected:
, select-multipleUsage: Triggered each time an item is highlighted.
$3
Payload:
Input types affected:
, select-multipleUsage: Triggered each time an item is unhighlighted.
$3
Payload:
Input types affected:
, select-multipleUsage: Triggered each time a choice is selected by a user, regardless if it changes the value of the input.
is a Choice object here (see terminology or typings file)$3
Payload:
value: stringInput types affected:
, select-one, select-multipleUsage: Triggered each time an item is added/removed by a user.
$3
Payload:
, resultCount: numberInput types affected:
, select-multipleUsage: Triggered when a user types into an input to search choices. When a search is ended, a search event with an empty value with no resultCount is triggered.
$3
Payload: -
Input types affected:
, select-multipleUsage: Triggered when the dropdown is shown.
$3
Payload: -
Input types affected:
, select-multipleUsage: Triggered when the dropdown is hidden.
$3
Payload:
Input types affected:
, select-multipleUsage: Triggered when a choice from the dropdown is highlighted.
The
argument is choices.passedElement object that was affected.Methods
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
const choices = new Choices(element, {
addItems: false,
removeItems: false,
});
choices.setValue(['Set value 1', 'Set value 2']);
choices.disable();
`$3
Input types affected:
, select-multiple, select-oneUsage: Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.
$3
Input types affected:
, select-multiple, select-oneUsage: Creates a new instance of Choices, adds event listeners, creates templates and renders a Choices element to the DOM.
Note: 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
).$3
Input types affected:
select-multiple, select-oneUsage: Reads options from backing