npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@wizardhealth/stimulus-multiselect

v1.0.0

Published

Multiselect component built on the back of stimulus and html select tag

Downloads

30,880

Readme

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.

multiselect

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

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

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