React View Transitions: How to Add Smooth Page Animations

A React application can respond quickly to user actions and still feel disconnected when its interface changes. A product image may suddenly disappear when a user opens its details, or a page transition may replace the entire screen without showing how the new content relates to the previous view.

These abrupt changes can make an application feel less polished. Animations can help, but building them manually with CSS and JavaScript often requires extra state management and careful coordination between components.

The View Transition API provides a browser feature for animating changes between different visual states. React developers can use it to create smoother navigation, image transitions, and component updates without building every animation from scratch.

In this article, you will learn how the View Transition API works, how to use it in React, and how to handle browser compatibility and accessibility.

What Is the View Transition API?

The View Transition API allows a browser to capture the current visual state of a page, apply an update, capture the new state, and animate between them.

For example, imagine a product listing page containing several product images. When a user selects an item, the application opens a details page showing a larger version of the selected image.

Instead of replacing the image abruptly, the browser can animate its transition from the original position to the new position.

The API supports transitions between DOM states in a single document. It also supports cross-document transitions between eligible navigations, subject to browser support and the required document configuration.

React does not provide its own built-in View Transition API. Instead, React applications can call the browser's native API and coordinate it with state updates.

The main benefit is that the browser handles much of the visual transition process while React continues to manage the application interface.

Why Use View Transitions in React?

Traditional CSS animations are useful when an element moves, fades, or changes size. However, transitions between different component states can require additional coordination.

For example, when one component disappears and another appears, a CSS animation alone may not preserve a visual relationship between the two elements.

View transitions allow developers to identify related elements and let the browser animate their visual states.

Common use cases include:

Navigating between a product list and a product details page.
Expanding an image into a larger view.
Switching between tabs or application sections.
Animating dashboard panels when their content changes.
Improving the visual continuity of client-side navigation.

These transitions are most useful when they help users understand how the interface changes. Animating every element can make an application distracting and slower to navigate.

How View Transitions Work

The basic browser API is document.startViewTransition().

It accepts a callback that updates the document. The browser captures the old visual state, executes the callback, and captures the new state before running the transition animation.

A simplified example looks like this:

function updateContent() {
  const transition = document.startViewTransition(() => {
    document.querySelector("#content").textContent =
      "New content";
  });

  return transition;
}

The browser then animates between the previous and updated visual states using its default transition behavior or custom CSS.

The API is asynchronous. Its returned transition object exposes promises that can be used to track different stages of the transition.

In React, the callback should update React state rather than manually replacing elements managed by React.

Create a View Transition in React

Let's build a small example in which a user switches between two panels.

Step 1: Create the React Component

The following component uses React state to control the visible content.

import { useState } from "react";
import "./App.css";

export default function App() {
  const [showDetails, setShowDetails] = useState(false);

  function toggleView() {
    const update = () => {
      setShowDetails((current) => !current);
    };

    if (
      typeof document.startViewTransition === "function"
    ) {
      document.startViewTransition(update);
    } else {
      update();
    }
  }

  return (
    <main className="container">
      <h1>React View Transitions</h1>

      <button onClick={toggleView}>
        {showDetails ? "Show Overview" : "Show Details"}
      </button>

      <section className="panel">
        {showDetails ? (
          <div className="details">
            <h2>Product Details</h2>
            <p>
              Explore the product features and specifications.
            </p>
          </div>
        ) : (
          <div className="overview">
            <h2>Product Overview</h2>
            <p>
              Learn about the product before exploring its details.
            </p>
          </div>
        )}
      </section>
    </main>
  );
}

The toggleView function checks whether the browser supports the API before using it.

When supported, the function passes the React state update to document.startViewTransition(). Otherwise, it performs the same update without animation.

This fallback is important because an unsupported browser should still display the correct content.

React remains responsible for rendering the component. Avoid modifying React-managed DOM nodes directly inside the transition callback.

Step 2: Add CSS Transitions

Create an App.css file:

.container {
  max-width: 700px;
  margin: 40px auto;
  padding: 24px;
  font-family: Arial, sans-serif;
}

button {
  padding: 10px 16px;
  margin-bottom: 20px;
  cursor: pointer;
}

.panel {
  padding: 24px;
  border-radius: 12px;
  background: #f2f5f9;
  view-transition-name: product-panel;
}

::view-transition-old(product-panel) {
  animation: fade-out 180ms ease-out both;
}

::view-transition-new(product-panel) {
  animation: fade-in 220ms ease-in both;
}

