# Reading progress (goodtabs UI)

A 2px bar at the top of the page or a container that fills as you scroll.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/reading-progress.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/reading-progress`

## Usage

```tsx
import { ReadingProgress } from "@/components/ui/reading-progress"

// Page: fixed to the top of the viewport
<ReadingProgress />

// A scrolling panel: the parent is relative, the panel has the ref
<div className="relative">
  <ReadingProgress container={ref} />
  <div ref={ref} className="h-96 overflow-auto">...</div>
</div>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| container | `RefObject<HTMLElement | null>` |  | A scrolling element to track instead of the window. |
| position | `"fixed" | "absolute"` | `container ? "absolute" : "fixed"` | fixed sits on the viewport; absolute at the top of the nearest positioned parent. |
| height | `number` | `2` | Bar thickness in px. |
| label | `string` | `"Reading progress"` | Accessible name of the progressbar. |

## When to use

- Long articles, docs and changelogs where a sense of how much is left helps
- At the top of a scrolling panel, such as a sheet or a reading pane
- When a bar is enough and a table of contents would be too much

## When not to use

- On short pages: it renders nothing until there is something to scroll, so it would never show
- For task progress, use a progress bar with real steps
- On app screens where the main scroll is not the content

## Notes for agents

- It is a client component. The window version works from a server page; the container version needs a ref from a client component
- In container mode the parent must be relative so the absolute bar sits at the top of the box, above the scrolling element
- The width is a scaleX transform with no transition, so it tracks scroll exactly and needs no reduced-motion fallback
- It renders null until the target can scroll, then a role="progressbar" with aria-valuenow 0 to 100

Docs: https://ui.goodtabs.co/components/reading-progress