> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-feat-registry-theme-families.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Motion Blur

> Velocity-driven directional motion blur — samples element position each frame and applies a one-sided ghost trail proportional to speed

# Motion Blur

Velocity-driven directional motion blur — samples element position each frame and applies a one-sided ghost trail proportional to speed.

`effect` `motion-blur` `velocity` `animation` `physics`

<video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/motion-blur.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/components/motion-blur.png" autoPlay muted loop playsInline />

## Install

<CodeGroup>
  ```bash Terminal theme={null}
  npx hyperframes add motion-blur
  ```
</CodeGroup>

## Details

| Property | Value     |
| -------- | --------- |
| Type     | Component |

## Files

| File               | Target                                     | Type                |
| ------------------ | ------------------------------------------ | ------------------- |
| `motion-blur.html` | `compositions/components/motion-blur.html` | hyperframes:snippet |

## Usage

Paste the snippet into your composition, then call `attachMotionBlur()` after your GSAP tweens and before registering `window.__timelines`.

```html theme={null}
<!-- Extend the timeline to data-duration before calling attachMotionBlur -->
tl.set(document.body, {}, DATA_DURATION);

attachMotionBlur("#my-box", tl, {
  axis: "x",      // "x" | "y" | "both"
  blurMax: 40,    // max blur radius in px (default 20)
});

window.__timelines = window.__timelines || {};
window.__timelines["my-composition"] = tl;
```

## How it works

Each target element gets its own SVG filter. On every timeline seek, `attachMotionBlur` samples the element's GSAP `x`/`y` position, computes velocity, and drives three SVG filter primitives:

1. **Ghost copies** — three faded, blurred copies of the element placed behind it at increasing offsets proportional to speed. Inherently one-sided: no forward blur.
2. **Top blur** — a small symmetric Gaussian at the current position so the element looks in-motion rather than crisp on top of the trail.

Blur scales linearly with velocity up to `blurMax`. Both the ghost trail and top blur clear automatically when the element decelerates to rest.

## Options

| Option         | Default  | Description                                         |
| -------------- | -------- | --------------------------------------------------- |
| `axis`         | `"both"` | Motion axis — `"x"`, `"y"`, or `"both"`             |
| `blurScale`    | `0.008`  | Blur per px/s of velocity                           |
| `blurMax`      | `20`     | Max blur radius on the motion axis (px)             |
| `stretchScale` | `0.0002` | scaleX/Y added per px/s (requires `stretchMax > 0`) |
| `stretchMax`   | `0`      | Max stretch above 1.0 — disabled by default         |