# <motion-parallax>

Lightweight parallax scroll primitive. Moves the slotted content along the
chosen axis by a configurable depth relative to the scroll position.

**Use it for:** background images, decorative shapes and layered hero art
that should move at a different speed than the page while it scrolls.

**Avoid it for:** text and controls people need to read or use. For a
pinned scroll sequence, use `motion-scene`. For a one-time entrance, use
`motion-reveal`.

**Accessibility:** the component adds no roles or aria attributes. The
content stays in the page and in reading order. Only `transform` changes,
so the layout does not shift. Give decorative images an empty `alt`.

**Reduced motion:** the scroll effect does not start, and the content stays
at its normal position. If you call `play()`, the content jumps to its end
offset and does not follow the scroll.

**Common mistakes:** expecting `axis="x"` to follow a sideways scroller:
`axis` only sets the direction of movement, and the movement still follows
vertical scrolling. A `container` selector that matches nothing falls back
to the page scroll without a warning.

Docs: https://www.motion-components.dev/docs/scroll/motion-parallax/

## Install

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

Or without a build step:

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

## Example

```html
<motion-parallax depth="0.3" axis="y">
  <img src="background.jpg" alt="" />
</motion-parallax>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `depth` | `number` | `0.5` | Parallax intensity. `0` = no movement (scrolls with page), `1` = strong drift. |
| `axis` | `'x' \| 'y'` | `'y'` | Scroll axis: `'x'` for horizontal, `'y'` for vertical. |
| `container` | `string` | `''` | CSS selector for a custom scroll container element (defaults to the document). |

## 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. |

## Slots

| Slot | Description |
| --- | --- |
| (default) | The content that parallax-scrolls. |