@keyframes fade-out {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

@keyframes fade-in {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

The view-transition-name property identifies the panel as a named transition element.

The browser creates transition pseudo-elements for the old and new visual states. The CSS rules control how those states fade out and in.

The timing values are examples rather than universal performance recommendations. Adjust them according to the interface and test the result on supported devices.

Animate React State Updates Safely

The previous example demonstrates a basic transition. More complex applications need to handle asynchronous updates, repeated clicks, and component rendering.

React state updates may be batched, and the view transition callback should not be treated as a general-purpose asynchronous task runner.

For example, avoid writing an async callback that fetches data and then performs a state update:

document.startViewTransition(async () => {
  const response = await fetch("/api/products");
  const products = await response.json();

  setProducts(products);
});

The browser expects the transition callback to perform the update that should be captured as the new visual state. Returning a promise does not automatically make arbitrary asynchronous work part of the transition.

Instead, fetch the data first, then initiate the transition when the application is ready to render the new state.

async function loadProducts() {
  const response = await fetch("/api/products");

  if (!response.ok) {
    throw new Error("Unable to load products.");
  }

  const products = await response.json();

  const update = () => {
    setProducts(products);
  };

  if (
    typeof document.startViewTransition === "function"
  ) {
    document.startViewTransition(update);
  } else {
    update();
  }
}

In production, handle request failures and display a suitable loading or error state. Also consider whether the new content should appear immediately rather than waiting for data retrieval.

Use Named Elements for Connected Transitions

Named transition elements are particularly useful when the same content appears in different layouts.

Suppose a product image appears as a small thumbnail on one screen and a larger image on another. Assigning the same view-transition-name to the corresponding element in each state allows the browser to animate the visual connection.

.product-image {
  view-transition-name: selected-product;
}

The name should identify a unique transition element within the relevant view.

If a product list contains multiple images, assigning the same name to every image can cause problems because transition names are expected to identify distinct elements in a captured state.

Use a stable, unique name for the selected item, and remove or change that name when the item is no longer the transition target.

This technique works well for product galleries, article previews, profile images, and similar interfaces.

React View Transitions vs. Traditional CSS Animations

Both approaches are useful, but they solve different problems.

Feature	View Transition API	Traditional CSS animations
Main purpose	Animate visual changes between document states	Animate properties of existing elements
DOM replacement	Can animate between old and new visual states	Usually requires additional coordination
Browser support	Depends on View Transition API support	Widely supported for common animation properties
React integration	Requires coordinating the browser API with state updates	Usually controlled through classes, styles, or animation libraries
Complex navigation	Useful for connected page and component transitions	Possible, but may require additional implementation
Accessibility	Requires attention to motion preferences and interaction design	Also requires attention to motion preferences and interaction design

View transitions do not replace CSS animations. They complement them by providing a mechanism for transitioning between visual states.

For a simple button hover or a color change, ordinary CSS is usually sufficient. For navigation between related content, the View Transition API may provide a cleaner solution.

Browser Support and Accessibility

Before adopting view transitions, check the browsers your application supports. Feature availability differs across browsers and versions, particularly for newer API capabilities.

Use feature detection instead of assuming the API exists:

const supportsViewTransitions =
  typeof document.startViewTransition === "function";

Provide a nonanimated fallback so the application remains usable when the API is unavailable.

Accessibility also matters. Some users prefer reduced motion because animations can cause discomfort or distraction.

You can respect this preference in CSS:

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(product-panel),
  ::view-transition-new(product-panel) {
    animation-duration: 0.01ms;
    animation-iteration-count: 1;
  }
}

This example minimizes the animation duration. Test the result in supported browsers and ensure that the interface remains understandable without motion.

Do not use animation as the only way to communicate an important status change. Content, focus management, and accessible labels should still provide the information users need.

Common Mistakes to Avoid

One common mistake is calling document.startViewTransition() without checking whether it exists. This can cause runtime errors in unsupported browsers.

Another mistake is changing the DOM directly while React is managing the same elements. Such changes can conflict with React's rendering process. Update state through React and let React produce the new DOM.

Developers should also avoid using the same transition name for multiple elements in a single state. Give connected elements unique and meaningful names.

Finally, avoid adding transitions to every component. Too many animations can distract users and make navigation feel slower, even when the application responds quickly.

Best Practices for Production Applications

Use view transitions when they explain a visual relationship between two states. Keep animations short enough to preserve a responsive experience, and avoid blocking important interactions while a transition is running.

Use feature detection and provide a fallback. Respect reduced-motion preferences, and test transitions on different screen sizes and supported browsers.

For data-driven applications, separate data fetching from the visual transition. Fetch and validate the required data first, then transition to the updated state when appropriate.

Measure the real user experience rather than judging animations only on a development machine. Large images, complex layouts, and expensive rendering work can affect how smooth a transition feels.

Advantages and Disadvantages

Advantages

Creates smoother transitions between related visual states.
Reduces the need to manually coordinate some animations.
Works with React state updates when integrated correctly.
Supports connected transitions between related elements.
Allows graceful fallback to normal rendering.

Disadvantages

Browser support varies by API feature.
Complex state changes require careful coordination.
Incorrect transition names can cause unexpected behavior.
Large visual changes can still produce distracting animations.
Accessibility and reduced-motion support require deliberate testing.

Summary

The View Transition API gives React developers another way to create smooth transitions between component states and page views. It is particularly useful when the relationship between the old and new content matters, such as opening a product detail page or switching between related views.

Start by checking browser support, wrap the appropriate React state update in document.startViewTransition(), and use CSS to customize the animation. For asynchronous operations, prepare the data before initiating the transition.

The best results come from using animations purposefully, preserving React's control over the DOM, and providing accessible fallbacks for users who cannot or prefer not to use motion.