# Route Progress

> A thin bar across the top while the next page loads. Quick page changes show nothing.

```tsx
'use client';

import { useRef, useState } from 'react';
import { RouteProgress } from '@brand-studio/ui';

const pages = [
  { name: 'Overview', ms: 1200 },
  { name: 'Orders', ms: 2400 },
  { name: 'Team', ms: 150, note: 'answers in 150 ms, so no bar shows' },
];

export default function RouteProgressDemo() {
  const [current, setCurrent] = useState('Overview');
  const [active, setActive] = useState(false);
  const nav = useRef(0);
  const go = (name: string, ms: number) => {
    const id = ++nav.current;
    setActive(true);
    window.setTimeout(() => { if (id !== nav.current) return; setActive(false); setCurrent(name); }, ms);
  };
  return (
    <div style={{ position: 'relative', width: '100%', maxWidth: 520, overflow: 'hidden', border: '1px solid var(--bs-line)', borderRadius: 'var(--bs-radius)', background: 'var(--bs-elevated)' }}>
      <RouteProgress active={active} contained label="Loading page" />
      <nav aria-label="Demo pages" style={{ display: 'flex', flexWrap: 'wrap', gap: 4, padding: 8, borderBottom: '1px solid var(--bs-line)' }}>
        {pages.map(page => (
          <a key={page.name} href={`#${page.name.toLowerCase()}`} aria-current={current === page.name ? 'page' : undefined}
            onClick={event => { event.preventDefault(); go(page.name, page.ms); }}
            style={{ padding: '10px 12px', borderRadius: 8, fontWeight: current === page.name ? 600 : 400, textDecoration: 'none' }}>
            {page.name}
          </a>
        ))}
      </nav>
      <div style={{ padding: '20px 20px 24px' }}>
        <h3 style={{ margin: '0 0 8px', fontSize: 20 }}>{current}</h3>
        <p style={{ margin: 0, color: 'var(--bs-muted)' }}>The old page stays readable while the next one loads. Team {pages[2]!.note}.</p>
      </div>
    </div>
  );
}
```

## Installation

```sh
npm install @brand-studio/ui
```

React 18 or 19 is a peer dependency. Import the stylesheet once and wrap the app in a brand theme:

```tsx
import '@brand-studio/ui/styles.css';
import { BrandTheme, RouteProgress } from '@brand-studio/ui';
import brand from './brand.json';

<BrandTheme palette={brand.tokens} mode="system">
  {/* your app */}
</BrandTheme>
```

## Usage

```tsx
import { RouteProgress } from '@brand-studio/ui';
```

```tsx
<RouteProgress active={navigation.state === 'loading'} />
```

Set `active` while your router fetches the next page. The bar waits `delay` (250 ms), so quick page changes show nothing. It then creeps toward 85% without claiming to finish, fills when `active` turns off, and fades. The page underneath stays readable the whole time.

It is fixed to the top of the window. Pass `contained` to pin it to the top of the nearest positioned box instead, such as an app's main pane.

## Accessibility

- The bar is hidden from screen readers. A separate status line says `label` while the bar shows.
- Your router still owns moving focus and setting the page title when the new page arrives.

## API Reference

| Prop | Type | Default |
|---|---|---|
| `active` | `boolean` | – |
| `label?` | `string` | `'Loading page'` |
| `delay?` | `number` | `250` |
| `contained?` | `boolean` | `false` |
| `className?` | `string` | `''` |

Source: https://brandstudio.js.org/docs/components/route-progress/
