hotwire

name: hotwire description: "Build modern Rails interfaces with Hotwire (Turbo + Stimulus). Use when implementing: (1) Page navigation and form handling with Turbo Drive, (2) Partial page updates with Turbo Frames, (3) Real-time DOM updates with Turbo Streams, (4) JavaScript behaviors with Stimulus controllers, (5) WebSocket broadcasts with Action Cable, (6) Any interactive UI without heavy JavaScript frameworks."

Hotwire

Hotwire sends HTML over the wire instead of JSON, enabling SPA-like interactivity without JavaScript frameworks.

Decision Framework

Choose the right tool for each interaction:

Rule of thumb: Use Turbo for server-driven updates, Stimulus for client-side behavior.

Turbo Frames Quick Reference

Wrap content in a frame to scope navigation:

<%= turbo_frame_tag @todo do %>
  <p><%= @todo.description %></p>
  <%= link_to "Edit", edit_todo_path(@todo) %>
<% end %>

Clicking "Edit" replaces only this frame with the matching frame from the response.

Lazy loading:

<%= turbo_frame_tag "sidebar", src: sidebar_path, loading: "lazy" %>

Break out of frame:

<%= link_to "Full page", path, data: { turbo_frame: "_top" } %>

See references/turbo.md for complete Turbo documentation.

Turbo Streams Quick Reference

Stream actions for DOM updates:

Controller response:

respond_to do |format|
  format.turbo_stream
  format.html { redirect_to @item }
end

Template (create.turbo_stream.erb):

<%= turbo_stream.append :items, @item %>
<%= turbo_stream.update :form, partial: "form" %>

Real-time broadcasts:

# In model
broadcasts_refreshes  # Simple: triggers page refresh with morphing

# Or manual:
broadcast_append_to :items, target: :items

See references/turbo.md for stream actions and broadcasting.

Stimulus Quick Reference

Controller structure:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["input", "output"]
  static values = { url: String, count: { type: Number, default: 0 } }
  static classes = ["active"]
  static outlets = ["other-controller"]

  connect() { /* called when controller connects to DOM */ }
  disconnect() { /* called when removed from DOM */ }

  // Action methods (called from data-action)
  submit() {
    this.outputTarget.textContent = this.inputTarget.value
    this.countValue++
    this.dispatch("submitted", { detail: { value: this.inputTarget.value } })
  }

  // Private methods
  #helperMethod() { }
}

HTML:

<div data-controller="example"
     data-example-url-value="/api"
     data-example-active-class="is-active">
  <input data-example-target="input" data-action="input->example#submit">
  <span data-example-target="output"></span>
</div>

Action syntax: event->controller#method

• Default events: click for buttons, submit for forms, input for inputs
• Modifiers: :prevent, :stop, :once, @window, @document
• Key filters: keydown.enter->controller#method

See references/stimulus.md for complete reference.

Rails Helpers

Turbo Frame tag:

<%= turbo_frame_tag @model %>
<%= turbo_frame_tag @model, :section %>
<%= turbo_frame_tag "custom_id", src: path, loading: "lazy" %>

Turbo Stream tag:

<%= turbo_stream.append :target, partial: "item", locals: { item: @item } %>
<%= turbo_stream.replace @model %>
<%= turbo_stream.remove @model %>

Stimulus controller generator:

bin/rails generate stimulus controller_name

See references/rails-integration.md for helpers and setup.