[!IMPORTANT] HotwireCombobox is at an early stage of development. It's nearing a beta release, but the API might change and bugs are expected. Please continue to use the library and report any issues in the GitHub repo.
First, make sure Turbo and Stimulus are configured and running properly on your app.
Then, add this line to your application's Gemfile and run bundle install
:
gem "hotwire_combobox"
Finally, configure your assets:
Before continuing, you should know whether your app is using importmaps or JS bundling in your asset pipeline.
Most apps using importmaps won't need any configuration. If things aren't working for you, read on.
In app/javascript/controllers/index.js
you should have one of the following:
Either,
import { application } from "controllers/application" // or equivalent
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
eagerLoadControllersFrom("controllers", application)
Or,
import { application } from "controllers/application" // or equivalent
import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
lazyLoadControllersFrom("controllers", application)
Or,
import { application } from "controllers/application" // or equivalent
import HwComboboxController from "controllers/hw_combobox_controller"
application.register("hw-combobox", HwComboboxController)
First, install the JS portion of HotwireCombobox from npm with one of the following:
yarn add @josefarias/hotwire_combobox
npm install @josefarias/hotwire_combobox
Then, register the library's stimulus controller in app/javascript/controllers/index.js
as follows:
import { application } from "./application" // or equivalent
import HwComboboxController from "@josefarias/hotwire_combobox"
application.register("hw-combobox", HwComboboxController)
[!WARNING] Keep in mind you need to update both the npm package and the gem every time there's a new version of HotwireCombobox. You should always run the same version number on both sides.
This library comes with optional default styles. Follow the instructions below to include them in your app.
Read the docs section for instructions on styling the combobox yourself.
This approach works for all setups. Simply add the stylesheet to your layout (this would go in your document's <head>
):
<%= combobox_style_tag %>
This helper accepts any of the options you can pass to stylesheet_link_tag
.
Require the styles in app/assets/stylesheets/application.css
:
*= require hotwire_combobox
Visit the docs site for a demo and detailed documentation. If the site is down, you can run the docs locally by cloning the docs repo.
This gem follows the APG combobox pattern guidelines with some exceptions we feel increase the usefulness of the component without much detriment to the overall accessible experience.
These are the exceptions:
Up Arrow
when the user is on the first option will select the last option. And pressing Down Arrow
when on the last option will select the first option. In paginated comboboxes, the first and last options refer to the currently available options. More options may be loaded after navigating to the last currently available option.It should be noted none of the maintainers use assistive technologies in their daily lives. If you do, and you feel these exceptions are detrimental to your ability to use the component, or if you find an undocumented exception, please open a GitHub issue. We'll get it sorted.
Please read CONTRIBUTING.md.
The gem is available as open source under the terms of the MIT License.