solid-route-progress

A route progress bar for SolidJS and SolidStart: the thin loading bar along the top of the page while the next route loads. The loading drift is one CSS transition, so you theme and retime it from CSS.

Documentation · Live demo · Example on StackBlitz

Why solid-route-progress?

• With @solidjs/router it takes one component. <RouteProgress /> follows useIsRouting(), so links, navigate(), back/forward, action redirects and every <Suspense> the next route waits on show the bar.
• The drift toward completion is a single CSS transition, and no JavaScript timer steps it. Color, height and timing are custom properties.
• A navigation shorter than delay (200 ms) draws nothing, so quick loads never flash.
• Routes, track(fetch(...)) and your own start() each hold the bar, and it completes when the last one lets go.
• Navigations that leave the page (external links, form posts, reloads) show it too, through the Navigation API. solid-route-progress/navigation works without a router.
• Styles sit in a cascade layer, so Tailwind v4 utilities win without !important, and data-state works as a variant. The bar renders on the server and is a labeled role="progressbar" that follows dir="rtl" and forced colors.
• <RouteProgress /> adds about 2.4 kB min+gzip to your bundle, and there are no dependencies. The bar only animates opacity and translate, so it stays smooth on the compositor thread while the next route keeps the main thread busy.

Installation

npm i solid-route-progress
# or
pnpm add solid-route-progress
# or
yarn add solid-route-progress
# or
bun add solid-route-progress

It needs solid-js 1.9 or a later 1.x, and @solidjs/router 0.15 or 1.x for the router integration; Solid 2 is not supported yet. The bar draws in Chrome and Edge 111, Firefox 113 and Safari 15.4 or later; see browser support.

Usage

Import the stylesheet once:

/* src/app.css */
@import 'tailwindcss'; /* optional */
@import 'solid-route-progress/style.css';

Render the bar once under <Router>. With SolidStart:

// src/app.tsx
import { Router } from '@solidjs/router'
import { FileRoutes } from '@solidjs/start/router'
import { Suspense } from 'solid-js'
import { RouteProgress } from 'solid-route-progress/router'
import './app.css'

export default function App() {
  return (
    <Router
      root={(props) => (
        <>
          <RouteProgress />
          <Suspense>{props.children}</Suspense>
        </>
      )}
    >
      <FileRoutes />
    </Router>
  )
}

Theme it with custom properties, on :root or anywhere else:

:root {
  --sp-color: oklch(0.62 0.19 264); /* or a Tailwind token: var(--color-indigo-500) */
  --sp-height: 2px;
}

Hold it for work that is not a navigation. Wrap the app in <ProgressProvider>, and useProgress() reaches the same bar from anywhere:

const progress = useProgress()
progress.track(fetch('/api/items')) // shows the bar until the request settles

Without @solidjs/router, render <NavigationProgress /> from solid-route-progress/navigation instead. For server rendering, use a bundler that resolves the solid export condition, as SolidStart and vite-plugin-solid do.

Documentation

| Page | Covers | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Quick start | @solidjs/router, SolidStart, no router, and driving the bar yourself | | Styling | custom properties, Tailwind utilities, state hooks, custom templates, recipes | | Controller | createProgress() options, start(), done(), set(), track(), and the types | | Components | <Progress>, <ProgressProvider>, useProgress(), <Bar> | | Router integration | ignored links, navigations that leave the page, actions without a redirect | | Navigation API | <NavigationProgress>, for apps without a router | | Examples | live demos of each API |

For AI coding assistants

The package ships these docs as Markdown for the installed version, in node_modules/solid-route-progress/dist/docs/ (start at README.md). To have your agent read them first, add a line to your AGENTS.md or CLAUDE.md:

Before using solid-route-progress, read node_modules/solid-route-progress/dist/docs/README.md.

The site serves the same docs as llms.txt, llms-full.txt, and a .md copy of every page. There is also an agent skill for Claude Code, Codex, Cursor and other agents that read skills:

npx skills add kecan0406/solid-route-progress

Coming from NProgress / BProgress

| There | Here | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | minimum | --sp-start | | trickleSpeed, easing, speed | --sp-trickle-duration, --sp-trickle-easing, speed / --sp-speed | | trickle: false | trickleTo equal to --sp-start: the bar reveals and waits for set() / done() | | color, height, template | --sp-color, --sp-height, children | | showSpinner, spinnerPosition | the spinner recipe, placed with your own top / inset-inline-end | | parent | render the bar inside the container, class="absolute" | | direction: 'rtl' | automatic under dir="rtl" | | startPosition, delay, stopDelay | set(n), delay (default 200 ms), stopDelay | | shallowRouting, targetPreprocessor | shallow, filter(to, from) | | disableSameURL | built in: navigations the router drops never show a bar | | data-disable-progress, data-prevent-progress | data-sp-ignore | | promise() | track(promise); start() returns its own release | | inc(), dec(), pause(), resume() | none: the drift is a CSS transition, so JS holds no current position to step or freeze. Stepwise loads: set(k / n). | | indeterminate | none: trickling already reads as indeterminate to assistive tech; style data-state="trickle" as you like | | nonce, style, disableStyle, memo | not needed: styles are a stylesheet you import, components are plain Solid |

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first, and report security issues as described in SECURITY.md.

License

MIT