docs / core / page transition

Page Transition

a route-level fade and lift: content enters from below and exits softly upward, with the outgoing view finishing before the next mounts. framework-neutral, keyed on whatever routeKey you hand it.

intensity · guidesrsc · client

provenance

authored in usva

layer

core / motion

intensity

guides · leads the eye through a sequence, then clears

composition

wraps the route outlet in the app shell, onceany router works, key it on the pathnamenever nested. one transition per shellnot for in-page swaps like tabs or lists, it unmounts everything under it

a11y

returns children untouched under prefers-reduced-motion · the wrapper is a plain div, no roles, no focus trappingjest-axe

dependencies

motion
live · simulated routes
users2,412uptime99.9%builds18

the summary at a glance. switch tabs and the whole view lifts out while the next one fades up from below.

props

proptypedefaultnotes
routeKeystring—the current route. usePathname() in next, location.pathname anywhere else. a change fires the transition.
childrenReactNode—the route content. the whole subtree unmounts and remounts on every key change.

get it

bun add @usva-ui/reactcopy
usagecopy
"use client";
import { PageTransition } from "@usva-ui/react/motion/page-transition";
import { usePathname } from "next/navigation";

export function Shell({ children }) {
  return (
    <PageTransition routeKey={usePathname()}>
      {children}
    </PageTransition>
  );
}