multiselector component test

Web component demo

<multi-selector> is a web component that lets a user select multiple options from a drop-down menu:

Arbitrarily nested groups of options
Searchable
Easy to control and navigate (also with the keyboard)
Reads options from JSON or mark up
Style with custom properties
VanillaJS (no dependencies)

On this page you will find several examples of how to use this web component.

Load from JSON
Load from DOM
Categories with optgroup
Control & navigation
Form integration
Disable
Styling with custom properties
Alternatives

Load from JSON

Supply the data as JSON using the src attribute of <multi-selector>.

The data should be provided in this format:

{ "label": "label", "value": "value", "children": [] }

See soaps.json for an example.

It is also possible to provide the data as a nested object where the options are given as strings in an array. <multi-selector> will convert this to the format above.

See countries.json for an example.


  <!-- html -->
  <multi-selector
    src="data/countries.json"
    name="countries">
  </multi-selector>

Load from DOM

Populate <multi-selector> with markup by using <option> tags. <multi-selector> will assume that the value of an option is its text content unless a value attribute is supplied.

Adding options to the DOM automatically will update the web component.

Note that updating the web component will completely re-render it.

Add a color to the color selector:


  <!-- html -->
  <multi-selector name="colors">
    <option>Red</option>
    <option>Yellow</option>
    <option>Green</option>
    <option>Blue</option>
  </multi-selector>

Categories with optgroup

Use <optgroup> tags to categorize options. Unlike the default <optgroup> tag (see MDN) it can be nested.

Set labels and values with the label and value attributes. If not present labels and values will be set from the textContent.


  <!-- html -->
  <multi-selector name="instruments">
  <optgroup label="String instruments" value="string">
      <optgroup label="Guitar" value="guitar">
          <option value="acoustic">Acoustic</option>
          <option value="electric">Electric</option>
      </optgroup>
      <option value="violin">Violin</option>
      <option value="cello">Cello</option>
  </optgroup>
  <optgroup label="Wind instruments" value="wind">
      <optgroup label="Brass instruments" value="brass">
          <option value="trumpet">Trumpet</option>
          <option value="trombone">Trombone</option>
          <option value="saxophone">Saxophone</option>
      </optgroup>
      <optgroup label="Woodwind instruments" value="woodwind">
          <option value="flute">Flute</option>
          <option value="clarinet">Clarinet</option>
      </optgroup>
  <optgroup label="Percussion instruments" value="percussion">
      <option value="drums">Drums</option>
      <option value="xylophone">Xylophone</option>
      <option value="marimba">Marimba</option>
  </optgroup>
  </multi-selector>

(De)select groups of options using the group checkboxes.
Use the search input to filter options by key-word.
Use the ☑-button or use ctrl-\ to show only the selected options.
Use the ⨯-button or use ctrl-/ show all options (clear applied filter).
(Un)fold all groups at once with the folding buttons in the control panel or use ctrl-[ and ctrl-] to fold/unfold when the component is in focus.
Use up, down, home, end and tab to navigate through groups and options with the keyboard.
Close the component with esc.


  <!-- html -->
  <multi-selector
    src="data/fallacies.json"
    name="fallacies">
  </multi-selector>

Disable

Disable <multi-selector> with the disabled attribute.

Also note that the placeholder-attribute can be used to provide the user a brief hint to the expected input.

The component dispatches change events whenever an option is (de)selected. Check the console to see it in action.


  <!-- html -->
  <multi-selector
    name="Select genres"
    src="data/genres.json"
    placeholder=
      "What are your favorite media genres?"
    disabled>
  </multi-selector>

Form integration

Use <multi-selector> within a <form>.

Selected options will be stored as a stringified JSON array.

The selectedValues property on the <multi-selector> element will return the selection as an array.

Form data


  <!-- html -->
  <form>
    <label for="Albums">Select albums</label>
    <multi-selector
      src="data/albums.json"
      name="Albums"
      placeholder=
        "Select Captain Beefheart albums...">
    </multi-selector>
    <button type="submit">submit</button>
  </form>

Styling with custom properties

Some simple styling is possible using custom properties. The following properties are available:

--ms-primary-color
--ms-primary-color-disabled
--ms-background:
--ms-option-hover
--ms-text-color
--ms-text-color-disabled
--ms-main-padding
--ms-border-radius
--ms-button-color
--ms-button-hover
--ms-button-active
--ms-accent-color
--ms-search-background
--ms-search-text-color
--ms-search-placeholder-color
--ms-max-height


  /* css */
  .styling-example multi-selector {
    --ms-primary-color:
      hsl(120, 24%, 55%);
    --ms-background:
      hsl(120, 24%, 25%);
    --ms-search-background:
      hsl(120, 24%, 35%);
    --ms-search-placeholder-color:
      hsl(0, 5%, 68%);
    --ms-text-color:
      hsl(0, 5%, 84%);
    --ms-accent-color:
      hsl(120, 24%, 15%);
    --ms-button-background:
      hsl(120, 20%, 44%);
    --ms-button-hover:
      hsl(120, 20%, 57%);
    --ms-button-active:
      hsl(120, 20%, 67%);
    width: 240px;
    margin: 0;
  }

Multi-Selector