# Shared-Element Page Transitions with React ViewTransition

> Source: https://agilitycms.com/docs/nextjs/view-transitions-with-next-js

When a visitor clicks a blog card, the card's image can grow into the post's hero image instead of the page just swapping. This article shows how the [Advanced Next.js Demo Site](/docs/nextjs/using-the-advanced-next-js-demo-site) does it with React's `ViewTransition` component, and what to copy into your own site.

## See it in the demo

Open the [blog listing](https://demo.agilitycms.com/blog) and click any post. The card image moves and resizes into the hero image at the top of the post. Go back and it reverses. If your browser doesn't support view transitions, the navigation works as normal, with no animation.

The code lives in these files:

- [`src/components/agility-components/post-listing/PostCard.tsx`](https://github.com/agility/nextjs-demo-site-2026/blob/main/src/components/agility-components/post-listing/PostCard.tsx), the card on the listing
- [`src/components/agility-components/post-details/PostImage.tsx`](https://github.com/agility/nextjs-demo-site-2026/blob/main/src/components/agility-components/post-details/PostImage.tsx), the hero image on the post
- [`src/lib/hooks/useViewTransition.ts`](https://github.com/agility/nextjs-demo-site-2026/blob/main/src/lib/hooks/useViewTransition.ts), the function that builds the shared name
- [`src/styles/view-transitions.css`](https://github.com/agility/nextjs-demo-site-2026/blob/main/src/styles/view-transitions.css), the timing

## How it works

The demo runs Next.js 16.3.5 and React 19.3.0 (`package.json`). React 19.3 made `ViewTransition` a stable export, so you import it from `react`:

```tsx
import { ViewTransition } from 'react'
```

The demo's `next.config.mjs` used to set `experimental.viewTransition`. That flag is gone: Next 16.3 no longer recognizes it and warns about it on boot, so the config just carries a comment explaining the removal. You don't need any config for this feature.

Next.js route navigations are React transitions, so a `<ViewTransition>` animates during navigation with nothing extra to wire up. React finds elements that have the same `name` on the old and new page and animates between their size and position. The [Next.js guide on view transitions](https://nextjs.org/docs/app/guides/view-transitions) covers the full set of patterns.

### The shared name

Both pages need the same name, and it has to be unique per post. The demo builds it from the post's Agility `contentID`:

```ts
// src/lib/hooks/useViewTransition.ts
export function createPostImageTransitionName(contentID: string | number) {
	return `post-image-${contentID}`
}
```

Keeping this in one function means the card and the hero can't drift apart.

### The card

`PostCard` wraps its image in `ViewTransition` and passes the post's `contentID`:

```tsx
// src/components/agility-components/post-listing/PostCard.tsx
<ViewTransition name={createPostImageTransitionName(post.contentID)}>
	<AgilityPic
		image={post.image}
		fallbackWidth={400}
		className="absolute inset-0 w-full h-full rounded-2xl ..."
		sources={[/* per-breakpoint crops */]}
	/>
</ViewTransition>
```

### The hero image

`PostImage` does the same on the post page. `PostDetails` renders it with the post's `contentID`:

```tsx
// src/components/agility-components/post-details/PostImage.tsx
<ViewTransition name={createPostImageTransitionName(contentID)}>
	<AgilityPic
		data-agility-field="image"
		image={image}
		priority
		fallbackWidth={672}
		className={className}
		sources={[/* retina and mobile variants */]}
	/>
</ViewTransition>
```

Both components are client components (`'use client'`), and both wrap an [`AgilityPic`](/docs/nextjs/using-the-agilitypic-component-for-responsive-images). The two images are cropped differently (a square on large screens in the card, a 3:2 box in the post), and the morph animates between those shapes.

### The CSS

`view-transitions.css` is imported once in `src/app/layout.tsx`. It sets the durations:

```css
/* src/styles/view-transitions.css */
@view-transition {
  navigation: auto;
}

@supports (view-transition-name: none) {
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation-duration: 400ms;
    animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
  }

  ::view-transition-old(root),
  ::view-transition-new(root) {
    animation-duration: 300ms;
    animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
  }
}
```

Named elements, like the post image, animate over 400ms. The rest of the page (`root`) cross-fades over 300ms. The `@view-transition { navigation: auto }` rule is the declaration for cross-document navigations (see [MDN's View Transition API page](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)). The blog morph itself is driven by the `ViewTransition` component.

### Browser support

The Next.js guide notes that React's integration uses newer View Transition features, available in Chromium 125+ and recent Safari and Firefox versions, and that some animations may behave differently in Safari. Where the browser doesn't support them, the app works normally and the transitions don't animate.

## Files in the demo you don't need

The demo also contains three older pieces that nothing imports:

| File | What it does | Used? |
| --- | --- | --- |
| `src/components/ViewTransitionLink.tsx` | A `Link` that calls `document.startViewTransition` around `router.push` on click | No |
| `src/components/ViewTransitionProvider.tsx` | Wraps `popstate` and internal link clicks in `document.startViewTransition` | No |
| `useViewTransition()` in `useViewTransition.ts` | Feature-detects `startViewTransition` and calls it | No |

They come from an earlier approach that triggered transitions by hand. With React's `ViewTransition`, they're redundant, and `ViewTransitionProvider` would also turn internal links into full page loads (`window.location.href`), so don't copy it. Only `createPostImageTransitionName` from that file is in use.

## Build it in your own site

1. Use Next.js 16.3 or later with React 19.3 or later, and remove `experimental.viewTransition` from your config if it's there.
2. Pick an identifier that is the same on the list and the detail page. For Agility content, the `contentID` works.
3. Write one function that turns that identifier into a name, and import it in both places.
4. Wrap the element on the listing in `<ViewTransition name={...}>`, and wrap the matching element on the detail page with the same name.
5. Optionally add a stylesheet to set `animation-duration` on `::view-transition-old(*)` and `::view-transition-new(*)`.

Two things to check if the morph doesn't play. The Next.js guide says the morph plays when the destination renders in the same commit as the navigation, which is the case for prefetched pages, and that if the destination suspends into a fallback first, no pair forms. And give each card its own name, as the demo does with the `contentID`.

## Related

- [Advanced Next.js Demo Site](/docs/nextjs/using-the-advanced-next-js-demo-site)
- [Using the AgilityPic Component for Responsive Images](/docs/nextjs/using-the-agilitypic-component-for-responsive-images)
- [How the Next.js Starter Works](/docs/nextjs/how-the-next-js-starter-works)

---

## Related pages

- [Using the Advanced Next.js Demo Site](https://agilitycms.com/docs/nextjs/using-the-advanced-next-js-demo-site.md)
- [Audience and Region Personalization with Next.js](https://agilitycms.com/docs/nextjs/audience-and-region-personalization-with-next-js.md)
- [A Provider-Agnostic Analytics Layer with PostHog in Next.js](https://agilitycms.com/docs/nextjs/analytics-layer-with-posthog-in-next-js.md)
- [AI Search, Clean Markdown and an MCP Server in a Next.js Site](https://agilitycms.com/docs/nextjs/ai-search-markdown-and-mcp-endpoints.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt
