Choices.js

I'm looking for active maintainers for this project as I no longer have the time to support it. Please get in touch if you're interested 👍

A vanilla, lightweight (~19kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.

Demo

TL;DR

• Lightweight
• No jQuery dependency
• Configurable sorting
• Flexible styling
• Fast search/filtering
• Clean API
• Right-to-left support
• Custom templates

Interested in writing your own ES6 JavaScript plugins? Check out ES6.io for great tutorials! 💪🏼

Installation

With NPM:

npm install choices.js

With Yarn:

yarn add choices.js

From a CDN:

Note: There is sometimes a delay before the latest version of Choices is reflected on the CDN.

Or include Choices directly:

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.

  // 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,
    addItems: true,
    addItemFilter: null,
    removeItems: true,
    removeItemButton: false,
    editItems: 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: () => {...},
    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',
    addItemText: (value) => {
      return Press Enter to add <b>"${value}"</b>;
    },
    maxItemText: (maxItemCount) => {
      return Only ${maxItemCount} values can be added;
    },
    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',
      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',
      noResults: 'has-no-results',
      noChoices: 'has-no-choices'
    },
    // Choices uses the great Fuse library for searching. You
    // can find more options here: https://github.com/krisk/Fuse#options
    fuseOptions: {
      include: 'score'
    },
    callbackOnInit: null,
    callbackOnCreateTemplates: null
  });

Terminology

| Word | Definition | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Choice | A choice is a value a user can select. A choice would be equivalent to the

Configuration options

silent

Type:

Boolean

false

Input types affected:

text

select-single

select-multiple

Usage: Optionally suppress console errors and warnings.

items

Type:

Array

[]

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'
  }
}]

choices

Type:

Array

[]

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'
  },
}]

renderChoiceLimit

Type:

Number

-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.

maxItemCount

Type:

Number

-1

Input types affected:

text

select-multiple

Usage: The amount of items a user can input/select ("-1" indicates no limit).

addItems

Type:

Boolean

true

Input types affected:

text

Usage: Whether a user can add items.

removeItems

Type:

Boolean

true

Input types affected:

text

select-multiple

Usage: Whether a user can remove items.

removeItemButton

Type:

Boolean

false

Input types affected:

text

select-one

select-multiple

Usage: Whether each item should have a remove button.

editItems

Type:

Boolean

false

Input types affected:

text

Usage: Whether a user can edit items. An item's value can be edited by pressing the backspace.

duplicateItemsAllowed

Type:

Boolean

true

Input types affected:

text

select-multiple

Usage: Whether duplicate inputted/chosen items are allowed

delimiter

Type:

String

,

Input types affected:

text

Usage: What divides each value. The default delimiter separates each value with a comma:

"Value 1, Value 2, Value 3"

paste

Type:

Boolean

true

Input types affected:

text

select-multiple

Usage: Whether a user can paste into the input.

searchEnabled

Type:

Boolean

true

Input types affected:

select-one

Usage: Whether a search area should be shown. Note: Multiple select boxes will always show search areas.

searchChoices

Type:

Boolean

true

Input types affected:

select-one

Usage: Whether choices should be filtered by input or not. If

false

searchFields

Type:

Array/String

['label', 'value']

Input types affected:

select-one

select-multiple

Usage: 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:

['label', 'value', 'customProperties.example']

searchFloor

Type:

Number

1

Input types affected:

select-one

select-multiple

Usage: The minimum length a search value should be before choices are searched.

searchResultLimit: 4,

Type:

Number

4

Input types affected:

select-one

select-multiple

Usage: The maximum amount of search results to show.

position

Type:

String

auto

Input types affected:

select-one

select-multiple

Usage: Whether the dropdown should appear above (

top

bottom

resetScrollPosition

Type:

Boolean

true

Input types affected:

select-multiple

Usage: Whether the scroll position should reset after adding an item.

addItemFilter

Type:

string | RegExp | Function

null

Input types affected:

text

Usage: A RegExp or string (will be passed to RegExp constructor internally) or filter function that will need to return

true

Example:

// 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$';
});

shouldSort

Type:

Boolean

true

Input types affected:

select-one

select-multiple

Usage: Whether choices and groups should be sorted. If false, choices/groups will appear in the order they were given.

shouldSortItems

Type:

Boolean

false

Input types affected:

text

select-multiple

Usage: Whether items should be sorted. If false, items will appear in the order they were selected.

