choices.js

What is choices.js?

Choices.js is a lightweight, configurable select box/text input plugin. It allows you to create customizable select boxes, text inputs, and tags input fields with ease. It provides a user-friendly interface for managing selections and input values.

What are choices.js's main functionalities?

Single Select

This feature allows you to create a single select dropdown where users can choose one option from a list. The `searchEnabled` option is set to false to disable the search functionality.

const choices = new Choices('#single-select', { searchEnabled: false });

Multiple Select

This feature allows you to create a multiple select dropdown where users can choose multiple options. The `removeItemButton` option adds a button to each selected item to allow users to remove it.

const choices = new Choices('#multiple-select', { removeItemButton: true });

Text Input

This feature allows you to create a text input field where users can add multiple tags separated by a delimiter. The `delimiter` option specifies the character used to separate tags.

const choices = new Choices('#text-input', { delimiter: ',' });

Predefined Choices

This feature allows you to initialize the select box or text input with predefined choices. The `items` option is used to specify the initial choices.

const choices = new Choices('#predefined-choices', { items: ['Choice 1', 'Choice 2', 'Choice 3'] });

Other packages similar to choices.js

select2

Select2 is a jQuery-based replacement for select boxes. It supports searching, remote data sets, and infinite scrolling of results. Compared to Choices.js, Select2 offers more advanced features like AJAX support and theming but requires jQuery as a dependency.

react-select

React-Select is a flexible and beautiful Select Input control for ReactJS with multiselect, autocomplete, and async support. It is specifically designed for React applications, making it a better choice for React developers compared to Choices.js, which is framework-agnostic.

selectize

Selectize is a jQuery-based hybrid of a textbox and select box. It is useful for tagging, contact lists, country selectors, and more. Selectize offers a rich set of features similar to Choices.js but also includes additional plugins for extended functionality.

README

Choices.js

A lightweight, configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.

Setup

<!-- 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>
<script>
    // Pass multiple elements:
    const choices = new Choices(elements);
    
    // Pass single element:
    const choices = new Choices(element);
    
    // Pass reference
    const choices = new Choices('[data-choice']);
    const choices = new Choices('.js-choice');
    
    // Passing options (with default options)
    const choices = new Choices(elements, {
        items: [],
        maxItemCount: -1,
        addItems: true,
        removeItems: true,
        removeItemButton: false,
        editItems: false,
        duplicateItems: true,
        delimiter: ',',
        paste: true,
        search: true, 
        regexFilter: null,
        placeholder: true,
        placeholderValue: null,
        prependValue: null,
        appendValue: null,
        loadingText: 'Loading...',
        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',
            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',
            loadingState: 'is-loading',
        },
        callbackOnInit: () => {},
        callbackOnAddItem: (id, value, passedInput) => {},
        callbackOnRemoveItem: (id, value, passedInput) => {},
        callbackOnRender: () => {},
    });
</script>

Installation

Coming to NPM soon.

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

Configuration options

items

Type: Default: [] Usage: Add pre-selected items to 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
}]

maxItemCount

Type: Number Default:-1

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

addItems

Type: Boolean Default:true

Usage: Whether a user can add items to the passed input's value.

removeItems

Type: Boolean Default:true

Usage: Whether a user can remove items (only affects text and multiple select input types).

removeButton

Type: Boolean Default:false

Usage: Whether a button should show that, when clicked, will remove an item (only affects text and multiple select input types).

editItems

Type: Boolean Default:false

Usage: Whether a user can edit selected items (only affects text input types).

Usage: Optionally set an item limit (-1 indicates no limit).

delimiter

Type: String Default:,

Usage: What divides each value (only affects text input types).

duplicates

Type: Boolean Default:true

Usage: Whether a user can input a duplicate item (only affects text input types).

paste

Type: Boolean Default:true

Usage: Whether a user can paste into the input.

search

Type: Boolean Default:true

Usage: Whether a user can filter options by searching (only affects select input types).

regexFilter

Type: Regex Default:null

Usage: A filter that will need to pass for a user to successfully add an item (only affects text input types).

placeholder

Type: Boolean Default:true

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

placeholderValue

Type: String Default:null

Usage: The value of the inputs placeholder.

prependValue

Type: String Default:null

Usage: Prepend a value to each item added to input (only affects text input types).

appendValue

Type: String Default:null

Usage: Append a value to each item added to input (only affects text input types).

loadingText

Type: String Default:Loading...

Usage: The loading text that is shown when options are populated via an AJAX callback.

classNames

Type: Object 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',
    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',
    hiddenState: 'is-hidden',
    flippedState: 'is-flipped',
    selectedState: 'is-highlighted',
}

Usage: Classes added to HTML generated by Choices. By default classnames follow the BEM notation.

callbackOnInit

Type: Function Default:() => {}

Usage: Function to run once Choices initialises.

callbackOnAddItem

Type: Function Default:(id, value, passedInput) => {}

Usage: Function to run each time an item is added.

callbackOnRemoveItem

Type: Function Default:(id, value, passedInput) => {}

Usage: Function to run each time an item is removed.

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

highlightAll();

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

unhighlightAll();

Usage: Un-highlight each chosen item.

removeItemsByValue(value);

Usage: Remove each item by a given value.

removeActiveItems(excludedId);

Usage: Remove each selectable item.

removeHighlightedItems();

Usage: Remove each item the user has selected.

showDropdown();

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

hideDropdown();

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

toggleDropdown();

Usage: Toggle dropdown between showing/hidden.

setValue(args);

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

clearValue();

Usage: Clear value of input.

clearInput();

Usage: Clear input of any user inputted text (only affects text inputs).

disable();

Usage: Disable input from selecting further options.

ajax(fn);

Usage: Populate options via a callback.

Browser compatibility

ES5 browsers and above (http://caniuse.com/#feat=es5).

Development

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

npm install

NPM tasks

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

Contributions

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

License

MIT License

Changelog

Bug Fixes (from 11.0.0)

• Fix input text - method setValue didn't work #1207
• Fix tab and esc keys handling #1234 #1209
• Fix Notice for max item limit is removed permanently if you keep typing #1201
• Fix search was not stopped when leaving focus with esc key #1240
• Fix single-select mode disabling search when tab => arrow keys are pressed [#1230]https://github.com/Choices-js/Choices/issues/1230)
• Fix HTML comments were copied from backing <option> and were rendered as text [#1231]https://github.com/Choices-js/Choices/issues/1231)