hotwire_combobox is an accessible ARIA combobox for Rails apps on Hotwire

The problem: an autocomplete that screen readers can actually use

hotwire_combobox describes itself as an accessible autocomplete for Ruby on Rails, and the tagline is easy and accessible autocomplete for Ruby on Rails. The interesting part is what the accessibility claim rests on.

A native HTML select with a datalist, or a JavaScript autocomplete attached to a text input, is what most Rails applications reach for. Both are hard to use without a mouse and worse with a screen reader, because the ARIA roles, the live region announcements and the focus management all have to be built by hand for each project. The gem's answer is to implement the pattern once, properly.

The specific standard it follows is the APG combobox pattern guidelines from the W3C WAI-ARIA Authoring Practices. The README says the gem follows them with some exceptions the maintainers feel increase the usefulness of the component without much detriment to the overall accessible experience, and then it lists the exceptions, which is the part any reviewer should read.

The project is a Ruby gem with a JavaScript half. The primary language is Ruby, the licence is MIT, the homepage is hotwirecombobox.com, and the last push was on 2026-10-19 with the repository not archived. Recent releases are v0.4.1 from 2026-02-13, v0.4.0 from 2025-03-17 and v0.3.2 from 2024-08-31, and the version strings on the older two carry an alpha suffix, so the version line has been moving for two years.

The README's own status note is the first thing a reader should take in: HotwireCombobox is at an early stage of development, it is nearing a beta release, the API might change, and bugs are expected, with the request being to keep using the library and report issues.

Installing the gem and the JavaScript half, which must match

Installation has three parts and the middle one is where projects get stuck.

First, the README asks you to make sure Turbo and Stimulus are configured and running properly in the app, linking to turbo-rails and stimulus-rails. Then the gem goes in the Gemfile and you run bundle install:

gem "hotwire_combobox"

Then the assets. The configuration depends on whether the app uses importmaps or a JavaScript bundler, and the README covers both.

For importmaps, most apps need no configuration at all. If things are not working, the controller has to be registered, either by using eagerLoadControllersFrom or lazyLoadControllersFrom in app/javascript/controllers/index.js, or by editing app/javascript/controllers/application.js directly:

import { Application } from "@hotwired/stimulus"
const application = Application.start()

// Add the following two lines:
import HwComboboxController from "controllers/hw_combobox_controller"
application.register("hw-combobox", HwComboboxController)

export { application }

For bundlers such as esbuild or rollup, the JavaScript half is installed from npm, and the README gives two commands:

npm install @josefarias/hotwire_combobox

and the yarn equivalent. The registration then imports from the package rather than from the controllers path:

import { Application } from "@hotwired/stimulus"
const application = Application.start()

// Add the following two lines:
import HwComboboxController from "@josefarias/hotwire_combobox"
application.register("hw-combobox", HwComboboxController)

export { application }

And then the warning that shapes your release process: you need to update both the npm package and the gem every time there is a new version of HotwireCombobox, and you should always run the same version number on both sides. The package.json confirms the two are versioned in lockstep, with the npm package at 0.4.1 matching the v0.4.1 gem release.

The stylesheet helper and the Sprockets path

The CSS side is small, and the default approach is the one that works everywhere.

The library ships customizable default styles, and the universal way to include them is a helper in the layout, in the document's head:

<%= combobox_style_tag %>

The README notes this helper accepts any of the options you can pass to stylesheet_link_tag, so you can add a media attribute or a nonce without dropping back to writing the tag by hand.

For Sprockets users there is a second path, requiring the styles in app/assets/stylesheets/application.css:

*= require hotwire_combobox

The reason there are two paths is that the asset story differs across Rails setups, and the helper exists so that the common case does not need to know which one you are in.

If you want to style the combobox yourself rather than use the defaults, the README points at the docs section, and the docs site at hotwirecombobox.com carries a demo and the detailed documentation. The docs can also be run locally by cloning the separate docs repository, which is worth knowing if the site is down when you are trying to implement something specific.

