# <motion-stretch>

Springy character spread on hover. Each character springs outward from
the centre by `spread`, snapping back on mouse leave.

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 words, logos or labels whose letters should spread
apart with a springy bounce when the mouse moves over them.

**Avoid it for:** text that must wrap, because the letters sit on one line,
and effects that keyboard users need to see. To lift or scale a whole
element on hover, use `motion-hover`.

**Accessibility:** the full text is in a visually hidden span and the
letter spans have `aria-hidden`, so screen readers read the text once, as
normal words. The effect reacts to the mouse only, not to keyboard focus,
so do not use it to show state or meaning.

**Reduced motion:** the letters do not move when the mouse enters.

**Common mistakes:** a large `spread` next to other content: the edge
letters move about `spread` pixels outside the element and can cover the
content next to it, so leave space around it. Changing the child text after
the element connects has no effect; set `text` instead.

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

## Install

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

Or without a build step:

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

## Example

```html
<motion-stretch spread="16">STRETCH</motion-stretch>
```

## Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string \| undefined` |  | Text to stretch. Falls back to the element's child text when unset. |
| `spread` | `number` | `12` | Maximum lateral displacement of edge characters, in pixels. |
| `duration` | `number` | `0.77` | Spring duration of the spread and release, in seconds. |
| `bounce` | `number` | `0.55` | Spring bounciness (0 = critically damped, higher = more elastic). |
| `disabled` | `boolean` | `false` | When `true`, ignores pointer input and settles back. `pauseAll()` sets it. |