Skip to content

Latest commit

 

History

History
147 lines (116 loc) · 8.78 KB

README.md

File metadata and controls

147 lines (116 loc) · 8.78 KB
Raw

Multiple-Select-Vanilla

License: MIT TypeScript Playwright npm Actions Status

Stable Release

We now have a fully working and official release including a Live demo for displaying all available options/methods. You can also take a look at the "Used by" section below to see real world applications taking advantage of this library.

Description

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.6.0. The main difference from the original lib is that we dropped jQuery and we now use native code and this mean zero external dependency. We also added a few extra features which you can see in the list 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.

Fully tested with Playwright

The Live demo website is also used by Playwright for E2E testing of the library, all examples are covered with Playwright tests.

Installation

npm install multiple-select-vanilla

Changelog

CHANGELOG

LICENSE

The MIT License

Changes vs Original lib (multiple-select)

New Multiple-Select Options:

  • dropped jQuery requirement and replaced necessary code with browser native code.
  • written in TypeScript which also brings typings support
  • add extra features:
    • 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 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=""> (from select option value) that can be used to display shorter text of selected options.
      • example: will show "1,3" 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 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)

CSP Compliance

The library is now CSP (Content Security Policy) compliant since v0.6.0, however there are some exceptions to be aware of. When using any html string as template (with 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 DOMPurify to return TrustedHTML as shown below and with that in place you will again 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 }),
   data: [
      {
         text: '<i class="fa fa-star"></i> January',
         value: 1,
      },
   ]
});

with this code in place, we can use the following CSP meta tag (which is what we use in the lib demo, ref: 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 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 use the library

  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 ESM 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
  cjs/
    multiple-select.cjs             # CJS (CommonJS), use with: require()
  esm/
    multiple-select.js              # ESM, use with: import from
  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/
  types/                            # d.ts Type Definitions

Used by

This fork was created mostly to drop jQuery, and is used by a few other libraries that I maintain:

Contributions

PR

Pull Request are welcome, feel free to contribute.

Development / Contributions

If you wish to contribute to the project, please follow these steps:

Note: this project uses pnpm workspaces, you can install pnpm by following their installation or simply run npx pnpm to run any of the pnpm scripts shown below:

  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 these steps for your PR to succeed:

  1. make sure that you already ran pnpm install
  2. run the Prettier code formatting npm script (or use step 3)
    • pnpm run prettier:write
  3. run a full Build (this will also run Prettier format, so you could skip step 2)
    • pnpm run build