<pressbooks-multiselect>

A web component which enhances the native <select multiple> element, built with Lit. This web component follows the open-wc recommendations.

It owes a great debt to prior work and research by Sarah Higley.

Installation

npm i @pressbooks/multiselect

Usage

Wrap a <select> element with the multiple attribute and a semantically valid label in the <pressbooks-multiselect> tag.

<script type="module">
  import '@pressbooks/multiselect/pressbooks-multiselect.js';
</script>

<pressbooks-multiselect>
  <label for="selections">Multiple Selections</label>
  <select id="selections" name="selections[]">
    <option value="option-1">Option 1</option>
    <!-- Et cetera. -->
  </select>
</pressbooks-multiselect>

If you wrap a single select or a select element without a valid label, the component will not render and your existing markup will be displayed without modification.

If the <select> element has a relationship with a hint via the aria-describedby attribute, the hint will be attached to the rendered component as well. If you'd like the hint to appear after the rendered component, add the slot="after" attribute to it:

<pressbooks-multiselect>
  <label for="selections">Multiple Selections</label>
  <select id="selections" name="selections[]" aria-describedby="selections-hint">
    <option value="option-1">Option 1</option>
    <!-- Et cetera. -->
  </select>
  <p id="selections-hint" slot="after">Pick some!</p>
</pressbooks-multiselect>

If you group options within the <select> using <optgroup> elements, the multiselect will group options using the ARIA grouped listbox pattern.

Styling

Because this web component uses the Shadow Dom, styling is limited to modification via CSS custom properties. However, there are plenty to choose from.

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Testing with Web Test Runner

To execute a single test run:

npm run test

To run the tests in interactive watch mode run:

npm run test:watch

Demoing with Storybook

To run a local instance of Storybook for your component, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

Tooling configs

For most of the tools, the configuration is in the package.json to minimize the amount of files in your project.

If you customize the configuration a lot, you can consider moving them to individual files.

Local Demo with web-dev-server

npm start

To run a local development server that serves the basic demo located in demo/index.html

Publishing to NPM

As this is a scoped package it must be published by someone within the Pressbooks NPM organization and must use the --access public flag:

npm publish --access public