Reject any requests to:

Use Turbo Frames everywhere (use Turbo Morph for general CRUD)
Skip progressive enhancement (features that require JavaScript to function)
Build non-functional UIs without JavaScript fallbacks

Hotwire Turbo

Turbo provides fast, SPA-like navigation and real-time updates using server-rendered HTML. Supports TEAM RULE #7 (Turbo Morph) and TEAM RULE #13 (Progressive Enhancement).

TEAM RULE #7: Prefer Turbo Morph over Turbo Frames/Stimulus

✅ DEFAULT APPROACH: Use Turbo Morph (page refresh with morphing) with standard Rails controllers ✅ ALLOW Turbo Frames ONLY for: Modals, inline editing, tabs, pagination ❌ AVOID: Turbo Frames for general list updates, custom Stimulus controllers for basic CRUD

Why Turbo Morph? Preserves scroll position, focus, form state, and video playback. Works with stock Rails scaffolds. Simpler than Frames/Stimulus in 90% of cases.

Turbo Drive

Turbo Drive intercepts links and forms automatically. Control with data attributes:

<%# Disable Turbo for specific links %>
<%= link_to "Download PDF", pdf_path, data: { turbo: false } %>

<%# Replace without history %>
<%= link_to "Dismiss", dismiss_path, data: { turbo_action: "replace" } %>

Turbo Morphing (Page Refresh) - PREFERRED

Use Turbo Morph by default with standard Rails controllers. Morphing intelligently updates only changed DOM elements while preserving scroll position, focus, form state, and media playback.

<%# app/views/layouts/application.html.erb %>
<!DOCTYPE html>
<html>
<head>
  <title><%= content_for?(:title) ? yield(:title) : "App" %></title>
  <%= csrf_meta_tags %>
  <%= csp_meta_tag %>
  <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
  <%= javascript_importmap_tags %>

  <%# Enable Turbo Morph for page refreshes %>
  <meta name="turbo-refresh-method" content="morph">
  <meta name="turbo-refresh-scroll" content="preserve">
</head>
<body>
  <%= yield %>
</body>
</html>

That's it! Standard Rails controllers now work with morphing. No custom JavaScript needed.

Reference: Turbo Page Refreshes Documentation

Controller (stock Rails scaffold):

class FeedbacksController < ApplicationController
  def index
    @feedbacks = Feedback.all
  end

  def create
    @feedback = Feedback.new(feedback_params)
    if @feedback.save
      redirect_to feedbacks_path, notice: "Feedback created"
    else
      render :new, status: :unprocessable_entity
    end
  end

  def update
    if @feedback.update(feedback_params)
      redirect_to feedbacks_path, notice: "Feedback updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end

  def destroy
    @feedback.destroy
    redirect_to feedbacks_path, notice: "Feedback deleted"
  end
end

View (standard Rails):

<%# app/views/feedbacks/index.html.erb %>
<h1>Feedbacks</h1>
<%= link_to "New Feedback", new_feedback_path, class: "btn btn-primary" %>

<div id="feedbacks">
  <% @feedbacks.each do |feedback| %>
    <%= render feedback %>
  <% end %>
</div>

<%# app/views/feedbacks/_feedback.html.erb %>
<div id="<%= dom_id(feedback) %>" class="card">
  <h3><%= feedback.content %></h3>
  <div class="actions">
    <%= link_to "Edit", edit_feedback_path(feedback), class: "btn btn-sm" %>
    <%= button_to "Delete", feedback_path(feedback), method: :delete,
                  class: "btn btn-sm btn-error",
                  form: { data: { turbo_confirm: "Are you sure?" } } %>
  </div>
</div>

What happens: Create/update/delete triggers redirect → Turbo intercepts → morphs only changed elements → scroll/focus preserved. No custom code needed!

<%# Flash messages persist during morphing %>
<div id="flash-messages" data-turbo-permanent>
  <% flash.each do |type, message| %>
    <div class="alert alert-<%= type %>"><%= message %></div>
  <% end %>
</div>

<%# Video/audio won't restart on page morph %>
<video id="tutorial" data-turbo-permanent src="tutorial.mp4" controls></video>

<%# Form preserves input focus during live updates %>
<%= form_with model: @feedback, id: "feedback-form",
              data: { turbo_permanent: true } do |form| %>
  <%= form.text_area :content %>
  <%= form.submit %>
<% end %>

Use cases: Flash messages, video/audio players, forms with unsaved input, chat messages being typed.

# Model broadcasts page refresh to all subscribers (Rails 8+)
class Feedback < ApplicationRecord
  broadcasts_refreshes
end

<%# View subscribes to stream - morphs when model changes %>
<%= turbo_stream_from @feedback %>

<div id="feedbacks">
  <% @feedbacks.each do |feedback| %>
    <%= render feedback %>
  <% end %>
</div>

