Troubleshooting

Component renders but interactions do nothing

Symptom. A dialog/menu/accordion/etc. renders fine, looks fine, but clicking the trigger does nothing. No errors in the browser console.

Root cause (99% of the time). The Stimulus identifier on the rendered HTML does not match the identifier your controllers/index.js registered. Stimulus is silent about this: no controller matches the element, so nothing fires.

Diagnosis ladder

1. Inspect the rendered DOM. Find the component's wrapper element and read the data-controller attribute. That string is the source of truth.
2. Compare it to app/javascript/controllers/index.js. Find the application.register("...", XController) line for that component. The first argument must match exactly.
   • If the DOM says data-controller="dialog", you need application.register("dialog", ...).
   • If the DOM says data-controller="rui--dialog", you need application.register("rui--dialog", ...).
3. Check config.stimulus_namespace in config/initializers/rapid_rails_ui.rb. If it's set to "rui", every gem-emitted identifier is prefixed with rui--. The cleanest fix is to re-run the installer with --stimulus-namespace=rui, which rewrites index.js to match. See Stimulus Namespace .
4. Custom triggers in your own templates. If you wrote <button data-action="dialog#open"> outside the component slot, that action string must use the same identifier the gem emits. With stimulus_namespace = "rui", write data-action="rui--dialog#open" — or use the stimulus_action(:dialog, "click->#open") helper, which adapts automatically.
5. v0.47.0 with namespace set: known caveat. On v0.47.0, a handful of internal component templates (Dialog, Pagination, Steps) still emit hardcoded unnamespaced action strings for built-in close / backdrop / paginate handlers. Custom triggers you write yourself work; built-in ones may not. Patched in the next release.

esbuild fails: "The symbol X has already been declared"

Your app already declares a JS class named AccordionController, DialogController, etc., and esbuild trips when the gem imports its same-named class into the same module.

Re-run the installer with the namespace-imports flag (v0.46.0+):

rails g rapid_rails_ui:install --namespace-imports=Rui

Full context on the Installation page (advanced section).

Native inputs render alongside the gem's styled inputs

A bare <input type="checkbox"> sits next to (or on top of) the gem's styled checkbox. Same pattern can appear with radio, text, or search inputs.

Root cause: your host app has an unscoped global rule like input[type="checkbox"] { ... } that wins on specificity against the gem's .sr-only. Surgical fix: exclude the gem's hidden inputs by adding :not(.sr-only):not(.peer) to each selector. Full walkthrough on the Installation page .