View-Transition-Class: One Rule Set for Every Item
The tutorials stop at a single hero image, but the architecture breaks the moment you scale it: every view-transition-name on a page must be unique, or the browser can't map elements between the two documents and discards the entire transition. A listing page with 48 products needs 48 unique names; a gallery of 200 thumbnails needs 200. Generating the names is easy. The pain is that each pseudo-element selector in your CSS targets one specific name, so your animation styles balloon into a wall of selectors.
The fix is the distinction between view-transition-name and view-transition-class, which read like synonyms and are not. The name carries identity — it tells the browser which element on page A corresponds to which element on page B, as when a thumbnail is named card-7 on the grid and the hero image carries card-7 on the detail page. The class is purely a styling hook, closer to a regular CSS class: .btn doesn't identify one button, it says "style me like a button." A database analogy holds — name is the primary key, class is a category column you can query across.
So fifty elements can share view-transition-class: card, and one rule controls duration, easing, and object-fit for all of them:
- Six cards, six unique names, three CSS rules covering every animation behavior. It scales to sixty cards or six hundred without adding a selector.
- The selector
::view-transition-group(*.card)reads as "any view transition group whose element hasview-transition-class: card, whatever its specific name is" — the asterisk wildcards the name,.cardmatches the class.
For cross-document MPA transitions the pattern is identical; you just generate names server-side instead of by hand.
<!-- Page A -->
<div class="grid">
<!-- ... -->
<a
href="https://css-tricks.com/product/42"
class="card"
style="view-transition-name: product-42; view-transition-class: card"
>
<img src="https://css-tricks.com/images/42-thumb.jpg" alt="Widget" />
</a>
<a
href="https://css-tricks.com/product/43"
class="card"
style="view-transition-name: product-43; view-transition-class: card"
>
<img src="https://css-tricks.com/images/43-thumb.jpg" alt="Gadget" />
</a>
</div>
<!-- Page B -->
<div
class="product-hero"
style="view-transition-name: product-42; view-transition-class: card"
>
<img src="https://css-tricks.com/images/42-hero.jpg" alt="Widget" />
</div>
/* ONE stylesheet, shared by all pages, handles every product */
@view-transition {
navigation: auto;
}
::view-transition-group(*.card) {
animation-duration: 0.35s;
animation-timing-function: cubic-bezier(0.25, 0.46, 0.45, 0.94);
}
::view-transition-old(*.card),
::view-transition-new(*.card) {
object-fit: cover;
}
Three rules become the whole animation stylesheet for a catalog of thousands of products.
Earlier workarounds were far worse: looping through items in JavaScript to emit <style> blocks with hundreds of selectors, or preprocessor loops generating every name permutation at build time. view-transition-class exists because the spec authors recognized the original API didn't scale.
Support and Fallbacks
The property arrived in Chrome 125 and is supported in Chrome, Edge, and Safari 18.2+. Older Chromium and Firefox won't recognize it. The degradation is graceful: transitions still run, they just fall back to the default fade instead of your custom timing. Elements can hold multiple classes just like ordinary CSS — view-transition-class: card featured is valid and matches either ::view-transition-group(*.card) or ::view-transition-group(*.featured), useful when most items should animate alike but a few need to stand out.
Sibling-Index Today, ident() Later
Pure CSS could someday collapse the whole problem to a single rule: apply ident() to sibling-index() and every list item gets an auto-generated unique name, whether you have ten cards or ten thousand. Half of that ships already — sibling-index(), which returns an element's position among its siblings, landed in Chrome 138 and is usable now for staggered animations and calculated styles. ident(), proposed to the CSS Working Group by Bramus, concatenates strings, integers, and identifiers into a valid CSS name and carries a Chrome Intent to Prototype from May 2025. No browser ships it yet and no timeline exists.
The same pattern reaches beyond view transitions to scroll-timeline-name, container-name, and view-timeline-name — anywhere unique identifiers are needed at scale. Pulling values from markup with attr() instead of sibling-index() works too, e.g. ident("--item-" attr(id) "-tl"). Until ident() lands and that complexity dissolves, the class-based approach above is how you solve it with tools that exist today.
Name Transition Targets at Interaction Time
Declaring view-transition-name in the stylesheet from page load works, but it carries a cost that only appears at scale. A name assigned that way tells the browser the element takes part in every transition on the page, so it must be snapshotted, measured, and given pseudo-elements on each navigation. For a single hero image that is negligible. For a grid of 48 product cards, it means 47 snapshots nobody asked for. On a mid-range Android device pulling product images over LTE, the transition can stutter or be skipped entirely while the browser struggles to set everything up.
The alternative is to treat the name as just-in-time state: assign it when the user interacts, not when the page loads. No view-transition-name declarations sit in the CSS at all. The sequence is:
- The user clicks a card on the listing page and navigation begins;
pageswapfires on the outgoing page. - The
pageswaphandler readsevent.activation.entry.urlto determine the destination, locates the clicked card, and appliesview-transition-name: product-42. - The browser snapshots that one named element alongside the default
roottransition, and navigation proceeds. pagerevealfires on the incoming page; the handler reads the URL, finds the hero element, and assigns the matching nameproduct-42.- Matching names on both snapshots let the browser morph between them.
- When the
.finishedpromise resolves, the names are cleared.
event.activation removes the need for global state, sessionStorage, or extra query parameters: the outgoing page gets the destination from event.activation.entry.url, and the incoming page reads window.location. Cleanup matters as much as assignment. If a user returns to the listing and picks a different card, a leftover name on the old card causes either duplicate-name conflicts, which kill the transition instantly, or matching against the wrong element. Keep your pageswap logic fast, too — the browser gives you a narrow window of roughly 10–50ms before it takes snapshots.
This is essentially what Astro's transition:name directive and Nuxt's view transition support do internally: they assign and remove names around the navigation lifecycle, hiding the pageswap/pagereveal wiring behind a component attribute.
Patterns for Common Layouts
Galleries with Mixed Aspect Ratios
Galleries are harder because thumbnails and the full-size view rarely share an aspect ratio. The fix for stretched images is essential, and the transition should look deliberate rather than chaotic.
/* Gallery items get their own class for targeted animation */
::view-transition-group(*.gallery-item) {
animation-duration: 0.5s;
animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
}
::view-transition-old(*.gallery-item),
::view-transition-new(*.gallery-item) {
object-fit: cover;
overflow: hidden;
}
/* Lightbox-style overlay - fade the background separately */
::view-transition-group(*.lightbox-bg) {
animation-duration: 0.3s;
}
Apply the view-transition-name to the <img> rather than to the card wrapping it, so only the image morphs from thumbnail to lightbox size — not the card background, padding, and caption. Name the image; style the card separately. Give the lightbox overlay its own view-transition-name and view-transition-class so it fades in independently while the image morphs: two transitions with separate timing, from two names.
Same-Page Tab and Section Switches
Grid-to-detail isn't the only case. Dashboard tabs, multi-step forms, and content panels can use same-document view transitions, and view-transition-class scales the same way.
/* Shared header that persists across tabs */
::view-transition-group(*.persistent) {
animation-duration: 0s; /* don't animate - it should feel anchored */
}
/* Tab content that swaps */
::view-transition-group(*.tab-content) {
animation-duration: 0.25s;
}
::view-transition-old(*.tab-content) {
animation: slide-out-left 0.25s ease-in;
}
::view-transition-new(*.tab-content) {
animation: slide-in-right 0.25s ease-out;
}
@keyframes slide-out-left {
to {
transform: translateX(-100%);
opacity: 0;
}
}
@keyframes slide-in-right {
from {
transform: translateX(100%);
opacity: 0;
}
}
Note the animation-duration: 0s applied to persistent elements. A site header carrying a view-transition-name avoids the default root cross-fade, but it shouldn't animate either; zero duration makes it snap to its new position so it reads as stationary. Stable landmarks make the content that does move feel grounded.
Infinite Scroll and Dynamically Added Content
Items appended via fetch() during infinite scroll don't need names either — not until one is clicked. The pageswap handler queries the DOM at navigation time, so an element added five minutes after load is found and named identically to one present at load, with no extra setup. The one requirement is that your matching keys, such as data-id attributes, stay unique across all loaded batches. IDs returned by your API are already safe; client-generated IDs must not collide as new batches arrive.
Respecting Reduced-Motion Preferences
/* The responsible way to set up view transitions */
@view-transition {
navigation: auto;
}
/* All your animation customizations go INSIDE this media query */
@media (prefers-reduced-motion: no-preference) {
::view-transition-group(*.card) {
animation-duration: 0.35s;
animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
}
::view-transition-old(*.card),
::view-transition-new(*.card) {
object-fit: cover;
}
/* Custom keyframes, staggered delays, the fun stuff - all in here */
::view-transition-old(root) {
animation: fade-out 0.2s ease-in;
}
::view-transition-new(root) {
animation: fade-in 0.3s ease-out;
}
}
/* If the user HAS requested reduced motion: instant cut, no animation */
@media (prefers-reduced-motion: reduce) {
::view-transition-group(*),
::view-transition-old(*),
::view-transition-new(*) {
animation-duration: 0s !important;
}
}
@keyframes fade-out {
to {
opacity: 0;
}
}
@keyframes fade-in {
from {
opacity: 0;
}
}
This is not a nice-to-have. For people with vestibular disorders — a larger group than most developers assume — unexpected motion causes real nausea, dizziness, and migraines lasting hours. The prefers-reduced-motion query exists because users have explicitly asked the OS to stop motion.
The @view-transition opt-in itself can stay outside the media query, since it only enables cross-document transitions; without animation customizations the result is an instant cut, visually identical to a normal navigation. Gate the durations, easing curves, and custom keyframes behind prefers-reduced-motion: no-preference. A prefers-reduced-motion: reduce block that forces animation-duration: 0s on all transition pseudo-elements adds a safety net for any rule you miss; the !important is ugly but justified when you want an unconditional override. The conditional opt-in from Part 1 still applies:
/* You can also just disable transitions entirely for reduced-motion users */
@media (prefers-reduced-motion: no-preference) {
@view-transition {
navigation: auto;
}
}
Both approaches work. Wrapping the whole @view-transition rule means no transition is attempted at all — a plain navigation. Leaving @view-transition active and zeroing durations means it technically fires and completes instantly, which matters if your pagereveal logic depends on event.viewTransition existing. Pick whichever fits your setup, but don't ship animated transitions without checking.
Consider also that reduced motion doesn't have to mean no motion. Some users tolerate fades but not slides or zooms, so a gentler fast cross-fade is less likely to trigger symptoms than a 400ms morph with easing curves.
@media (prefers-reduced-motion: reduce) {
/* Instead of zero duration, use a quick crossfade only */
::view-transition-group(*) {
animation-duration: 0.15s !important;
animation-timing-function: linear !important;
}
::view-transition-old(*) {
animation: fade-out 0.15s linear !important;
}
::view-transition-new(*) {
animation: fade-in 0.15s linear !important;
}
}
That's a judgment call. The safest option is zero motion: if you're unsure, use animation-duration: 0s and add a gentler alternative later, once you've tested it with users who rely on the setting.
Older Browsers Need No Fallback
/* Feature detection, if you need it */
@supports (view-transition-name: none) {
.card {
/* maybe you want contain: paint for better snapshotting */
contain: paint;
}
}
// JS-side feature detection
if (document.startViewTransition) {
// same-document transition API exists
}
// For cross-document transitions, there's no direct JS check -
// the browser either supports @view-transition in CSS or ignores it.
// That's... actually fine.
You probably don't need that @supports check. Browsers that don't understand @view-transition { navigation: auto; } ignore the rule; the user clicks a link and gets an ordinary page load. Nothing breaks: no JavaScript errors, no layout shifts, no fallback to write. view-transition-name properties are ignored, the ::view-transition-* pseudo-element selectors match nothing, and pageswap/pagereveal listeners either don't fire or return null for event.viewTransition so your guard clause exits early.
Today Chrome and Edge fully support cross-document view transitions, including view-transition-class; Safari ships full cross-document support as of Safari 18.2; Firefox still holds it behind a flag.
@supports earns its place only for styles that make sense solely in the context of a transition — contain: paint to improve snapshot quality, or hiding a loading state the transition would normally cover. Gate those behind @supports (view-transition-name: none) so other browsers don't inherit the side effects without the payoff.
Takeaways
- Opt in with CSS, not the deprecated meta tag:
@view-transition { navigation: auto; }. - Both pages must opt in, or no transition runs.
- The 4-second timeout starts at navigation, not at render — use
pagerevealto catchTimeoutError. - Images stretch during transitions because pseudo-elements default to
object-fit: fill; fix withobject-fit: coveron::view-transition-oldand::view-transition-new. view-transition-nameis identity (unique per page);view-transition-classis a styling hook (shared across elements).- Assign names just-in-time via
pageswapandpagereveal, keeping thepageswaphandler fast for the 10–50ms pre-snapshot window. - Clear names after
viewTransition.finishedresolves to avoid stale conflicts. - Gate animations behind
prefers-reduced-motion: no-preference— this is mandatory. - Progressive enhancement is built in; unsupported browsers get normal page loads.
Naming Problems at Scale
Unique names work fine while you have a couple of elements in one document. Applied to a cross-document view transition over 100 products, though, you end up with 100 names and equally many view-transition-name declarations, which the source describes as a nightmare.
Assigning Names Only When Needed
The fix is to stop naming everything in advance. Instead of a rule per product, names can be handed out at the moment the transition starts — a precedent examined in the first two parts of this series — so no view-transition-name values have to be maintained for elements that rarely change. This approach scales to hundreds of elements and shares points with view transition scratch cards for selectively producing named elements.



