React View Transitions
Animate between UI states using the browser's native
document.startViewTransition
. Declare
what
with
, trigger
when
with
startTransition
/
useDeferredValue
/
Suspense
, control
how
with CSS classes. Unsupported browsers skip animations gracefully.
When to Animate
Every
should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
Implement
all
applicable patterns from this list, in this order:
Priority
Pattern
What it communicates
1
Shared element
(
name
)
"Same thing — going deeper"
2
Suspense reveal
"Data loaded"
3
List identity
(per-item
key
)
"Same items, new arrangement"
4
State change
(
enter
/
exit
)
"Something appeared/disappeared"
5
Route change
(layout-level)
"Going to a new place"
This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
Choosing Animation Style
Context
Animation
Why
Hierarchical navigation (list → detail)
Type-keyed
nav-forward
/
nav-back
Communicates spatial depth
Lateral navigation (tab-to-tab)
Bare
(fade) or
default="none"
No depth to communicate
Suspense reveal
enter
/
exit
string props
Content arriving
Revalidation / background refresh
default="none"
Silent — no animation needed
Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
Availability
Next.js:
Do
not
install
react@canary
— the App Router already bundles React canary internally.
ViewTransition
works out of the box.
npm ls react
may show a stable-looking version; this is expected.
Without Next.js:
Install
react@canary react-dom@canary
(
ViewTransition
is not in stable React).
Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
Implementation Workflow
When adding view transitions to an existing app,
follow
references/implementation.md
step by step.
Start with the audit — do not skip it. Copy the CSS recipes from
references/css-recipes.md
into the global stylesheet — do not write your own animation CSS.
Core Concepts
The
Component
import
{
ViewTransition
}
from
'react'
;
<
ViewTransition
<
Component
/>
</
ViewTransition
React auto-assigns a unique
view-transition-name
and calls
document.startViewTransition
behind the scenes. Never call
startViewTransition
yourself.
Animation Triggers
Trigger
When it fires
enter
first inserted during a Transition
exit
first removed during a Transition
update
DOM mutations inside a
. With nested VTs, mutation applies to the innermost one
share
Named VT unmounts and another with same
name
mounts in the same Transition
Only
startTransition
,
useDeferredValue
, or
Suspense
activate VTs. Regular
setState
does not animate.
Critical Placement Rule
only activates enter/exit if it appears
before any DOM nodes
:
// Works
<
ViewTransition
enter
=
"
auto
"
exit
=
"
auto
"
<
div
Content
</
div
</
ViewTransition
// Broken — div wraps the VT, suppressing enter/exit
<
div
<
ViewTransition
enter
=
"
auto
"
exit
=
"
auto
"
<
div
Content
</
div
</
ViewTransition
</
div
Styling with View Transition Classes
Props
Values:
"auto"
(browser cross-fade),
"none"
(disabled),
"class-name"
(custom CSS), or
{ [type]: value }
for type-specific animations.
<
ViewTransition
default
=
"
none
"
enter
=
"
slide-in
"
exit
=
"
slide-out
"
share
=
"
morph
"
/>
If
default
is
"none"
, all triggers are off unless explicitly listed.
CSS Pseudo-Elements
::view-transition-old(.class)
— outgoing snapshot
::view-transition-new(.class)
— incoming snapshot
::view-transition-group(.class)
— container
::view-transition-image-pair(.class)
— old + new pair
See
references/css-recipes.md
for ready-to-use animation recipes.
Transition Types
Tag transitions with
addTransitionType
so VTs can pick different animations based on context. Call it multiple times to stack types — different VTs in the tree react to different types:
startTransition
(
(
)
=>
{
addTransitionType
(
'nav-forward'
)
;
addTransitionType
(
'select-item'
)
;
router
.
push
(
'/detail/1'
)
;
}
)
;
Pass an object to map types to CSS classes. Works on
enter
,
exit
,
and
share
:
<
ViewTransition
enter
=
{
{
'nav-forward'
:
'slide-from-right'
,
'nav-back'
:
'slide-from-left'
,
default
:
'none'
}
}
exit
=
{
{
'nav-forward'
:
'slide-to-left'
,
'nav-back'
:
'slide-to-right'
,
default
:
'none'
}
}
share
=
{
{
'nav-forward'
:
'morph-forward'
,
'nav-back'
:
'morph-back'
,
default
:
'morph'
}
}
default
=
"
none
"
<
Page
/>
</
ViewTransition
enter
and
exit
don't have to be symmetric. For example, fade in but slide out directionally:
<
ViewTransition
enter
=
{
{
'nav-forward'
:
'fade-in'
,
'nav-back'
:
'fade-in'
,
default
:
'none'
}
}
exit
=
{
{
'nav-forward'
:
'nav-forward'
,
'nav-back'
:
'nav-back'
,
default
:
'none'
}
}
default
=
"
none
"
TypeScript:
ViewTransitionClassPerType
requires a
default
key in the object.
For apps with multiple pages, extract the type-keyed VT into a reusable wrapper:
export
function
DirectionalTransition
(
{
children
}
:
{
children
:
React
.
ReactNode
}
)
{
return
(
<
ViewTransition
enter
=
{
{
'nav-forward'
:
'nav-forward'
,
'nav-back'
:
'nav-back'
,
default
:
'none'
}
}
exit
=
{
{
'nav-forward'
:
'nav-forward'
,
'nav-back'
:
'nav-back'
,
default
:
'none'
}
}
default
=
"
none
"
{
children
}
</
ViewTransition
)
;
}
router.back()
and Browser Back Button
router.back()
and the browser's back/forward buttons do
not
trigger view transitions (
popstate
is synchronous, incompatible with
startViewTransition
). Use
router.push()
with an explicit URL instead.
Types and Suspense
Types are available during navigation but
not
during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
Shared Element Transitions
Same
name
on two VTs — one unmounting, one mounting — creates a shared element morph:
<
ViewTransition
name
=
"
hero-image
"
<
img
src
=
"
/thumb.jpg
"
onClick
=
{
(
)
=>
startTransition
(
(
)
=>
onSelect
(
)
)
}
/>
</
ViewTransition
// On the other view — same name
<
ViewTransition
name
=
"
hero-image
"
<
img
src
=
"
/full.jpg
"
/>
</
ViewTransition
Only one VT with a given
name
can be mounted at a time — use unique names (
photo-${id}
). Watch for reusable components: if a component with a named VT is rendered in both a modal/popover
and
a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
share
takes precedence over
enter
/
exit
. Think through each navigation path: when no matching pair forms (e.g., the target page doesn't have the same name),
enter
/
exit
fires instead. Consider whether the element needs a fallback animation for those paths.
Never use a fade-out exit on pages with shared morphs — use a directional slide instead.
Common Patterns
Enter/Exit
{
show
&&
(
<
ViewTransition
enter
=
"
fade-in
"
exit
=
"
fade-out
"
<
Panel
/>
</
ViewTransition
)
}
List Reorder
{
items
.
map
(
item
=>
(
<
ViewTransition
key
=
{
item
.
id
}
<
ItemCard
item
=
{
item
}
/>
</
ViewTransition
)
)
}
Trigger inside
startTransition
. Avoid wrapper
s between list and VT.
Composing Shared Elements with List Identity
Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested
boundaries:
{
items
.
map
(
item
=>
(
<
ViewTransition
key
=
{
item
.
id
}
>
{
/* list identity */
}
<
Link
href
=
{
`
/items/
${
item
.
id
}
`
}
>
<
ViewTransition
name
=
{
`
item-image-
${
item
.
id
}
`
}
share
=
"
morph
"
>
{
/* shared element */
}
<
Image
src
=
{
item
.
image
}
/>
<
p
>
{
item
.
name
}
)
)
}
The outer VT handles list reorder/enter animations. The inner VT handles the cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
Force Re-Enter with
key
<
ViewTransition
key
=
{
searchParams
.
toString
(
)
}
enter
=
"
slide-up
"
default
=
"
none
"
>
<
ResultsGrid
/>
Caution:
If wrapping
, changing
key
remounts the boundary and refetches.
Suspense Fallback to Content
Simple cross-fade:
<
ViewTransition
>
<
Suspense
fallback
=
{
<
Skeleton
/>
}
>
<
Content
/>
Directional reveal:
<
Suspense
fallback
=
{
<
ViewTransition
exit
=
"
slide-down
"
>
<
Skeleton
/>
}
>
<
ViewTransition
enter
=
"
slide-up
"
default
=
"
none
"
>
<
Content
/>
For more patterns, see
references/patterns.md
.
How Multiple VTs Interact
Every VT matching the trigger fires simultaneously in a single
document.startViewTransition
. VTs in
different
transitions (navigation vs later Suspense resolve) don't compete.
Use
default="none"
Liberally
Without it, every VT fires the browser cross-fade on
every
transition — Suspense resolves,
useDeferredValue
updates, background revalidations. Always use
default="none"
and explicitly enable only desired triggers.
Two Patterns Coexist
Pattern A — Directional slides:
Type-keyed VT on each page, fires during navigation.
Pattern B — Suspense reveals:
Simple string props, fires when data loads (no type).
They coexist because they fire at different moments.
default="none"
on both prevents cross-interference. Always pair
enter
with
exit
. Place directional VTs in page components, not layouts.
Nested VT Limitation
When a parent VT exits, nested VTs inside it do
not
fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See
react#36135
for an experimental opt-in fix.
Next.js Integration
For Next.js setup (
experimental.viewTransition
flag,
transitionTypes
prop on
next/link
, App Router patterns, Server Components), see
references/nextjs.md
.
Accessibility
Always add the reduced motion CSS from
references/css-recipes.md
to your global stylesheet.
Reference Files
references/implementation.md
— Step-by-step implementation workflow.
references/patterns.md
— Patterns, animation timing, events API, troubleshooting.
references/css-recipes.md
— Ready-to-use CSS animation recipes.
references/nextjs.md
— Next.js App Router patterns and Server Component details.
Full Compiled Document
For the complete guide with all reference files expanded:
AGENTS.md
← 返回排行榜