assets | ||
.babelrc | ||
.eslintrc | ||
.gitignore | ||
index.html | ||
LICENSE | ||
package.json | ||
README.md | ||
server.js | ||
webpack.config.dev.js | ||
webpack.config.prod.js |
Choices.js - beta
A lightweight, configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
Coming soon.
Setup
<script src="/assets/js/dist/choices.min.js"></script>
<script>
// Pass multiple elements:
var choices = new Choices(elements);
// Pass single element:
var choice = new Choices(element);
// Pass reference
var choice = new Choices('[data-choice']);
var choice = new Choices('.js-choice');
// Passing options (with default options)
var choices = new Choices(elements, {
items: [],
maxItemCount: -1,
addItems: true,
removeItems: true,
removeItemButton: false,
editItems: false,
duplicateItems: true,
delimiter: ',',
paste: true,
searchOptions: true,
regexFilter: null,
placeholder: true,
placeholderValue: null,
prependValue: null,
appendValue: null,
loadingText: 'Loading...',
templates: {},
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-selected',
},
callbackOnInit: () => {},
callbackOnAddItem: (id, value, passedInput) => {},
callbackOnRemoveItem: (id, value, passedInput) => {},
});
</script>
Installation
To install via NPM, run npm install --save-dev choices.js
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 (if you are using Choices with a text input) or a selected choice (if you are using Choices with a select element). |
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).
allowDuplicates
Type: Boolean
Default:true
Usage: Whether a user can input a duplicate item (only affects text input types).
allowPaste
Type: Boolean
Default:true
Usage: Whether a user can paste into the input.
allowSearch
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).
highlightAll
Type: Boolean
Default:true
Usage: Whether a user can highlight items.
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-selected',
}
Usage: Classes added to HTML generated by Choices.
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
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.
removeSelectedItems();
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