mirror of
https://github.com/Choices-js/Choices.git
synced 2024-06-08 00:42:15 +02:00
parent
dbd15d7823
commit
64407174e3
335
README.md
335
README.md
|
@ -1,29 +1,36 @@
|
||||||
# Choices.js [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Unit%20Tests/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![npm](https://img.shields.io/npm/v/choices.js.svg)](https://www.npmjs.com/package/choices.js) [![codebeat badge](https://codebeat.co/badges/55120150-5866-42d8-8010-6aaaff5d3fa1)](https://codebeat.co/projects/github-com-jshjohnson-choices-master)
|
# Choices.js [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Unit%20Tests/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![npm](https://img.shields.io/npm/v/choices.js.svg)](https://www.npmjs.com/package/choices.js) [![codebeat badge](https://codebeat.co/badges/55120150-5866-42d8-8010-6aaaff5d3fa1)](https://codebeat.co/projects/github-com-jshjohnson-choices-master)
|
||||||
|
|
||||||
A vanilla, lightweight (~19kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
|
A vanilla, lightweight (~19kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
|
||||||
|
|
||||||
[Demo](https://joshuajohnson.co.uk/Choices/)
|
[Demo](https://joshuajohnson.co.uk/Choices/)
|
||||||
|
|
||||||
## TL;DR
|
## TL;DR
|
||||||
* Lightweight
|
|
||||||
* No jQuery dependency
|
|
||||||
* Configurable sorting
|
|
||||||
* Flexible styling
|
|
||||||
* Fast search/filtering
|
|
||||||
* Clean API
|
|
||||||
* Right-to-left support
|
|
||||||
* Custom templates
|
|
||||||
|
|
||||||
----
|
- 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](https://ES6.io/friend/JOHNSON) for great tutorials! 💪🏼
|
### Interested in writing your own ES6 JavaScript plugins? Check out [ES6.io](https://ES6.io/friend/JOHNSON) for great tutorials! 💪🏼
|
||||||
----
|
|
||||||
|
---
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
With [NPM](https://www.npmjs.com/package/choices.js):
|
With [NPM](https://www.npmjs.com/package/choices.js):
|
||||||
|
|
||||||
```zsh
|
```zsh
|
||||||
npm install choices.js
|
npm install choices.js
|
||||||
```
|
```
|
||||||
|
|
||||||
With [Yarn](https://yarnpkg.com/):
|
With [Yarn](https://yarnpkg.com/):
|
||||||
|
|
||||||
```zsh
|
```zsh
|
||||||
yarn add choices.js
|
yarn add choices.js
|
||||||
```
|
```
|
||||||
|
@ -34,9 +41,15 @@ From a [CDN](https://www.jsdelivr.com/package/npm/choices.js):
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<!-- Include base CSS (optional) -->
|
<!-- Include base CSS (optional) -->
|
||||||
<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/public/assets/styles/base.min.css"
|
||||||
|
/>
|
||||||
<!-- Include Choices CSS -->
|
<!-- Include Choices 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/public/assets/styles/choices.min.css"
|
||||||
|
/>
|
||||||
<!-- Include Choices JavaScript -->
|
<!-- Include Choices JavaScript -->
|
||||||
<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/public/assets/scripts/choices.min.js"></script>
|
||||||
```
|
```
|
||||||
|
@ -45,12 +58,13 @@ Or include Choices directly:
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<!-- Include base CSS (optional) -->
|
<!-- Include base CSS (optional) -->
|
||||||
<link rel="stylesheet" href="public/assets/styles/base.min.css">
|
<link rel="stylesheet" href="public/assets/styles/base.min.css" />
|
||||||
<!-- Include Choices CSS -->
|
<!-- Include Choices CSS -->
|
||||||
<link rel="stylesheet" href="public/assets/styles/choices.min.css">
|
<link rel="stylesheet" href="public/assets/styles/choices.min.css" />
|
||||||
<!-- Include Choices JavaScript -->
|
<!-- Include Choices JavaScript -->
|
||||||
<script src="/public/assets/scripts/choices.min.js"></script>
|
<script src="/public/assets/scripts/choices.min.js"></script>
|
||||||
```
|
```
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
If you pass a selector which targets multiple elements, an array of Choices instances
|
If you pass a selector which targets multiple elements, an array of Choices instances
|
||||||
|
@ -152,24 +166,26 @@ will be returned. If you target one element, that instance will be returned.
|
||||||
```
|
```
|
||||||
|
|
||||||
## Terminology
|
## Terminology
|
||||||
|
|
||||||
| Word | Definition |
|
| 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. |
|
| 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. |
|
| 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">` |
|
| 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">` |
|
||||||
|
|
||||||
|
|
||||||
## Configuration options
|
## Configuration options
|
||||||
|
|
||||||
### silent
|
### silent
|
||||||
**Type:** `Boolean` **Default:** `false`
|
|
||||||
|
**Type:** `Boolean` **Default:** `false`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-single`, `select-multiple`
|
**Input types affected:** `text`, `select-single`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Optionally suppress console errors and warnings.
|
**Usage:** Optionally suppress console errors and warnings.
|
||||||
|
|
||||||
|
|
||||||
### items
|
### items
|
||||||
**Type:** `Array` **Default:** `[]`
|
|
||||||
|
**Type:** `Array` **Default:** `[]`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
|
||||||
|
@ -198,7 +214,8 @@ Pass an array of objects:
|
||||||
```
|
```
|
||||||
|
|
||||||
### choices
|
### choices
|
||||||
**Type:** `Array` **Default:** `[]`
|
|
||||||
|
**Type:** `Array` **Default:** `[]`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
|
||||||
|
@ -226,6 +243,7 @@ Pass an array of objects:
|
||||||
```
|
```
|
||||||
|
|
||||||
### renderChoiceLimit
|
### renderChoiceLimit
|
||||||
|
|
||||||
**Type:** `Number` **Default:** `-1`
|
**Type:** `Number` **Default:** `-1`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -233,6 +251,7 @@ Pass an array of objects:
|
||||||
**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.
|
**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
|
### maxItemCount
|
||||||
|
|
||||||
**Type:** `Number` **Default:** `-1`
|
**Type:** `Number` **Default:** `-1`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -240,6 +259,7 @@ Pass an array of objects:
|
||||||
**Usage:** The amount of items a user can input/select ("-1" indicates no limit).
|
**Usage:** The amount of items a user can input/select ("-1" indicates no limit).
|
||||||
|
|
||||||
### addItems
|
### addItems
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -247,6 +267,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether a user can add items.
|
**Usage:** Whether a user can add items.
|
||||||
|
|
||||||
### removeItems
|
### removeItems
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -254,6 +275,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether a user can remove items.
|
**Usage:** Whether a user can remove items.
|
||||||
|
|
||||||
### removeItemButton
|
### removeItemButton
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `false`
|
**Type:** `Boolean` **Default:** `false`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
@ -261,6 +283,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether each item should have a remove button.
|
**Usage:** Whether each item should have a remove button.
|
||||||
|
|
||||||
### editItems
|
### editItems
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `false`
|
**Type:** `Boolean` **Default:** `false`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -268,6 +291,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether a user can edit items. An item's value can be edited by pressing the backspace.
|
**Usage:** Whether a user can edit items. An item's value can be edited by pressing the backspace.
|
||||||
|
|
||||||
### duplicateItemsAllowed
|
### duplicateItemsAllowed
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -275,6 +299,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether duplicate inputted/chosen items are allowed
|
**Usage:** Whether duplicate inputted/chosen items are allowed
|
||||||
|
|
||||||
### delimiter
|
### delimiter
|
||||||
|
|
||||||
**Type:** `String` **Default:** `,`
|
**Type:** `String` **Default:** `,`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -282,6 +307,7 @@ Pass an array of objects:
|
||||||
**Usage:** What divides each value. The default delimiter seperates each value with a comma: `"Value 1, Value 2, Value 3"`.
|
**Usage:** What divides each value. The default delimiter seperates each value with a comma: `"Value 1, Value 2, Value 3"`.
|
||||||
|
|
||||||
### paste
|
### paste
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -289,21 +315,23 @@ Pass an array of objects:
|
||||||
**Usage:** Whether a user can paste into the input.
|
**Usage:** Whether a user can paste into the input.
|
||||||
|
|
||||||
### searchEnabled
|
### searchEnabled
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `select-one`
|
**Input types affected:** `select-one`
|
||||||
|
|
||||||
**Usage:** Whether a search area should be shown. **Note:** Multiple select boxes will *always* show search areas.
|
**Usage:** Whether a search area should be shown. **Note:** Multiple select boxes will _always_ show search areas.
|
||||||
|
|
||||||
### searchChoices
|
### searchChoices
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `select-one`
|
**Input types affected:** `select-one`
|
||||||
|
|
||||||
**Usage:** Whether choices should be filtered by input or not. If `false`, the search event will still emit, but choices will not be filtered.
|
**Usage:** Whether choices should be filtered by input or not. If `false`, the search event will still emit, but choices will not be filtered.
|
||||||
|
|
||||||
|
|
||||||
### searchFields
|
### searchFields
|
||||||
|
|
||||||
**Type:** `Array/String` **Default:** `['label', 'value']`
|
**Type:** `Array/String` **Default:** `['label', 'value']`
|
||||||
|
|
||||||
**Input types affected:**`select-one`, `select-multiple`
|
**Input types affected:**`select-one`, `select-multiple`
|
||||||
|
@ -311,6 +339,7 @@ Pass an array of objects:
|
||||||
**Usage:** Specify which fields should be used when a user is searching. If you have added custom properties to your choices, you can add these values thus: `['label', 'value', 'customProperties.example']`.
|
**Usage:** Specify which fields should be used when a user is searching. If you have added custom properties to your choices, you can add these values thus: `['label', 'value', 'customProperties.example']`.
|
||||||
|
|
||||||
### searchFloor
|
### searchFloor
|
||||||
|
|
||||||
**Type:** `Number` **Default:** `1`
|
**Type:** `Number` **Default:** `1`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -318,6 +347,7 @@ Pass an array of objects:
|
||||||
**Usage:** The minimum length a search value should be before choices are searched.
|
**Usage:** The minimum length a search value should be before choices are searched.
|
||||||
|
|
||||||
### searchResultLimit: 4,
|
### searchResultLimit: 4,
|
||||||
|
|
||||||
**Type:** `Number` **Default:** `4`
|
**Type:** `Number` **Default:** `4`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -325,6 +355,7 @@ Pass an array of objects:
|
||||||
**Usage:** The maximum amount of search results to show.
|
**Usage:** The maximum amount of search results to show.
|
||||||
|
|
||||||
### position
|
### position
|
||||||
|
|
||||||
**Type:** `String` **Default:** `auto`
|
**Type:** `String` **Default:** `auto`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -332,6 +363,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether the dropdown should appear above (`top`) or below (`bottom`) the input. By default, if there is not enough space within the window the dropdown will appear above the input, otherwise below it.
|
**Usage:** Whether the dropdown should appear above (`top`) or below (`bottom`) the input. By default, if there is not enough space within the window the dropdown will appear above the input, otherwise below it.
|
||||||
|
|
||||||
### resetScrollPosition
|
### resetScrollPosition
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `select-multiple`
|
**Input types affected:** `select-multiple`
|
||||||
|
@ -339,6 +371,7 @@ Pass an array of objects:
|
||||||
**Usage:** Whether the scroll position should reset after adding an item.
|
**Usage:** Whether the scroll position should reset after adding an item.
|
||||||
|
|
||||||
### addItemFilterFn
|
### addItemFilterFn
|
||||||
|
|
||||||
**Type:** `Function` **Default:** `null`
|
**Type:** `Function` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -357,6 +390,7 @@ new Choices(element, {
|
||||||
```
|
```
|
||||||
|
|
||||||
### shouldSort
|
### shouldSort
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -364,6 +398,7 @@ new Choices(element, {
|
||||||
**Usage:** Whether choices and groups should be sorted. If false, choices/groups will appear in the order they were given.
|
**Usage:** Whether choices and groups should be sorted. If false, choices/groups will appear in the order they were given.
|
||||||
|
|
||||||
### shouldSortItems
|
### shouldSortItems
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `false`
|
**Type:** `Boolean` **Default:** `false`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -371,6 +406,7 @@ new Choices(element, {
|
||||||
**Usage:** Whether items should be sorted. If false, items will appear in the order they were selected.
|
**Usage:** Whether items should be sorted. If false, items will appear in the order they were selected.
|
||||||
|
|
||||||
### sortFn
|
### sortFn
|
||||||
|
|
||||||
**Type:** `Function` **Default:** sortByAlpha
|
**Type:** `Function` **Default:** sortByAlpha
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -389,11 +425,12 @@ const example = new Choices(element, {
|
||||||
```
|
```
|
||||||
|
|
||||||
### placeholder
|
### placeholder
|
||||||
|
|
||||||
**Type:** `Boolean` **Default:** `true`
|
**Type:** `Boolean` **Default:** `true`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `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.
|
**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.
|
||||||
|
|
||||||
**Note:** For single select boxes, the recommended way of adding a placeholder is as follows:
|
**Note:** For single select boxes, the recommended way of adding a placeholder is as follows:
|
||||||
|
|
||||||
|
@ -409,6 +446,7 @@ const example = new Choices(element, {
|
||||||
For backward compatibility, `<option placeholder>This is a placeholder</option>` is also supported.
|
For backward compatibility, `<option placeholder>This is a placeholder</option>` is also supported.
|
||||||
|
|
||||||
### placeholderValue
|
### placeholderValue
|
||||||
|
|
||||||
**Type:** `String` **Default:** `null`
|
**Type:** `String` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
@ -416,6 +454,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The value of the inputs placeholder.
|
**Usage:** The value of the inputs placeholder.
|
||||||
|
|
||||||
### searchPlaceholderValue
|
### searchPlaceholderValue
|
||||||
|
|
||||||
**Type:** `String` **Default:** `null`
|
**Type:** `String` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `select-one`
|
**Input types affected:** `select-one`
|
||||||
|
@ -423,6 +462,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The value of the search inputs placeholder.
|
**Usage:** The value of the search inputs placeholder.
|
||||||
|
|
||||||
### prependValue
|
### prependValue
|
||||||
|
|
||||||
**Type:** `String` **Default:** `null`
|
**Type:** `String` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
@ -430,6 +470,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** Prepend a value to each item added/selected.
|
**Usage:** Prepend a value to each item added/selected.
|
||||||
|
|
||||||
### appendValue
|
### appendValue
|
||||||
|
|
||||||
**Type:** `String` **Default:** `null`
|
**Type:** `String` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
@ -437,6 +478,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** Append a value to each item added/selected.
|
**Usage:** Append a value to each item added/selected.
|
||||||
|
|
||||||
### renderSelectedChoices
|
### renderSelectedChoices
|
||||||
|
|
||||||
**Type:** `String` **Default:** `auto`
|
**Type:** `String` **Default:** `auto`
|
||||||
|
|
||||||
**Input types affected:** `select-multiple`
|
**Input types affected:** `select-multiple`
|
||||||
|
@ -444,6 +486,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** Whether selected choices should be removed from the list. By default choices are removed when they are selected in multiple select box. To always render choices pass `always`.
|
**Usage:** Whether selected choices should be removed from the list. By default choices are removed when they are selected in multiple select box. To always render choices pass `always`.
|
||||||
|
|
||||||
### loadingText
|
### loadingText
|
||||||
|
|
||||||
**Type:** `String` **Default:** `Loading...`
|
**Type:** `String` **Default:** `Loading...`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -451,6 +494,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown whilst choices are being populated via AJAX.
|
**Usage:** The text that is shown whilst choices are being populated via AJAX.
|
||||||
|
|
||||||
### noResultsText
|
### noResultsText
|
||||||
|
|
||||||
**Type:** `String/Function` **Default:** `No results found`
|
**Type:** `String/Function` **Default:** `No results found`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -458,6 +502,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown when a user's search has returned no results. Optionally pass a function returning a string.
|
**Usage:** The text that is shown when a user's search has returned no results. Optionally pass a function returning a string.
|
||||||
|
|
||||||
### noChoicesText
|
### noChoicesText
|
||||||
|
|
||||||
**Type:** `String/Function` **Default:** `No choices to choose from`
|
**Type:** `String/Function` **Default:** `No choices to choose from`
|
||||||
|
|
||||||
**Input types affected:** `select-multiple`
|
**Input types affected:** `select-multiple`
|
||||||
|
@ -465,6 +510,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown when a user has selected all possible choices. Optionally pass a function returning a string.
|
**Usage:** The text that is shown when a user has selected all possible choices. Optionally pass a function returning a string.
|
||||||
|
|
||||||
### itemSelectText
|
### itemSelectText
|
||||||
|
|
||||||
**Type:** `String` **Default:** `Press to select`
|
**Type:** `String` **Default:** `Press to select`
|
||||||
|
|
||||||
**Input types affected:** `select-multiple`, `select-one`
|
**Input types affected:** `select-multiple`, `select-one`
|
||||||
|
@ -472,6 +518,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown when a user hovers over a selectable choice.
|
**Usage:** The text that is shown when a user hovers over a selectable choice.
|
||||||
|
|
||||||
### addItemText
|
### addItemText
|
||||||
|
|
||||||
**Type:** `String/Function` **Default:** `Press Enter to add "${value}"`
|
**Type:** `String/Function` **Default:** `Press Enter to add "${value}"`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -479,6 +526,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown when a user has inputted a new item but has not pressed the enter key. To access the current input value, pass a function with a `value` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example), otherwise pass a string.
|
**Usage:** The text that is shown when a user has inputted a new item but has not pressed the enter key. To access the current input value, pass a function with a `value` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example), otherwise pass a string.
|
||||||
|
|
||||||
### maxItemText
|
### maxItemText
|
||||||
|
|
||||||
**Type:** `String/Function` **Default:** `Only ${maxItemCount} values can be added`
|
**Type:** `String/Function` **Default:** `Only ${maxItemCount} values can be added`
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
@ -486,6 +534,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** The text that is shown when a user has focus on the input but has already reached the [max item count](https://github.com/jshjohnson/Choices#maxitemcount). To access the max item count, pass a function with a `maxItemCount` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example), otherwise pass a string.
|
**Usage:** The text that is shown when a user has focus on the input but has already reached the [max item count](https://github.com/jshjohnson/Choices#maxitemcount). To access the max item count, pass a function with a `maxItemCount` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example), otherwise pass a string.
|
||||||
|
|
||||||
### itemComparer
|
### itemComparer
|
||||||
|
|
||||||
**Type:** `Function` **Default:** `strict equality`
|
**Type:** `Function` **Default:** `strict equality`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
@ -493,6 +542,7 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
|
||||||
**Usage:** Compare choice and value in appropriate way (e.g. deep equality for objects). To compare choice and value, pass a function with a `itemComparer` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example).
|
**Usage:** Compare choice and value in appropriate way (e.g. deep equality for objects). To compare choice and value, pass a function with a `itemComparer` argument (see the [default config](https://github.com/jshjohnson/Choices#setup) for an example).
|
||||||
|
|
||||||
### classNames
|
### classNames
|
||||||
|
|
||||||
**Type:** `Object` **Default:**
|
**Type:** `Object` **Default:**
|
||||||
|
|
||||||
```
|
```
|
||||||
|
@ -527,9 +577,11 @@ classNames: {
|
||||||
**Usage:** Classes added to HTML generated by Choices. By default classnames follow the [BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) notation.
|
**Usage:** Classes added to HTML generated by Choices. By default classnames follow the [BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) notation.
|
||||||
|
|
||||||
## Callbacks
|
## Callbacks
|
||||||
|
|
||||||
**Note:** For each callback, `this` refers to the current instance of Choices. This can be useful if you need access to methods (`this.disable()`) or the config object (`this.config`).
|
**Note:** For each callback, `this` refers to the current instance of Choices. This can be useful if you need access to methods (`this.disable()`) or the config object (`this.config`).
|
||||||
|
|
||||||
### callbackOnInit
|
### callbackOnInit
|
||||||
|
|
||||||
**Type:** `Function` **Default:** `null`
|
**Type:** `Function` **Default:** `null`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
@ -537,6 +589,7 @@ classNames: {
|
||||||
**Usage:** Function to run once Choices initialises.
|
**Usage:** Function to run once Choices initialises.
|
||||||
|
|
||||||
### callbackOnCreateTemplates
|
### callbackOnCreateTemplates
|
||||||
|
|
||||||
**Type:** `Function` **Default:** `null` **Arguments:** `template`
|
**Type:** `Function` **Default:** `null` **Arguments:** `template`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
@ -547,28 +600,45 @@ classNames: {
|
||||||
|
|
||||||
```js
|
```js
|
||||||
const example = new Choices(element, {
|
const example = new Choices(element, {
|
||||||
callbackOnCreateTemplates: function (template) {
|
callbackOnCreateTemplates: function(template) {
|
||||||
return {
|
return {
|
||||||
item: (classNames, data) => {
|
item: (classNames, data) => {
|
||||||
return template(`
|
return template(`
|
||||||
<div class="${classNames.item} ${data.highlighted ? classNames.highlightedState : classNames.itemSelectable} ${data.placeholder ? classNames.placeholder : ''}" data-item data-id="${data.id}" data-value="${data.value}" ${data.active ? 'aria-selected="true"' : ''} ${data.disabled ? 'aria-disabled="true"' : ''}>
|
<div class="${classNames.item} ${
|
||||||
|
data.highlighted
|
||||||
|
? classNames.highlightedState
|
||||||
|
: classNames.itemSelectable
|
||||||
|
} ${
|
||||||
|
data.placeholder ? classNames.placeholder : ''
|
||||||
|
}" data-item data-id="${data.id}" data-value="${data.value}" ${
|
||||||
|
data.active ? 'aria-selected="true"' : ''
|
||||||
|
} ${data.disabled ? 'aria-disabled="true"' : ''}>
|
||||||
<span>★</span> ${data.label}
|
<span>★</span> ${data.label}
|
||||||
</div>
|
</div>
|
||||||
`);
|
`);
|
||||||
},
|
},
|
||||||
choice: (classNames, data) => {
|
choice: (classNames, data) => {
|
||||||
return template(`
|
return template(`
|
||||||
<div class="${classNames.item} ${classNames.itemChoice} ${data.disabled ? classNames.itemDisabled : classNames.itemSelectable}" data-select-text="${this.config.itemSelectText}" data-choice ${data.disabled ? 'data-choice-disabled aria-disabled="true"' : 'data-choice-selectable'} data-id="${data.id}" data-value="${data.value}" ${data.groupId > 0 ? 'role="treeitem"' : 'role="option"'}>
|
<div class="${classNames.item} ${classNames.itemChoice} ${
|
||||||
|
data.disabled ? classNames.itemDisabled : classNames.itemSelectable
|
||||||
|
}" data-select-text="${this.config.itemSelectText}" data-choice ${
|
||||||
|
data.disabled
|
||||||
|
? 'data-choice-disabled aria-disabled="true"'
|
||||||
|
: 'data-choice-selectable'
|
||||||
|
} data-id="${data.id}" data-value="${data.value}" ${
|
||||||
|
data.groupId > 0 ? 'role="treeitem"' : 'role="option"'
|
||||||
|
}>
|
||||||
<span>★</span> ${data.label}
|
<span>★</span> ${data.label}
|
||||||
</div>
|
</div>
|
||||||
`);
|
`);
|
||||||
},
|
},
|
||||||
};
|
};
|
||||||
}
|
},
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## Events
|
## 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.
|
**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:**
|
**Example:**
|
||||||
|
@ -577,29 +647,38 @@ const example = new Choices(element, {
|
||||||
const element = document.getElementById('example');
|
const element = document.getElementById('example');
|
||||||
const example = new Choices(element);
|
const example = new Choices(element);
|
||||||
|
|
||||||
element.addEventListener('addItem', function(event) {
|
element.addEventListener(
|
||||||
// do something creative here...
|
'addItem',
|
||||||
console.log(event.detail.id);
|
function(event) {
|
||||||
console.log(event.detail.value);
|
// do something creative here...
|
||||||
console.log(event.detail.label);
|
console.log(event.detail.id);
|
||||||
console.log(event.detail.customProperties);
|
console.log(event.detail.value);
|
||||||
console.log(event.detail.groupValue);
|
console.log(event.detail.label);
|
||||||
}, false);
|
console.log(event.detail.customProperties);
|
||||||
|
console.log(event.detail.groupValue);
|
||||||
|
},
|
||||||
|
false,
|
||||||
|
);
|
||||||
|
|
||||||
// or
|
// or
|
||||||
const example = new Choices(document.getElementById('example'));
|
const example = new Choices(document.getElementById('example'));
|
||||||
|
|
||||||
example.passedElement.element.addEventListener('addItem', function(event) {
|
example.passedElement.element.addEventListener(
|
||||||
// do something creative here...
|
'addItem',
|
||||||
console.log(event.detail.id);
|
function(event) {
|
||||||
console.log(event.detail.value);
|
// do something creative here...
|
||||||
console.log(event.detail.label);
|
console.log(event.detail.id);
|
||||||
console.log(event.detail.customProperties);
|
console.log(event.detail.value);
|
||||||
console.log(event.detail.groupValue);
|
console.log(event.detail.label);
|
||||||
}, false);
|
console.log(event.detail.customProperties);
|
||||||
|
console.log(event.detail.groupValue);
|
||||||
|
},
|
||||||
|
false,
|
||||||
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
### addItem
|
### addItem
|
||||||
|
|
||||||
**Arguments:** `id, value, label, groupValue, keyCode`
|
**Arguments:** `id, value, label, groupValue, keyCode`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**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).
|
**Usage:** Triggered each time an item is added (programmatically or by the user).
|
||||||
|
|
||||||
### removeItem
|
### removeItem
|
||||||
|
|
||||||
**Arguments:** `id, value, label, groupValue`
|
**Arguments:** `id, value, label, groupValue`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**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).
|
**Usage:** Triggered each time an item is removed (programmatically or by the user).
|
||||||
|
|
||||||
### highlightItem
|
### highlightItem
|
||||||
|
|
||||||
**Arguments:** `id, value, label, groupValue`
|
**Arguments:** `id, value, label, groupValue`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**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.
|
**Usage:** Triggered each time an item is highlighted.
|
||||||
|
|
||||||
### unhighlightItem
|
### unhighlightItem
|
||||||
|
|
||||||
**Arguments:** `id, value, label, groupValue`
|
**Arguments:** `id, value, label, groupValue`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**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.
|
**Usage:** Triggered each time an item is unhighlighted.
|
||||||
|
|
||||||
### choice
|
### choice
|
||||||
**Arguments:** `value, keyCode`
|
|
||||||
|
**Arguments:** `choice`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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.
|
**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
|
### change
|
||||||
|
|
||||||
**Arguments:** `value`
|
**Arguments:** `value`
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**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**.
|
**Usage:** Triggered each time an item is added/removed **by a user**.
|
||||||
|
|
||||||
### search
|
### search
|
||||||
|
|
||||||
**Arguments:** `value`, `resultCount`
|
**Arguments:** `value`, `resultCount`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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.
|
**Usage:** Triggered when a user types into an input to search choices.
|
||||||
|
|
||||||
### showDropdown
|
### showDropdown
|
||||||
|
|
||||||
**Arguments:** -
|
**Arguments:** -
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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.
|
**Usage:** Triggered when the dropdown is shown.
|
||||||
|
|
||||||
### hideDropdown
|
### hideDropdown
|
||||||
|
|
||||||
**Arguments:** -
|
**Arguments:** -
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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.
|
**Usage:** Triggered when the dropdown is hidden.
|
||||||
|
|
||||||
### highlightChoice
|
### highlightChoice
|
||||||
|
|
||||||
**Arguments:** `el`
|
**Arguments:** `el`
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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
|
||||||
|
|
||||||
Methods can be called either directly or by chaining:
|
Methods can be called either directly or by chaining:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
// Calling a method by chaining
|
// Calling a method by chaining
|
||||||
const choices = new Choices(element, {
|
const choices = new Choices(element, {
|
||||||
addItems: false,
|
addItems: false,
|
||||||
removeItems: false,
|
removeItems: false,
|
||||||
})
|
})
|
||||||
.setValue(['Set value 1', 'Set value 2'])
|
.setValue(['Set value 1', 'Set value 2'])
|
||||||
.disable();
|
.disable();
|
||||||
|
|
||||||
|
@ -687,16 +778,18 @@ const choices = new Choices(element, {
|
||||||
removeItems: false,
|
removeItems: false,
|
||||||
});
|
});
|
||||||
|
|
||||||
choices.setValue(['Set value 1', 'Set value 2'])
|
choices.setValue(['Set value 1', 'Set value 2']);
|
||||||
choices.disable();
|
choices.disable();
|
||||||
```
|
```
|
||||||
|
|
||||||
### destroy();
|
### destroy();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`, `select-one`
|
**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.
|
**Usage:** Kills the instance of Choices, removes all event listeners and returns passed input to its initial state.
|
||||||
|
|
||||||
### init();
|
### init();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`, `select-one`
|
**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.
|
**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()`).
|
**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();
|
### highlightAll();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Highlight each chosen item (selected items can be removed).
|
**Usage:** Highlight each chosen item (selected items can be removed).
|
||||||
|
|
||||||
|
|
||||||
### unhighlightAll();
|
### unhighlightAll();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Un-highlight each chosen item.
|
**Usage:** Un-highlight each chosen item.
|
||||||
|
|
||||||
|
|
||||||
### removeActiveItemsByValue(value);
|
### removeActiveItemsByValue(value);
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Remove each item by a given value.
|
**Usage:** Remove each item by a given value.
|
||||||
|
|
||||||
|
|
||||||
### removeActiveItems(excludedId);
|
### removeActiveItems(excludedId);
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Remove each selectable item.
|
**Usage:** Remove each selectable item.
|
||||||
|
|
||||||
|
|
||||||
### removeHighlightedItems();
|
### removeHighlightedItems();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Remove each item the user has selected.
|
**Usage:** Remove each item the user has selected.
|
||||||
|
|
||||||
|
|
||||||
### showDropdown();
|
### showDropdown();
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Show option list dropdown (only affects select inputs).
|
**Usage:** Show option list dropdown (only affects select inputs).
|
||||||
|
|
||||||
|
|
||||||
### hideDropdown();
|
### hideDropdown();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-multiple`
|
**Input types affected:** `text`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Hide option list dropdown (only affects select inputs).
|
**Usage:** Hide option list dropdown (only affects select inputs).
|
||||||
|
|
||||||
### setChoices(choices, value, label, replaceChoices);
|
### setChoices(choices, value, label, replaceChoices);
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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).
|
**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
|
```js
|
||||||
const example = new Choices(element);
|
const example = new Choices(element);
|
||||||
|
|
||||||
example.setChoices([
|
example.setChoices(
|
||||||
{value: 'One', label: 'Label One', disabled: true},
|
[
|
||||||
{value: 'Two', label: 'Label Two', selected: true},
|
{ value: 'One', label: 'Label One', disabled: true },
|
||||||
{value: 'Three', label: 'Label Three'},
|
{ value: 'Two', label: 'Label Two', selected: true },
|
||||||
], 'value', 'label', false);
|
{ value: 'Three', label: 'Label Three' },
|
||||||
|
],
|
||||||
|
'value',
|
||||||
|
'label',
|
||||||
|
false,
|
||||||
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
**Example 2:**
|
**Example 2:**
|
||||||
|
@ -766,37 +866,50 @@ example.setChoices([
|
||||||
```js
|
```js
|
||||||
const example = new Choices(element);
|
const example = new Choices(element);
|
||||||
|
|
||||||
example.setChoices([{
|
example.setChoices(
|
||||||
label: 'Group one',
|
[
|
||||||
id: 1,
|
{
|
||||||
disabled: false,
|
label: 'Group one',
|
||||||
choices: [
|
id: 1,
|
||||||
{value: 'Child One', label: 'Child One', selected: true},
|
disabled: false,
|
||||||
{value: 'Child Two', label: 'Child Two', disabled: true},
|
choices: [
|
||||||
{value: 'Child Three', label: 'Child Three'},
|
{ 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,
|
label: 'Group two',
|
||||||
choices: [
|
id: 2,
|
||||||
{value: 'Child Four', label: 'Child Four', disabled: true},
|
disabled: false,
|
||||||
{value: 'Child Five', label: 'Child Five'},
|
choices: [
|
||||||
{value: 'Child Six', label: 'Child Six', customProperties: {
|
{ value: 'Child Four', label: 'Child Four', disabled: true },
|
||||||
description: 'Custom description about child six',
|
{ value: 'Child Five', label: 'Child Five' },
|
||||||
random: 'Another random custom property'
|
{
|
||||||
}},
|
value: 'Child Six',
|
||||||
]
|
label: 'Child Six',
|
||||||
}], 'value', 'label', false);
|
customProperties: {
|
||||||
|
description: 'Custom description about child six',
|
||||||
|
random: 'Another random custom property',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
'value',
|
||||||
|
'label',
|
||||||
|
false,
|
||||||
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
### clearChoices();
|
### clearChoices();
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Clear all choices from select
|
**Usage:** Clear all choices from select
|
||||||
|
|
||||||
### getValue(valueOnly)
|
### getValue(valueOnly)
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**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.
|
**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);
|
### setValue(items);
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**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.
|
**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
|
// via an array of objects
|
||||||
example.setValue([
|
example.setValue([
|
||||||
{value: 'One', label: 'Label One'},
|
{ value: 'One', label: 'Label One' },
|
||||||
{value: 'Two', label: 'Label Two'},
|
{ value: 'Two', label: 'Label Two' },
|
||||||
{value: 'Three', label: 'Label Three'},
|
{ value: 'Three', label: 'Label Three' },
|
||||||
]);
|
]);
|
||||||
|
|
||||||
// or via an array of strings
|
// or via an array of strings
|
||||||
example.setValue(['Four','Five','Six']);
|
example.setValue(['Four', 'Five', 'Six']);
|
||||||
```
|
```
|
||||||
|
|
||||||
### setChoiceByValue(value);
|
### setChoiceByValue(value);
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**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
|
**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
|
```js
|
||||||
const example = new Choices(element, {
|
const example = new Choices(element, {
|
||||||
choices: [
|
choices: [
|
||||||
{value: 'One', label: 'Label One'},
|
{ value: 'One', label: 'Label One' },
|
||||||
{value: 'Two', label: 'Label Two', disabled: true},
|
{ value: 'Two', label: 'Label Two', disabled: true },
|
||||||
{value: 'Three', label: 'Label Three'},
|
{ value: 'Three', label: 'Label Three' },
|
||||||
],
|
],
|
||||||
});
|
});
|
||||||
|
|
||||||
|
@ -850,29 +965,31 @@ example.setChoiceByValue('Two'); // Choice with value of 'Two' has now been sele
|
||||||
```
|
```
|
||||||
|
|
||||||
### clearStore();
|
### clearStore();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Removes all items, choices and groups. Use with caution.
|
**Usage:** Removes all items, choices and groups. Use with caution.
|
||||||
|
|
||||||
|
|
||||||
### clearInput();
|
### clearInput();
|
||||||
|
|
||||||
**Input types affected:** `text`
|
**Input types affected:** `text`
|
||||||
|
|
||||||
**Usage:** Clear input of any user inputted text.
|
**Usage:** Clear input of any user inputted text.
|
||||||
|
|
||||||
|
|
||||||
### disable();
|
### disable();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Disables input from accepting new value/selecting further choices.
|
**Usage:** Disables input from accepting new value/selecting further choices.
|
||||||
|
|
||||||
### enable();
|
### enable();
|
||||||
|
|
||||||
**Input types affected:** `text`, `select-one`, `select-multiple`
|
**Input types affected:** `text`, `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Enables input to accept new values/select further choices.
|
**Usage:** Enables input to accept new values/select further choices.
|
||||||
|
|
||||||
|
|
||||||
### ajax(fn);
|
### ajax(fn);
|
||||||
|
|
||||||
**Input types affected:** `select-one`, `select-multiple`
|
**Input types affected:** `select-one`, `select-multiple`
|
||||||
|
|
||||||
**Usage:** Populate choices/groups via a callback.
|
**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.
|
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
|
```js
|
||||||
const example = new Choices(element)
|
const example = new Choices(element);
|
||||||
|
|
||||||
example.ajax(function(callback) {
|
example.ajax(function(callback) {
|
||||||
fetch(url)
|
fetch(url)
|
||||||
|
@ -915,6 +1032,7 @@ example.ajax(function(callback) {
|
||||||
```
|
```
|
||||||
|
|
||||||
## Browser compatibility
|
## 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/):
|
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:**
|
**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:**
|
**Features used in Choices:**
|
||||||
|
|
||||||
* Array.prototype.forEach
|
- Array.prototype.forEach
|
||||||
* Array.prototype.map
|
- Array.prototype.map
|
||||||
* Array.prototype.find
|
- Array.prototype.find
|
||||||
* Array.prototype.some
|
- Array.prototype.some
|
||||||
* Array.prototype.includes
|
- Array.prototype.includes
|
||||||
* Array.from
|
- Array.from
|
||||||
* Array.prototype.reduce
|
- Array.prototype.reduce
|
||||||
* Array.prototype.indexOf
|
- Array.prototype.indexOf
|
||||||
* Object.assign
|
- Object.assign
|
||||||
* Element.prototype.classList
|
- Element.prototype.classList
|
||||||
* window.requestAnimationFrame
|
- window.requestAnimationFrame
|
||||||
* CustomEvent
|
- CustomEvent
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
To setup a local environment: clone this repo, navigate into it's directory in a terminal window and run the following command:
|
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
|
### NPM tasks
|
||||||
|
|
||||||
| Task | Usage |
|
| Task | Usage |
|
||||||
| ------------------------- | ------------------------------------------------------------ |
|
| ------------------------- | ------------------------------------------------------------ |
|
||||||
| `npm run start` | Fire up local server for development |
|
| `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 |
|
| `npm run css:build` | Compile, minify and prefix SCSS files to CSS |
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License
|
MIT License
|
||||||
|
|
||||||
## Web component
|
## 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).
|
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
|
## 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!
|
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!
|
||||||
|
|
38
types/index.d.ts
vendored
38
types/index.d.ts
vendored
|
@ -13,7 +13,7 @@ import { FuseOptions } from 'fuse.js';
|
||||||
declare namespace Choices {
|
declare namespace Choices {
|
||||||
namespace Types {
|
namespace Types {
|
||||||
type strToEl = (
|
type strToEl = (
|
||||||
str: string
|
str: string,
|
||||||
) => HTMLElement | HTMLInputElement | HTMLOptionElement;
|
) => HTMLElement | HTMLInputElement | HTMLOptionElement;
|
||||||
type stringFunction = () => string;
|
type stringFunction = () => string;
|
||||||
type noticeStringFunction = (value: string) => string;
|
type noticeStringFunction = (value: string) => string;
|
||||||
|
@ -99,9 +99,9 @@ declare namespace Choices {
|
||||||
*
|
*
|
||||||
* **Input types affected:** select-one, select-multiple
|
* **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**.
|
* 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.
|
* Triggered when a choice from the dropdown is highlighted.
|
||||||
*
|
*
|
||||||
* Input types affected: select-one, select-multiple
|
* 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 {
|
interface Group {
|
||||||
|
@ -168,52 +168,52 @@ declare namespace Choices {
|
||||||
isSelectElement: boolean,
|
isSelectElement: boolean,
|
||||||
isSelectOneElement: boolean,
|
isSelectOneElement: boolean,
|
||||||
searchEnabled: boolean,
|
searchEnabled: boolean,
|
||||||
passedElementType: passedElement['type']
|
passedElementType: passedElement['type'],
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
containerInner: (this: Choices, classNames: ClassNames) => HTMLElement;
|
containerInner: (this: Choices, classNames: ClassNames) => HTMLElement;
|
||||||
itemList: (
|
itemList: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
isSelectOneElement: boolean
|
isSelectOneElement: boolean,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
placeholder: (
|
placeholder: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
value: string
|
value: string,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
item: (
|
item: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
data: Choice,
|
data: Choice,
|
||||||
removeItemButton: boolean
|
removeItemButton: boolean,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
choiceList: (
|
choiceList: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
isSelectOneElement: boolean
|
isSelectOneElement: boolean,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
choiceGroup: (
|
choiceGroup: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
data: Choice
|
data: Choice,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
choice: (
|
choice: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
data: Choice,
|
data: Choice,
|
||||||
selectText: string
|
selectText: string,
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
input: (
|
input: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
placeholderValue: string
|
placeholderValue: string,
|
||||||
) => HTMLInputElement;
|
) => HTMLInputElement;
|
||||||
dropdown: (this: Choices, classNames: ClassNames) => HTMLElement;
|
dropdown: (this: Choices, classNames: ClassNames) => HTMLElement;
|
||||||
notice: (
|
notice: (
|
||||||
this: Choices,
|
this: Choices,
|
||||||
classNames: ClassNames,
|
classNames: ClassNames,
|
||||||
label: string,
|
label: string,
|
||||||
type: '' | 'no-results' | 'no-choices'
|
type: '' | 'no-results' | 'no-choices',
|
||||||
) => HTMLElement;
|
) => HTMLElement;
|
||||||
option: (data: Choice) => HTMLOptionElement;
|
option: (data: Choice) => HTMLOptionElement;
|
||||||
}
|
}
|
||||||
|
@ -280,9 +280,9 @@ declare namespace Choices {
|
||||||
type: K,
|
type: K,
|
||||||
listener: (
|
listener: (
|
||||||
this: HTMLInputElement | HTMLSelectElement,
|
this: HTMLInputElement | HTMLSelectElement,
|
||||||
ev: Choices.EventMap[K]
|
ev: Choices.EventMap[K],
|
||||||
) => void,
|
) => void,
|
||||||
options?: boolean | AddEventListenerOptions
|
options?: boolean | AddEventListenerOptions,
|
||||||
): void;
|
): void;
|
||||||
};
|
};
|
||||||
type: 'text' | 'select-one' | 'select-multiple';
|
type: 'text' | 'select-one' | 'select-multiple';
|
||||||
|
@ -750,7 +750,7 @@ declare namespace Choices {
|
||||||
* @default null
|
* @default null
|
||||||
*/
|
*/
|
||||||
callbackOnCreateTemplates: (
|
callbackOnCreateTemplates: (
|
||||||
template: Choices.Types.strToEl
|
template: Choices.Types.strToEl,
|
||||||
) => Partial<Choices.Templates>;
|
) => Partial<Choices.Templates>;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -769,7 +769,7 @@ export default class Choices {
|
||||||
|
|
||||||
constructor(
|
constructor(
|
||||||
selectorOrElement: string | HTMLInputElement | HTMLSelectElement,
|
selectorOrElement: string | HTMLInputElement | HTMLSelectElement,
|
||||||
userConfig?: Partial<Choices.Options>
|
userConfig?: Partial<Choices.Options>,
|
||||||
);
|
);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -942,7 +942,7 @@ export default class Choices {
|
||||||
choices: Choices.Choice[],
|
choices: Choices.Choice[],
|
||||||
value: string,
|
value: string,
|
||||||
label: string,
|
label: string,
|
||||||
replaceChoices?: boolean
|
replaceChoices?: boolean,
|
||||||
): this;
|
): this;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
Loading…
Reference in a new issue