# <motion-progress>

Fixed progress bar driven by document or per-element scroll. Spring-eased
scaleX transform — settles past the value rather than hard-snapping.

**Use it for:** a thin reading progress bar at the top or bottom of the
window on long articles and documentation pages.

**Avoid it for:** the progress of a task such as an upload; it only follows
scrolling and has no value you can set. Use the native `<progress>` element
for that.

**Accessibility:** the bar is decoration only, so it has
`aria-hidden="true"` and screen readers skip it. Screen reader users follow
their own reading position, not the scroll position. The bar never takes
focus and ignores the pointer.

**Reduced motion:** the bar still follows scrolling, but without the
spring. Its width matches the scroll position exactly.

**Common mistakes:** pointing `target` at a box that scrolls on its own; the
bar measures how that element moves through the window, not scrolling
inside it. Setting `target` to an element that is not in the page yet when
the bar starts; the bar then follows the whole document instead.

Docs: https://www.motion-components.dev/docs/components/motion-progress/

## Install

```js
import 'motion-components/motion-progress'
```

Or without a build step:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/motion-components@1/dist/motion-progress.js/+esm"></script>
```

## Example

```html
<motion-progress thickness="3" style="--mc-progress-color: #60a5fa"></motion-progress>
<motion-progress target="#article" position="bottom"></motion-progress>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `'top' \| 'bottom'` | `'top'` | `'top'` or `'bottom'` of the viewport. |
| `thickness` | `number` | `3` | Bar thickness in pixels. |
| `target` | `string` | `''` | CSS selector of the scroll target. Defaults to the document. |
| `bounce` | `number` | `0.15` | Spring bounciness applied to the scaleX response (0 = none). |
| `duration` | `number` | `0.4` | Spring duration of the scaleX response, in seconds. |

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `playState` | `'idle' \| 'running' \| 'paused' \| 'finished'` | Current state: `'idle'`, `'running'`, `'paused'` or `'finished'`. |
| `finished` | `Promise<void>` | Resolves when the current run settles. A new run replaces the promise. |

## Methods

| Method | Description |
| --- | --- |
| `play()` | Starts the animation, or resumes it when paused. Resolves once the run settles. Under `prefers-reduced-motion: reduce` the final state is applied immediately without animating. |
| `pause()` | Holds the animation at its current position. No-op unless running. |
| `finish()` | Jumps to the final state and settles. Fires `motion-finish`. |
| `cancel()` | Reverts to the initial state and returns to idle. Fires `motion-cancel`. |

## Events

The `motion-*` events bubble and are composed.

| Event | Description |
| --- | --- |
| `motion-start` | When a run starts. |
| `motion-finish` | When a run finishes, or `finish()` jumps to the end. |
| `motion-cancel` | When `cancel()` stops a run and resets it. |

## CSS custom properties

| Property | Description |
| --- | --- |
| `--mc-progress-color` | Bar color. Default `var(--mc-color-accent, #2563eb)`. |