sorter

Type:

Function

Input types affected:

select-one

select-multiple

Usage: 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:

// 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;
  },
};

placeholder

Type:

Boolean

true

Input types affected:

text

Usage: Whether the input should show a placeholder. Used in conjunction with

placeholderValue

placeholder

placeholderValue

Note: For select boxes, the recommended way of adding a placeholder is as follows:

  This is a placeholder
  ...
  ...
  ...

For backward compatibility,

This is a placeholder

placeholderValue

Type:

String

null

Input types affected:

text

Usage: The value of the inputs placeholder.

searchPlaceholderValue

Type:

String

null

Input types affected:

select-one

Usage: The value of the search inputs placeholder.

prependValue

Type:

String

null

Input types affected:

text

select-one

select-multiple

Usage: Prepend a value to each item added/selected.

appendValue

Type:

String

null

Input types affected:

text

select-one

select-multiple

Usage: Append a value to each item added/selected.

renderSelectedChoices

Type:

String

auto

Input types affected:

select-multiple

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

always

loadingText

Type:

String

Loading...

Input types affected:

select-one

select-multiple

Usage: The text that is shown whilst choices are being populated via AJAX.

noResultsText

Type:

String/Function

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. Optionally pass a function returning a string.

noChoicesText

Type:

String/Function

No choices to choose from

Input types affected:

select-multiple

Usage: The text that is shown when a user has selected all possible choices. Optionally pass a function returning a string.

itemSelectText

Type:

String

Press to select

Input types affected:

select-multiple

select-one

Usage: The text that is shown when a user hovers over a selectable choice.

addItemText

Type:

String/Function

Press Enter to add "${value}"

Input types affected:

text

Usage: 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

value

maxItemText

Type:

String/Function

Only ${maxItemCount} values can be added

Input types affected:

text

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

maxItemCount

valueComparer

Type:

Function

strict equality

Input types affected:

select-one

select-multiple

