| name | hotwire-patterns |
| description | Turbo and Stimulus patterns for Rails applications. Use when implementing interactivity, real-time updates, or frontend behavior without JavaScript frameworks. |
| trigger | turbo, stimulus, hotwire, frame, stream, javascript, frontend, spa |
Hotwire Patterns
Philosophy
"The HTML-over-the-wire approach. Turbo lets you get the speed of a single-page app without writing JavaScript."
Core Principles:
- Server renders HTML, not JSON
- Turbo handles navigation and updates
- Stimulus adds JS behavior when needed
- No build step, no npm
Turbo Drive
Intercepts links and forms, fetches via AJAX, replaces <body>:
<%# Automatic - no code needed %>
<%= link_to "Dashboard", dashboard_path %>
<%# Disable for specific links %>
<%= link_to "External", "https://example.com", data: { turbo: false } %>
<%# Disable for a section %>
<div data-turbo="false">
<%= link_to "Legacy", legacy_path %>
</div>
Turbo Frames
Independent sections that update without full page reload:
<%# Define a frame %>
<%= turbo_frame_tag "card_#{@card.id}" do %>
<%= render @card %>
<% end %>
<%# Navigation within frame stays in frame %>
<%= turbo_frame_tag "card_#{@card.id}" do %>
<%= link_to "Edit", edit_card_path(@card) %>
<% end %>
<%# Break out of frame %>
<%= link_to "View Full", card_path(@card), data: { turbo_frame: "_top" } %>
Lazy Loading
<%= turbo_frame_tag "comments",
src: card_comments_path(@card),
loading: :lazy do %>
<p class="text-gray-500">Loading comments...</p>
<% end %>
Frame Targeting
<%# Link targets different frame %>
<%= link_to "Preview", preview_card_path(@card),
data: { turbo_frame: "preview" } %>
<%= turbo_frame_tag "preview" %>
Turbo Streams
Real-time DOM updates:
Actions
<%# Append to end of container %>
<%= turbo_stream.append "cards", @card %>
<%# Prepend to start %>
<%= turbo_stream.prepend "cards", @card %>
<%# Replace element %>
<%= turbo_stream.replace dom_id(@card), @card %>
<%# Update content (keep element) %>
<%= turbo_stream.update dom_id(@card), @card %>
<%# Remove element %>
<%= turbo_stream.remove dom_id(@card) %>
<%# Before/after specific element %>
<%= turbo_stream.before dom_id(@card), partial: "card", locals: { card: @new_card } %>
<%= turbo_stream.after dom_id(@card), partial: "card", locals: { card: @new_card } %>
Controller Response
class CardsController < ApplicationController
def create
@card = Current.user.cards.create!(card_params)
respond_to do |format|
format.html { redirect_to @card }
format.turbo_stream
end
end
end
<%# app/views/cards/create.turbo_stream.erb %>
<%= turbo_stream.prepend "cards", @card %>
<%= turbo_stream.update "card_count" do %>
<%= Card.count %> cards
<% end %>
<%= turbo_stream.update "flash", partial: "shared/flash" %>
Broadcasting (Real-time)
class Card < ApplicationRecord
after_create_commit -> { broadcast_prepend_to "cards" }
after_update_commit -> { broadcast_replace_to "cards" }
after_destroy_commit -> { broadcast_remove_to "cards" }
end
<%# Subscribe in view %>
<%= turbo_stream_from "cards" %>
<div id="cards">
<%= render @cards %>
</div>
Stimulus
Basic Controller
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["menu"]
static values = { open: Boolean }
static classes = ["hidden"]
connect() {
this.openValue = false
}
toggle() {
this.openValue = !this.openValue
}
openValueChanged() {
this.menuTarget.classList.toggle(this.hiddenClass, !this.openValue)
}
clickOutside(event) {
if (!this.element.contains(event.target)) {
this.openValue = false
}
}
}
<div data-controller="dropdown"
data-dropdown-hidden-class="hidden"
data-action="click@window->dropdown#clickOutside">
<button data-action="click->dropdown#toggle">
Menu
</button>
<div data-dropdown-target="menu" class="hidden">
<%= render "menu_items" %>
</div>
</div>
Common Patterns
Form Submission
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
submit() {
this.element.requestSubmit()
}
}
<%= form_with model: @filter, data: { controller: "auto-submit" } do |f| %>
<%= f.select :status, options, {}, data: { action: "change->auto-submit#submit" } %>
<% end %>
Clipboard
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["source"]
copy() {
navigator.clipboard.writeText(this.sourceTarget.value)
}
}
Debounce
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["input"]
search() {
clearTimeout(this.timeout)
this.timeout = setTimeout(() => {
this.element.requestSubmit()
}, 300)
}
}
Turbo Integration
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
connect() {
}
disconnect() {
}
beforeCache() {
this.element.innerHTML = ""
}
}
Best Practices
DO
- Use Turbo Frames for isolated updates
- Use Turbo Streams for multi-element updates
- Keep Stimulus controllers small (<50 lines)
- Use data attributes for configuration
- Progressive enhancement (works without JS)
DON'T
- Don't use npm/yarn packages
- Don't build SPAs with Stimulus
- Don't manipulate DOM directly (use Turbo)
- Don't store complex state in Stimulus
- Don't import React/Vue components
