AnimatePresence

1. The wrapper must persist across the navigation. If

   AnimatePresence

   lives in a component that itself unmounts, there is nothing left to run the exit.
2. The child's

   key

   must change per route so AnimatePresence sees "old removed, new added".
3. During the brief overlap, the outgoing subtree must still render its old content — but the App Router has already swapped the route context, so the outgoing tree would otherwise render the new page's data. This is what FrozenRouter fixes.

template.tsx

layout.tsx

AnimatePresence

// app/template.tsx
'use client';
import { AnimatePresence } from 'framer-motion';
import { usePathname } from 'next/navigation';
import { FrozenRouter } from './frozen-router';
import { PageTransition } from './page-transition';

export default function Template({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  return (
    <AnimatePresence mode="wait" initial={false}>
      {/* key on pathname so AnimatePresence sees old removed / new added */}
      <PageTransition key={pathname}>
        {/* FrozenRouter keeps the OUTGOING tree rendering its old content
            while it animates out */}
        <FrozenRouter>{children}</FrozenRouter>
      </PageTransition>
    </AnimatePresence>
  );
}

// app/page-transition.tsx
'use client';
import { motion } from 'framer-motion';

export function PageTransition({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 12 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -12 }}
      transition={{ duration: 0.3, ease: [0.22, 1, 0.36, 1] }}
    >
      {children}
    </motion.div>
  );
}

// app/frozen-router.tsx
'use client';
import { useContext, useRef } from 'react';
import {
  LayoutRouterContext,
} from 'next/dist/shared/lib/app-router-context.shared-runtime';

// Freezes the router context so the exiting page keeps rendering its
// OWN content during the exit animation instead of the next route's.
export function FrozenRouter({ children }: { children: React.ReactNode }) {
  const context = useContext(LayoutRouterContext ?? {});
  const frozen = useRef(context).current;

  return (
    <LayoutRouterContext.Provider value={frozen}>
      {children}
    </LayoutRouterContext.Provider>
  );
}

• mode="wait"

  makes AnimatePresence fully finish the exit before mounting the new page. (Use the default mode if enter/exit should overlap/crossfade.)

• initial={false}

  skips the enter animation on first load (optional).

• key={pathname}

  is what makes AnimatePresence treat each route as a distinct presence.

• FrozenRouter

  snapshots

  LayoutRouterContext

  so the outgoing subtree renders the previous route's content throughout the exit, instead of flashing the new route's content. Without it, exit either skips or shows the wrong content.

LayoutRouterContext

1. Wrapper stays mounted.

   AnimatePresence

   must live in something persistent — ideally

   template.tsx

   , or a layout-level client component — not inside the page that's unmounting.
2. Stable, changing key. The animated child needs

   key={pathname}

   (or similar) so removal is detected. No key, or a key that doesn't change → no exit.
3. Direct motion descendant. The element with the

   exit

   prop must be a

   motion.*

   component and a child of

   AnimatePresence

   (a non-motion wrapper in between can block detection).

4. mode="wait"

   if old and new should not overlap; without it both render simultaneously and may jump.
5. FrozenRouter present if the outgoing page flashes the new route's content during exit.

6. 'use client'

   on every file using AnimatePresence/usePathname/motion.
7. Single child at a time under

   mode="wait"

   — AnimatePresence expects one keyed presence to swap.

Packaged helper (

scripts/

):

scripts/seek-shot.sh anim.html 0 1.5 3

freezes the

?t=N

harness and screenshots each moment;

scripts/contact-sheet.sh sheet.png frame-*.png

tiles them for one-glance review. See

scripts/README.md

.

motion

• One

  .html

  file: two view stubs and a toggle, animated with either an inline

  <script type="module">

  importing

  motion

  /React from CDN, or

  document.startViewTransition

  +

  ::view-transition-*

  CSS.
• A way to freeze the resolved end state — a route transition is state-driven (which view, mid-swap), so screenshot the state, not a clock.

?view=b

?phase=exit

<script>
  const p = new URLSearchParams(location.search);
  document.documentElement.dataset.view = p.get("view") || "a";   // CSS/React keys off this
  // Framer Motion: set the controlled key/route from ?view; for mode="wait" the resolved end is the new page
  // View Transitions: screenshot the END state (snapshots are transient); or pause via emulate slow animations
  window.__ready = true;
</script>

?view=a

?phase=exit

?view=b

mode="wait"

npx playwright screenshot --wait-for-timeout=500 "file://$PWD/transition.html?view=b" dest.png

1. Opens standalone — no console errors, CDN

   motion

   /React (if used) resolves,

   startViewTransition

   guarded.
2. The

   ?view=

   /

   ?phase=

   freeze lands a deterministic transition phase.
3. Screenshotted at source / mid / destination — matches the brief, no content flash or skipped exit.

4. prefers-reduced-motion

   honored — slide/translate dropped to a short crossfade.
5. Easing is intentional — entrances ease-out, exits ease-in, durations ~0.2–0.4s (not laggy under

   mode="wait"

   ).

• layout.tsx

  persists and will NOT remount per route — use

  template.tsx

  for per-route enter animations.
• Omitting FrozenRouter makes the exiting page render the new route's content mid-animation (visible flash) or skip exit entirely.

• LayoutRouterContext

  import path is a Next internal; it may change across versions — first thing to fix after an upgrade.
• Without

  key={pathname}

  , AnimatePresence sees the same child and never triggers exit.

• mode="wait"

  waits for exit before enter; overusing it on slow exits makes navigation feel laggy — tune durations (~0.2-0.4s).
• View Transitions API lacks full browser support; always guard

  document.startViewTransition

  .
• Every transition file needs

  'use client'

  ; server components can't use AnimatePresence/usePathname.

• references/full-examples.md

  — directional/slide transitions, shared-element View Transitions with

  view-transition-name

  , a non-

  mode="wait"

  crossfade variant, loading-state transitions with

  loading.tsx

  , and a complete working App Router folder layout.