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 @wizardhealth/stimulus-multiselect

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

./bin/importmap pin @wizardhealth/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 '@wizardhealth/stimulus-multiselect'

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

Remote search

Fetches the data from the server by specifying endpoint url in data-multiselect-search-url attribute. This is useful when you have a lot of data to load and you don't want to load it all at once.

Example:

<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

Fetches the data from the server when the page renders by specifying endpoint url in data-preload-preload-url attribute. This is useful for small to medium size datasets that will not slow the page load.

Example:

<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.

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.

TODO

Explain addable
Explain preselecting

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.

christianrojas / stimulus-multiselect