CSS class-based animations for Turbo page refresh morphs with form protection
npm install turbo-refresh-animationsAnimates elements that enter, exit, or change during Turbo Page Refreshes.
Features:
- Opt-in animations via data-turbo-refresh-animate attribute.
- Animates entries, exits, and changes.
- Protect elements (especially forms) during same-page refresh morphs; the initiator still morphs.
- Customize animations via CSS classes.
- Works with importmaps, esbuild, webpack, or any bundler.
- Installation
- With importmaps (Rails 7+)
- With npm/yarn
- Quick Start
- 1. Import the library
- 2. Add the CSS
- 3. Enable morphing in your layout
- 4. Opt in elements for animations
- Data Attributes Reference
- How It Works
- Change Detection
- Protecting Elements During Same-Page Refreshes
- data-turbo-refresh-stream-permanent
- Form-specific conveniences
- Flash protected elements on update
- Customization
- Custom animation classes per element
- Enable specific animations
- Define your own animations
- Example animations
- Refresh Deduping Notes
- Disabling the Turbo Progress Bar
- TODOs
- License
``bash`
bin/importmap pin turbo-refresh-animations
`bash`
npm install turbo-refresh-animationsor
yarn add turbo-refresh-animations
Peer dependency: @hotwired/turbo >= 8. If you're using Rails with turbo-rails, it's already included; otherwise install @hotwired/turbo alongside this package.
`javascript`
// app/javascript/application.js
import "@hotwired/turbo-rails"
import "turbo-refresh-animations"
Add CSS for the animation classes in your app's stylesheet. This package does not ship CSS. You can copy the example styles from the Example animations section or write your own.
`erb`
<%# app/views/layouts/application.html.erb %>
<%= turbo_refreshes_with method: :morph, scroll: :preserve %>
Add data-turbo-refresh-animate and an id to elements you want to animate:
`erb`
<%# app/views/items/_item.html.erb %>
<%= item.title %>
Elements will animate when created, changed, or deleted during Turbo morphs.
| Attribute | Purpose |
|-----------|---------|
| id | Element identifier (required for enter/change/exit animations) |data-turbo-refresh-animate
| | Opt-in for animations (=""/present enables all, ="enter,exit" enables subset, ="none" disables) |data-turbo-refresh-enter="class"
| | Custom enter animation class (single class token; no spaces) |data-turbo-refresh-change="class"
| | Custom change animation class (single class token; no spaces) |data-turbo-refresh-exit="class"
| | Custom exit animation class (single class token; no spaces) |data-turbo-refresh-stream-permanent
| | Protect element during same-page refresh morphs (except initiator) |data-turbo-refresh-version
| | Override change detection (used instead of textContent, e.g. item.cache_key_with_version) |
The library compares each element's "meaningful signature" before and after Turbo renders a page refresh morph. Elements with both an id and the data-turbo-refresh-animate attribute will be animated:
| Animation | Trigger | Default CSS class |
|-----------|---------|-------------------|
| Enter | New element added to DOM | turbo-refresh-enter |turbo-refresh-change
| Change | Element text changes (or version changes) | |turbo-refresh-exit
| Exit | Element removed from DOM | |
By default, change animations run only when an element's normalized textContent differs between the old and new page. This naturally ignores most "noise" that isn't user-visible (CSRF tokens, framework attributes, etc.).
Normalization collapses all whitespace to single spaces and trims leading/trailing whitespace.
For precise control (and to count non-text changes as meaningful), use data-turbo-refresh-version:
`erb
data-turbo-refresh-animate
data-turbo-refresh-version="<%= item.cache_key_with_version %>">
<%= item.title %>
<%= button_to "Delete", item, method: :delete %>
When
is present, it's used instead of textContent to decide whether a change is meaningful. This is useful when:- If you want to respect invisible changes like hidden inputs (e.g. CSRF tokens) or attributes.
- Elements include dynamic attributes from JavaScript frameworks.
- You want explicit control over what constitutes a "change".
Protecting Elements During Same-Page Refreshes
$3
When using
broadcasts_refreshes_to (or any same-page refresh morph), any element with this attribute will be protected from morphing when the refresh comes from elsewhere (e.g., another user's refresh stream). This is useful for any element whose current DOM state you want to preserve during external refreshes.Unlike Turbo's
data-turbo-permanent, this protection is conditional: the element is allowed to morph when it contains the form submit or same-page link that initiated the refresh, so user-initiated updates still apply.`erb
`This protection does not require an
(unless you also want the element to participate in enter/change/exit animations).The most common use case is forms. Without protection, a user typing in a form would lose their input whenever another user's action triggers a refresh stream:
`erb
<%= form_with model: item do |f| %>
<%= f.text_field :title %>
<%= f.submit "Add" %>
<% end %>
`$3
Since forms are the most common use case, the library includes special handling:
1. Submitter's form still clears: When a user submits a form inside a protected element, that specific element is allowed to morph normally (so the form clears after submission via the redirect response). Other protected elements remain protected.
2. Same-page refreshes preserve state: Even during refresh morphs that stay on the same URL (e.g.,
back to the current page), elements with data-turbo-refresh-stream-permanent stay protected. This preserves user-created UI state like open edit forms. If a user clicks a same‑page link inside a protected element (e.g., "Cancel"), the library sets data-turbo-action="replace" on that link so Turbo uses a refresh morph; the initiating element updates while other protected elements remain open.
- For this behavior, “same page” means the same origin + pathname + search (hash ignored).
- Note: links to an anchor in the current document (e.g. /lists/1#comments) are treated as in-page navigation and are not forced into a refresh morph.$3
To show a visual indicator when a protected element's underlying data changes (e.g., another user edits the same item), add
data-turbo-refresh-version:`erb
data-turbo-refresh-stream-permanent
data-turbo-refresh-animate
data-turbo-refresh-version="<%= item.cache_key_with_version %>">
<%= form_with model: [item.list, item] do |f| %>
<%= f.text_field :title %>
<%= f.submit "Save" %>
<% end %>
When the version changes during an external refresh, the element flashes with the change animation while keeping its current content protected.
Note: protected elements can temporarily be in a different "view state" than the server-rendered HTML (e.g., an open edit form vs a read-only item view). To avoid false positives, the library only flashes protected elements based on
from the incoming HTML. In practice, add data-turbo-refresh-version to all render variants of a given id if you want flashing to work reliably.Customization
$3
Use a different animation class for specific elements:
`erb
data-turbo-refresh-animate
data-turbo-refresh-enter="my-custom-enter"
data-turbo-refresh-exit="my-custom-exit">
$3
By default,
enables all three animation types. Specify a comma-separated list to enable only certain types:`erb
<%# Only animate exits (no enter or change) %>
<%# Animate enter and exit (no change) %>
<%# All animations (default) %>
`Options:
, exit, changeTo explicitly disable animations on an element, use
(or "false"). This can be useful when a helper emits the attribute automatically.$3
You can override the default class names or use custom class names per element.
If you already have an existing class you want the library to use by default, CSS doesn't provide true
"class aliasing", but you can get the same effect:
`css
/ Apply the same rules to both selectors /
.turbo-refresh-enter,
.my-enter {
animation: myEnter 180ms ease-out;
}
`If you use Sass/SCSS, you can also do:
scss
/ Make .turbo-refresh-enter reuse .my-enter rules /
.turbo-refresh-enter { @extend .my-enter; }
`Alternatively, set
(or ...-change / ...-exit) on specific elements.Exit animations can be implemented with CSS transitions (not just keyframes). The exit class should
change a property with a non-zero transition duration (for example, opacity or transform). The
element is removed after the transition ends (with a timeout fallback).
For predictable timing, use explicit transition properties (e.g.,
opacity, transform) instead of
transition-property: all.#### Example: Background color flash
`css
/ Enter - green background fade /
@keyframes bg-flash-enter {
from { background-color: #D1E7DD; }
to { background-color: inherit; }
}.bg-flash-enter {
animation: bg-flash-enter 1.2s ease-out;
}
/ Change - yellow background fade /
@keyframes bg-flash-change {
from { background-color: #FFF3CD; }
to { background-color: inherit; }
}
.bg-flash-change {
animation: bg-flash-change 1.2s ease-out;
}
/ Exit - red background fade + opacity /
@keyframes bg-flash-exit {
from { background-color: #F8D7DA; opacity: 1; }
to { background-color: inherit; opacity: 0; }
}
.bg-flash-exit {
animation: bg-flash-exit 0.6s ease-out forwards;
}
`#### Example: Slide in/out
css
@keyframes slideInDown {
from {
transform: translate3d(0, -100%, 0);
visibility: visible;
}
to {
transform: translate3d(0, 0, 0);
}
}.slideInDown {
animation: slideInDown 0.5s ease-out;
}
@keyframes slideOutUp {
from {
transform: translate3d(0, 0, 0);
}
to {
visibility: hidden;
transform: translate3d(0, -100%, 0);
}
}
.slideOutUp {
animation: slideOutUp 0.5s ease-out forwards;
}
`##### Masking slide animations
Transform-based slide animations can "ghost" over adjacent rows because they paint outside their own box.
To keep the motion contained, apply
on the animated element and animate a child:`erb
data-turbo-refresh-enter="slide-mask-enter"
data-turbo-refresh-exit="slide-mask-exit">
`css
.slide-mask-enter,
.slide-mask-exit {
overflow: hidden;
}.slide-mask-enter > .slide-mask-content {
animation: slideInDown 0.5s ease-out;
}
.slide-mask-exit > .slide-mask-content {
animation: slideOutUp 0.5s ease-out forwards;
}
`Use custom classes per element:
erb
data-turbo-refresh-animate
data-turbo-refresh-enter="slideInDown"
data-turbo-refresh-exit="slideOutUp">
<%= item.title %>
`$3
Copy/paste this example into your app's stylesheet:
css
/ Enter - fade in /
.turbo-refresh-enter {
animation: turbo-refresh-enter 300ms ease-out;
}@keyframes turbo-refresh-enter {
from { opacity: 0; }
to { opacity: 1; }
}
/ Exit - fade out /
.turbo-refresh-exit {
animation: turbo-refresh-exit 300ms ease-out forwards;
}
@keyframes turbo-refresh-exit {
from { opacity: 1; }
to { opacity: 0; }
}
/ Change - yellow background flash /
.turbo-refresh-change {
animation: turbo-refresh-change 800ms ease-out;
}
@keyframes turbo-refresh-change {
from { background-color: #FFF3CD; }
to { background-color: inherit; }
}
@media (prefers-reduced-motion: reduce) {
.turbo-refresh-enter,
.turbo-refresh-change,
.turbo-refresh-exit {
animation-duration: 1ms;
animation-iteration-count: 1;
}
}
`Refresh Deduping Notes
You might be worried about the performance of using Turbo Refreshes so heavily, especially when paired with
from models. It's not as bad as you might think, because Turbo does two kinds of refresh deduping:- Backend (Turbo Rails):
broadcasts_refreshes_to uses broadcast_refresh_later_to, which is debounced per stream name + request_id on the current thread. Multiple refreshes in quick succession coalesce into the last one. This does not apply to broadcast_refresh_to, and it is not a process-wide/global dedupe.
- Frontend (Turbo Source): refresh stream actions are debounced in the session (default 150ms via pageRefreshDebouncePeriod), and refreshes with a request-id that matches a recent client request are ignored. The request-id is set automatically when you use Turbo.fetch (it adds X-Turbo-Request-Id).Disabling the Turbo Progress Bar
This library disables the Turbo progress bar during morph operations (but keeps it for regular navigation):
`javascript
document.addEventListener("turbo:morph", () => {
Turbo.navigator.delegate.adapter.progressBar.hide()
})
`See hotwired/turbo#1221 for discussion on making this configurable in Turbo itself.
TODOs
- Expose a hook to set animation parameters before animations run (e.g., to measure
for jQuery UI-style "push siblings" slide animations).License
MIT