npm package: @maxweb/choice-js
Description: ChoiceJS is a Javascript micro Library for simple, lightweight select boxes with features like search, multi select and more.
Author: Maxweb Solutions
Latest version: 2.1.9

# ChoiceJS

**ChoiceJS** is a Javascript micro Library for simple, lightweight select boxes. The goal of this library was to create something that meets the following criteria



* Dependency-less

* Lightweight

* Quick and efficient

* As minimal as possible, but still ticking all boxes



## Current Version

1.1.4

*For more detailed release notes, see `releases.md`*

## Install

Choice JS can be installed one of the following ways

### NPM

To install via NPM run the following

```
npm i @s-r0/choice-js
```

then import the module using

```javascript
import { Choice } from '@s-r0/choice-js';
```



### Manually

Manual installation can be done by simply downloading this library and including the build `choice.js` file. Once downloaded and placed in your directory, import the module like so.

```javascript
import { Choice } from  '{{path_to_choice.js}}';
```



### Styles

Feel free to write your own styles for choiceJS, but if you want to use the default styles (or at least the basics and overwrite them), import the styles in to your project

```scss
@import "@s-r0/choice-js/src/scss/choice";
```



## Basic Usage

ChoiceJS accepts 2 arguments, the select HTML Element you want to bind to, and an object of options.

```javascript
let element = document.getElementById('mySelect'),
    options = { closeOnSelect: true };

Choice(element, options); //Use our options defined above
Choice(element); //Use the default options
```

To bind to all select boxes, use the following

```javascript
let choicejs_promises = [];
for(let select of document.querySelectorAll('select')){
	choicejs_promises.push(Choice(select, options));
}
await Promise.all(choicejs_promises);
```



## Options

| Param            | Type             | Default   | Details                                                      |
| ---------------- | ---------------- | --------- | ------------------------------------------------------------ |
| `width`          | `string`         | `inherit` | Used to specify the width of the select box (not including the dropdown). Choice takes what you entered here and applies it directly to the select box, so `inherit`, `50px` and `100%` are all valid options. When using `inherit`, choice will do its best job to figure out its size based on the item you're binding it to. |
| `height`         | `string`         | `inherit` | Same rules as `width`.                                       |
| `placeholder`    | `string/boolean` | `false`   | Provide a string for what you would like the placeholder to say when nothing is selected. |
| `class`          | `string`         | `''`      | Any extra classes you want adding to the select box for customisation |
| `closeOnSelect`  | `boolean`        | `false`   | Do you want choice to close its dropdown when an item is selected? |
| `event`          | `string`         | `change`  | The event you want choice to listen to, just incase you want to change it. |
| `copyAttributes` | `boolean`        | `true`    | Do you want choice to copy any attributes from the select/options its binding to? |



## Other Configurations

Choice JS has some other configurations that are deemed as core functions.

### Multiple Options

If you want choice to allow you to select multiple options, just include `multiple="true"` on your select, and choicejs will do the rest.

### Dynamic live search

Choice can also search an endpoint dynamically to handle bigger data sets. To enable dynamic live search, just include the `data-choice-search-url` attribute on your select box and provide a url.

Choice will take the users input, and fetch your endpoint with the users input passed as a GET parameter called `choicesearch` (choicesearch was chosen to avoid conflicts with popular terms like `search` or `s`).

Your endpoint **must** return a an array of objects, containing `value` and `label` properties, for example

```json
[{"value":"pizza","label":"Pizza"},{"value":"chips","label":"Chips"}]
```

Choice will take your JSON object and create new options on the fly.

You can populate your select box with options on page load, choice will just replace them on search.

A good use case for this is having a large data set which is slowing page load. You could load an initial 50/100 records in your select, then live search all of your data.

> Dynamic searching **DOES NOT** work along side multiple options. This is to avoid issues with users selecting an option and then searching, and their pre-selected options being removed.


## Authors

**Sam Rutter**



## Copyright

Copyright © 2021 Samgraphic



## License

ChoiceJS is under the MIT License