├── .github
└── workflows
│ └── ci.yml
├── .gitignore
├── LICENSE
├── README.md
├── cypress.json
├── cypress
├── integration
│ └── multiselect.js
└── support
│ ├── commands.js
│ └── index.js
├── examples
├── cars.json
├── index.html
├── preload.html
├── search.html
├── static.html
├── stimulus-multiselect.css
└── stimulus-multiselect.js
├── package-lock.json
├── package.json
├── src
├── multiselect.css
└── multiselect.js
└── yarn.lock
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | name: Tests
2 | on: [push, pull_request]
3 | jobs:
4 | cypress-run:
5 | runs-on: ubuntu-latest
6 | steps:
7 | - name: Checkout
8 | uses: actions/checkout@v3
9 |
10 | - name: Run tests
11 | uses: cypress-io/github-action@v3
12 | with:
13 | command: yarn run test
14 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | /node_modules
3 | yarn-error.log
4 | cypress/screenshots/
5 | cypress/videos/
6 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2022 Vernes
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Stimulus Multiselect controller
2 | 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.
3 |
4 | 
5 |
6 | ## Installation
7 |
8 | If you are using a js bundler with `node_modules` support (such as esbuild, rollup.js or Webpack) install the package from npm:
9 |
10 | ```plain
11 | yarn add @wizardhealth/stimulus-multiselect
12 | ```
13 |
14 | If you're using [importmap-rails](https://github.com/rails/importmap-rails), you'll need to pin `@wizardhealth/stimulus-multiselect`:
15 |
16 | ```plain
17 | ./bin/importmap pin @wizardhealth/stimulus-multiselect
18 | ```
19 |
20 | ## Usage
21 |
22 | Load your stimulus application as usual and the register the multiselect
23 | controller with it:
24 |
25 | ```javascript
26 | import { Application } from '@hotwired/stimulus'
27 | import { Multiselect } from '@wizardhealth/stimulus-multiselect'
28 |
29 | const application = Application.start()
30 | application.register('multiselect', Multiselect)
31 | ```
32 |
33 | ### Remote search
34 |
35 | Fetches the data from the server by specifying endpoint url in `data-multiselect-search-url` attribute.
36 | This is useful when you have a lot of data to load and you don't want to load it all at once.
37 |
38 | Example:
39 | ```html
40 |
41 |
43 | ```
44 |
45 | 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:
46 |
47 | ```json
48 | [
49 | {
50 | "value": "toyota",
51 | "text": "Jaris 🚗"
52 | },
53 | {
54 | "value": "ambulance",
55 | "text": "Ambulance 🚑"
56 | },
57 | {
58 | "value": "police",
59 | "text": "Police 🚓"
60 | },
61 | {
62 | "value": "taxi",
63 | "text": "Taxi 🚕"
64 | },
65 | {
66 | "value": "truck",
67 | "text": "Truck 🚚"
68 | }
69 | ]
70 | ```
71 |
72 | **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 ",").
73 |
74 | ### Preload
75 |
76 | Fetches the data from the server when the page renders by specifying endpoint url in `data-preload-preload-url` attribute.
77 | This is useful for small to medium size datasets that will not slow the page load.
78 |
79 | Example:
80 | ```html
81 |
82 |
84 | ```
85 |
86 | 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.
87 |
88 | **Note**: the server response for the preload url needs to provide a json array just like in the example above.
89 |
90 | ### Static collection
91 |
92 | 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 %>"`).
93 |
94 | ```html
95 |
96 |
98 | ```
99 |
100 | ## Good to know
101 |
102 | - 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:
103 |
104 | ```js
105 | document.getElementById("multiselect_id").values
106 | ```
107 |
108 | - The multiselect comes with a .css file with some styles but feel free to change it when using it in your app.
109 |
110 | ### Accessibility
111 |
112 | - Arrow navigation on the elements in the dropdown
113 | - Selecting elements with Enter key
114 | - Close dropdown on Escape
115 | - If search is empty Backspace deletes the last item
116 |
117 |
118 | ## Events
119 |
120 | - `multiselect-change` whenever an element is added or removed
121 | - `multiselect-removed` whenever an element is removed. This event contains the value of the removed element in the events `detail` under `id`:
122 |
123 | ```javascript
124 | myFunction(event) {
125 | console.log(event.detail.id) // Should print the value of the item removed - 13
126 | }
127 | ```
128 |
129 | - `multiselect-added` whenever an element is added. This event contains the added object in the events `detail` under `item`:
130 |
131 | ```javascript
132 | myFunction(event) {
133 | console.log(event.detail.item) // Should print the added object - { "value": "test", "text": "Test" }
134 | }
135 | ```
136 | - `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.
137 |
138 | ## Examples
139 |
140 | The current examples are contained in the [examples folder](https://github.com/WizardComputer/stimulus-multiselect/tree/main/examples). You can use the included http-server to test the examples.
141 |
142 | ## Contributing
143 |
144 | 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](https://www.contributor-covenant.org/).
145 |
146 |
147 | ## TODO
148 | * Explain addable
149 | * Explain preselecting
150 |
151 |
152 | ## Releasing
153 |
154 | 1. Update the version number in `package.json`. Try to follow semantic versioning guidelines as much as possible.
155 |
156 | 2. Publish the package to npmjs.com with `yarn run release`
157 |
158 | ## License
159 |
160 | This package is available as open source under the terms of the MIT License.
161 |
--------------------------------------------------------------------------------
/cypress.json:
--------------------------------------------------------------------------------
1 | {
2 | "baseUrl": "http://localhost:3300",
3 | "pluginsFile": false
4 | }
--------------------------------------------------------------------------------
/cypress/integration/multiselect.js:
--------------------------------------------------------------------------------
1 | describe("Stimulus multiselect", () => {
2 | const resultsListSelector = "[data-multiselect-target='list'] li"
3 |
4 | it("displays results on click", () => {
5 | cy.visitPage()
6 | cy.clickOnSelect()
7 | cy.get(resultsListSelector).should("have.length", 3)
8 | })
9 |
10 | it("filters results on base on the search term", () => {
11 | cy.visitPage()
12 |
13 | cy.enterSearchTerm("Roost")
14 | cy.get(resultsListSelector).should("have.length", 1)
15 |
16 | cy.enterSearchTerm("no-results")
17 | cy.get(resultsListSelector).should('not.exist')
18 | })
19 | })
--------------------------------------------------------------------------------
/cypress/support/commands.js:
--------------------------------------------------------------------------------
1 | const resultsListSelector = "[data-multiselect-target='list'] li"
2 | const input = "[data-multiselect-target='search']"
3 |
4 | Cypress.Commands.add("visitPage", (path = "/") => {
5 | cy.visit(path)
6 | })
7 |
8 | Cypress.Commands.add("enterSearchTerm", (term) => {
9 | cy.get(input).type(term)
10 | })
11 |
12 | Cypress.Commands.add("clickOnSelect", () => {
13 | const element = cy.get(".multiselect__container")
14 | element.click()
15 | })
16 |
--------------------------------------------------------------------------------
/cypress/support/index.js:
--------------------------------------------------------------------------------
1 | import './commands'
2 |
3 |
--------------------------------------------------------------------------------
/examples/cars.json:
--------------------------------------------------------------------------------
1 | [
2 | { "value": "toyota", "text": "Jaris 🚗" },
3 | { "value": "ambulance", "text": "Ambulance 🚑" },
4 | { "value": "police", "text": "Police 🚓" },
5 | { "value": "taxi", "text": "Taxi 🚕" },
6 | { "value": "truck", "text": "Truck 🚚" }
7 | ]
--------------------------------------------------------------------------------
/examples/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Stimulus Multiselect
7 |
8 |
31 |
Stimulus multiselect example
32 |
33 |
38 |
Stimulus Multiselect
7 |
8 |
31 |
Stimulus multiselect example
32 |
33 |
38 |
Stimulus Multiselect
7 |
8 |
31 |
Stimulus multiselect example
32 |
The search will show all items since this http-server doesnt have an actual backend to filter out the results
33 |
38 |
Stimulus Multiselect
7 |
8 |
32 |
Stimulus multiselect example
33 |
34 |
39 |
",
10 | "license": "MIT",
11 | "private": false,
12 | "keywords": [
13 | "stimulus",
14 | "multiselect",
15 | "controller",
16 | "components"
17 | ],
18 | "repository": {
19 | "type": "git",
20 | "url": "https://github.com/BakiVernes/stimulus-multiselect"
21 | },
22 | "bugs": {
23 | "url": "https://github.com/BakiVernes/stimulus-multiselect/issues"
24 | },
25 | "homepage": "https://github.com/BakiVernes/stimulus-multiselect",
26 | "peerDependencies": {
27 | "@hotwired/stimulus": "^3.1.0"
28 | },
29 | "devDependencies": {
30 | "@hotwired/stimulus": "^3.1.0",
31 | "cypress": "^9.2.0",
32 | "http-server": "^14.0.0",
33 | "start-server-and-test": "^1.14.0"
34 | },
35 | "scripts": {
36 | "start": "http-server ./examples -p 3300",
37 | "cy:run": "cypress run",
38 | "test": "start-server-and-test start http://localhost:3300 cy:run",
39 | "postversion": "git push && git push --tags",
40 | "release": "yarn test && yarn version && npm adduser && npm publish"
41 | }
42 | }
43 |
--------------------------------------------------------------------------------
/src/multiselect.css:
--------------------------------------------------------------------------------
1 | .multiselect__container {
2 | font-family: sans-serif;
3 | padding-top: 0.4rem;
4 | padding-bottom: 0.4rem;
5 | padding-right: 1.75rem;
6 | padding-left: 0.5rem;
7 | background: url("data:image/svg+xml;utf8,
313 |
314 |
315 |
${this.inputTemplate}
316 |
318 |
319 |
320 | ${this.allItems}
321 |
322 |
323 |
${this.element.dataset.noResultsMessage}
`
329 | return `
330 |
331 |
332 | ${this.element.dataset.addablePlaceholder}
333 |
334 |
335 | `
336 | }
337 |
338 | get inputTemplate() {
339 | return `
340 |
374 |
375 | ${item.text}
378 |
379 |
380 | `
381 | }
382 |
383 | checkBoxChange(event) {
384 | event.preventDefault()
385 | this.searchTarget.focus()
386 | this.toggleItem(event.currentTarget)
387 | }
388 |
389 | pillTemplate(item) {
390 | if (this.disabledValue) {
391 | return `
392 | ${item.text}
393 |
`
394 | } else {
395 | return `
396 |
${item.text}
397 |
398 |
399 |
402 |
403 |