@s-r0/choice-js
v2.0.7
Published
ChoiceJS is a Javascript micro Library for simple, lightweight select boxes with features like search, multi select and more.
Downloads
148
Maintainers
Readme
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