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 visit 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-vanilla

Changelog

CHANGELOG

LICENSE

MIT 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 section below)
• revamped the UI 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 "-", 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 by reading the widest list option width
  • dataTest will add a data-test attribute on the .ms-parent and .ms-drop divs for easier E2E testing
  • useSelectOptionLabel will 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)
  • useSelectOptionLabelToHtml similar to useSelectOptionLabel 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 adds an "OK" button at the end of the multiple select option list (see demo)
  • showSearchClear show a clear filter button on the search filter input (see demo)
  • diacriticParser custom parser to normalize diacritic symbols when filtering select list (see demo)
  • darkMode to enable our 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)

CSP Compliance

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 without unsafe-inline.

Installation / Structure

There are multiple ways to install and use the library, you can see below the folder structure of the distribution files

1. dist/browser: Standalone build which assigns multipleSelect on the window.multipleSelect object
   • browser standalone means that you can simply load it with <script></script> and then multipleSelect('#mySelect')
   • 2 builds are available CJS (.cjs) and ESM (.js) and for the latter you will need to load it with <script type="module">
2. cjs: to use as CommonJS with require('multiple-select-vanilla')
3. esm: to use as ESM with import 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

Used 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:

• Angular-Slickgrid
• Aurelia-Slickgrid
• Slickgrid-React
• Slickgrid-Universal

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.

1. clone the lib:
   • git clone https://github.com/ghiscoding/multiple-select-vanilla
2. install with pnpm from the root:
   • pnpm install OR npx pnpm install
3. run a full TypeScript build
   • pnpm run build OR npx pnpm run build
4. run in development mode (lib & demo)
   • pnpm run dev OR npx 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:

1. make sure that you have already executed pnpm install
2. run the Biome lint npm script (or simply jump to step 4)
   • pnpm run biome:lint:write
3. run the Biome code formatting npm script (or simply jump to step 4)
   • pnpm run biome:format:write
4. run a full Build (this will also run Biome lint/format, so you could skip step 2)
   • pnpm run build

Sponsors