Multiple-Select-Vanilla is a fork of the popular Multiple-Select (jQuery) library (thanks to @wenzhixin for this great lib). 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 as you can see from the list shown 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.
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 visit real world Open Source projects taking advantage of this library.
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.
npm install multiple-select-vanilla
New Multiple-Select Options:
- dropped jQuery requirement and replaced necessary code with browser native code.
- rewritten in TypeScript to also add typings support (
d.ts
) - make the lib CSP compliant (see section below)
- revamped the UI to give it a more Modern Look:
- improve CSS styling and use SVG icons (CSS/SASS variables are also availables)
- new Dark Mode
- replace tabIndex by a more intuitive navigation & highlight by using arrow keys (or mouse hover)
- show 3 different states on multiple selections (none " ", partial "-", all "🗸")
- add extra options:
autoAdjustDropHeight
will automatically adjust the drop (up/down) height by available space (see demo)autoAdjustDropPosition
will find best position (top/bottom) by its available space (see demo)autoAdjustDropWidthByTextSize
automatically set the drop width size from the widest list option widthdataTest
will add adata-test
attribute on the.ms-parent
and.ms-drop
divs for easier E2E testinguseSelectOptionLabel
will use the<option label="">
that can be used to display shorter text of selected options.- example: display "1,3" as label instead of "January,March" (see demo)
useSelectOptionLabelToHtml
similar touseSelectOptionLabel
but also renders HTML.renderOptionLabelAsHtml
will render selected options as HTML code (see demo)sanitizer
can be used to sanitize HTML code and prevent XSS cross-site scripting attacks (see demo).showOkButton
to add an "OK" button at the end of the multiple select option list (see demo)showSearchClear
show a clear button on the search filter input (see demo)diacriticParser
custom parser to normalize diacritic signs when filtering select list (see demo)darkMode
option for a new Dark Mode Theme (see demo)infiniteScroll
option (see demo)onFilterClear
callback that will be executed when the filter gets cleared (see demo)onClose(reason)
callback that will be executed when the dropdown closes (see demo)
The library is now CSP (Content Security Policy) compliant, however there are 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 that in our demo we are actually adding
unsafe-inline
simply because we are using Vite (which is not CSP compliant in Dev mode), but the library should work nonetheless withoutunsafe-inline
.
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 assignsmultipleSelect
on thewindow.multipleSelect
object- browser standalone means that you can simply load it with
<script></script>
and thenmultipleSelect('#mySelect')
- 2 builds are available CJS (
.cjs
) and ESM (.js
) and for the latter you will need to load it with<script type="module">
- browser standalone means that you can simply load it with
cjs
: to use as CommonJS withrequire('multiple-select-vanilla')
esm
: to use as ESM withimport from 'multiple-select-vanilla'
dist/
browser/
multiple-select.js # ESM build, use with: window.multipleSelect
multiple-select.cjs # CJS (CommonJS) build, use with: window.multipleSelect
locales/
multiple-select-all-locales.cjs # all-in-1 locales as CJS
multiple-select-all-locales.js # all-in-1 locales as ESM
..
multiple-select-fr-FR.cjs # French locale as CJS
multiple-select-fr-FR.js # French locale as ESM
...
styles/ # CSS and SASS Stylings
css/
sass/
index.d.ts # d.ts Type Definitions
multiple-select.cjs # CJS (CommonJS), used by: require()
multiple-select.js # ESM, used by: import from
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:
Pull Request are welcome, feel free to contribute.
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 install
ORnpx pnpm install
- run a full TypeScript build
pnpm run build
ORnpx pnpm run build
- run in development mode (lib & demo)
pnpm run dev
ORnpx pnpm run dev
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