ghiscoding
Multiple-Select-Vanilla
Description
Multiple-Select-Vanilla is a fork of the popular Multiple-Select (jQuery) library (thanks to @wenzhixin for this great project). This fork was based on its latest known version at the time, which was v1.5.2, but later updated to v1.7.0. The main difference from the original lib is that we dropped jQuery in favor of native browser code and this mean zero external dependency. As a bonus, a few extra features were also added to the library and you can see them listed below Changes vs Original lib.
This lib allows you to select multiple elements with checkboxes :).
To get started take a look at the Live demo for all available options and methods that the library offers.
Demo
Take a look at the Live demo to see all available options/methods (there's a lot). You can also take a look at the "Used by" section below to see and try live real world Open Source projects taking advantage of this library.
Fully tested with
The Live demo website is also helpful to run a full suite of E2E tests by using Playwright, all project examples have dedicated Playwright tests.
Installation
npm install multiple-select-vanillaBasic Usage
1. from a native <select>
<select class="multiple-select full-width" data-test="select1">
<option value="1">First</option>
<option value="2">Second</option>
<option value="3">Third</option>
<option value="4">Fourth</option>
</select>and then initialize ms-select
import { multipleSelect } from 'multiple-select-vanilla';
const ms = multipleSelect('.multiple-select');2. or from a data array or object
import { multipleSelect } from 'multiple-select-vanilla';
const ms = multipleSelect('.multiple-select', {
data: [
{ text: 'First', value: 1 },
{ text: 'Second', value: 2 },
{ text: 'Third', value: 3 },
{ text: 'Fourth', value: 4 },
]
});Changelog
LICENSE
Changes vs Original lib (multiple-select)
Changes and new options:
- dropped jQuery requirement and rewrote with browser native code.
- rewritten in TypeScript to also provide typings support (
d.ts) - make the lib CSP compliant (see CSP Compliance section below)
- add E2E tests, with Playwright, for all existing examples (over 80 of them)
- revamped the UI in v3.x to give it a more Modern Look:
- improved CSS styling by using SVG icons (CSS/SASS variables are also availables)
- new Dark Mode
- replace tabIndex with a more intuitive navigation & highlight by using arrow keys (or mouse hover)
- show 3 different states on multiple selections (none " ", partial "-" or all "🗸")
- add extra options:
autoAdjustDropHeightwill automatically adjust the drop (up/down) height by available space (see demo)autoAdjustDropPositionwill find best position (top/bottom) by its available space (see demo)autoAdjustDropWidthByTextSizeautomatically set the drop width size by reading the widest list option widthdataTestwill add adata-testattribute on the.ms-parentand.ms-dropdivs for easier E2E testinguseSelectOptionLabelwill use the<option label="">which can be used to display shorter text of selected options.- example: display
"1,3"as label instead of"January,March"(see demo)
- example: display
useSelectOptionLabelToHtmlsimilar touseSelectOptionLabelbut also renders HTML.renderOptionLabelAsHtmlwill render selected options as HTML code (see demo)sanitizercan be used to sanitize HTML code and prevent XSS cross-site scripting attacks (see demo).showOkButtonadds an "OK" button at the end of the multiple select option list (see demo)showSearchClearshow a clear filter button on the search filter input (see demo)diacriticParsercustom parser to normalize diacritic symbols when filtering select list (see demo)darkModeto enable our new Dark Mode Theme (see demo)infiniteScrolloption (see demo)onFilterClearcallback that will be executed when the filter gets cleared (see demo)onClose(reason)callback that will be executed when the dropdown closes (see demo)preFilterprovide a Filter predicate to pre-filter data (see demo)preSortprovide a Sort Comparer to pre-sort data (see demo)lazyDataprovide a function callback that will return a Promise with data collection (see demo)
CSP Compliance
The library is now CSP (Content Security Policy) compliant, there are however some exceptions to be aware of. When using any HTML strings as template (when using textTemplate, labelTemplate, renderOptionLabelAsHtml or useSelectOptionLabelToHtml), you will not be fully compliant unless you return TrustedHTML. You can achieve this by using the sanitizer method in combo with an external library like DOMPurify (recommended) to return TrustedHTML as shown below and with that in place you will be CSP compliant.
import DOMPurify from 'dompurify';
import { multipleSelect, MultipleSelectInstance } from 'multiple-select-vanilla';
const ms1 = multipleSelect('#select1', {
name: 'my-select',
single: false,
useSelectOptionLabelToHtml: true,
sanitizer: (html) => DOMPurify.sanitize(html, { RETURN_TRUSTED_TYPE: true }), // return TrustedHTML Type
data: [
{ text: '<i class="fa fa-star"></i> January', value: 1 },
{ text: '<i class="fa fa-star"></i> February', value: 2 },
]
});with this code in place, we can now use the following CSP meta tag (which is what we use in the demo index.html)
<meta http-equiv="Content-Security-Policy" content="default-src 'self';style-src 'self' data:; img-src * 'self' data: https:; require-trusted-types-for 'script'; trusted-types dompurify">[!NOTE] in our demo we are only adding
unsafe-inlinesimply because we are using Vite (which is not CSP compliant in Dev mode), but the library should work nonetheless withoutunsafe-inline.
Installation / Structure
There are multiple ways to install and use the library, you can see below the folder structure of the distribution files
dist/browser: Standalone build which assignsmultipleSelecton thewindow.multipleSelectobject- browser standalone means that you can simply load it with
<script></script>and thenmultipleSelect('#mySelect') - only ESM build (
.js) are provided, you will need to load it with<script type="module">
- browser standalone means that you can simply load it with
esm: to use as ESM withimport from 'multiple-select-vanilla'
dist/
browser/
multiple-select.js # ESM build, use with: window.multipleSelect
locales/
multiple-select-all-locales.js # all-in-1 locales
..
multiple-select-es-ES.js # Spanish locale
multiple-select-fr-FR.js # French locale
...
styles/ # CSS and SASS Stylings
css/
sass/
index.d.ts # d.ts Type Definitions
multiple-select.js # ESM, used by: import fromUsed by
This fork was created mostly to drop jQuery, and it is used by a few other Open Source projects of mine that I also maintain:
Contributions
Pull Request are welcome, feel free to contribute.
Development / Contributions
If you wish to contribute to the project, please follow the steps shown below:
Note: this project uses pnpm workspaces, you can install pnpm by following their installation or use NodeJS corepack enable to run any of these pnpm scripts.
- clone the lib:
git clone https://github.com/ghiscoding/multiple-select-vanilla
- install with pnpm from the root:
pnpm installORnpx pnpm install
- run a full TypeScript build
pnpm run buildORnpx pnpm run build
- run in development mode (lib & demo)
pnpm run devORnpx pnpm run dev
Pull Request Contribution
Before submitting a PR (pull request), please make sure that you followed the steps below for a better chance of a successfull PR:
- make sure that you have already executed
pnpm install - run the Biome lint npm script (or simply jump to step 4)
pnpm run biome:lint:write
- run the Biome code formatting npm script (or simply jump to step 4)
pnpm run biome:format:write
- run a full Build (this will also run Biome lint/format, so you could skip step 2)
pnpm run build
Sponsors