The repository layout backs this up with a Gemfile, a gemspec, a package.json with a rollup build script, a lib directory, an app directory, a config directory, a docs directory, a test directory and a Procfile.dev, so the gem, the npm package and the documentation site are all built from one tree.

The three documented departures from the APG combobox pattern

The accessibility section is where this project is either trustworthy or not, and the README earns some of that trust by publishing its deviations rather than claiming full conformance.

The first exception is wrap-around selection in the listbox. Pressing Up Arrow when the user is on the first option selects the last option, and pressing Down Arrow on the last option selects the first. In paginated comboboxes, the first and last options refer to the currently available options, and more options may be loaded after navigating to the last currently available option. The stated reasoning is that this increases usefulness without much detriment to the accessible experience.

The second is that an unlabeled combobox is possible, with that responsibility delegated to the implementing user. This is the one that will matter most to a team with a design system, because it means the gem will not stop you from shipping a combobox with no accessible name, and the review of that has to happen in your own codebase.

The third is multiselect. There are currently no APG guidelines for a multiselect combobox, and the maintainers say they have introduced some mechanisms to make the experience accessible, such as announcing multi-selections via a live region, and they would welcome feedback on how to make it better until official guidelines are available.

One more note in the same section is worth repeating because it is unusual to see stated plainly: none of the maintainers use assistive technologies in their daily lives. They ask that anyone who does, and who finds these exceptions detrimental or finds an undocumented exception, open a GitHub issue, and says they will get it sorted. That is an admission of limits and a commitment to fix what is found, and it is a better position than silent conformance claims.

Where hotwire_combobox is the wrong tool

Three boundaries, and the first is a licensing and process one rather than a technical one.

The first is the dual package version lock. The gem and the npm package have to be on the same version at all times, and if your app uses a bundler with a lockfile and your CI pins the gem, then every release of the library is a coordinated update of two dependency trees. In a large application with a slow dependency review process, that is a recurring cost for a component you could have written once, badly, and fixed once.

The second is the pre-1.0 status, and the README does not soften it. The API might change and bugs are expected, and the maintainers ask you to keep using it and report issues. That is fine for an application you control, and less fine for a component you are building into a public interface where a change in behaviour is a breaking change for your users. The version history is consistent with the warning, since the two older releases carry alpha suffixes and the project is described as nearing a beta rather than being one.

The third is scope. The README documents the combobox itself, its registration, its styling and its accessibility exceptions. It does not document the server side of the search in any detail, so how the results are fetched, how pagination is driven and how the multi-select is submitted are things you learn from the docs site rather than from this page. If your requirement includes a specific selection model, such as multi-select with server-side persistence across a form, you need to read the full documentation before committing, and if your requirement is something else entirely, such as a command palette, a date picker or a tag editor, this gem is the wrong shape for it.

The alternative approach is to use the ARIA authoring practices pattern directly and implement it once in your own application, with your own controller and your own tests. The difference in approach is that the gem buys you a maintained implementation of a fiddly pattern and asks you to accept its three documented exceptions and its release coupling, while writing it yourself buys you exactly the behaviour you want at the cost of owning the ARIA details and the focus management that make the difference between an accessible and an inaccessible combobox in the first place.

Editorial conclusion

Adopt hotwire_combobox if you are building a Rails interface on Hotwire and need a combobox that is genuinely screen-reader usable rather than a styled input with a datalist, since the package implements the W3C APG combobox pattern and ships the ARIA plumbing with it. Do not adopt it if you cannot keep the gem and the npm package on the same version, because the README warns that both must be updated together, and do not treat it as a stable API, since the project says outright that the API might change and bugs are expected. Verify first that Turbo and Stimulus are configured in your app, that your asset pipeline can serve the stylesheet through the combobox_style_tag helper, that you can decide who labels the combobox since the gem allows an unlabelled one, and that the three documented deviations from the APG pattern, wrap-around selection, delegated labelling and the multiselect guidance, are acceptable for your users.

Frequently asked questions

Official sources

1. josefarias/hotwire_combobox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases