Hotwire Turbo — Fast Web Apps with HTML Over the Wire

Introduction

Turbo is a JavaScript library from the Hotwire suite that makes web applications feel fast by intercepting navigations and form submissions, fetching HTML from the server, and merging it into the current page. Instead of building a JSON API and rendering on the client with a JavaScript framework, you send HTML from the server and let Turbo handle the page updates. This keeps the programming model simple while delivering snappy user experiences.

What Hotwire Turbo Does

• Intercepts link clicks and replaces the page body with server-rendered HTML without a full reload (Turbo Drive)
• Decomposes pages into independent frames that load and update asynchronously (Turbo Frames)
• Streams HTML fragments over WebSocket or SSE to update specific parts of the page in real time (Turbo Streams)
• Supports morphing updates that preserve DOM state like scroll position and form values
• Handles form submissions with automatic redirect following and error rendering

Architecture Overview

Turbo is split into three subsystems. Turbo Drive globally intercepts navigation and form submissions, fetching the new page via fetch API and swapping the body element. Turbo Frames scope this behavior to individual sections of the page, each identified by a <turbo-frame> element that can load its content lazily or on user interaction. Turbo Streams deliver targeted DOM mutations (append, prepend, replace, remove, update, morph) via a simple HTML-based protocol over WebSocket, SSE, or HTTP responses. All three subsystems work together without requiring custom JavaScript.

Self-Hosting & Configuration

• Install via npm or import from a CDN; for Rails, turbo-rails gem provides server-side helpers
• Turbo Drive activates automatically on all links and forms once the library is imported
• Add <turbo-frame id="name"> elements to scope navigation to specific page sections
• Use <turbo-stream> elements in HTTP responses to perform targeted DOM updates
• For real-time updates, broadcast Turbo Stream fragments via ActionCable (Rails) or any WebSocket/SSE source

Key Features

• Zero-JavaScript page transitions that feel instant by avoiding full page reloads
• Frame-based partial updates that keep surrounding page state intact
• Real-time DOM updates via a declarative HTML streaming protocol
• Morphing mode that diffs the DOM and preserves input focus, scroll position, and CSS transitions
• Works with any backend language; not limited to Ruby on Rails

Comparison with Similar Tools

• htmx — similar HTML-over-the-wire approach with attribute-driven AJAX; more granular control per element but no built-in streaming protocol
• Livewire — Laravel-specific server-driven UI; tighter PHP integration but framework-locked
• Phoenix LiveView — Elixir-based server-rendered reactive UI; persistent WebSocket connection for all updates
• Inertia.js — bridges server-side routing with client-side rendering (React, Vue, Svelte); requires a JavaScript framework
• Unpoly — progressive enhancement library with layer-based navigation; similar philosophy but different API surface

FAQ

Q: Do I need to write JavaScript with Turbo? A: For most use cases, no. Turbo Drive, Frames, and Streams work through HTML attributes and server-rendered responses. You only write JavaScript for custom behavior via Stimulus (another Hotwire library) or event listeners.

Q: Can Turbo work with backends other than Rails? A: Yes. Turbo is a standalone JavaScript library. Any backend that returns HTML can use Turbo Drive and Frames. Turbo Streams require sending <turbo-stream> elements, which is straightforward in any language.

Q: How does Turbo handle forms with validation errors? A: When a form submission returns a 422 status, Turbo renders the response within the current frame, showing server-rendered error messages without a full page reload.

Q: What is the difference between Turbo and Turbolinks? A: Turbo is the successor to Turbolinks. It includes everything Turbolinks did (fast navigation) plus Frames and Streams for partial page updates and real-time features.

Sources

• https://github.com/hotwired/turbo
• https://turbo.hotwired.dev/