# <motion-gravity>

Gravity-drop text. Each character falls in from above and bounces to rest
with a stagger across the line.

Text can be set with the `text` attribute or as child text. Child text
doubles as a pre-upgrade fallback: the browser shows it before the
element is defined, so the page never paints an empty gap.

**Use it for:** short, playful words and headings whose letters drop in and
bounce into place, when the page loads or, with `trigger="view"`, when they
scroll into view.

**Avoid it for:** long sentences. For a split-text reveal of longer text,
use `motion-split` or `motion-headline`.

**Accessibility:** screen readers read the whole text once from a visually
hidden copy. The falling letters are `aria-hidden`. The element has no
heading role, so put it inside a heading element when it is a heading.

**Reduced motion:** the letters show at their final position at once, with
no drop.

**Common mistakes:** placing it far down the page with the default
`trigger="mount"`, so the drop is over before anyone sees it; set
`trigger="view"`. Changing
the child text after the element is on the page; the child text is read
once, so set the `text` property instead.

Docs: https://www.motion-components.dev/docs/text/motion-gravity/

## Install

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

Or without a build step:

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

## Example

```html
<motion-gravity height="80" interval="0.06">GRAVITY</motion-gravity>
<motion-gravity trigger="view">drops in on scroll</motion-gravity>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string \| undefined` |  | Text to drop in. Falls back to the element's child text when unset. |
| `height` | `number` | `60` | Drop distance in pixels (each char starts this far above its rest). |
| `interval` | `number` | `0.05` | Delay between successive character drops, in seconds. |
| `duration` | `number` | `0.6` | Spring duration of each character's fall, in seconds. |
| `bounce` | `number` | `0.45` | Spring bounciness of the landing (0 = no overshoot). |
| `delay` | `number` | `0` | Delay before the first character starts falling, in seconds. |
| `trigger` | `'mount' \| 'view'` | `'mount'` | When the letters drop: `'mount'` (as soon as it renders) or `'view'` (the first time half of it is in view). |

## 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 gravity drop. |
| `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. |