reactive islands in server-rendered apps
Turbo replaces full page changes with fast partial updates, yet client-side UI state can easily get lost on every Turbo Frame render. Alpine.js and Turbo/Hotwire together deliver exactly what each approach lacks on its own: server-side navigation without a reload, plus reliably re-initialized, local reactivity in every component.
Table of Contents
- 1. Why Alpine.js and Turbo/Hotwire make sense together
- 2. Turbo lifecycle: turbo:load instead of DOMContentLoaded
- 3. Combining Turbo Frames with x-data
- 4. Turbo Streams and Alpine state after partial updates
- 5. data-turbo-permanent for persistent widgets
- 6. Coordinating events between Turbo and Alpine
- 7. Division of labor: what Turbo owns, what Alpine owns
- 8. Common mistakes with Alpine.js and Turbo/Hotwire
- 9. Alpine.js and Turbo/Hotwire compared to alternatives
- 10. Summary
- 11. FAQ
1. Why Alpine.js and Turbo/Hotwire make sense together
Hotwire Turbo replaces classic full page navigation with AJAX requests that only swap out the body content, creating the feel of a single-page application without a single line of client-side JavaScript for routing. What Turbo deliberately does not ship is a reactivity system for local UI state within a page, such as a dropdown, a multi-step form or live validation. This is exactly where Alpine.js and Turbo/Hotwire come together.
The combination is especially common in Rails projects, where Hotwire is the official frontend approach, but the same pattern works identically in Laravel or Django projects with server-side rendering. Alpine takes care of micro-interactions inside a Turbo Frame, while Turbo controls navigation between pages and the partial reload of page sections.
The biggest technical challenge with Alpine.js and Turbo/Hotwire is the lifecycle: Turbo replaces DOM nodes on every navigation, and Alpine needs to reliably know when to re-initialize. The following sections show how this lifecycle works, how Turbo Frames and Turbo Streams interact with Alpine components, and which division of labor has proven itself in practice.
2. Turbo lifecycle: turbo:load instead of DOMContentLoaded
In a classic multi-page application, DOMContentLoaded fires exactly once per page visit. Turbo, however, prevents a full page reload and only replaces the <body> content, which means DOMContentLoaded never fires again on a Turbo navigation. Alpine itself already solves this problem internally: it watches DOM mutations through a MutationObserver and automatically initializes newly inserted x-data elements, independent of the Turbo lifecycle.
For your own initialization code outside of x-data, for instance setting up a global Alpine store instance, you should still listen for Turbo's own turbo:load event, which fires on every completed Turbo navigation, both on the initial page load and after every subsequent frame change. This keeps Alpine.js and Turbo/Hotwire initialization logic consistent, whether the page was freshly loaded or navigated to via Turbo.
// app/javascript/application.js
import Alpine from 'alpinejs'
import '@hotwired/turbo-rails'
// Runs on the very first page load AND after every Turbo navigation
document.addEventListener('turbo:load', () => {
console.log('Page ready, Turbo navigation finished')
})
// Alpine's own MutationObserver handles x-data re-initialization automatically —
// no manual work needed for standard components
window.Alpine = Alpine
Alpine.start()
// Global store, only needs to be defined once regardless of navigation
document.addEventListener('alpine:init', () => {
Alpine.store('theme', {
dark: localStorage.getItem('dark') === 'true',
toggle() {
this.dark = !this.dark
localStorage.setItem('dark', this.dark)
},
})
})
3. Combining Turbo Frames with x-data
A Turbo Frame encapsulates a section of the page that can be reloaded independently of the rest, such as a comment form or a paginated list. Inside a frame, x-data works exactly like on a regular page, with one important caveat: if the entire frame content is replaced by a server response, any Alpine state inside that frame is discarded, because the old DOM nodes along with their state are completely removed.
This is usually the desired behavior with Alpine.js and Turbo/Hotwire: a form freshly rendered by the server should start in its initial state, not with the old client state of a previous attempt. For cases where state should survive, for instance an already expanded accordion, the server must explicitly write that state back into the newly rendered HTML, for example through a query parameter or a data attribute.
<!-- app/views/comments/_form.html.erb -->
<turbo-frame id="comment_form">
<div x-data="{ charsLeft: 500 }">
<textarea
name="comment[body]"
maxlength="500"
x-on:input="charsLeft = 500 - $event.target.value.length"
></textarea>
<p class="text-xs text-slate-500">
<span x-text="charsLeft"></span> characters left
</p>
<button type="submit">Submit comment</button>
</div>
</turbo-frame>
<!-- After a successful POST, the server re-renders this same frame,
Alpine state resets to its initial value automatically — desired here -->
4. Turbo Streams and Alpine state after partial updates
Turbo Streams go a step further than frames: they let the server surgically replace, append or remove individual DOM fragments over a WebSocket or as a response to a form submit, without affecting the page as a whole. For Alpine.js and Turbo/Hotwire, that means every fragment inserted via a stream with an x-data attribute is automatically detected and initialized by Alpine's MutationObserver, exactly as with a regular Turbo Frame navigation.
A practical use case is a live notification list that receives new entries over a WebSocket via Turbo Stream, while each entry itself carries a small Alpine component for a fade-out animation after a few seconds. The server only takes care of inserting the HTML, Alpine takes care of the client-side behavior of that new element, without the two systems ever needing to know about each other.
<!-- app/views/notifications/create.turbo_stream.erb -->
<turbo-stream action="prepend" target="notifications">
<template>
<div
x-data="{ visible: true }"
x-show="visible"
x-init="setTimeout(() => visible = false, 5000)"
x-transition
class="rounded-lg bg-teal-50 p-3 text-sm"
>
New message received
</div>
</template>
</turbo-stream>
5. data-turbo-permanent for persistent widgets
Some elements should survive Turbo navigations entirely, instead of being recreated on every page change, for instance an audio player that should keep playing while browsing through the page. Turbo offers data-turbo-permanent for this: the element with this marker and a unique id is not replaced on navigation but carried over unchanged into the new page, complete with its full Alpine state.
This is the only reliable way to preserve Alpine state across a real Turbo navigation without manually duplicating it in localStorage or a server-side session. It matters that data-turbo-permanent elements must exist on both sides of the navigation, the old and the new page, with an identical id, otherwise the persistence does not kick in and Turbo treats the element like any other.
6. Coordinating events between Turbo and Alpine
Turbo sends a series of lifecycle events that are useful for Alpine.js and Turbo/Hotwire coordination: turbo:before-fetch-request before a request, turbo:submit-end after a form submit, and turbo:frame-load once an individual frame has finished loading. Alpine components can react to these events with x-on:turbo:submit-end.window, for instance to hide a loading indicator once Turbo has finished the request.
Conversely, Alpine can dispatch its own custom events that a Turbo Frame update reacts to, for instance to trigger a targeted Turbo Frame reload through frame.reload() after client-side validation. This two-way communication over standard browser events is the core of what makes Alpine.js and Turbo/Hotwire work together so well, without either system needing to know about or import the other.
<div
x-data="{ submitting: false }"
x-on:turbo:submit-start.window="submitting = true"
x-on:turbo:submit-end.window="submitting = false"
>
<form data-turbo-frame="comment_form">
<button type="submit" x-bind:disabled="submitting">
<span x-show="!submitting">Submit</span>
<span x-show="submitting">Sending...</span>
</button>
</form>
</div>
// Programmatically reload a specific Turbo Frame after client-side validation
<button
x-data
x-on:click="
if (validateForm()) {
document.getElementById('comment_form').reload()
}
"
>
Validate and reload
</button>
7. Division of labor: what Turbo owns, what Alpine owns
The clear rule for Alpine.js and Turbo/Hotwire is: anything related to navigation, form submits and exchanging page content between client and server belongs to Turbo. Anything that is purely client-side, ephemeral interaction within an already loaded fragment belongs to Alpine. Switching tabs within a page is Alpine, switching to a new route is Turbo.
A common design mistake is using Turbo Frames for things that are really pure client interaction, for instance solving a menu toggle through a server roundtrip where x-show would have been entirely sufficient. Conversely, nobody should try to rebuild complex server-side data queries or form validation with real database access inside Alpine when Turbo is built exactly for that.
8. Common mistakes with Alpine.js and Turbo/Hotwire
The most common mistake is assuming that DOMContentLoaded listeners fire again on every Turbo navigation. They only fire on the very first hard page load, never again as long as navigation happens purely through Turbo. Anyone writing initialization code outside of Alpine must use turbo:load instead of DOMContentLoaded.
// WRONG: only fires once, never again after Turbo navigations
document.addEventListener('DOMContentLoaded', () => {
initAnalytics()
})
// RIGHT: fires on the first load AND after every Turbo navigation
document.addEventListener('turbo:load', () => {
initAnalytics()
})
// WRONG: expecting Alpine state to survive a Turbo Frame replacement
<turbo-frame id="widget">
<div x-data="{ count: 0 }" x-on:click="count++">{{ count }}</div>
</turbo-frame>
<!-- Any server re-render of this frame resets count back to 0 -->
// RIGHT: use data-turbo-permanent only when state must truly persist
<div id="persistent-widget" data-turbo-permanent x-data="{ count: 0 }">
<button x-on:click="count++" x-text="count"></button>
</div>
9. Alpine.js and Turbo/Hotwire compared to alternatives
There are several ways to add interactivity to server-rendered applications. The following table compares Alpine.js and Turbo/Hotwire with the most common alternatives.
| Approach | Client reactivity | Navigation | Fit |
|---|---|---|---|
| Alpine.js and Turbo/Hotwire | Local per fragment | Turbo, no reload | Server-rendered apps with micro-interactions |
| Pure Turbo, no Alpine | Very limited | Turbo, no reload | Simple CRUD interfaces |
| Full SPA framework | Comprehensive | Client router, separate API needed | Data-intensive, highly interactive apps |
| Stimulus instead of Alpine | Comparable, more boilerplate | Turbo, no reload | Rails projects with a strict controller pattern |
| Plain vanilla JS | Manual, error-prone | Turbo, no reload | Very small, specific scripts |
10. Summary
Alpine.js and Turbo/Hotwire complement each other because both systems have different responsibilities that barely overlap. Turbo handles navigation, form submits and exchanging page content through frames and streams. Alpine handles local, ephemeral reactivity within already loaded fragments and, thanks to its built-in MutationObserver, is automatically re-initialized on every Turbo update.
The most important technical pitfalls are the lifecycle difference between DOMContentLoaded and turbo:load, the intentional or accidental reset of Alpine state on frame replacements, and data-turbo-permanent for the rare cases where state truly needs to survive a navigation. Anyone who knows these rules gets, with Alpine.js and Turbo/Hotwire, a lightweight, server-centric alternative to full SPA frameworks.
Alpine.js and Turbo/Hotwire: the essentials at a glance
Lifecycle
turbo:load instead of DOMContentLoaded for custom initialization code outside x-data.
Re-initialization
Alpine's MutationObserver automatically initializes new x-data elements after Turbo Frames and Streams.
Preserving state
data-turbo-permanent with a stable ID for widgets whose Alpine state should survive navigation.
Division of labor
Navigation and data exchange to Turbo, purely visual micro-interaction to Alpine.