Hotwire Patterns

Hotwire Patterns for Rails

Hotwire (HTML Over The Wire) provides a modern approach to building interactive Rails applications with minimal JavaScript. It consists of Turbo (Drive, Frames, Streams) and Stimulus.

Component Overview

Stimulus Essentials

Stimulus controllers add client-side behavior to HTML elements using data attributes.

Naming Conventions

• data-controller="search" maps to search_controller.js
• data-search-target="input" accesses this.inputTarget
• data-action="input->search#search" calls search() method
• data-search-url-value="/api/search" accesses this.urlValue
• data-search-active-class="highlighted" accesses this.activeClass

Declare targets, values, and classes as static properties. Always implement disconnect() to clean up event listeners and timers.

Turbo Frames Essentials

Turbo Frames decompose pages into independently updatable sections. Key principles:

• Use dom_id helper for unique, meaningful frame IDs
• Provide loading state content for lazy-loaded frames
• Use data-turbo-frame="_top" to break out of frame scope
• Wrap both show and edit views in the same frame tag for inline editing

Turbo Streams Actions

Respond with format.turbo_stream in controllers. Use .turbo_stream.erb templates for complex responses, or render inline for simple cases.

Review Checklists

Stimulus

• Controllers follow naming conventions (name_controller.js)
• Targets, values, and classes are declared as static properties
• Actions use proper event syntax (event->controller#method)
• No direct DOM queries — use targets instead
• disconnect() cleans up event listeners and timers

Turbo Frames

• Frame IDs are unique and meaningful (use dom_id helper)
• Loading states provide user feedback
• Frame boundaries are logical (don't wrap too much or too little)
• Non-Turbo fallback works for progressive enhancement

Turbo Streams

• Stream actions match the intended DOM update
• Target elements exist in the DOM before streaming
• Partials render correctly in isolation
• Broadcasting scope is appropriate (don't over-broadcast)

Performance

• No unnecessary full-page reloads (Turbo Drive not disabled broadly)
• DOM updates are targeted (prefer replace over full refresh)
• Caching still works with frames and streams
• JavaScript bundle size is reasonable

Quick Reference

Additional Resources

Reference Files

For detailed code examples and implementation patterns, consult:

• references/stimulus-patterns.md — Stimulus controller examples (search, toggle, form feedback) and conventions table
• references/turbo-frames-patterns.md — Turbo Frames examples (basic frames, lazy loading, inline editing, breaking out) and Turbo Drive configuration
• references/turbo-streams-patterns.md — Turbo Streams controller responses, templates, inline streams, ActionCable model broadcasting, custom broadcasting, and morphing (Rails 7.1+)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.