`);
},
choice: (classNames, data) => {
return template(`
-
0 ? 'role="treeitem"' : 'role="option"'}>
+
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`. Arguments are accessible within the `event.detail` object.
**Example:**
@@ -577,29 +647,38 @@ const example = new Choices(element, {
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);
+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);
+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
+
**Arguments:** `id, value, label, groupValue, keyCode`
**Input types affected:** `text`, `select-one`, `select-multiple`
@@ -607,6 +686,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered each time an item is added (programmatically or by the user).
### removeItem
+
**Arguments:** `id, value, label, groupValue`
**Input types affected:** `text`, `select-one`, `select-multiple`
@@ -614,6 +694,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered each time an item is removed (programmatically or by the user).
### highlightItem
+
**Arguments:** `id, value, label, groupValue`
**Input types affected:** `text`, `select-multiple`
@@ -621,6 +702,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered each time an item is highlighted.
### unhighlightItem
+
**Arguments:** `id, value, label, groupValue`
**Input types affected:** `text`, `select-multiple`
@@ -628,13 +710,16 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered each time an item is unhighlighted.
### choice
-**Arguments:** `value, keyCode`
+
+**Arguments:** `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` is a Choice object here (see terminology or typings file)
### change
+
**Arguments:** `value`
**Input types affected:** `text`, `select-one`, `select-multiple`
@@ -642,6 +727,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered each time an item is added/removed **by a user**.
### search
+
**Arguments:** `value`, `resultCount`
**Input types affected:** `select-one`, `select-multiple`
@@ -649,6 +735,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered when a user types into an input to search choices.
### showDropdown
+
**Arguments:** -
**Input types affected:** `select-one`, `select-multiple`
@@ -656,6 +743,7 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered when the dropdown is shown.
### hideDropdown
+
**Arguments:** -
**Input types affected:** `select-one`, `select-multiple`
@@ -663,21 +751,24 @@ example.passedElement.element.addEventListener('addItem', function(event) {
**Usage:** Triggered when the dropdown is hidden.
### highlightChoice
+
**Arguments:** `el`
**Input types affected:** `select-one`, `select-multiple`
-**Usage:** Triggered when a choice from the dropdown is highlighted. The `el` argument is the HTML element node object that was affected.
+**Usage:** Triggered when a choice from the dropdown is highlighted.
+The `el` argument is choices.passedElement object that was affected.
## Methods
+
Methods can be called either directly or by chaining:
```js
// Calling a method by chaining
const choices = new Choices(element, {
- addItems: false,
- removeItems: false,
- })
+ addItems: false,
+ removeItems: false,
+})
.setValue(['Set value 1', 'Set value 2'])
.disable();
@@ -687,16 +778,18 @@ const choices = new Choices(element, {
removeItems: false,
});
-choices.setValue(['Set value 1', 'Set value 2'])
+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.
@@ -704,47 +797,49 @@ choices.disable();
**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, 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); Optionally pass a true `replaceChoices` value to remove any existing choices. Optionally pass a `customProperties` object to add additional data to your choices (useful when searching/filtering etc). Passing an empty array as the first parameter, and a true `replaceChoices` is the same as calling `clearChoices` (see below).
@@ -754,11 +849,16 @@ choices.disable();
```js
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.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:**
@@ -766,37 +866,50 @@ example.setChoices([
```js
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);
+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` to only return values rather than value objects.
@@ -810,6 +923,7 @@ const valueArray = example.getValue(); // returns [{ active: true, choiceId: 1,
```
### 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` option but can be called after initialising Choices.
@@ -821,16 +935,17 @@ 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'},
+ { 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']);
+example.setValue(['Four', 'Five', 'Six']);
```
### setChoiceByValue(value);
+
**Input types affected:** `select-one`, `select-multiple`
**Usage:** Set value of input based on existing Choice. `value` can be either a single string or an array of strings
@@ -840,9 +955,9 @@ example.setValue(['Four','Five','Six']);
```js
const example = new Choices(element, {
choices: [
- {value: 'One', label: 'Label One'},
- {value: 'Two', label: 'Label Two', disabled: true},
- {value: 'Three', label: 'Label Three'},
+ { value: 'One', label: 'Label One' },
+ { value: 'Two', label: 'Label Two', disabled: true },
+ { value: 'Three', label: 'Label Three' },
],
});
@@ -850,29 +965,31 @@ example.setChoiceByValue('Two'); // Choice with value of 'Two' has now been sele
```
### 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.
-
### ajax(fn);
+
**Input types affected:** `select-one`, `select-multiple`
**Usage:** Populate choices/groups via a callback.
@@ -899,7 +1016,7 @@ example.ajax(function(callback) {
If your structure differs from `data.value` and `data.key` structure you can write your own `key` and `value` into the `callback` function. This could be useful when you don't want to transform the given response.
```js
-const example = new Choices(element)
+const example = new Choices(element);
example.ajax(function(callback) {
fetch(url)
@@ -915,6 +1032,7 @@ example.ajax(function(callback) {
```
## Browser compatibility
+
Choices is compiled using [Babel](https://babeljs.io/) to enable support for [ES5 browsers](http://caniuse.com/#feat=es5). If you need to support a browser that does not support one of the features listed below, I suggest including a polyfill from the very good [polyfill.io](https://cdn.polyfill.io/v2/docs/):
**Polyfill example used for the demo:**
@@ -925,25 +1043,27 @@ Choices is compiled using [Babel](https://babeljs.io/) to enable support for [ES
**Features used in Choices:**
-* Array.prototype.forEach
-* Array.prototype.map
-* Array.prototype.find
-* Array.prototype.some
-* Array.prototype.includes
-* Array.from
-* Array.prototype.reduce
-* Array.prototype.indexOf
-* Object.assign
-* Element.prototype.classList
-* window.requestAnimationFrame
-* CustomEvent
+- Array.prototype.forEach
+- Array.prototype.map
+- Array.prototype.find
+- Array.prototype.some
+- Array.prototype.includes
+- Array.from
+- Array.prototype.reduce
+- Array.prototype.indexOf
+- Object.assign
+- Element.prototype.classList
+- window.requestAnimationFrame
+- CustomEvent
## 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 install`
### NPM tasks
+
| Task | Usage |
| ------------------------- | ------------------------------------------------------------ |
| `npm run start` | Fire up local server for development |
@@ -958,10 +1078,13 @@ To setup a local environment: clone this repo, navigate into it's directory in a
| `npm run css:build` | Compile, minify and prefix SCSS files to CSS |
## 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](https://github.com/adidas/choicesjs-stencil).
## Misc
+
Thanks to [@mikefrancis](https://github.com/mikefrancis/) for [sending me on a hunt](https://twitter.com/_mikefrancis/status/701797835826667520) for a non-jQuery solution for select boxes that eventually led to this being built!
diff --git a/types/index.d.ts b/types/index.d.ts
index 73923df..6afa1eb 100644
--- a/types/index.d.ts
+++ b/types/index.d.ts
@@ -13,7 +13,7 @@ import { FuseOptions } from 'fuse.js';
declare namespace Choices {
namespace Types {
type strToEl = (
- str: string
+ str: string,
) => HTMLElement | HTMLInputElement | HTMLOptionElement;
type stringFunction = () => string;
type noticeStringFunction = (value: string) => string;
@@ -99,9 +99,9 @@ declare namespace Choices {
*
* **Input types affected:** select-one, select-multiple
*
- * Arguments: value, keyCode
+ * Arguments: choice: Choice
*/
- choice: CustomEvent<{ value: string; keyCode: string }>;
+ choice: CustomEvent<{ choice: Choices.Choice }>;
/**
* Triggered each time an item is added/removed **by a user**.
@@ -143,9 +143,9 @@ declare namespace Choices {
* Triggered when a choice from the dropdown is highlighted.
*
* Input types affected: select-one, select-multiple
- * Arguments: el is the HTML element node object that was affected.
+ * Arguments: el is the choice.passedElement that was affected.
*/
- highlightChoice: CustomEvent<{ el: HTMLOptionElement }>;
+ highlightChoice: CustomEvent<{ el: Choices.passedElement }>;
}
interface Group {
@@ -168,52 +168,52 @@ declare namespace Choices {
isSelectElement: boolean,
isSelectOneElement: boolean,
searchEnabled: boolean,
- passedElementType: passedElement['type']
+ passedElementType: passedElement['type'],
) => HTMLElement;
containerInner: (this: Choices, classNames: ClassNames) => HTMLElement;
itemList: (
this: Choices,
classNames: ClassNames,
- isSelectOneElement: boolean
+ isSelectOneElement: boolean,
) => HTMLElement;
placeholder: (
this: Choices,
classNames: ClassNames,
- value: string
+ value: string,
) => HTMLElement;
item: (
this: Choices,
classNames: ClassNames,
data: Choice,
- removeItemButton: boolean
+ removeItemButton: boolean,
) => HTMLElement;
choiceList: (
this: Choices,
classNames: ClassNames,
- isSelectOneElement: boolean
+ isSelectOneElement: boolean,
) => HTMLElement;
choiceGroup: (
this: Choices,
classNames: ClassNames,
- data: Choice
+ data: Choice,
) => HTMLElement;
choice: (
this: Choices,
classNames: ClassNames,
data: Choice,
- selectText: string
+ selectText: string,
) => HTMLElement;
input: (
this: Choices,
classNames: ClassNames,
- placeholderValue: string
+ placeholderValue: string,
) => HTMLInputElement;
dropdown: (this: Choices, classNames: ClassNames) => HTMLElement;
notice: (
this: Choices,
classNames: ClassNames,
label: string,
- type: '' | 'no-results' | 'no-choices'
+ type: '' | 'no-results' | 'no-choices',
) => HTMLElement;
option: (data: Choice) => HTMLOptionElement;
}
@@ -280,9 +280,9 @@ declare namespace Choices {
type: K,
listener: (
this: HTMLInputElement | HTMLSelectElement,
- ev: Choices.EventMap[K]
+ ev: Choices.EventMap[K],
) => void,
- options?: boolean | AddEventListenerOptions
+ options?: boolean | AddEventListenerOptions,
): void;
};
type: 'text' | 'select-one' | 'select-multiple';
@@ -750,7 +750,7 @@ declare namespace Choices {
* @default null
*/
callbackOnCreateTemplates: (
- template: Choices.Types.strToEl
+ template: Choices.Types.strToEl,
) => Partial
;
}
}
@@ -769,7 +769,7 @@ export default class Choices {
constructor(
selectorOrElement: string | HTMLInputElement | HTMLSelectElement,
- userConfig?: Partial
+ userConfig?: Partial,
);
/**
@@ -942,7 +942,7 @@ export default class Choices {
choices: Choices.Choice[],
value: string,
label: string,
- replaceChoices?: boolean
+ replaceChoices?: boolean,
): this;
/**