# Introduction

Source: https://solid-route-progress.vercel.app/docs

```tsx
import { Router } from '@solidjs/router'
import { Suspense } from 'solid-js'
import { RouteProgress } from 'solid-route-progress/router'
import 'solid-route-progress/style.css'

<Router
  root={(props) => (
    <>
      <RouteProgress />
      <Suspense>{props.children}</Suspense>
    </>
  )}
/>
```

## Entry points

| Entry                             | Exports                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------ |
| `solid-route-progress`            | `createProgress`, `<Progress>`, `<ProgressProvider>`, `<Bar>`, `useProgress()`, `createCrossDocumentProgress()`, `IGNORE_ATTRIBUTE` |
| `solid-route-progress/router`     | `<RouteProgress>`, `createRouteProgress()`                                                                                             |
| `solid-route-progress/navigation` | `<NavigationProgress>`, `createNavigationProgress()`                                                                                   |
| `solid-route-progress/style.css`  | the stylesheet                                                                                                                         |

## What JavaScript writes

| Written        | On       | Value                                        |
| -------------- | -------- | -------------------------------------------- |
| `--sp-value`   | the bar  | `0` to `1`, the target of the CSS transition |
| `--sp-speed`   | the bar  | the `speed` option                           |
| `data-state`   | the bar  | `idle \| trickle \| active \| done`          |
| `data-error`   | the bar  | during the done phase of a failed load       |
| `data-sp-busy` | `<html>` | while any bar is visible                     |

Everything else is CSS.

## How it works

1. `start()` waits `delay` (200 ms), then flips `data-state` to `trickle` and sets `--sp-value` to `trickleTo` (0.95). The stylesheet's `trickle` rule has a 10 s transition on `translate` whose curve races out and then crawls. It is one transition, and no timer steps it.
2. `set(n)` switches to `active`, which leaves the bar on its short `--sp-speed` transition for the hop, then hands back to `trickle`. CSS transitions interrupt from the _current_ animated value, so there is nothing to sync.
3. Once the last hold is released (or on `done()`), the bar hops to 100% in the `done` state (with `data-error` if a hold was released as an `'error'`; a `'cancel'` skips this step and fades straight out), then `idle` fades the whole bar out with `opacity` + a delayed `visibility: hidden`. The bar itself is parked back at `--sp-start` only after the fade has finished. Both steps take `speed`, which the bar also writes to `--sp-speed`, so the CSS and the timers never disagree. A load that starts during this phase waits for the fade and for `delay`, whichever is longer.
4. If the load ends while `delay` is still pending, or before the browser painted the bar (tracked with a single `requestAnimationFrame`), the bar is dropped silently.

## Size

What each setup adds to your bundle, in bytes, after tree-shaking:

| Import                                                      | min  | gzip | brotli |
| ----------------------------------------------------------- | ---- | ---- | ------ |
| `<RouteProgress />`, `solid-route-progress/router`          | 4838 | 2363 | 2135   |
| `<NavigationProgress />`, `solid-route-progress/navigation` | 4300 | 2099 | 1905   |
| `createProgress` alone                                      | 1721 | 908  | 841    |
| `solid-route-progress/style.css`                            | 1089 | 510  | 418    |

Zero dependencies. The bar only moves `opacity` and `translate`, so its animations run on the compositor thread and stay smooth while the next route keeps the main thread busy.

## Next

