# <motion-stagger>

Staggered viewport-triggered reveal for a list of children. Fades and
translates each direct child in sequence once the first child enters the viewport.

**Use it for:** lists, card grids and icon rows whose items should fade and
rise into place one after another when the list scrolls into view.

**Avoid it for:** a single block of content; use `motion-reveal` or
`motion-blur-in`. Avoid long lists that go far below the screen: the whole
sequence starts when the first child comes into view, so items lower down
can finish animating before anyone scrolls to them.

**Accessibility:** the children stay in the page while they are hidden, so
screen readers read them before they animate. Only opacity and transform
change, so the layout does not shift.

**Reduced motion:** all children show at their final position at once,
with no animation. No run starts, so `motion-start` and `motion-finish` do
not fire.

**Common mistakes:** only direct child elements animate. Wrapping all items
in one `<div>` or `<ul>` makes them animate as one block; put the items
directly inside `motion-stagger`. Text placed directly inside, outside a
child element, is not animated.

Docs: https://www.motion-components.dev/docs/reveal/motion-stagger/

## Install

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

Or without a build step:

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

## Example

```html
<motion-stagger interval="0.08" from="first">
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
</motion-stagger>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `interval` | `number` | `0.06` | Delay between each child's reveal, in seconds. |
| `duration` | `number` | `0.5` | Spring duration of each child's reveal, in seconds. |
| `y` | `number` | `16` | Initial vertical offset in pixels for each child; rises to 0. |
| `from` | `'first' \| 'last' \| 'center'` | `'first'` | Stagger origin: `'first'`, `'last'` or `'center'`. |
| `once` | `boolean` | `true` | When `true`, only animate the first time the list enters view. Set `once="false"` to turn it off. |

## 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 |
| --- | --- |
| `replay()` | Resets and re-runs the staggered reveal. |
| `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 list of children to reveal in sequence. |