@s-r0/choice-js

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

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.

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

@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.

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

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

[{"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