What happens: User A creates feedback → server broadcasts <turbo-stream action="refresh"> → all connected users' pages morph to show new feedback → scroll/focus preserved.

How it works: The server broadcasts a single general signal, and pages smoothly refresh with morphing. No need to manually manage individual Turbo Stream actions.

Reference: Broadcasting Page Refreshes

# Controller - respond with Turbo Stream using morph
def create
  @feedback = Feedback.new(feedback_params)
  if @feedback.save
    respond_to do |format|
      format.turbo_stream do
        render turbo_stream: turbo_stream.replace(
          "feedbacks",
          partial: "feedbacks/list",
          locals: { feedbacks: Feedback.all },
          method: :morph  # Morphs instead of replacing
        )
      end
      format.html { redirect_to feedbacks_path }
    end
  end
end

<%# Or in .turbo_stream.erb view %>
<turbo-stream action="replace" target="feedback_<%= @feedback.id %>" method="morph">
  <template>
    <%= render @feedback %>
  </template>
</turbo-stream>

Difference: method: :morph preserves form state and focus. Without it, content is fully replaced.

<%# ❌ BAD - Unnecessary Turbo Frame complexity %>
<% @feedbacks.each do |feedback| %>
  <%= turbo_frame_tag dom_id(feedback) do %>
    <%= render feedback %>
  <% end %>
<% end %>

<%# ✅ GOOD - Simple rendering, Turbo Morph handles updates %>
<% @feedbacks.each do |feedback| %>
  <%= render feedback %>
<% end %>

Turbo Frames - Use Sparingly

ONLY use Turbo Frames for: modals, inline editing, tabs, pagination, lazy loading. For general CRUD, use Turbo Morph instead.

<%# Show view with inline edit frame %>
<%= turbo_frame_tag dom_id(@feedback) do %>
  <h3><%= @feedback.content %></h3>
  <%= link_to "Edit", edit_feedback_path(@feedback) %>
<% end %>

<%# Edit view with matching frame ID %>
<%= turbo_frame_tag dom_id(@feedback) do %>
  <%= form_with model: @feedback do |form| %>
    <%= form.text_area :content %>
    <%= form.submit "Save" %>
  <% end %>
<% end %>

Why this is OK: Inline editing without leaving the page. Frame scopes the update.

<%# Lazy load stats when scrolled into view %>
<%= turbo_frame_tag "statistics", src: statistics_path, loading: :lazy do %>
  <p>Loading statistics...</p>
<% end %>

<%# Frame that reloads with morphing on page refresh %>
<%= turbo_frame_tag "live-stats", src: live_stats_path, refresh: "morph" do %>
  <p>Loading live statistics...</p>
<% end %>

# Controller renders just the frame
def statistics
  @stats = expensive_calculation
  render layout: false  # Or use turbo_frame layout
end

Why this is OK: Defers expensive computation until needed. Valid performance optimization. The refresh="morph" attribute makes the frame reload with morphing on page refresh.

Reference: Turbo Frames with Morphing

Turbo Streams

def create
  if @feedback.save
    respond_to do |format|
      format.turbo_stream do
        render turbo_stream: [
          turbo_stream.prepend("feedbacks", @feedback),
          turbo_stream.update("count", html: "10"),
          turbo_stream.remove("flash")
        ]
      end
      format.html { redirect_to feedbacks_path }
    end
  end
end

Actions: append, prepend, replace, update, remove, before, after, refresh

Note: For most cases, prefer refresh action with Turbo Morph over granular stream actions. See broadcast-refresh-realtime pattern above.

# Model broadcasts to subscribers
class Feedback < ApplicationRecord
  after_create_commit -> { broadcast_prepend_to "feedbacks" }
  after_update_commit -> { broadcast_replace_to "feedbacks" }
  after_destroy_commit -> { broadcast_remove_to "feedbacks" }
end

<%# View subscribes to stream %>
<%= turbo_stream_from "feedbacks" %>

<div id="feedbacks">
  <%= render @feedbacks %>
</div>

Hotwire Stimulus

Stimulus is a modest JavaScript framework that connects JavaScript objects to HTML elements using data attributes, enhancing server-rendered HTML.

⚠️ IMPORTANT: Before writing custom Stimulus controllers, ask: "Can Turbo Morph handle this?" Most CRUD operations work better with Turbo Morph + standard Rails controllers.

Use Stimulus for:

Client-side interactions (dropdowns, tooltips, character counters)
Form enhancements (dynamic fields, auto-save)
UI behavior (modals, tabs, accordions)

Don't use Stimulus for:

Basic CRUD operations (use Turbo Morph)
Simple list updates (use Turbo Morph)
Navigation (use Turbo Drive)

Core Concepts

Controller:

