Installation

pnpm dlx uselab@latest add use-page-transition

Usage

import * as React from "react"
 
import { usePageTransition } from "@/hooks/use-page-transition"
 
export function LayoutWithSpinner({ children }: { children: React.ReactNode }) {
  const { isTransitioning } = usePageTransition({ minDuration: 200 })
 
  return (
    <div className="relative">
      {isTransitioning && (
        <div className="absolute inset-x-0 top-0 z-10 h-0.5 animate-pulse bg-gradient-to-r from-sky-500 via-violet-500 to-emerald-500" />
      )}
      {children}
    </div>
  )
}

API Reference

usePageTransition(options?)

Parameters

Return value

Events tracked

The hook wires into multiple browser signals to infer “page transitions”:

• SPA routing
  • Patches history.pushState and history.replaceState.
  • Listens to popstate for back/forward navigations.
• Browser-driven navigations
  • beforeunload and pagehide start a transition.
  • pageshow and visibilitychange (back to visible) clear transitions.

In all cases, transitions are debounced with minDuration so your loaders do not flicker for ultra-fast route changes.

Types

interface UsePageTransitionOptions {
  minDuration?: number
}
 
interface UsePageTransitionResult {
  isTransitioning: boolean
}

Notes

• Designed for SPA-style routing where you want a global “page is changing” flag without coupling to a specific router.
• For frameworks that already expose navigation events (e.g., Next.js App Router, React Router), you can combine those with usePageTransition or rely on the hook’s history/visibility detection as a drop-in solution.
• Use it to drive top-level progress bars, blur overlays, skeleton pages, or to temporarily disable critical actions during transitions.