Page Transitions in Next.js App Router: What Failed and What Worked

Adding a simple fade transition to the main content area sounds like frontend 101. In the Next.js App Router, it took three attempts to get right — including a memorable "content → blank → content" triple flash along the way.

This post documents the full debugging journey and the final solution.

#The Goal

On route changes, fade in the main content area. Nav and footer stay put; only the content region animates.

The reference feel: cheyuwu.com — subtle, not flashy, but enough to signal that navigation happened.

#Attempt 1: layout + AnimatePresence (failed — flicker)

The obvious approach: wrap children in layout.tsx with framer-motion's AnimatePresence for a fade-out-then-fade-in sequence.

1
<AnimatePresence mode="wait">
2
  <motion.div
3
    key={pathname}
4
    initial={{ opacity: 0 }}
5
    animate={{ opacity: 1 }}
6
    exit={{ opacity: 0 }}
7
  >
8
    {children}
9
  </motion.div>
10
</AnimatePresence>

What happened: Every navigation flashed — like "content appears → blank → content appears again."

Why: children in layout.tsx is a shared slot. On navigation, Next.js immediately injects the new page content — it does not wait for the exit animation to finish.

The timeline:

1. New content is already rendered (flash)
2. Old content's exit animation runs (blank)
3. New content's enter animation runs (appears again)

This is not a performance issue. It is an architectural mismatch between layout + AnimatePresence and the App Router's children update model.

#Attempt 2: template.tsx (failed — no effect)

Docs suggest template.tsx remounts on navigation — perfect for enter animations, right?

1
'use client'
2

3
export default function Template({ children }) {
4
  return (
5
    <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
6
      {children}
7
    </motion.div>
8
  )
9
}

What happened: No animation at all when switching between home and the writing page.

Why: template.tsx only remounts when its own segment changes.

Our file lives at app/[locale]/template.tsx. Navigating from / to /writing does not change locale (both are zh) — only the child segment changes. The template never remounts, so the animation never fires.

From the Next.js docs:

Templates remount when that segment (including its dynamic params) changes. Navigations within deeper segments do not remount higher-level templates.

For template-based animations to work here, the file would need to sit at a segment level that changes on every page navigation — or you accept it only covers cases like locale switches.

#Attempt 3: layout fade-in with pathname as key (works)

Back to layout, but with a different strategy: skip exit animation, only fade in. Use key={pathname} so the motion.div fully remounts on route change.

1
'use client'
2

3
import { usePathname } from '@/i18n/routing'
4
import { motion } from 'framer-motion'
5

6
const isFirst = { current: true }
7

8
export default function PageTransition({ children }: { children: React.ReactNode }) {
9
  const pathname = usePathname()
10
  const skipInitial = isFirst.current
11

12
  useEffect(() => {
13
    if (isFirst.current) isFirst.current = false
14
  }, [])
15

16
  return (
17
    <motion.div
18
      key={pathname}
19
      initial={skipInitial ? false : { opacity: 0 }}
20
      animate={{ opacity: 1 }}
21
      transition={{ duration: 0.3, ease: 'easeOut' }}
22
    >
23
      {children}
24
    </motion.div>
25
  )
26
}

In layout.tsx:

1
<main className="flex-1">
2
  <PageTransition>{children}</PageTransition>
3
</main>

Result: Old page vanishes instantly. New page fades in over 300ms. Clean, no flicker.

#Why does this work?

The core idea: do not fight the App Router's children update model. When the new page arrives, put it in a fresh container and fade that in.

#What about bidirectional animations?

Fade-in only is the most reliable approach in the App Router today. For true fade-out + fade-in, the options are:

• React 19's <ViewTransition> with Next.js 16's experimental.viewTransition (browser-native View Transitions API)
• Accept the trade-off: old page disappears instantly, new page fades in (good enough for most blogs)

I chose the latter for this site. Simple, zero flicker, easy to maintain.

#Summary

Page transition animations in the App Router are less about picking an animation library and more about understanding the lifecycle of layout, template, and children. Once that clicks, a dozen lines of code is enough.