Cross-Document View Transitions

Smooth page-to-page animations between separate HTML files — with nothing but CSS.

Core Idea

CSS can now animate between two separate HTML pages, so a normal link can feel like a smooth app transition.

Fade between pages, slide content in and out, or animate a single image into a new position — all without JavaScript.

1. Enable the feature

To activate cross-document view transitions, add the @view-transition rule in your shared CSS:

@view-transition {
    navigation: auto;
}

Once enabled, the browser applies a default crossfade between pages. Click any link, and the old page blends into the new one.

Important — This only works between pages on the same domain that share the same CSS setup. Use one shared CSS file for all HTML pages.

2. Control the animation

Use the ::view-transition-group pseudo-element to adjust timing globally:

::view-transition-group(root) {
    animation-duration: 1s;
}

This slows down the default crossfade. For a custom slide effect, define your own keyframes:

@keyframes slide-out {
    to { transform: translateX(-100vw); }
}
@keyframes slide-in {
    from { transform: translateX(100vw); }
}

Then assign them to the old and new page snapshots:

::view-transition-old(root) {
    animation: slide-out 0.6s ease-in-out;
}
::view-transition-new(root) {
    animation: slide-in 0.6s ease-in-out;
}

The group pseudo-element controls overall duration & timing; old and new handle each page individually.

3. Isolate parts of the page

By default, the entire page animates — including shared elements like a navigation bar. To keep the nav still, assign a custom view-transition name to the main content area:

main {
    view-transition-name: page-content;
}

Then target that name in your pseudo-elements instead of root:

::view-transition-group(page-content) {
    animation-duration: 0.6s;
}
::view-transition-old(page-content) {
    animation: slide-out 0.6s ease-in-out;
}
::view-transition-new(page-content) {
    animation: slide-in 0.6s ease-in-out;
}

Now only the main element slides — the navigation bar stays fixed in place.

✦ Advanced ✦

4. Shared image transitions

When the same image appears on two pages (e.g. a card thumbnail and a hero image), you can animate it smoothly between positions and sizes.

Give both elements the same view-transition-name in your shared CSS:

.card-image,
.hero-image {
    view-transition-name: article-image;
}

The browser creates a dedicated transition group for that image, comparing old and new visual states and animating between them automatically.

Tip: Disable other sliding transitions while testing shared image animations to avoid visual clutter.

⚠️ Considerations

5. Important caveats

Unique names per element A view-transition-name must be unique on the current page. If you have multiple blog cards, each post image needs its own name.

Respect reduced motion Wrap the entire view-transition setup inside a media query for users who prefer reduced motion:

@media (prefers-reduced-motion: no-preference) {
    /* view transition rules here */
}

Browser support Cross-document view transitions currently work in Chrome, Edge, and Safari — not in Firefox. Treat this as a progressive enhancement; unsupported browsers fall back to normal navigation.

Development quirks Live server setups may cause glitches in Chrome. Edge is a more stable environment during development.

Key Takeaway

Cross-document view transitions are a progressive enhancement. If a browser doesn't support them, the page navigates normally. It's a nice-to-have feature that makes multi-page sites feel like single-page apps.

In a nutshell

Add @view-transition { navigation: auto; } to your shared CSS.
Customize with ::view-transition-group, ::view-transition-old, and ::view-transition-new.
Use view-transition-name to isolate specific elements (nav, main content, images).
Shared image transitions work by assigning the same name to matching elements across pages.
Always respect prefers-reduced-motion and test across browsers.

Generated by CuteNote.app Visual Notes

CSS Cross-Document View Transitions