How to Use View Transitions in Astro for Smooth Page Changes

In Astro, you can use the native document.startViewTransition() API inside client scripts to create smooth view transitions between page states. Wrap your navigation or state changes inside this method to animate the content change seamlessly.

Syntax

The basic syntax for using view transitions in Astro involves calling document.startViewTransition() with a callback that updates the page content or navigates to a new route.

• document.startViewTransition(() => { ... }): Starts the transition and runs the callback where you update the DOM or navigate.
• The callback should contain the code that changes the view, like updating state or calling Astro's client-side navigation.
• The browser animates the transition automatically between the old and new content.

javascript

document.startViewTransition(() => {
  // Update page content or navigate here
  window.location.href = '/new-page';
});

Example

This example shows how to use view transitions in an Astro component with client-side navigation. When the button is clicked, the page smoothly transitions to a new route.

astro

---
// src/components/ViewTransitionButton.astro
---
<script type="module" client:load>
  import { useNavigate } from 'astro/client';
  const navigate = useNavigate();

  function handleClick() {
    document.startViewTransition(() => {
      navigate('/about');
    });
  }
</script>

<button onClick={handleClick} aria-label="Go to About page">Go to About</button>

Output

<button>Go to About</button> (clicking triggers smooth page transition to /about)

Common Pitfalls

Common mistakes when using view transitions in Astro include:

• Not wrapping the navigation or DOM update inside startViewTransition(), which disables the animation.
• Trying to use view transitions on full page reloads instead of client-side navigation.
• Forgetting to enable client-side JavaScript with client:load or similar directives in Astro components.
• Using incompatible navigation methods that do not update the DOM asynchronously.

javascript

/* Wrong way: navigation outside startViewTransition disables animation */
function wrongClick() {
  navigate('/about'); // No animation
}

/* Right way: wrap navigation inside startViewTransition */
function rightClick() {
  document.startViewTransition(() => {
    navigate('/about');
  });
}

Quick Reference

Tips for using view transitions in Astro:

• Always wrap DOM or navigation changes inside document.startViewTransition().
• Use Astro's client directives like client:load to enable JavaScript.
• Use client-side navigation methods (like Astro's useNavigate) for smooth transitions.
• Test transitions in browsers that support the View Transitions API (Chrome 111+).

Key Takeaways

Wrap page state changes or navigation inside document.startViewTransition() for smooth animations.

Enable client-side JavaScript in Astro components using client directives like client:load.

Use Astro's client-side navigation methods to avoid full page reloads and enable transitions.

View Transitions API is supported in modern browsers like Chrome 111 and later.

Avoid updating the page outside the startViewTransition callback to keep animations working.