[Installation](https://solid-route-progress.vercel.app/docs/installation.md) · [Quick start](https://solid-route-progress.vercel.app/docs/quick-start.md) · [Examples](https://solid-route-progress.vercel.app/docs/examples.md)

---

# Installation

Source: https://solid-route-progress.vercel.app/docs/installation

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

| Peer              | Version                                        |
| ----------------- | ---------------------------------------------- |
| `solid-js`        | 1.9 or a later 1.x                             |
| `@solidjs/router` | 0.15 or 1.x, for `solid-route-progress/router` |

Solid 2 is not supported yet.

## Stylesheet

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

```ts
import 'solid-route-progress/style.css'
```

## Browsers

The bar draws in Chrome and Edge 111, Firefox 113 and Safari 15.4 or later (`@layer`, plus `oklch()` for the default color).

| Feature                                                     | Chrome / Edge | Firefox | Safari | Without it                                    |
| ----------------------------------------------------------- | ------------- | ------- | ------ | --------------------------------------------- |
| `linear()` trickle curve                                    | 113           | 112     | 17.2   | the drift eases with `ease` instead           |
| `@property`, for `--sp-value` on your own elements          | 85            | 128     | 16.4   | those elements jump; the bar is unaffected    |
| `:dir()`, for right-to-left pages                           | 120           | 49      | 16.4   | the bar fills from the left under `dir="rtl"` |
| Navigation API, for cross-document and `NavigationProgress` | 102           | 147     | 26.2   | those navigations are not tracked             |

## Builds

| Export condition | Build                                                                   |
| ---------------- | ----------------------------------------------------------------------- |
| `solid`          | JSX untouched; SolidStart and `vite-plugin-solid` compile it themselves |
| default          | DOM-compiled, no server rendering                                       |
| `development`    | dev warnings; production resolves it to `false` and drops them          |

---

# Quick start

Source: https://solid-route-progress.vercel.app/docs/quick-start

## `@solidjs/router`

```tsx
import { Router, Route } from '@solidjs/router'
import { Suspense } from 'solid-js'
import { RouteProgress } from 'solid-route-progress/router'
import 'solid-route-progress/style.css'

const Layout = (props) => (
  <>
    <RouteProgress />
    <Suspense>{props.children}</Suspense>
  </>
)

<Router root={Layout}>
  <Route path="/" component={Home} />
</Router>
```

## SolidStart

```tsx
// 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>
  )
}
```

A complete app, themed with Tailwind: [`examples/solidstart`](https://github.com/kecan0406/solid-route-progress/tree/main/examples/solidstart) ([open in StackBlitz](https://stackblitz.com/github/kecan0406/solid-route-progress/tree/main/examples/solidstart?file=src/app.tsx)).

## Without a router

```tsx
import { NavigationProgress } from 'solid-route-progress/navigation'

const Layout = (props) => (
  <>
    <NavigationProgress />
    {props.children}
  </>
)
```

[Navigation API](https://solid-route-progress.vercel.app/docs/navigation-api.md)

## Driving it yourself

```tsx
import { ProgressProvider, useProgress } from 'solid-route-progress'

<ProgressProvider>
  <RouteProgress />
  {children}
</ProgressProvider>
```

```ts
const progress = useProgress()

await progress.track(fetch('/api/items'))

const release = progress.start()
progress.set(0.6)
release() // release('error') · release('cancel')
```

[Controller](https://solid-route-progress.vercel.app/docs/controller.md) · [Examples](https://solid-route-progress.vercel.app/docs/examples.md)

---

# Styling

Source: https://solid-route-progress.vercel.app/docs/styling

## Custom properties

| Property                | Default                | Meaning                                                      |
| ----------------------- | ---------------------- | ------------------------------------------------------------ |
| `--sp-color`            | `oklch(0.65 0.14 241)` | bar color                                                    |
| `--sp-height`           | `3px`                  | bar thickness                                                |
| `--sp-z-index`          | `9999`                 | bar stacking order                                           |
| `--sp-start`            | `0.08`                 | value the bar is revealed at                                 |
| `--sp-trickle-duration` | `10s`                  | how long the loading drift takes                             |
| `--sp-trickle-easing`   | `linear(…)`            | shape of the drift                                           |
| `--sp-speed`            | the `speed` option     | read-only; set it through [`speed`](https://solid-route-progress.vercel.app/docs/controller.md#options) |

Set them on `:root`, in Tailwind's `@theme`, on a class, or inline.

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

```css
:root {
  color-scheme: light dark;
  --sp-color: light-dark(oklch(0.55 0.2 264), oklch(0.75 0.12 264));
}
```

## Utilities

```tsx
<RouteProgress class="h-1 data-[state=done]:opacity-50" />
```

The stylesheet sits in the `components.sprogress` sublayer, so utilities, your own `@layer components` rules and unlayered CSS all beat it without `!important`.

## Hooks for the rest of the page

| Hook                                             | Where    | When                        |
| ------------------------------------------------ | -------- | --------------------------- |
| `data-state="idle \| trickle \| active \| done"` | the bar  | always                      |
| `data-error`                                     | the bar  | done phase of a failed load |
| `data-sp-busy`                                   | `<html>` | while any bar is visible    |

```tsx
<main class="transition-opacity [[data-sp-busy]_&]:opacity-60">…</main>
```

```tsx
<Progress busyAttribute={false} /> // opt out
<Progress ariaBusy /> // also aria-busy="true"
```

## Inside a container

```tsx
<div class="relative overflow-hidden rounded-xl">
  <Progress controller={panel} class="absolute" />…
</div>
```

## Your own template

```tsx
import { Show } from 'solid-js'
import { Bar, useProgress } from 'solid-route-progress'

const Percent = () => {
  const progress = useProgress()
  // `value()` is the target, and while trickling that is `trickleTo`, not the drawn position
  return (
    <Show when={progress.state() !== 'trickle'}>
      <output>{Math.round(progress.value() * 100)}%</output>
    </Show>
  )
}

<RouteProgress>
  <Bar class="rounded-r-full" />
  <Percent />
</RouteProgress>
```

`--sp-value` is registered as a `<number>`, so your own elements can transition it. Keep the `var()` fallbacks.

```css
.ring {
  background: conic-gradient(
    var(--sp-color, oklch(0.65 0.14 241)) calc(var(--sp-value) * 1turn),
    transparent 0
  );
  transition: --sp-value var(--sp-trickle-duration, 10s) var(--sp-trickle-easing, ease-out);
}
```

## Recipes

They are not shipped, so they cost nothing until you paste them. See them live in [Examples](https://solid-route-progress.vercel.app/docs/examples.md#styling-recipes).

### Failed loads

```css
.sprogress[data-error] {
  --sp-color: oklch(0.63 0.19 23);
}
```

### Spinner

```tsx
<RouteProgress>
  <Bar />
  <div class="spinner" aria-hidden="true" />
</RouteProgress>
```

```css
.spinner {
  position: absolute;
  top: 15px;
  inset-inline-end: 15px;
  box-sizing: border-box;
  width: 18px;
  height: 18px;
  border: 2px solid transparent;
  border-block-start-color: var(--sp-color, oklch(0.65 0.14 241));
  border-inline-start-color: var(--sp-color, oklch(0.65 0.14 241));
  border-radius: 50%;
  animation: spinner 400ms linear infinite;
}
.sprogress[data-state='idle'] .spinner {
  animation: none;
}
@media (prefers-reduced-motion: reduce) {
  .spinner {
    display: none;
  }
}
@keyframes spinner {
  to {
    rotate: 1turn;
  }
}
```

```tsx
<div
  aria-hidden="true"
  class="absolute end-4 top-4 size-4.5 animate-spin rounded-full border-2 border-transparent border-s-(color:--sp-color) border-t-(color:--sp-color) in-data-[state=idle]:animate-none motion-reduce:hidden"
/>
```

### Glow

```css
.sprogress-bar::after {
  content: '';
  position: absolute;
  inset-inline-end: 0;
  top: 0;
  width: 100px;
  height: 100%;
  box-shadow:
    0 0 10px var(--sp-color, oklch(0.65 0.14 241)),
    0 0 5px var(--sp-color, oklch(0.65 0.14 241));
  transform: rotate(3deg) translateY(-4px);
}
.sprogress:dir(rtl) .sprogress-bar::after {
  transform: rotate(-3deg) translateY(-4px);
}
```

## Built in

|                | |
| -------------- | -------------------------------------------------- |
| RTL            | the bar slides in from the right under `dir="rtl"`  |
| Forced colors  | paints with the system `Highlight` color            |

## The stylesheet

```css
/*
 * solid-route-progress — all rendering lives here. JS only writes `--sp-value`, `--sp-speed` and `data-state`.
 *
 * Tunables (set them anywhere: `:root`, `@theme`, a class, or inline):
 *   --sp-color            bar color                       oklch(0.65 0.14 241)
 *   --sp-height           bar thickness                    3px
 *   --sp-z-index          bar stacking order               9999
 *   --sp-start            value the bar is revealed at     0.08
 *   --sp-trickle-duration length of the loading drift      10s
 *   --sp-trickle-easing   shape of the loading drift       linear() curve
 *
 * `--sp-speed` mirrors the `speed` option so CSS transitions and JS timers agree: read it in
 * your own rules, set it through `speed`.
 *
 * Everything sits in the `components.sprogress` sublayer, so Tailwind utilities, your own
 * `@layer components` rules and unlayered CSS all win without `!important`. Motion is
 * `opacity` and `translate` only, so it runs on the compositor even while the page is busy.
 */

@property --sp-value {
  syntax: '<number>';
  inherits: true;
  initial-value: 0;
}

@layer components.sprogress {
  .sprogress {
    position: fixed;
    inset: 0 0 auto;
    z-index: var(--sp-z-index, 9999);
    height: var(--sp-height, 3px);
    pointer-events: none;
    visibility: visible;
    transition:
      opacity var(--sp-speed),
      visibility 0s;
  }

  .sprogress[data-state='idle'] {
    opacity: 0;
    visibility: hidden;
    /* keep painting while the opacity fades, then drop out of the a11y tree / hit-testing. A
       delayed 0s step, not a timed one: the main thread sleeps through the fade */
    transition-delay: 0s, var(--sp-speed);
  }

  .sprogress-bar {
    position: absolute;
    inset: 0;
    background: var(--sp-color, oklch(0.65 0.14 241));
    /* full-width bar slid in from the inline-start edge; `translate` leaves `transform` to you */
    translate: calc((var(--sp-value) - 1) * 100%);
    /* set() / done(): a short, eased hop */
    transition: translate var(--sp-speed);
  }

  .sprogress:dir(rtl) .sprogress-bar {
    translate: calc((1 - var(--sp-value)) * 100%);
  }

  /* loading: fast out of the gate, then a long crawl — never quite arriving. Longhands, so a
     browser without linear() loses only the curve (falling back to ease), not the drift */
  .sprogress[data-state='trickle'] .sprogress-bar {
    transition-duration: var(--sp-trickle-duration, 10s);
    transition-timing-function: var(
      --sp-trickle-easing,
      linear(0, 0.25 5%, 0.4 10%, 0.55 18%, 0.7 30%, 0.8 45%, 0.88 60%, 0.94 75%, 0.98 90%, 1)
    );
  }

  /* hidden: park the bar at the start position, but only after the fade-out finished */
  .sprogress[data-state='idle'] .sprogress-bar {
    --sp-value: var(--sp-start, 0.08);
    transition-duration: 0s;
    transition-delay: var(--sp-speed);
  }

  /* forced colors strip backgrounds; paint the bar with the system highlight instead */
  @media (forced-colors: active) {
    .sprogress-bar {
      forced-color-adjust: none;
      background: Highlight;
    }
  }
}
```

---

# Examples

Source: https://solid-route-progress.vercel.app/docs/examples

Each demo is a real component, and the code under it is that component's file, imported with `?raw`. Every bar sits in its own panel (the [container recipe](https://solid-route-progress.vercel.app/docs/styling.md#inside-a-container)) and passes `busyAttribute={false}`.

## `track()`

| Button             | Result                                                     |
| ------------------ | ---------------------------------------------------------- |
| Fetch (1.5 s)       | holds, then completes                                      |
| Fail it (1.2 s)     | releases as `'error'`, sets `data-error`, and turns [red](https://solid-route-progress.vercel.app/docs/styling.md#failed-loads) |
| Too fast (120 ms)   | shorter than `delay`, so it is never painted               |

```tsx
import { createProgress, Progress } from 'solid-route-progress'
import { Btn, delay, fail, Panel, Readout, Row } from './ui'

export function TrackPromise() {
  // `speed` is stretched from its 200 ms default so the done phase (and the red of a failed
  // load) lasts long enough to see.
  const progress = createProgress({ speed: 450 })

  return (
    <Panel>
      <Progress
        controller={progress}
        class="ex-error absolute"
        label="Tracked request"
        busyAttribute={false}
      />
      <Row>
        <Btn onClick={() => progress.track(delay(1500))}>Fetch (1.5 s)</Btn>
        <Btn onClick={() => progress.track(fail(1200)).catch(() => {})}>Fail it (1.2 s)</Btn>
        <Btn onClick={() => progress.track(delay(120))}>Too fast to show (120 ms)</Btn>
      </Row>
      <Readout>
        state: {progress.state()}
        {progress.error() ? ' · error' : ''}
      </Readout>
    </Panel>
  )
}
```

## `start()` and `release()`

| Button             | Result                                    |
| ------------------ | ----------------------------------------- |
| Take a hold        | one more hold                             |
| Release one        | bar keeps going until the last hold goes  |
| Release as cancel  | fades out without reaching 100%           |
| Release as error   | completes with `data-error`               |

```tsx
import { createSignal } from 'solid-js'
import { createProgress, Progress, type Release } from 'solid-route-progress'
import { Btn, Panel, Readout, Row } from './ui'

export function ManualHolds() {
  // `speed` is stretched from its 200 ms default so the done phase (and the red of a failed
  // load) lasts long enough to see.
  const progress = createProgress({ speed: 450 })
  const [holds, setHolds] = createSignal<Release[]>([])

  const take = () => setHolds([...holds(), progress.start()])
  const letGo = (outcome?: 'error' | 'cancel') => {
    const [first, ...rest] = holds()
    if (!first) return
    first(outcome)
    setHolds(rest)
  }

  return (
    <Panel>
      <Progress
        controller={progress}
        class="ex-error absolute"
        label="Manual holds"
        busyAttribute={false}
      />
      <Row>
        <Btn onClick={take}>Take a hold</Btn>
        <Btn onClick={() => letGo()}>Release one</Btn>
        <Btn onClick={() => letGo('cancel')}>Release as cancel</Btn>
        <Btn onClick={() => letGo('error')}>Release as error</Btn>
      </Row>
      <Readout>
        {holds().length} hold(s) · state: {progress.state()}
        {progress.error() ? ' · error' : ''}
      </Readout>
    </Panel>
  )
}
```

## `set()`

`aria-valuenow` and `getValueLabel`'s `aria-valuetext` appear once the value is known.

```tsx
import { createSignal, onCleanup } from 'solid-js'
import { createProgress, Progress } from 'solid-route-progress'
import { Btn, Panel, Readout, Row } from './ui'

export function DeterminateValue() {
  const progress = createProgress()
  const [sent, setSent] = createSignal(0)
  let timer: ReturnType<typeof setInterval> | undefined
  onCleanup(() => clearInterval(timer))

  const upload = () => {
    clearInterval(timer)
    setSent(0)
    timer = setInterval(() => {
      setSent(Math.min(1, sent() + 0.125))
      // `set()` reveals the bar, moves it, then hands back to the trickle; 1 completes it.
      progress.set(sent())
      if (sent() >= 1) clearInterval(timer)
    }, 320)
  }

  return (
    <Panel>
      <Progress
        controller={progress}
        class="absolute"
        label="Upload"
        getValueLabel={(percent) => `${percent} percent uploaded`}
        busyAttribute={false}
      />
      <Row>
        <Btn onClick={upload}>Upload a file</Btn>
        <Btn onClick={() => progress.done('cancel')}>Abort</Btn>
      </Row>
      <Readout>
        {Math.round(progress.value() * 100)}% · state: {progress.state()}
      </Readout>
    </Panel>
  )
}
```

## Custom template

`<Progress>` renders `<Bar />` unless you give it children; children read the controller with `useProgress()`.

```tsx
import { Show } from 'solid-js'
import { Bar, createProgress, Progress, useProgress } from 'solid-route-progress'
import { Btn, delay, Panel, Row } from './ui'

/**
 * Children of `<Progress>` read its controller with `useProgress()`. `value()` is the target,
 * which is `trickleTo` while trickling, so the number only shows once it is known.
 */
const Percent = () => {
  const progress = useProgress()
  return (
    <Show when={progress.state() !== 'trickle'}>
      <output class="absolute top-3 right-3 font-mono text-[11px] text-muted-foreground">
        {Math.round(progress.value() * 100)}%
      </output>
    </Show>
  )
}

export function CustomTemplate() {
  const progress = createProgress()

  return (
    <Panel>
      <Progress
        controller={progress}
        class="absolute"
        label="Custom template"
        busyAttribute={false}
      >
        <Bar class="rounded-r-full" />
        <Percent />
      </Progress>
      <Row>
        <Btn onClick={() => progress.track(delay(2500))}>Load something slow</Btn>
      </Row>
    </Panel>
  )
}
```

## Skipping navigations

Both bars are wired to this page's router. The links only change the search string.

| Link           | default + `filter` | `shallow` |
| -------------- | ------------------ | --------- |
| `?skip=go`     | flashes            | ignores   |
| `?skip=blocked` | `filter` returns `false` | ignores   |
| `?skip=quiet`  | `data-sp-ignore`   | ignores   |

```tsx
import { A } from '@solidjs/router'
import type { JSX } from 'solid-js'
import { createProgress } from 'solid-route-progress'
import { RouteProgress } from 'solid-route-progress/router'
import { Panel, Readout, Row } from './ui'

// These links only change the search string, so every navigation here is instant. `delay: 0`
// and a long `stopDelay` make the flash visible; what matters is which bar flashes at all.
const options = { delay: 0, stopDelay: 700 }

const Slot = (props: { name: string; children: JSX.Element }) => (
  <div class="relative overflow-hidden rounded-lg border border-border py-3 text-center">
    {props.children}
    <span class="font-mono text-[11px] text-muted-foreground">{props.name}</span>
  </div>
)

export function SkippingNavigations() {
  const plain = createProgress(options)
  const shallow = createProgress(options)

  return (
    <Panel>
      <div class="mb-4 grid gap-3 sm:grid-cols-2">
        <Slot name="default + filter">
          <RouteProgress
            controller={plain}
            class="absolute"
            label="Default bar"
            busyAttribute={false}
            crossDocument={false}
            filter={(to) => !to.includes('skip=blocked')}
          />
        </Slot>
        <Slot name="shallow">
          <RouteProgress
            controller={shallow}
            class="absolute"
            label="Shallow bar"
            busyAttribute={false}
            crossDocument={false}
            shallow
          />
        </Slot>
      </div>
      <Row>
        <A href="?skip=go" noScroll class="rounded-lg border border-border px-3 py-2 text-[13px]">
          ?skip=go
        </A>
        <A
          href="?skip=blocked"
          noScroll
          class="rounded-lg border border-border px-3 py-2 text-[13px]"
        >
          ?skip=blocked: filtered out
        </A>
        <A
          href="?skip=quiet"
          noScroll
          data-sp-ignore
          class="rounded-lg border border-border px-3 py-2 text-[13px]"
        >
          ?skip=quiet: data-sp-ignore
        </A>
      </Row>
      <Readout>
        left: {plain.state()} · right: {shallow.state()}
      </Readout>
    </Panel>
  )
}
```

## Leaving the document

`createCrossDocumentProgress()` on its own, which is what [`<RouteProgress>`](https://solid-route-progress.vercel.app/docs/router.md#leaving-the-document) does for you.

```tsx
import { createCrossDocumentProgress, createProgress, Progress } from 'solid-route-progress'
import { REPO } from '~/links'
import { Panel, Readout, Row } from './ui'

/**
 * `<RouteProgress>` does this for you. Here it runs on its own, so the bar reacts only to
 * navigations that leave the document. It relies on the Navigation API, and where that is missing,
 * nothing happens.
 */
export function CrossDocument() {
  const progress = createProgress()
  createCrossDocumentProgress(progress)

  return (
    <Panel>
      <Progress
        controller={progress}
        class="absolute"
        label="Leaving the page"
        busyAttribute={false}
      />
      <Row>
        <a href={REPO} class="rounded-lg border border-border px-3 py-2 text-[13px]">
          Leave for GitHub: the bar holds until the browser hands over
        </a>
        <a href={REPO} data-sp-ignore class="rounded-lg border border-border px-3 py-2 text-[13px]">
          Same link with data-sp-ignore: nothing shows
        </a>
      </Row>
      <Readout>state: {progress.state()} · use the back button to come back</Readout>
    </Panel>
  )
}
```

## Styling recipes

The [recipes](https://solid-route-progress.vercel.app/docs/styling.md#recipes), pasted into `app.css` as `.ex-glow` and `.ex-spinner`.

```tsx
import { createSignal, Show } from 'solid-js'
import { Bar, createProgress, Progress } from 'solid-route-progress'
import { Btn, delay, fail, Panel, Row } from './ui'

const Toggle = (props: { label: string; on: boolean; onChange: (on: boolean) => void }) => (
  <label class="flex items-center gap-1.5 text-[13px]">
    <input
      type="checkbox"
      checked={props.on}
      onChange={(event) => props.onChange(event.currentTarget.checked)}
    />
    {props.label}
  </label>
)

/** The recipes from the Styling docs, pasted into `app.css` as `.ex-glow` / `.ex-spinner`. */
export function StyleRecipes() {
  // `speed` is stretched from its 200 ms default so the done phase (and the red of a failed
  // load) lasts long enough to see.
  const progress = createProgress({ speed: 450 })
  const [glow, setGlow] = createSignal(true)
  const [spinner, setSpinner] = createSignal(true)

  return (
    <Panel>
      <Progress
        controller={progress}
        class={`ex-error absolute${glow() ? ' ex-glow' : ''}`}
        label="Styled bar"
        busyAttribute={false}
      >
        <Bar />
        <Show when={spinner()}>
          <div class="ex-spinner" aria-hidden="true" />
        </Show>
      </Progress>
      <Row>
        <Btn onClick={() => progress.track(delay(2500))}>Load</Btn>
        <Btn onClick={() => progress.track(fail(1800)).catch(() => {})}>Load and fail</Btn>
        <Toggle label="glow" on={glow()} onChange={setGlow} />
        <Toggle label="spinner" on={spinner()} onChange={setSpinner} />
      </Row>
    </Panel>
  )
}
```

---

# Controller

Source: https://solid-route-progress.vercel.app/docs/controller

```ts
import { createProgress } from 'solid-route-progress'

const progress = createProgress({ delay: 300 })
```

## Options

| Option      | Default | Meaning                                              |
| ----------- | ------- | ---------------------------------------------------- |
| `trickleTo` | `0.95`  | value the bar drifts toward while loading            |
| `delay`     | `200`   | ms a load must last before the bar shows             |
| `stopDelay` | `0`     | ms to wait before completing once the last hold goes |
| `speed`     | `200`   | ms for hops and fades; written to `--sp-speed`       |

Read lazily, so reactive props work. They belong to whoever creates the controller.

## `start()`

```ts
const release = progress.start()
release()
release('error')
release('cancel')
```

```ts
{
  using hold = progress.start() // where the runtime has Symbol.dispose
  await work()
}
```

| | |
| ---------------- | ---------------------------------------------------------- |
| returns          | `Release`                                                   |
| shows            | once the load has lasted `delay`                            |
| completes        | when the last hold is released                              |
| `release()`      | done                                                        |
| `release('error')` | completes with `data-error`; wins over any other outcome  |
| `release('cancel')` | fades out without reaching 100%                          |
| releasing twice  | no-op                                                       |

## `done()`

```ts
progress.done()
progress.done('error')
progress.done('cancel')
```

| | |
| ------------- | ------------------------------------------------ |
| drops         | every hold                                        |
| after         | `stopDelay`                                       |
| while hidden  | no-op                                             |
| never painted | dropped silently                                  |

## `set()`

```ts
progress.set(0.6)
progress.set(1) // completes
```

| | |
| ------------- | ---------------------------------------------- |
| range         | `0` to `1`, clamped                             |
| then          | resumes trickling toward `trickleTo`            |
| while hidden  | shows the bar, unless `delay` is still pending  |
| trickle       | not compared: a value below it moves the bar back |

## `track()`

```ts
const items = await progress.track(fetch('/api/items').then((r) => r.json()))

progress.track(upload(file), { timeout: 30_000 })
```

| | |
| ---------- | ----------------------------------------- |
| holds      | one hold per call                         |
| rejection  | releases as `'error'`                     |
| returns    | the promise, unchanged                    |
| `timeout`  | ms; lets go even if the promise never settles |

## Signals

| Accessor   | Type                                        | Meaning                                |
| ---------- | ------------------------------------------- | -------------------------------------- |
| `value()`  | `number`                                    | target value, `0` to `1`; `trickleTo` while trickling |
| `state()`  | `'idle' \| 'trickle' \| 'active' \| 'done'` | mirrored as `data-state`               |
| `active()` | `boolean`                                   | visible                                |
| `error()`  | `boolean`                                   | done phase of a failed load            |
| `options`  | `Readonly<ProgressOptions>`                 | what it was created with               |

| State     | Meaning                                              |
| --------- | ---------------------------------------------------- |
| `idle`    | hidden: faded out, `visibility: hidden`              |
| `trickle` | drifting toward `trickleTo` on the long transition   |
| `active`  | moving to a `set()` value on the short transition    |
| `done`    | moving to 100%, then fading out                      |

## On the server

Every method is a no-op; `start()` still returns a release. `<Progress>` renders the idle shell.

## Types

```ts
import type {
  DisposableLike,
  Outcome, // 'error' | 'cancel'
  ProgressController,
  ProgressOptions,
  ProgressState,
  Release,
  TrackOptions,
} from 'solid-route-progress'
```

---

# Components

Source: https://solid-route-progress.vercel.app/docs/components

```tsx
import { Bar, Progress, ProgressProvider, useProgress } from 'solid-route-progress'
```

## `<Progress>`

```tsx
import { createProgress, Progress } from 'solid-route-progress'

const progress = createProgress()

<Progress controller={progress} label="Loading page" />
```

| Prop                                       | Default                          | Meaning                                                  |
| ------------------------------------------ | -------------------------------- | -------------------------------------------------------- |
| `controller`                               | nearest provided, else a new one | the controller to drive                                  |
| `trickleTo`, `delay`, `stopDelay`, `speed` |                                  | applied only when the bar creates its own controller     |
| `label`                                    | `Loading`                        | accessible name                                          |
| `getValueLabel`                            |                                  | `(percent) => string`, read as `aria-valuetext`          |
| `busyAttribute`                            | `true`                           | `data-sp-busy` on `<html>` while visible                 |
| `ariaBusy`                                 | `false`                          | `aria-busy="true"` on `<html>` while visible             |
| `class`, `style`, …                        |                                  | forwarded; `style` merges with the custom properties     |
| `children`                                 | `<Bar />`                        | custom template                                          |

| Renders                          | When                            |
| -------------------------------- | ------------------------------- |
| `role="progressbar"`             | always                          |
| no `aria-valuenow`               | while trickling (indeterminate) |
| `aria-valuenow` + `aria-valuetext` | after `set()`                 |

The attributes that mirror the controller (`role`, the `aria-*` values, `data-state`, `data-error`, the class, and the custom properties) win over props spread onto the element. With several bars the `<html>` attributes stay until the last one goes idle.

## `<ProgressProvider>`

```tsx
<ProgressProvider delay={300}>
  <RouteProgress />
  {children}
</ProgressProvider>
```

| Prop         | Meaning                                |
| ------------ | -------------------------------------- |
| `controller` | share an existing one                  |
| options      | otherwise it creates one from them     |

Renders nothing.

## `useProgress()`

```tsx
const progress = useProgress()

progress.track(upload(file))
```

Reads the nearest controller from `<ProgressProvider>`, `<Progress>`, `<RouteProgress>` or `<NavigationProgress>`. Throws outside them.

## `<Bar>`

```tsx
<RouteProgress>
  <Bar class="rounded-r-full" />
  <div class="spinner" aria-hidden="true" />
</RouteProgress>
```

The default template. It forwards `class` and other attributes. A spinner and a glow are [recipes](https://solid-route-progress.vercel.app/docs/styling.md#recipes).

## `ProgressContext`

The shared context, exported for integrations. Prefer `useProgress()`.

---

# Router integration

Source: https://solid-route-progress.vercel.app/docs/router

```tsx
import { RouteProgress } from 'solid-route-progress/router'

<Router root={(props) => <><RouteProgress /><Suspense>{props.children}</Suspense></>}>
```

| Covered by `useIsRouting()`                                             |
| ----------------------------------------------------------------------- |
| `<A>` clicks · `navigate()` · back/forward · action redirects · every `<Suspense>` the new route waits on |

## `<RouteProgress>`

Every [`<Progress>` prop](https://solid-route-progress.vercel.app/docs/components.md), plus:

| Prop            | Default | Meaning                                                            |
| --------------- | ------- | ------------------------------------------------------------------ |
| `shallow`       | `false` | skip navigations that keep the `pathname`                          |
| `filter`        |         | `(to, from) => boolean`; `false` skips it                          |
| `crossDocument` | `true`  | also hold for navigations that leave the document                  |

```tsx
<RouteProgress shallow filter={(to) => !to.startsWith('/admin')} />
```

Each navigation takes its own [hold](https://solid-route-progress.vercel.app/docs/controller.md#start).

## Ignoring links

```tsx
<A href="/settings" data-sp-ignore>
  Settings
</A>
```

Works for `<A>`, plain anchors and Navigation API navigations alike.

## Leaving the document

| Navigation                                                          | Bar                                    |
| ------------------------------------------------------------------- | -------------------------------------- |
| external link, plain form post, `location` assignment, `reload()`   | holds until the document unloads        |
| stopped, or superseded by a newer one                               | fades out without reaching 100%         |
| back from the bfcache                                               | fades out                               |
| intercepted after all                                               | completes on `navigatesuccess`          |
| no response (a `204`, a server-sent download)                       | completes after `timeout`               |
| started from the browser itself (reload button, address bar)        | nothing                                 |
| `mailto:`, `tel:`, `download`, canceled by another listener        | nothing                                 |

```tsx
<RouteProgress
  crossDocument={{ timeout: 5000, filter: (event) => event.navigationType !== 'reload' }}
/>
```

```tsx
<RouteProgress crossDocument={false} />
```

```ts
import { createCrossDocumentProgress } from 'solid-route-progress'

createCrossDocumentProgress(controller, options)
```

## Actions without a redirect

An action that only revalidates runs outside `useIsRouting()`, so the bar stays hidden. Hold it for the actions you want covered:

```tsx
import { useSubmission } from '@solidjs/router'
import { createEffect, onCleanup } from 'solid-js'
import { useProgress } from 'solid-route-progress'

const saving = useSubmission(saveProfile)
const progress = useProgress()
createEffect(() => {
  if (saving.pending) onCleanup(progress.start())
})
```

The submission stays pending until the action and its revalidation have both finished.

## `createRouteProgress()`

```tsx
import { createProgress, Progress } from 'solid-route-progress'
import { createRouteProgress } from 'solid-route-progress/router'

const progress = createProgress()
createRouteProgress(progress, { shallow: true })

<Progress controller={progress} />
```

---

# Navigation API

Source: https://solid-route-progress.vercel.app/docs/navigation-api

```tsx
import { NavigationProgress } from 'solid-route-progress/navigation'

const Layout = (props) => (
  <>
    <NavigationProgress />
    {props.children}
  </>
)
```

It works without a router.

## `<NavigationProgress>`

Every [`<Progress>` prop](https://solid-route-progress.vercel.app/docs/components.md), plus:

| Prop      | Default | Meaning                                                  |
| --------- | ------- | -------------------------------------------------------- |
| `filter`  |         | `(event) => boolean` on the `navigate` event; `false` skips it |
| `timeout` | `10000` | safety net for navigations that never unload; `0` disables it |

```tsx
<NavigationProgress filter={(event) => event.navigationType !== 'replace'} />
```

## When the bar completes

| Navigation                                    | Bar                                              |
| --------------------------------------------- | ------------------------------------------------ |
| intercepted by a router                       | holds until `navigatesuccess` / `navigateerror`  |
| `navigateerror` with an `AbortError`          | fades out without reaching 100%                  |
| `navigateerror`, anything else                | completes as an [`'error'`](https://solid-route-progress.vercel.app/docs/controller.md#start) |
| plain `pushState`, nobody intercepting        | commits before the first paint, so nothing shows |
| cross-document                                | holds until the page unloads                     |
| back from the bfcache                         | fades out                                        |
| hash change, `download`, `data-sp-ignore`     | nothing                                          |
| canceled by another listener                 | nothing                                          |

Each navigation holds the bar on its own.

## Where the API is missing

Nothing is tracked; `<NavigationProgress>` renders an idle bar. `solid-route-progress/router`'s cross-document tracking needs it too.

## `createNavigationProgress()`

```tsx
import { createProgress, Progress } from 'solid-route-progress'
import { createNavigationProgress } from 'solid-route-progress/navigation'

const progress = createProgress()
createNavigationProgress(progress, { timeout: 5000 })

<Progress controller={progress} />
```

`@solidjs/router` loads outside the Navigation API, so use [`solid-route-progress/router`](https://solid-route-progress.vercel.app/docs/router.md) for it.