Usage: A custom compare function used when finding choices by value (using

setChoiceByValue

Example:

const example = new Choices(element, {
  valueComparer: (a, b) => value.trim() === b.trim(),
};

classNames

Type:

Object

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',
  selectedState: 'is-selected',
  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.

Callbacks

Note: For each callback,

this

this.disable()

this.config

callbackOnInit

Type:

Function

null

Input types affected:

text

select-one

select-multiple

Usage: Function to run once Choices initialises.

callbackOnCreateTemplates

Type:

Function

null

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 data attributes defined here. If you want just extend a little original template then you may use

Choices.defaults.templates

Example:

const example = new Choices(element, {
  callbackOnCreateTemplates: () => ({
    input: (...args) =>
      Object.assign(Choices.defaults.templates.input.call(this, ...args), {
        type: 'email',
      }),
  }),
});

or more complex:

const example = new Choices(element, {
  callbackOnCreateTemplates: function(template) {
    return {
      item: (classNames, data) => {
        return template(`
          

            ★ ${data.label}
          
        `);
      },
      choice: (classNames, data) => {
        return template(`
          
 0 ? 'role="treeitem"' : 'role="option"'
        }>
            ★ ${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

this.passedElement

event.detail

Example:

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,
);

addItem

Payload:

id, value, label, customProperties, groupValue, keyCode

Input types affected:

text

select-one

select-multiple

Usage: Triggered each time an item is added (programmatically or by the user).

removeItem

Payload:

id, value, label, customProperties, groupValue

Input types affected:

text

select-one

select-multiple

Usage: Triggered each time an item is removed (programmatically or by the user).

highlightItem

Payload:

id, value, label, groupValue

Input types affected:

text

select-multiple

Usage: Triggered each time an item is highlighted.

unhighlightItem

Payload:

id, value, label, groupValue

Input types affected:

text

select-multiple

Usage: Triggered each time an item is unhighlighted.

choice

Payload:

choice

Input types affected:

select-one

select-multiple

Usage: Triggered each time a choice is selected by a user, regardless if it changes the value of the input.

choice

change

Payload:

value

Input types affected:

text

select-one

select-multiple

Usage: Triggered each time an item is added/removed by a user.

search

Payload:

value

resultCount

Input types affected:

select-one

select-multiple

Usage: Triggered when a user types into an input to search choices.

showDropdown

Payload: -

Input types affected:

select-one

select-multiple

Usage: Triggered when the dropdown is shown.

hideDropdown

Payload: -

Input types affected:

select-one

select-multiple

Usage: Triggered when the dropdown is hidden.

highlightChoice

Payload:

el

Input types affected:

select-one

select-multiple

Usage: Triggered when a choice from the dropdown is highlighted. The

el

Methods

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();

destroy();

Input types affected:

text

select-multiple

select-one

Usage: Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.

init();

Input types affected:

text

select-multiple

select-one

Usage: 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

destroy()

highlightAll();

Input types affected:

text

select-multiple

Usage: Highlight each chosen item (selected items can be removed).

unhighlightAll();

Input types affected:

text

select-multiple

Usage: Un-highlight each chosen item.

removeActiveItemsByValue(value);

Input types affected:

text

select-multiple

Usage: Remove each item by a given value.

removeActiveItems(excludedId);

Input types affected:

text

select-multiple

Usage: Remove each selectable item.

removeHighlightedItems();

Input types affected:

text

select-multiple

Usage: Remove each item the user has selected.

showDropdown();

Input types affected:

select-one

select-multiple

Usage: Show option list dropdown (only affects select inputs).

hideDropdown();

Input types affected:

text

select-multiple

Usage: Hide option list dropdown (only affects select inputs).

setChoices(choices, value, label, replaceChoices);

Input types affected:

select-one

select-multiple

Usage: Set choices of select input via an array of objects (or function that returns array of object or promise of it), a value field name and a label field name.

This behaves the similar as passing items via the

choices

replaceChoices

customProperties

replaceChoices

clearChoices

Example 1:

const example = new Choices(element);

example.setChoices(
  [
    { value: 'One', label: 'Label One', disabled: true },
    { value: 'Two', label: 'Label Two', selected: true },
    { value: 'Three', label: 'Label Three' },
  ],
  'value',
  'label',
  false,
);

Example 2:

const example = new Choices(element);

// Passing a function that returns Promise of choices
example.setChoices(async () => {
  try {
    const items = await fetch('/items');
    return items.json();
  } catch (err) {
    console.error(err);
  }
});

Example 3:

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',
          customProperties: {
            description: 'Custom description about child six',
            random: 'Another random custom property',
          },
        },
      ],
    },
  ],
  'value',
  'label',
  false,
);

clearChoices();

Input types affected:

select-one

select-multiple

Usage: Clear all choices from select

getValue(valueOnly)

Input types affected:

text

select-one

select-multiple

Usage: Get value(s) of input (i.e. inputted items (text) or selected choices (select)). Optionally pass an argument of

true

Example:

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'}];

setValue(items);

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

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']);

setChoiceByValue(value);

Input types affected:

select-one

select-multiple

Usage: Set value of input based on existing Choice.

value

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.setChoiceByValue('Two'); // Choice with value of 'Two' has now been selected.

clearStore();

Input types affected:

text

select-one

select-multiple

Usage: Removes all items, choices and groups. Use with caution.

clearInput();

Input types affected:

text

Usage: Clear input of any user inputted text.

disable();

Input types affected:

text

select-one

select-multiple

Usage: Disables input from accepting new value/selecting further choices.

enable();

Input types affected:

text

select-one

select-multiple

Usage: Enables input to accept new values/select further choices.

Browser compatibility

Choices is compiled using Babel targeting browsers with more than 1% of global usage and expecting that features listed below are available or polyfilled in browser. You may see exact list of target browsers by running

npx browserslist

Polyfill example used for the demo:

Features used in Choices:

Array.from
Array.prototype.find
Array.prototype.includes
Symbol
Symbol.iterator
DOMTokenList
Object.assign
CustomEvent
Element.prototype.classList
Element.prototype.closest
Element.prototype.dataset

Development

To setup a local environment: clone this repo, navigate into its directory in a terminal window and run the following command:

npm install

NPM tasks

| Task | Usage | | ------------------------- | ------------------------------------------------------------ | |

npm run start

npm run test:unit

npm run test:unit:watch

npm run test:e2e

npm run test

npm run cypress:open

npm run cypress:run

npm run js:build

npm run css:watch

npm run css:build

License

MIT License

Web component

Want to use Choices as a web component? You're in luck. Adidas have built one for their design system which can be found here.

Misc

Thanks to @mikefrancis for sending me on a hunt for a non-jQuery solution for select boxes that eventually led to this being built!