// app/javascript/controllers/feedback_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["content", "charCount"]
  static values = { maxLength: { type: Number, default: 1000 } }

  connect() {
    this.updateCharCount()
  }

  updateCharCount() {
    const count = this.contentTarget.value.length
    this.charCountTarget.textContent = `${count} / ${this.maxLengthValue}`
  }

  disconnect() {
    // Clean up (important for memory leaks)
  }
}

HTML:

<div data-controller="feedback" data-feedback-max-length-value="1000">
  <textarea data-feedback-target="content"
            data-action="input->feedback#updateCharCount"></textarea>
  <div data-feedback-target="charCount">0 / 1000</div>
</div>

Syntax: event->controller#method (default event based on element type)

// app/javascript/controllers/countdown_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static values = {
    seconds: { type: Number, default: 60 },
    autostart: Boolean
  }

  connect() {
    if (this.autostartValue) this.start()
  }

  start() {
    this.timer = setInterval(() => {
      this.secondsValue--
      if (this.secondsValue === 0) this.stop()
    }, 1000)
  }

  secondsValueChanged() {
    this.element.textContent = this.secondsValue
  }

  disconnect() {
    clearInterval(this.timer)
  }
}

<div data-controller="countdown"
     data-countdown-seconds-value="120"
     data-countdown-autostart-value="true">60</div>

Types: Array, Boolean, Number, Object, String

// app/javascript/controllers/search_controller.js
export default class extends Controller {
  static outlets = ["results"]

  search(event) {
    fetch(`/search?q=${event.target.value}`)
      .then(r => r.text())
      .then(html => this.resultsOutlet.update(html))
  }
}

// results_controller.js
export default class extends Controller {
  update(html) { this.element.innerHTML = html }
}

<div data-controller="search" data-search-results-outlet="#results">
  <input data-action="input->search#search">
</div>
<div id="results" data-controller="results"></div>

Form:

<div data-controller="nested-form">
  <%= form_with model: @feedback do |form| %>
    <div class="mb-6">
      <button type="button" class="btn btn-sm" data-action="nested-form#add">
        Add Attachment
      </button>
      <div data-nested-form-target="container" class="space-y-4">
        <%= form.fields_for :attachments do |f| %>
          <%= render "attachment_fields", form: f %>
        <% end %>
      </div>

      <template data-nested-form-target="template">
        <%= form.fields_for :attachments, Attachment.new, child_index: "NEW_RECORD" do |f| %>
          <%= render "attachment_fields", form: f %>
        <% end %>
      </template>
    </div>
  <% end %>
</div>

Stimulus Controller:

// app/javascript/controllers/nested_form_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["container", "template"]

  add(event) {
    event.preventDefault()
    const content = this.templateTarget.innerHTML
      .replace(/NEW_RECORD/g, new Date().getTime())
    this.containerTarget.insertAdjacentHTML("beforeend", content)
  }

  remove(event) {
    event.preventDefault()
    const field = event.target.closest(".nested-fields")
    const destroyInput = field.querySelector("input[name*='_destroy']")
    const idInput = field.querySelector("input[name*='[id]']")

    if (idInput && idInput.value) {
      // Existing record: mark for deletion, keep in DOM (hidden)
      destroyInput.value = "1"
      field.style.display = "none"
    } else {
      // New record: remove from DOM entirely
      field.remove()
    }
  }
}

// ❌ BAD - Memory leak
connect() {
  this.timer = setInterval(() => this.update(), 1000)
}

// ✅ GOOD - Clean up
disconnect() {
  clearInterval(this.timer)
}

# test/system/turbo_test.rb
class TurboTest < ApplicationSystemTestCase
  test "updates without full page reload" do
    visit feedbacks_path
    fill_in "Content", with: "New feedback"
    click_button "Create"
    assert_selector "#feedbacks", text: "New feedback"
  end

  test "edits within frame" do
    feedback = feedbacks(:one)
    visit feedbacks_path
    within "##{dom_id(feedback)}" do
      click_link "Edit"
      fill_in "Content", with: "Updated"
      click_button "Save"
      assert_text "Updated"
    end
  end
end

# test/system/stimulus_test.rb
class StimulusTest < ApplicationSystemTestCase
  test "character counter updates on input" do
    visit new_feedback_path
    fill_in "Content", with: "Test"
    assert_selector "[data-feedback-target='charCount']", text: "4 / 1000"
  end

  test "nested form add/remove works" do
    visit new_feedback_path
    initial_count = all(".nested-fields").count
    click_button "Add Attachment"
    assert_equal initial_count + 1, all(".nested-fields").count
  end
end

Manual Testing:

Test with JavaScript disabled (progressive enhancement)
Verify scroll position preservation with Turbo Morph
Check focus management in modals and inline editing
Test real-time updates in multiple browser tabs

Official Documentation:

Community Resources:

Hotwire Discussion Forum

rails-ai:hotwire

Hotwire (Turbo + Stimulus)