Choices.js

A vanilla, lightweight (~20kb 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! 💪🏼

Sponsored by:

---

Table of Contents

• Installation
• Setup
• Terminology
• Input Types
• Configuration Options
• Callbacks
• Events
• Methods
• CSS custom properties
• Development
• License

Installation

With NPM:

npm install choices.js

With Yarn:

yarn add choices.js

From a CDN:

Notes: * There is sometimes a delay before the latest version of Choices is reflected on the CDN. * Examples below pin a version (v11.1.0). Check latest release and update v11.1.0 to the latest tag before using.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/base.min.css"
/>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js@11.1.0/public/assets/styles/base.min.css"
/>


<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js/public/assets/styles/choices.min.css"
/>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/choices.js@11.1.0/public/assets/styles/choices.min.css"
/>


<script src="https://cdn.jsdelivr.net/npm/choices.js/public/assets/scripts/choices.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/choices.js@11.1.0/public/assets/scripts/choices.min.js"></script>

Or include Choices directly:

<link rel="stylesheet" href="https://github.com/Choices-js/Choices/raw/v11.2.3/public/assets/styles/base.min.css" />

<link rel="stylesheet" href="https://github.com/Choices-js/Choices/raw/v11.2.3/public/assets/styles/choices.min.css" />

<script src="https://github.com/Choices-js/Choices/raw/v11.2.3/public/assets/scripts/choices.min.js"></script>

CSS/SCSS

The use of import of css/scss is supported from webpack.

In .scss:

@import "choices.js/src/styles/choices";

In .js/.ts:

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.

  // 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,
    searchDisabledChoices: false,
    searchFloor: 1,
    searchResultLimit: 4,
    searchFields: ['label', 'value'],
    position: 'auto',
    resetScrollPosition: true,
    shouldSort: true,
    shouldSortItems: false,
    sorter: (a, b) => sortByAlpha,
    shadowRoot: null,
    placeholder: true,
    placeholderValue: null,
    searchPlaceholderValue: null,
    prependValue: null,
    appendValue: null,
    renderSelectedChoices: 'auto',
    searchRenderSelectedChoices: true,
    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, rawValue) => {
      return `Press Enter to add <b>"${value}"</b>`;
    },
    removeItemIconText: () => `Remove item`,
    removeItemLabelText: (value, rawValue) => `Remove item: ${value}`,
    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'],
      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'],
      invalidState: ['is-invalid'],
      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 <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 equivalent to a selected option element: <option value="Hello" selected></option> whereas in the context of a text input an item is equivalent to <input type="text" value="Hello">

Input Types

Choices works with the following input types, referenced in the documentation as noted.

HTML Element	Documentation "Input Type"
<input type="text">	text
<select>	select-one
<select multiple>	select-multiple

Configuration Options

silent

Type: Boolean Default: false

Input types affected: text, select-one, select-multiple

Usage: Optionally suppress console errors and warnings.

items

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

choices

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

renderChoiceLimit

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.

maxItemCount

Type: Number Default: -1

Input types affected: text, select-multiple

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

closeDropdownOnSelect

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

singleModeForMultiSelect

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.

addChoices

Type: Boolean Default: false

Input types affected: select-multiple, select-one

Usage: Whether a user can add choices dynamically.

Note: addItems must also be true

addItems

Type: Boolean Default: true

Input types affected: text

Usage: Whether a user can add items.

removeItems

Type: Boolean Default: true

Input types affected: text, select-multiple

Usage: Whether a user can remove items.

removeItemButton

Type: Boolean Default: false

Input types affected: text, select-one, select-multiple

Usage: Whether each item should have a remove button.

removeItemButtonAlignLeft

Type: Boolean Default: false

Input types affected: text, select-one, select-multiple

Usage: Align item remove button left vs right

editItems

Type: Boolean Default: false

Input types affected: text

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

allowHTML

Type: Boolean Default: false

Input types affected: text, select-one, select-multiple

Usage: Whether H