> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Progress Bar

> A seekable progress bar that reflects playback and emits scrub events.

> [tab] Preview

> [tab] Code
>
> ```jsx ProgressBar.jsx theme={null}
> "use client";
>
> import { useEffect, useRef } from "react";
>
> import { newEvent } from "@/lib/newEvent";
> import { usePlayer, usePlayerSelector } from "@/registry/react/PlayerProvider";
>
> export function ProgressBar() {
>   const player = usePlayer();
>   const currentTime = usePlayerSelector((p) => p.currentTime);
>   const duration = usePlayerSelector((p) => p.duration);
>   const progress = duration > 0 ? Math.max(0, Math.min(currentTime / duration, 1)) : 0;
>
>   const barRef = useRef(null);
>   const mouseDownRef = useRef(false);
>
>   const getMouseRatio = (event) => {
>     const clientX = event.clientX ?? event.touches?.[0]?.clientX ?? 0;
>     const { x, width } = barRef.current.getBoundingClientRect();
>     return Math.max(0, Math.min(1, (clientX - x) / width));
>   };
>
>   const handleMouseDown = (event) => {
>     mouseDownRef.current = true;
>     player.onEvent(
>       newEvent({
>         type: "PressedProgressBar",
>         description: "The progress bar was pressed at some ratio.",
>         initiatedBy: "user",
>         ratio: getMouseRatio(event),
>       }),
>     );
>   };
>
>   useEffect(() => {
>     const handleMouseMove = (event) => {
>       if (!mouseDownRef.current) return;
>       if (!barRef.current) {
>         handleMouseUp();
>         return;
>       }
>       player.onEvent(
>         newEvent({
>           type: "ScrubbedProgressBar",
>           description: "The user pressed on the progress bar then dragged.",
>           initiatedBy: "user",
>           ratio: getMouseRatio(event),
>         }),
>       );
>     };
>
>     const handleMouseUp = () => {
>       if (!mouseDownRef.current) return;
>       mouseDownRef.current = false;
>       player.onEvent(
>         newEvent({
>           type: "FinishedScrubbingProgressBar",
>           description: "The user let go after scrubbing the progress bar.",
>           initiatedBy: "user",
>         }),
>       );
>     };
>
>     window.addEventListener("mouseup", handleMouseUp);
>     window.addEventListener("mousemove", handleMouseMove);
>     window.addEventListener("touchend", handleMouseUp);
>     window.addEventListener("touchmove", handleMouseMove);
>
>     return () => {
>       window.removeEventListener("mouseup", handleMouseUp);
>       window.removeEventListener("mousemove", handleMouseMove);
>       window.removeEventListener("touchend", handleMouseUp);
>       window.removeEventListener("touchmove", handleMouseMove);
>     };
>   }, [player]);
>
>   return (
>     <div
>       ref={barRef}
>       className="relative isolate h-2 grow cursor-pointer overflow-hidden rounded"
>       onMouseDown={handleMouseDown}
>       onTouchStart={handleMouseDown}
>     >
>       <div className="absolute inset-0 cursor-pointer bg-[rgba(0,0,0,0.8)] opacity-15" />
>       <div className="pointer-events-none h-2 rounded bg-[rgba(0,0,0,0.8)]" style={{ width: `${progress * 100}%` }} />
>     </div>
>   );
> }
> ```

## Installation

```bash npm theme={null}
npx @beyondwords/cli components add progress-bar
```

```bash pnpm theme={null}
pnpm dlx @beyondwords/cli components add progress-bar
```

```bash yarn theme={null}
yarn dlx @beyondwords/cli components add progress-bar
```

```bash bun theme={null}
bunx --bun @beyondwords/cli components add progress-bar
```

## Usage

```tsx theme={null}
import { PlayerProvider } from '@/registry/react/PlayerProvider';
import { ProgressBar } from '@/registry/react/ProgressBar';

export function Player() {
  return (
    <PlayerProvider args={{ projectId: 9504, contentId: "ba00ef51-03ac-4a85-8b98-e45c957e8ef8", showUserInterface: false }}>
      <ProgressBar />
    </PlayerProvider>
  );
}
```

The bar fills to `currentTime / duration`, read from the surrounding
[`PlayerProvider`](https://docs.beyondwords.io/components/react/player-provider). Pressing and dragging emits a
sequence of events built with [`newEvent`](https://docs.beyondwords.io/components/react/new-event). Each one
carries the pressed `ratio` (0–1):

* **`PressedProgressBar`**: on press, to seek to a position.
* **`ScrubbedProgressBar`**: while dragging.
* **`FinishedScrubbingProgressBar`**: on release.

Drag tracking is attached to `window` (mouse and touch), so scrubbing keeps
working even when the pointer leaves the bar. The component grows to fill its
container (`grow`). Place it in a flex row alongside the other controls.

## Reference

| | |
| - | - |
| **Props** | None |
| **Player state read** | `currentTime`, `duration` |
| **Events emitted** | `PressedProgressBar`, `ScrubbedProgressBar`, `FinishedScrubbingProgressBar` (each carries a `ratio`, 0–1) |
| **Requires** | a [`PlayerProvider`](https://docs.beyondwords.io/components/react/player-provider) ancestor |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.