Route Progress React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Route Progress is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import RouteProgress from @/components/ui/route-progress.

"use client"

import type { ReactNode } from "react"
import Link from "next/link"
import { usePathname, useRouter } from "next/navigation"
import { Button } from "@/components/ui/button"
import { RouteProgress, routeProgress } from "@/components/ui/route-progress"
import { LinkProvider } from "@/lib/navigation"

// once, in the root layout's client providers: every NavLink click starts the bar, the new path finishes it
export function Providers({ children }: { children: ReactNode }) {
  const router = useRouter()
  return (
    <LinkProvider component={Link} currentPath={usePathname()} navigate={router.push}>
      <RouteProgress />
      {children}
    </LinkProvider>
  )
}

// by hand, for any async work
export function SaveInvoice({ save }: { save: () => Promise<void> }) {
  return (
    <Button
      onClick={async () => {
        routeProgress.start()
        try {
          await save()
        } finally {
          routeProgress.done()
        }
      }}
    >
      Save invoice
    </Button>
  )
}

Props

• autodefault true
  boolean

  Starts on in-app navigations (a NavLink click, useNavigate) and finishes when the current path changes. A click on the current page, a hash or a query change does not count.

• loading
  boolean

  Controlled mode: true starts, false finishes. It overrides auto. Leave it undefined to use auto and the imperative routeProgress API. Docs-only: the Controlled loading example drives it from a fake request.

• currentPath
  string

  The path whose change finishes a navigation. Defaults to the LinkProvider's currentPath, which is how the playground feeds it.

• delaydefault 120
  number

  Milliseconds before the bar appears. Anything that finishes sooner never shows it, so fast pages do not flash.

• minimumdefault 0.08
  number

  Where the bar starts, as a fraction of the width.

• trickledefault true
  boolean

  Creeps toward 90% while waiting; each step covers 5 to 15% of the distance left.

• trickleSpeeddefault 250
  number

  Milliseconds between trickle steps.

• timeoutdefault 10000
  number

  Milliseconds after which a navigation that never finished completes anyway (a cancelled route, a redirect back to the same page). 0 turns the safety net off.

• sizedefault "md"
  "sm" | "md" | "lg"

  Bar height: 2 / 3 / 4px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The bar's color from the design tokens. neutral is black in light mode and white in dark mode.

• colordefault ""
  string

  Any CSS color. Replaces the tone for the bar, the glow and the spinner. Leave empty to use the tone.

• glowdefault true
  boolean

  A soft glow on the last 96px of the bar, at 60% opacity. Dropped under reduced motion.

• spinnerdefault false
  boolean

  A 14px ring spinner in a small floating chip under the top end of the bar while loading.

• positiondefault "fixed"
  "fixed" | "absolute"

  fixed pins it to the top of the viewport; absolute pins it to the nearest positioned ancestor (a card, a panel, a demo frame).

• offsetdefault 0
  number

  Pixels from the top, e.g. 56 to sit under a fixed header.

• safeAreadefault true
  boolean

  Adds env(safe-area-inset-top) to the offset, so an installed web app draws the bar under the status bar. It is 0 in desktop browsers.

• labeldefault "Loading page"
  string

  The progressbar's aria-label.

• storedefault "routeProgress"
  RouteProgressStore

  The store this bar shows. Defaults to the shared routeProgress; pass createRouteProgress() when two bars must not share state.

• classNames
  Partial<Record<"track" | "bar" | "glow" | "spinner", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:var(--info)].

Parts

FAQ

More React feedback components