![Oracle Drags Its Feet in the JavaScript Trademark Dispute](https://cdn.sanity.io/images/cgdhsj6q/production/919c3b22c24f93884c548d60cbb338e819ff2435-1024x1024.webp?w=400&fit=max&auto=format)
Security News
Oracle Drags Its Feet in the JavaScript Trademark Dispute
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
choices.js
Advanced tools
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.
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'] });
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 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 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.
A vanilla, lightweight (~15kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
<!-- 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');
// Pass jQuery element
const choices = new Choices($('.js-choice')[0]);
// Passing options (with default options)
const choices = new Choices(elements, {
items: [],
choices: [],
maxItemCount: -1,
addItems: true,
removeItems: true,
removeItemButton: false,
editItems: false,
duplicateItems: true,
delimiter: ',',
paste: true,
search: true,
flip: true,
regexFilter: null,
sortFilter: sortByAlpha,
sortFields: ['label', 'value'],
placeholder: true,
placeholderValue: null,
prependValue: null,
appendValue: null,
loadingText: 'Loading...',
noResultsText: 'No results round',
noChoicesText: 'No choices to choose from',
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) => {},
callbackOnHighlightItem: (id, value, passedInput) => {},
callbackOnUnhighlightItem: (id, value, passedInput) => {},
callbackOnChange: (value, passedInput) => {},
});
</script>
npm install choices.js --save
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"> |
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
}]
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,
}]
Type: Number
Default: -1
Input types affected: text
, select-multiple
Usage: The amount of items a user can input/select ("-1" indicates no limit).
Type: Boolean
Default: true
Input types affected: text
Usage: Whether a user can add items to the passed input's value.
Type: Boolean
Default: true
Input types affected: text
, select-multiple
Usage: Whether a user can remove items.
Type: Boolean
Default: false
Input types affected: text
, select-multiple
Usage: Whether a button should show that, when clicked, will remove an item.
Type: Boolean
Default: false
Input types affected: text
Usage: Whether a user can edit items. An items value can be edited by pressing the backspace.
Type: Boolean
Default: true
Input types affected: text
, select-multiple
Usage: Whether a user can input/choose a duplicate item.
Type: String
Default: ,
Input types affected: text
Usage: What divides each value. By default the delimited value would be "Value 1, Value 2, Value 3"
.
Type: Boolean
Default: true
Input types affected: text
, select-multiple
Usage: Whether a user can paste into the input.
Type: Boolean
Default: true
Input types affected: text
, select-one
, select-multiple
Usage: Whether a search input should display allowing a user to filter choices.
Type: Boolean
Default: true
Input types affected: select-one
, select-multiple
Usage: Whether the dropdown should appear above the input if there is not enough space within the window.
Type: Regex
Default: null
Input types affected: text
Usage: A filter that will need to pass for a user to successfully add an item.
Type: Function
Default: sortByAlpha
Input types affected: select-one
, select-multiple
Usage: The function that will sort choices before they are displayed (unless a user is searching). By default choices are sorted by alphabetical order.
Example:
// 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;
},
};
Type: Array/String
Default: ['label', 'value']
Input types affected:select-one
, select-multiple
Usage: Specify which fields should be used for sorting.
Type: Boolean
Default: true
Input types affected: text
, select-one
, select-multiple
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.
Type: String
Default: null
Input types affected: text
, select-one
, select-multiple
Usage: The value of the inputs placeholder.
Type: String
Default: null
Input types affected: text
, select-one
, select-multiple
Usage: Prepend a value to each item added/selected.
Type: String
Default: null
Input types affected: text
, select-one
, select-multiple
Usage: Append a value to each item added/selected.
Type: String
Default: Loading...
Input types affected: select-one
, select-multiple
Usage: The text that is shown whilst choices are being populated via AJAX.
Type: String
Default: No results round
Input types affected: select-one
, select-multiple
Usage: The text that is shown when a user's search has returned no results.
Type: String
Default: No choices to choose from
Input types affected: select-multiple
Usage: The text that is shown when a user has selected all possible choices.
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',
}
Input types affected: text
, select-one
, select-multiple
Usage: Classes added to HTML generated by Choices. By default classnames follow the BEM notation.
Type: Function
Default: () => {}
Input types affected: text
, select-one
, select-multiple
Usage: Function to run once Choices initialises.
Type: Function
Default: (id, value, passedInput) => {}
Input types affected: text
, select-one
, select-multiple
Usage: Function to run each time an item is added (programmatically or by the user).
Type: Function
Default: (id, value, passedInput) => {}
Input types affected: text
, select-one
, select-multiple
Usage: Function to run each time an item is removed (programmatically or by the user).
Type: Function
Default: (id, value, passedInput) => {}
Input types affected: text
, select-multiple
Usage: Function to run each time an item is highlighted.
Type: Function
Default: (id, value, passedInput) => {}
Input types affected: text
, select-multiple
Usage: Function to run each time an item is unhighlighted.
Type: Function
Default: (value, passedInput) => {}
Input types affected: text
, select-one
, select-multiple
Usage: Function to run each time an item is added/removed by a user.
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();
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.
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()
).
Input types affected: text
, select-multiple
Usage: Highlight each chosen item (selected items can be removed).
Input types affected: text
, select-multiple
Usage: Un-highlight each chosen item.
Input types affected: text
, select-multiple
Usage: Remove each item by a given value.
Input types affected: text
, select-multiple
Usage: Remove each selectable item.
Input types affected: text
, select-multiple
Usage: Remove each item the user has selected.
Input types affected: select-one
, select-multiple
Usage: Show option list dropdown (only affects select inputs).
Input types affected: text
, select-multiple
Usage: Hide option list dropdown (only affects select inputs).
Input types affected: text
, select-multiple
Usage: Toggle dropdown between showing/hidden.
Input types affected: select-one
, select-multiple
Usage: 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);
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');
Example 2:
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');
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
to only return values rather than value objects.
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'}];
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
option but can be called after initialising Choices.
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']);
Input types affected: select-one
, select-multiple
Usage: Set value of input based on existing Choice.
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.setValueByChoice('Two'); // Choice with value of 'Two' has now been selected.
Input types affected: text
, select-one
, select-multiple
Usage: Removes all items, choices and groups. Use with caution.
Input types affected: text
Usage: Clear input of any user inputted text.
Input types affected: text
, select-one
, select-multiple
Usage: Disables input from accepting new value/sselecting further choices.
Input types affected: text
, select-one
, select-multiple
Usage: Enables input to accept new values/select further choices.
Input types affected: select-one
, select-multiple
Usage: Populate options via a callback.
Example:
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);
});
});
ES5 browsers and above (http://caniuse.com/#feat=es5).
To setup a local environment: clone this repo, navigate into it's directory in a terminal window and run the following command:
npm install
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 |
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
MIT License
Thanks to @mikefrancis for sending me on a hunt for a non-jQuery solution for select boxes that eventually led to this being built!
FAQs
A vanilla JS customisable text input/select box plugin
The npm package choices.js receives a total of 0 weekly downloads. As such, choices.js popularity was classified as not popular.
We found that choices.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.
Security News
Maven Central now validates Sigstore signatures, making it easier for developers to verify the provenance of Java packages.