@wizardhealth/stimulus-multiselect

Stimulus Multiselect controller

Multiselect component built on the back of stimulus and html select tag. Works with static imbedded json inside html, preloaded items from server and searching remotely.

Installation

If you are using a js bundler with node_modules support (such as esbuild, rollup.js or Webpack) install the package from npm:

yarn add stimulus-multiselect

If you're using importmap-rails, you'll need to pin stimulus-multiselect:

./bin/importmap pin stimulus-multiselect

Usage

Load your stimulus application as usual and the register the multiselect controller with it:

import { Application } from '@hotwired/stimulus'
import { Multiselect } from 'stimulus-multiselect'

const application = Application.start()
application.register('multiselect', Multiselect)

Remote search

To use the multiselect as a remote search component, you need some the following markup:

<div data-controller="multiselect" data-multiselect-search-url-value="/cars" data-placeholder="Search for cars...">
  <select multiple="multiple" class="multiselect__hidden" data-multiselect-target="hidden" name="form[test_ids][]" id="form_test_ids"></select>
</div>

The component makes a request to the data-multiselect-search-url to fetch results for the contents of the input field. The server must answer with a json array:

[
  {
    "value": "toyota",
    "text": "Jaris 🚗"
  },
  {
    "value": "ambulance",
    "text": "Ambulance 🚑"
  },
  {
    "value": "police",
    "text": "Police 🚓"
  },
  {
    "value": "taxi",
    "text": "Taxi 🚕"
  },
  {
    "value": "truck",
    "text": "Truck 🚚"
  }
]

Note: each object has to contain value and text. The server will receive a q query param that represents the search term. Another query param sent while searching is the preselects param that contains a set of already selected values in the multiselect (a string separated by a comma ",").

Preload

To preload items after rendering the page, you need some the following markup:

<div data-controller="multiselect" data-multiselect-preload-url-value="/cars" data-placeholder="Search for cars...">
  <select multiple="multiple" class="multiselect__hidden" data-multiselect-target="hidden" name="form[test_ids][]" id="form_test_ids"></select>
</div>

With this setup the component will search through the already preloaded components. In order to search remotely as well as preloading components we just need to add the data-multiselect-search-url-value attribute.

Note: the server response for the preload url needs to provide a json array just like in the example above.

Static collection

It is possible to use the data-multiselect-items-value attribute to load static json data. This is especially useful when your html is being preprocessed before being served (Rails ERB or as a React snippet - data-multiselect-items-value="<%= @cars.to_json %>").

<div data-controller="multiselect" data-multiselect-items-value='[{ "value": "cuckoo", "text": "Cuckoo 🐦"}, { "value": "macaw", "text": "Macaw 🦜"}, { "value": "rooster", "text": "Rooster 🐓"}]' data-placeholder="Search for birds...">
  <select multiple="multiple" class="multiselect__hidden" data-multiselect-target="hidden" name="form[test_ids][]" id="form_test_ids"></select>
</div>

Good to know

• The initial html markup contains a hidden select which serves as a hook for any forms that contain the multiselect. This select will reflect all changes on the multiselect. As an additional helper, if the multiselect is used outside of Stimulus scope, it is possible to get all the selected values via the values property:

document.getElementById("multiselect_id").values

• The multiselect comes with a .css file with some styles but feel free to change it when using it in your app.

TODO: Explain addable

Accessibility

• Arrow navigation on the elements in the dropdown
• Selecting elements with Enter key
• Close dropdown on Escape
• If search is empty Backspace deletes the last item

Events

• multiselect-change whenever an element is added or removed
• multiselect-removed whenever an element is removed. This event contains the value of the removed element in the events detail under id:

myFunction(event) {
  console.log(event.detail.id) // Should print the value of the item removed - 13
}

• multiselect-added whenever an element is added. This event contains the added object in the events detail under item:

myFunction(event) {
  console.log(event.detail.item) // Should print the added object - { "value": "test", "text": "Test" }
}

• multiselect-addable If the addable url is added to the multiselect when the search provides no results a link appears. Pressing this link fires this event. You can use this event as a hook to decide how you want to handle adding a non-existing element to the multiselect.

Examples

The current examples are contained in the examples folder. You can use the included http-server to test the examples.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/WizardComputer/stimulus-multiselect. Any contributions or suggestions are wellcome and will be considered. Please read the Contributor Covenant code of conduct.

Releasing

• Update the version number in package.json. Try to follow semantic versioning guidelines as much as possible.

• Publish the package to npmjs.com with yarn run release

License

This package is available as open source under the terms of the MIT License.