# Motion.page Documentation — Full Content

## Animation Presets

> Full catalog of built-in presets — Entrances, Loops, Text Reveals, Smooth Transitions, Creative Effects.

URL: https://motion.page/docs/sdk/animation-presets

import LivePreview from "../../components/docs/blocks/LivePreview";

Presets are ready-made animation configurations built into the Motion.page Builder. Each preset pre-fills `from`, `to`, stagger, split, and repeat settings — a starting point you can customize immediately.

In the **Builder**, open the Presets panel, pick a category, and click any preset to apply it to the selected element. In the **SDK**, copy the `from`/`to` values from the tables below directly into your `Motion()` call.

## SDK Usage

Presets don't have a dedicated API option — use the `from`/`to` values from each preset's row directly in `AnimationConfig`:

```typescript
import { Motion } from "@motion.page/sdk";

// Fade Up preset
Motion("hero", "#hero", {
  from: { opacity: 0, y: 100 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad();

// Pulse loop preset
Motion("badge", ".badge", {
  to: { scale: 1.1 },
  duration: 0.8,
  repeat: { times: -1, yoyo: true },
  ease: "power1.inOut",
}).onPageLoad();

// Text reveal preset (Words Slide Up)
Motion("headline", "h1", {
  split: "words",
  from: { opacity: 0, y: 20 },
  stagger: { each: 0.1, from: "start" },
  duration: 0.7,
  ease: "power2.out",
}).onPageLoad();
```

<LivePreview client:visible
  height={360}
  title="Animation preset showcase"
  html={`<div class="preset-grid">
  <article class="preset-card entrance-card">
    <span class="preset-label">Entrance</span>
    <div class="preset-shape">Fade Up</div>
  </article>
  <article class="preset-card loop-card">
    <span class="preset-label">Loop</span>
    <div class="preset-dot"></div>
    <strong>Pulse</strong>
  </article>
  <article class="preset-card text-card">
    <span class="preset-label">Text Reveal</span>
    <h3>Words slide up</h3>
  </article>
</div>`}
  css={`.preset-grid {
  width: min(720px, 100%);
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 14px;
}
.preset-card {
  min-height: 190px;
  padding: 18px;
  border: 1px solid rgba(153, 168, 255, 0.22);
  border-radius: 18px;
  background: linear-gradient(145deg, rgba(25, 30, 61, 0.92), rgba(8, 11, 31, 0.96));
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 18px;
  overflow: hidden;
}
.preset-label {
  align-self: flex-start;
  color: #9ea8c9;
  font-size: 11px;
  font-weight: 700;
  letter-spacing: 0.12em;
  text-transform: uppercase;
}
.preset-shape {
  width: 112px;
  height: 76px;
  border-radius: 14px;
  background: linear-gradient(135deg, #7047eb, #a97cff);
  display: grid;
  place-items: center;
  color: white;
  font-size: 13px;
  font-weight: 700;
  box-shadow: 0 18px 50px rgba(112, 71, 235, 0.34);
}
.preset-dot {
  width: 66px;
  height: 66px;
  border-radius: 50%;
  background: radial-gradient(circle at 30% 25%, #fff, #6ee7ff 22%, #356bff 70%);
  box-shadow: 0 0 38px rgba(70, 126, 255, 0.5);
}
.loop-card strong { font-size: 14px; }
.text-card h3 {
  max-width: 150px;
  color: #f4f5ff;
  font-size: clamp(20px, 3.2vw, 29px);
  line-height: 1.04;
  text-align: center;
}
@media (max-width: 560px) {
  .preset-grid { grid-template-columns: 1fr; }
  .preset-card {
    min-height: 88px;
    padding: 12px 14px;
    flex-direction: row;
    justify-content: space-between;
  }
  .preset-label { align-self: auto; }
  .preset-shape { width: 88px; height: 54px; }
  .preset-dot { width: 48px; height: 48px; }
  .text-card h3 { max-width: 125px; font-size: 18px; text-align: right; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("preset-fade-up", ".preset-shape", {
  from: { opacity: 0, y: 100 },
  duration: 0.8,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("preset-pulse", ".preset-dot", {
  to: { scale: 1.1 },
  duration: 0.8,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("preset-words", ".text-card h3", {
  split: "words",
  from: { opacity: 0, y: 20 },
  stagger: { each: 0.1, from: "start" },
  duration: 0.7,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Overriding Preset Values

Apply a preset in the Builder, then adjust any value — duration, ease, individual `from`/`to` properties. In the SDK, the preset values are just defaults: change whatever you need.

```typescript
// Fade Up with a slower duration and spring ease
Motion("section", ".section", {
  from: { opacity: 0, y: 60 },   // reduced offset (default: 100)
  duration: 1.2,                  // slower (common default: 0.8)
  ease: "elastic.out(1, 0.75)",  // spring instead of power ease
}).onPageLoad();
```

---

## Entrances

**Entrance** presets animate elements _into_ their natural state — all use `from` values only. The SDK resolves the missing `to` endpoint from the element's current computed CSS.

| Preset | `from` values |
|--------|--------------|
| **Fade In** | `opacity: 0` |
| **Blur In** | `opacity: 0, filter: "blur(10px)"` |
| **Fade Up** | `opacity: 0, y: 100` |
| **Fade Down** | `opacity: 0, y: -100` |
| **Fade Left** | `opacity: 0, x: 100` |
| **Fade Right** | `opacity: 0, x: -100` |
| **Scale In** | `scale: 0` |
| **Scale In Soft** | `scale: 0.5, opacity: 0` |
| **Zoom In** | `scale: 0.3, opacity: 0` |
| **Zoom Out** | `scale: 1.3, opacity: 0` |
| **Flip In X** | `rotateX: 90, opacity: 0` |
| **Flip In Y** | `rotateY: 90, opacity: 0` |
| **Rise & Fade** | `opacity: 0, y: 80, scale: 0.95` |
| **Skew Slide** | `opacity: 0, x: -100, skewX: 15` |
| **Spiral In** | `scale: 0, rotate: 180, opacity: 0` |
| **Corner Pop** | `scale: 0, rotate: -90, transformOrigin: "0% 0%"` |

All `x`/`y` values are in `px`. All `rotate`/`rotateX`/`rotateY` values are in degrees.

```typescript
// Flip In X
Motion("card", ".card", {
  from: { rotateX: 90, opacity: 0 },
  duration: 0.7,
  ease: "power3.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });

// Corner Pop — note the custom transform origin
Motion("pop", ".badge", {
  from: { scale: 0, rotate: -90 },
  duration: 0.5,
  ease: "back.out(1.7)",
}).onPageLoad();
// Set transform origin separately:
// Motion.set(".badge", { transformOrigin: "0% 0%" });
```

---

## Loops

**Loop** presets animate _to_ a custom state with infinite repeat. All use `to` values only — the SDK reads the element's current CSS as the start point.

| Preset | `to` values | Repeat |
|--------|------------|--------|
| **Pulse** | `scale: 1.1` | infinite yoyo |
| **Shake X** | `x: 10` | 3× yoyo then stops |
| **Shake Y** | `y: 10` | infinite yoyo |
| **Wiggle** | `rotate: 5` | infinite yoyo |
| **Bounce** | `y: -20` | infinite yoyo |
| **Rubber Band** | `scaleX: 1.3, scaleY: 0.8` | infinite yoyo |
| **Swing** | `rotate: 15, transformOrigin: "50% 0%"` | infinite yoyo |
| **Pendulum** | `rotate: 20, transformOrigin: "50% 0%"` | infinite yoyo |
| **Flash** | `opacity: 0.3` | infinite yoyo |
| **Strobe** | `opacity: 0` | infinite yoyo |
| **Flip Back** | `rotateY: 360` | infinite (no yoyo) |

`x`/`y` values are in `px`. `rotate`/`rotateY` in degrees. **Shake X** repeats 3 times (plays 4 total) then stops; all others loop infinitely.

```typescript
// Pulse
Motion("pulse", ".cta-button", {
  to: { scale: 1.1 },
  duration: 0.8,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();

// Swing — set the pivot point before animating
Motion.set(".pendulum", { transformOrigin: "50% 0%" });
Motion("swing", ".pendulum", {
  to: { rotate: 15 },
  duration: 1,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();

// Flip Back — continuous spin (no yoyo)
Motion("spin", ".icon", {
  to: { rotateY: 360 },
  duration: 2,
  ease: "none",
  repeat: { times: -1, yoyo: false },
}).onPageLoad();
```

---

## Text Reveals

**Text Reveal** presets split text into characters, words, or lines and stagger them in. All use `from` values with a `split` type and `stagger` configuration.

### Words

| Preset | `from` values | Stagger `each` | Stagger `from` |
|--------|--------------|----------------|----------------|
| **Words Fade In** | `opacity: 0` | 0.08s | start |
| **Words Slide Up** | `opacity: 0, y: 20` | 0.10s | start |
| **Words Slide Down** | `opacity: 0, y: -20` | 0.10s | start |
| **Words From Left** | `opacity: 0, x: -30` | 0.08s | start |
| **Words From Right** | `opacity: 0, x: 30` | 0.08s | start |
| **Words From Center** | `opacity: 0, scale: 0.5` | 0.10s | center |
| **Words From Edges** | `opacity: 0` | 0.10s | edges |
| **Words Blur In** | `opacity: 0, filter: "blur(10px)"` | 0.10s | start |
| **Words Skew In** | `opacity: 0, skewX: 20` | 0.08s | start |
| **Words Typewriter** | `opacity: 0, x: -10` | 0.15s | start |

### Characters

| Preset | `from` values | Stagger `each` | Stagger `from` |
|--------|--------------|----------------|----------------|
| **Chars Fade In** | `opacity: 0` | 0.03s | start |
| **Chars Cascade** | `opacity: 0, y: 30` | 0.03s | start |
| **Chars Pop In** | `scale: 0` | 0.02s | start |
| **Chars Rotate In** | `opacity: 0, rotate: 90` | 0.03s | start |
| **Chars Random** | `opacity: 0, y: 20` | 0.02s | random |
| **Chars 3D Flip** | `rotateX: 90, opacity: 0` | 0.03s | start |
| **Chars Wave** | `opacity: 0, y: -20` | 0.02s | start |
| **Typewriter** | `opacity: 0` | 0.05s | start |

### Lines

| Preset | `from` values | Stagger `each` | Stagger `from` |
|--------|--------------|----------------|----------------|
| **Lines Rise** | `opacity: 0, y: 40` | 0.20s | start |
| **Lines Fade** | `opacity: 0` | 0.15s | start |

All `x`/`y` values are in `px`. `rotate`/`rotateX` in degrees. `skewX` in degrees.

```typescript
// Words Slide Up
Motion("headline", "h1", {
  split: "words",
  from: { opacity: 0, y: 20 },
  stagger: { each: 0.1, from: "start" },
  duration: 0.7,
  ease: "power2.out",
}).onPageLoad();

// Chars 3D Flip — perspective helps the 3D effect read clearly
Motion("title-3d", ".title", {
  split: "chars",
  from: { rotateX: 90, opacity: 0 },
  stagger: { each: 0.03, from: "start" },
  duration: 0.6,
  ease: "power3.out",
}).onPageLoad();

// Words From Center — stagger radiates outward from middle
Motion("center-reveal", ".tagline", {
  split: "words",
  from: { opacity: 0, scale: 0.5 },
  stagger: { each: 0.1, from: "center" },
  duration: 0.6,
  ease: "back.out(1.7)",
}).onPageLoad();

// Lines Rise — use mask to clip overflow during slide
Motion("lines-in", ".paragraph", {
  split: "lines",
  mask: true,
  from: { opacity: 0, y: 40 },
  stagger: { each: 0.2, from: "start" },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();
```

---

## Smooth Transitions

**Smooth Transition** presets use subtle values for gentle, polished reveals. All use `from` values only. Good for body copy, cards, and supporting UI elements where dramatic entrances feel excessive.

| Preset | `from` values |
|--------|--------------|
| **Gentle Fade** | `opacity: 0.3` |
| **Soft Slide Up** | `y: 20, opacity: 0.5` |
| **Float In** | `y: 15, opacity: 0` |
| **Blur to Focus** | `opacity: 0, filter: "blur(5px)"` |
| **Elegant Scale** | `scale: 0.95, opacity: 0` |
| **Drift Right** | `x: -20, opacity: 0` |
| **Drift Left** | `x: 20, opacity: 0` |
| **Rise Subtle** | `y: 10, opacity: 0, scale: 0.98` |
| **Drop Subtle** | `y: -10, opacity: 0, scale: 0.98` |
| **Grow Subtle** | `scale: 0.9, opacity: 0` |
| **Shrink In** | `scale: 1.1, opacity: 0` |
| **Soft Blur Slide** | `y: 15, opacity: 0, filter: "blur(3px)"` |

`x`/`y` values are in `px`. Negative `opacity` start values (e.g. `0.3`, `0.5`) fade from partially visible rather than fully invisible — producing a softer effect.

```typescript
// Elegant Scale — great for modals and cards
Motion("card-reveal", ".card", {
  from: { scale: 0.95, opacity: 0 },
  duration: 0.5,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });

// Blur to Focus — cinematic feel for hero text
Motion("hero-focus", ".hero-text", {
  from: { opacity: 0, filter: "blur(5px)" },
  duration: 0.9,
  ease: "power2.out",
}).onPageLoad();

// Batch multiple elements with stagger
Motion("section-items", ".section-item", {
  from: { y: 15, opacity: 0 },
  duration: 0.5,
  stagger: 0.08,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

---

## Creative Effects

**Creative Effects** presets include entrance-only (`from`), exit-only (`to`), and complete transitions (`from` + `to` — where neither endpoint matches the element's natural state).

### Entrance (`from` only)

| Preset | `from` values |
|--------|--------------|
| **Spiral In** | `scale: 0, rotate: 180, opacity: 0` |
| **Twist In** | `rotate: 360, scale: 0, opacity: 0` |
| **Bounce In** | `scale: 0` |
| **Squeeze In** | `scaleX: 0, scaleY: 1, opacity: 0` |
| **Morph In** | `scale: 0.5, skewX: 20, opacity: 0` |

### Exit (`to` only)

| Preset | `to` values |
|--------|------------|
| **Spiral Out** | `scale: 0, rotate: -180, opacity: 0` |
| **Squeeze Out** | `scaleX: 1, scaleY: 0, opacity: 0` |

### Complete Transitions (`from` + `to`)

| Preset | `from` values | `to` values |
|--------|--------------|------------|
| **Slide Through** | `x: -100, opacity: 0` | `x: 100, opacity: 0` |
| **Zoom Through** | `scale: 0, opacity: 0` | `scale: 2, opacity: 0` |
| **Flip Full** | `rotateY: -90, opacity: 0` | `rotateY: 90, opacity: 0` |
| **Rotate Through** | `rotate: -180` | `rotate: 180` |
| **Color Shift** | `backgroundColor: "#ff0000"` | `backgroundColor: "#0000ff"` |
| **Skew Transform** | `skewX: -30, x: -50` | `skewX: 30, x: 50` |
| **Scale Bounce** | `scale: 0` | `scale: 1.2` + `repeat: { times: 1, yoyo: true }` |
| **Perspective Spin** | `rotateY: 180, scale: 0.5` | `rotateY: 360, scale: 1` |

`x` values are in `px`. `rotate`/`rotateY`/`skewX` in degrees. Complete transitions define explicit start and end states — the element passes through both on its way to the natural resting state (or is explicitly a pass-through effect like **Slide Through**).

```typescript
// Bounce In — add a back ease for the overshoot feel
Motion("pop-in", ".modal", {
  from: { scale: 0 },
  duration: 0.5,
  ease: "back.out(1.7)",
}).onPageLoad();

// Spiral Out — play on exit trigger
Motion("spiral-exit", ".panel", {
  to: { scale: 0, rotate: -180, opacity: 0 },
  duration: 0.6,
  ease: "power3.in",
}).onClick();

// Flip Full — complete flip transition, both endpoints are non-natural
Motion("flip-card", ".card", {
  from: { rotateY: -90, opacity: 0 },
  to: { rotateY: 90, opacity: 0 },
  duration: 0.6,
  ease: "power2.inOut",
}).onClick();

// Color Shift — hover color transition between two explicit colors
Motion("color-hover", ".button", {
  from: { backgroundColor: "#ff0000" },
  to: { backgroundColor: "#0000ff" },
  duration: 0.4,
  ease: "power2.inOut",
}).onHover({ each: true, onLeave: "reverse" });

// Scale Bounce — grows in then bounces once
Motion("scale-bounce", ".notification", {
  from: { scale: 0 },
  to: { scale: 1.2 },
  duration: 0.4,
  ease: "power2.out",
  repeat: { times: 1, yoyo: true },
}).onPageLoad();

// Perspective Spin — rotating reveal from a half-turn
Motion("spin-reveal", ".card", {
  from: { rotateY: 180, scale: 0.5 },
  to: { rotateY: 360, scale: 1 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad();
```

---

## Quick Reference

| Category | Count | Pattern | Trigger Style |
|----------|-------|---------|---------------|
| Entrances | 16 | `from` only | Page load, scroll |
| Loops | 11 | `to` + `repeat` | Page load (always-on) |
| Text Reveals | 20 | `from` + `split` + `stagger` | Page load, scroll |
| Smooth Transitions | 12 | `from` only (subtle values) | Scroll, page load |
| Creative Effects | 15 | `from`, `to`, or both | Page load, click, hover |

**Total: 74 presets.**

---

## Translate

> Move elements along X and Y axes with pixel or percentage values.

URL: https://motion.page/docs/sdk/translate

import LivePreview from "../../components/docs/blocks/LivePreview";

**Translate** moves elements along the X, Y, and Z axes. Properties `x` and `y` default to pixels; use `xPercent` and `yPercent` for responsive percentage-based movement that scales with element size.

## Basic Translate

Pass `x` or `y` inside `from` or `to`. Numbers are treated as pixels by default.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("slide", ".box", {
  from: { x: -100 },
  duration: 0.6,
  ease: "power2.out",
}).play();
```

<LivePreview client:load
  height={200}
  title="Slide up reveal"
  html={`<div style="display:flex;gap:16px;justify-content:center;align-items:center;height:100%;padding:24px;"><div class="box">1</div><div class="box">2</div><div class="box">3</div></div>`}
  css={`.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; display:flex;align-items:center;justify-content:center;color:white;font-weight:bold;font-size:20px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("reveal", ".box", {
  from: { y: 60, opacity: 0 },
  duration: 0.6,
  stagger: 0.12,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `x` | `number` | `0` | Horizontal offset in pixels |
| `y` | `number` | `0` | Vertical offset in pixels |
| `z` | `number` | `0` | Depth offset in pixels (3D) |
| `xPercent` | `number` | `0` | Horizontal offset as % of element width |
| `yPercent` | `number` | `0` | Vertical offset as % of element height |

---

## Percentage Values

`xPercent` and `yPercent` move an element relative to its own dimensions. A value of `-100` slides the element completely off-screen in its own width or height — ideal for full-bleed panel transitions.

```typescript
Motion("responsive-slide", ".panel", {
  from: { yPercent: -100 },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();
```

---

## From-Only Pattern for Reveals

The most common translate pattern: start offset, animate to the natural position. The SDK reads the element's current CSS (`x: 0`, `y: 0`) as the `to` endpoint automatically — no need to declare it.

```typescript
Motion("reveal", ".card", {
  from: { y: 100, opacity: 0 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

---

## Combining X and Y — Diagonal Movement

Set both `x` and `y` simultaneously to animate along a diagonal path.

```typescript
Motion("diagonal", ".element", {
  from: { x: -80, y: 60, opacity: 0 },
  duration: 0.7,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

---

## px vs % — When to Use Each

**Pixels** (`x`, `y`) — Fixed distance. Predictable across all screen sizes. Best for small UI shifts like hover lifts and nudges.

**Percent** (`xPercent`, `yPercent`) — Relative to element dimensions. Responsive. Best for full-width slides and off-screen entrances.

---

## Common Patterns

### Slide Up Reveal

```typescript
Motion("slide-up", ".section", {
  from: { y: 40, opacity: 0 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Horizontal Scroll

```typescript
const sections = Motion.utils.toArray(".panel");

Motion("h-scroll", ".track", {
  to: { xPercent: -100 * (sections.length - 1) },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  end: `+=${sections.length * 100}%`,
});
```

### Parallax Offset

Drive `y` with scroll scrub to produce a parallax effect. The element moves at a different speed than the page scroll.

```typescript
Motion("parallax", ".bg-layer", {
  from: { y: -50 },
  to: { y: 50 },
  duration: 1,
}).onScroll({ scrub: true });
```

---

## Z-Axis Translation (3D Depth)

`z` moves elements along the depth axis — toward or away from the viewer. It requires a parent element with a `perspective` CSS property to produce a visible 3D effect.

```typescript
Motion("depth", ".card", {
  from: { z: -200, opacity: 0 },
  duration: 0.8,
  ease: "power2.out",
}).play();
```

Set `perspective: 800px` (or similar) on the parent container:

```css
.container {
  perspective: 800px;
}
```

For more on combining translate with rotations and 3D, see the [3D Transforms](/docs/sdk/3d-transforms) page.

---

## Related

- [Opacity](/docs/sdk/opacity) — fade combined with translate for polished reveals
- [Scale](/docs/sdk/scale) — zoom effects often paired with translate
- [3D Transforms](/docs/sdk/3d-transforms) — rotateX, rotateY, and perspective
- [Transform Origin](/docs/sdk/transform-origin) — control the anchor point for all transforms

---

## Breakpoints

> Configure responsive breakpoints and per-breakpoint animation behavior.

URL: https://motion.page/docs/sdk/breakpoints

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

Motion.page uses four named breakpoint ranges — **phones**, **tablets**, **laptops**, and **desktop** — with configurable pixel thresholds. Use `Motion.responsive()` when variants should swap live, or native `matchMedia` for a one-time conditional guard. The Builder generates the appropriate responsive code automatically.

---

## Default Breakpoint Values

These are the global defaults. All SDK examples on this page use them. You can change the thresholds in **Builder > Settings > Breakpoints**.

| Range | Condition | Default threshold |
|-------|-----------|-------------------|
| Phones | `max-width` | `576px` |
| Tablets | `max-width` | `768px` |
| Laptops | `max-width` | `992px` |
| Desktop | `min-width` | `993px` |

Each threshold is a **maximum width** for the named range. Desktop has no upper bound — it applies from `993px` upward.

---

## SDK: matchMedia Guard

Use `window.matchMedia()` when a single animation only needs to be registered at one size. The check runs once at script execution time — if the condition doesn't match, the animation is never registered. For variants that react to resize, use [`Motion.responsive()`](/docs/sdk/responsive).

```typescript
import { Motion } from "@motion.page/sdk";

// Phones only — up to 576px
if (matchMedia("screen and (max-width: 576px)").matches) {
  Motion("mobile-hero", ".hero", {
    from: { opacity: 0, y: 20 },
    duration: 0.5,
  }).onPageLoad();
}
```

<LivePreview client:visible
  height={330}
  title="Breakpoint match at preview load"
  html={`<div class="breakpoint-demo">
  <div class="breakpoint-heading">
    <div>
      <span>Preview viewport</span>
      <strong class="viewport-width">—</strong>
    </div>
    <small>Resize the docs window, then use Re-run.</small>
  </div>
  <div class="range-grid">
    <div class="range-card" data-tier="phone"><span>≤ 576</span><strong>Phone</strong></div>
    <div class="range-card" data-tier="tablet"><span>577–768</span><strong>Tablet</strong></div>
    <div class="range-card" data-tier="laptop"><span>769–992</span><strong>Laptop</strong></div>
    <div class="range-card" data-tier="desktop"><span>≥ 993</span><strong>Desktop</strong></div>
  </div>
</div>`}
  css={`.breakpoint-demo {
  width: min(720px, 100%);
  padding: 20px;
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  background: linear-gradient(145deg, rgba(25, 30, 61, 0.94), rgba(7, 10, 27, 0.96));
}
.breakpoint-heading {
  display: flex;
  align-items: flex-end;
  justify-content: space-between;
  gap: 16px;
  margin-bottom: 20px;
}
.breakpoint-heading div { display: grid; gap: 3px; }
.breakpoint-heading span,
.breakpoint-heading small { color: #929abd; font-size: 12px; }
.viewport-width { color: #f4f5ff; font-size: 26px; }
.range-grid {
  display: grid;
  grid-template-columns: repeat(4, minmax(0, 1fr));
  gap: 10px;
}
.range-card {
  min-height: 100px;
  padding: 14px;
  border: 1px solid rgba(153, 168, 255, 0.18);
  border-radius: 14px;
  background: rgba(9, 13, 34, 0.78);
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}
.range-card span { color: #8f98bd; font-size: 11px; }
.range-card strong { font-size: 14px; }
.range-card.is-active {
  border-color: #8c6cff;
  background: linear-gradient(145deg, rgba(111, 70, 235, 0.72), rgba(47, 35, 105, 0.88));
  box-shadow: 0 16px 42px rgba(91, 64, 216, 0.28);
}
@media (max-width: 520px) {
  .breakpoint-heading { align-items: flex-start; flex-direction: column; }
  .range-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
  .range-card { min-height: 72px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const ranges = [
  { name: "phone", query: "screen and (max-width: 576px)", from: { opacity: 0.35, y: 20 } },
  { name: "tablet", query: "screen and (min-width: 577px) and (max-width: 768px)", from: { opacity: 0.35, scale: 0.92 } },
  { name: "laptop", query: "screen and (min-width: 769px) and (max-width: 992px)", from: { opacity: 0.35, x: -20 } },
  { name: "desktop", query: "screen and (min-width: 993px)", from: { opacity: 0.35, x: 20 } },
];

document.querySelector(".viewport-width").textContent = window.innerWidth + "px";
const active = ranges.find((range) => matchMedia(range.query).matches);

if (active) {
  const card = document.querySelector("[data-tier='" + active.name + "']");
  card.classList.add("is-active");
  Motion("matched-breakpoint", card, {
    from: active.from,
    duration: 0.8,
    ease: "power2.out",
    repeat: { times: -1, yoyo: true, delay: 0.6 },
  }).play();
}`}
/>

---

## Per-Range Examples

### Phones only

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (max-width: 576px)").matches) {
  Motion("mobile-reveal", ".section-title", {
    from: { opacity: 0, y: 24 },
    duration: 0.5,
    ease: "power2.out",
  }).onPageLoad();
}
```

### Tablets only

Tablets span from just above the phones threshold to the tablets threshold:

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (min-width: 577px) and (max-width: 768px)").matches) {
  Motion("tablet-grid", ".card", {
    from: { opacity: 0, scale: 0.95 },
    duration: 0.4,
    stagger: 0.06,
    ease: "power2.out",
  }).onScroll({ toggleActions: "play none none none" });
}
```

### Laptops only

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (min-width: 769px) and (max-width: 992px)").matches) {
  Motion("laptop-parallax", ".bg-shape", {
    from: { y: -40 },
    to: { y: 40 },
    duration: 1,
  }).onScroll({ scrub: true });
}
```

### Desktop only

```typescript
import { Motion } from "@motion.page/sdk";

// Skip on mobile and tablet — hover effects don't suit touch screens
if (matchMedia("screen and (min-width: 993px)").matches) {
  Motion("card-hover", ".card", {
    to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
    duration: 0.3,
    ease: "power2.out",
  }).onHover({ each: true, onLeave: "reverse" });
}
```

### Phones and tablets (up to 768px)

Combine ranges by using the upper threshold of the outermost range:

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (max-width: 768px)").matches) {
  Motion("small-screen-fade", ".hero-image", {
    from: { opacity: 0 },
    duration: 0.6,
  }).onPageLoad();
}
```

### Tablets, laptops, and desktop (min-width 577px)

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (min-width: 577px)").matches) {
  Motion("wide-parallax", ".feature-block", {
    from: { x: -60, opacity: 0 },
    duration: 0.8,
    stagger: 0.1,
    ease: "power3.out",
  }).onScroll({ toggleActions: "play none none none" });
}
```

---

## Different Animations per Breakpoint

Use multiple `matchMedia` checks to run different animations at different sizes. Only one block runs per page load.

```typescript
import { Motion } from "@motion.page/sdk";

// Desktop: full parallax
if (matchMedia("screen and (min-width: 993px)").matches) {
  Motion("hero-effect", ".hero-image", {
    from: { y: -60 },
    to: { y: 60 },
    duration: 1,
  }).onScroll({ scrub: true });
}

// Tablets and laptops: simple fade on scroll
if (
  matchMedia("screen and (min-width: 577px) and (max-width: 992px)").matches
) {
  Motion("hero-effect", ".hero-image", {
    from: { opacity: 0 },
    duration: 0.7,
    ease: "power2.out",
  }).onScroll({ toggleActions: "play none none none" });
}

// Phones: instant fade on load — skip scroll complexity
if (matchMedia("screen and (max-width: 576px)").matches) {
  Motion("hero-effect", ".hero-image", {
    from: { opacity: 0 },
    duration: 0.5,
  }).onPageLoad();
}
```

---

## Builder: Enabled Breakpoints

In the Builder, each timeline has an **Enabled Breakpoints** range selector in the Trigger Section. It maps to a five-point scale:

| Point | Icon | Range |
|-------|------|-------|
| 1 | ⊘ (disabled) | Below phones — animation off |
| 2 | Phone | Phones (`max-width: 576px`) |
| 3 | Tablet | Tablets (`max-width: 768px`) |
| 4 | Laptop | Laptops (`max-width: 992px`) |
| 5 | ∞ | Desktop and above (no upper bound) |

The default range is **1 → 5** (all devices). Drag either handle inward to restrict the animation to a narrower range.

The Builder wraps the generated code automatically:

```typescript
// Range set to phones + tablets [1–3] generates:
if (matchMedia("screen and (max-width: 768px)").matches) {
  // your animation code
}

// Range set to desktop only [4–5] generates:
if (matchMedia("screen and (min-width: 992px)").matches) {
  // your animation code
}
```

No manual code is needed when using the Builder — the `matchMedia` guard is injected at export time.

---

## Custom Breakpoint Thresholds

The pixel values for phones, tablets, and laptops are global settings. Change them in **Builder > Settings > Breakpoints**. All timelines and generated SDK code will reflect the updated thresholds.

| Setting | Tooltip | Default |
|---------|---------|---------|
| Phones | Maximum width in pixels | `576` |
| Tablets | Maximum width in pixels | `768` |
| Laptops | Maximum width in pixels | `992` |

After updating these values, the breakpoint reference table above changes accordingly. Update your SDK `matchMedia` calls to match if you override the defaults.

<CodeBlock
  filename="custom-breakpoints.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Site uses custom breakpoints: phones 480px, tablets 900px, desktop 901px+
if (matchMedia("screen and (min-width: 901px)").matches) {
  Motion("desktop-reveal", ".feature", {
    from: { opacity: 0, y: 40 },
    duration: 0.7,
    stagger: 0.08,
    ease: "power2.out",
  }).onScroll({ toggleActions: "play none none none" });
}`}
/>

---

## Resize-Aware Breakpoints

`matchMedia` checks run once at load. If a user resizes their browser past a threshold after the page has loaded, registered animations don't update. For resize-aware behavior, use `Motion.context()` with a `MediaQueryList` change listener:

```typescript
import { Motion } from "@motion.page/sdk";

const mq = matchMedia("screen and (min-width: 993px)");

let ctx = Motion.context(() => {
  if (mq.matches) {
    Motion("desktop-scroll", ".card", {
      from: { opacity: 0, y: 40 },
      duration: 0.6,
      stagger: 0.1,
    }).onScroll({ toggleActions: "play none none none" });
  }
});

mq.addEventListener("change", () => {
  ctx.revert();
  ctx = Motion.context(() => {
    if (mq.matches) {
      Motion("desktop-scroll", ".card", {
        from: { opacity: 0, y: 40 },
        duration: 0.6,
        stagger: 0.1,
      }).onScroll({ toggleActions: "play none none none" });
    }
  });
});
```

`ctx.revert()` kills all timelines in the context and restores initial CSS. Re-running `Motion.context()` reinitializes them with fresh selectors. For most sites, a one-time check at load is sufficient — resize-aware handling is only needed when your layout shifts significantly on breakpoint crossing.

---

## Related

- [Responsive Animations](/docs/sdk/responsive) — matchMedia patterns, reduced motion, and SPA-aware reinit
- [Core Concepts](/docs/sdk/core-concepts) — `Motion.context()` for lifecycle management and teardown
- [Page Load Trigger](/docs/sdk/page-load) — entrance animations on load
- [Scroll Trigger](/docs/sdk/scroll-trigger) — viewport-based scroll animations

---

## Duration & Delay

> Control animation timing with duration in seconds and delay before start.

URL: https://motion.page/docs/sdk/duration-delay

import LivePreview from "../../components/docs/blocks/LivePreview";

`duration` and `delay` are the two core timing properties in every `AnimationConfig`. Duration controls how long the animation runs; delay controls when it starts.

## Duration

**`duration`** sets how many seconds the animation takes to complete. It accepts any positive number, including decimals.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `duration` | `number` | `0.5` | Seconds the animation takes to complete |

```typescript
import { Motion } from "@motion.page/sdk";

// 0.3s — fast UI interaction
Motion("quick-fade", ".button", {
  from: { opacity: 0 },
  duration: 0.3,
}).play();

// 1.2s — slower scroll reveal
Motion("slow-reveal", ".hero", {
  from: { opacity: 0, y: 60 },
  duration: 1.2,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Duration 0 — Instant Snap

Setting `duration: 0` makes the animation apply instantly with no transition. This is functionally equivalent to `Motion.set()`.

```typescript
// These two are equivalent
Motion("snap", ".box", {
  to: { opacity: 0 },
  duration: 0,
}).play();

Motion.set(".box", { opacity: 0 });
```

Prefer `Motion.set()` when the intent is clearly "apply immediately" — it's more readable. Use `duration: 0` when you want snap behaviour inside a multi-step timeline where other entries have duration.

## Delay

**`delay`** sets how many seconds to wait before the animation begins. The element holds its initial state during the delay period.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `delay` | `number` | `0` | Seconds to wait before the animation starts |

```typescript
Motion("delayed-entry", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  delay: 0.4,
  ease: "power2.out",
}).play();
```

## Combining Duration & Delay

Use both together to fine-tune when and how fast an animation runs:

```typescript
Motion("entrance", ".modal", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.5,
  delay: 0.2,
  ease: "power2.out",
}).onPageLoad();
```

<LivePreview client:load
  height={200}
  title="Duration & delay"
  html={`<div class="scene"><div class="box"></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("appear", ".box", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.5,
  delay: 0.2,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 1.8 },
}).play();`}
/>

## Delay with Stagger

When `stagger` is used, the per-element delay is added **on top of** the base `delay`. The first element starts at `delay`, the second at `delay + stagger`, the third at `delay + 2 × stagger`, and so on.

```typescript
// Element 1 starts at 0.3s
// Element 2 starts at 0.3 + 0.08 = 0.38s
// Element 3 starts at 0.3 + 0.16 = 0.46s
// …and so on
Motion("list-reveal", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  delay: 0.3,
  stagger: 0.08,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

`delay` is useful here as a **scene delay** — a buffer before the staggered sequence begins, so it doesn't fire the instant the trigger activates.

See [Stagger](/docs/sdk/stagger) for the full `StaggerVars` API and advanced ordering options.

## API Reference

```typescript
interface AnimationConfig {
  duration?: number;                       // Seconds — how long the animation runs
  delay?: number;                          // Seconds — how long to wait before starting
  stagger?: number | StaggerVars;          // Per-element delay, stacks on top of delay
  // ...other props
}
```

## Timing Tips

**UI interactions** (hovers, clicks, toggles) — `0.2–0.4s`. Fast enough to feel responsive, slow enough to be visible.

**Standard transitions** (modals, panels, toasts) — `0.4–0.6s`. Balanced and polished.

**Scroll reveals and entrance animations** — `0.6–1.2s`. Longer reads as deliberate and cinematic.

**Stagger increments** — `0.02–0.08s` per element. Below `0.02s` is imperceptible; above `0.12s` starts feeling slow for most lists.

## Common Mistakes

**Using milliseconds instead of seconds.** Duration is always in seconds. `duration: 500` means 500 seconds, not 500ms. Use `duration: 0.5` for half a second.

**Forgetting that delay stacks with stagger.** With `delay: 0.5` and `stagger: 0.1`, the last element in a 10-item list starts at `0.5 + 0.9 = 1.4s`. Factor this in when the animation needs to complete within a tight time window.

---

Related: [Easing](/docs/sdk/easing) · [Stagger](/docs/sdk/stagger) · [Core Concepts](/docs/sdk/core-concepts)

---

## Presentation Mode

> Build a gesture-driven section deck with the public SDK and understand the Builder-generated presentation output.

URL: https://motion.page/docs/sdk/presentation-mode

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

**Presentation Mode** is a Motion.page Builder feature that exports a section navigator composed from public SDK primitives. In hand-written SDK code, build the same experience with ordinary `Motion()` timelines, `Motion.set()`, and `.onGesture()`.

## Public SDK Boundary

The public `GestureConfig` does **not** include a `presentation` property. Its required fields are `types` and `events`; optional fields include `target`, `tolerance`, `dragMinimum`, `wheelSpeed`, `preventDefault`, `each`, and the other options documented in [Observer & Gesture](/docs/sdk/observer-gesture).

```typescript
// The navigator below patches this timeline's play() and reverse() methods.
Motion("deck-gesture").onGesture({
  target: ".deck",
  types: ["wheel", "touch", "pointer"],
  events: { Down: "play", Up: "reverse" },
  preventDefault: true,
});
```

The SDK generator has a separate internal `GestureOptions` type that temporarily adds `presentation`. The Builder stores its Presentation Mode controls there, then consumes them to generate normal SDK code. That generator-only metadata is never passed to `.onGesture()`.

---

## How Builder Output Works

The generated presentation script:

1. Queries the configured section selector and stacks every section absolutely.
2. Creates an independent timeline for each section's configured animations.
3. Tracks `currentIndex` and an `animating` guard inside `gotoSection(index, direction)`.
4. Builds reusable outgoing and incoming transition timelines.
5. Registers a public `.onGesture()` trigger whose `play` and `reverse` actions call `gotoSection()`.
6. Exposes the generated navigator on `window` for absolute-index navigation.

The emitted gesture wiring uses `play` and `reverse`. It does not use `playNext` or `playPrevious`, because those actions require SDK `each`-mode sibling instances; the generator manages its own section array instead.

<CodeBlock
  filename="generated-gesture-wiring.ts"
  lang="typescript"
  code={`const gesture = Motion("deck-gesture");

gesture.onGesture({
  types: ["wheel", "touch", "pointer"],
  events: { Down: "play", Up: "reverse" },
  preventDefault: true,
});

// The generated navigator owns currentIndex and gotoSection().
gesture.play = function () {
  gotoSection(currentIndex + 1, 1);
  return gesture;
};
gesture.reverse = function () {
  gotoSection(currentIndex - 1, -1);
  return gesture;
};`}
/>

---

## Complete Hand-Written Example

The preview below implements the same architecture directly with the public SDK. Scroll or drag inside it, or use the Previous and Next buttons.

<LivePreview client:visible
  height={360}
  title="Hand-written gesture-driven section deck"
  html={`<div class="deck">
  <section class="slide s1"><span>Section 1</span><small>Scroll or drag to navigate</small></section>
  <section class="slide s2"><span>Section 2</span><small>Built from public SDK methods</small></section>
  <section class="slide s3"><span>Section 3</span><small>No presentation config required</small></section>
  <nav class="deck-nav" aria-label="Section navigation">
    <button type="button" data-direction="previous">Previous</button>
    <button type="button" data-direction="next">Next</button>
  </nav>
</div>`}
  css={`.deck {
  position: relative;
  width: 100%;
  height: calc(100vh - 2rem);
  min-height: 280px;
  overflow: hidden;
  border-radius: 18px;
  font-family: system-ui, sans-serif;
}
.slide {
  position: absolute;
  inset: 0;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 8px;
  color: white;
}
.slide span { font-size: 26px; font-weight: 750; }
.slide small { color: rgba(255, 255, 255, 0.62); font-size: 12px; }
.s1 { background: linear-gradient(135deg, #1a0533, #6633ee); }
.s2 { background: linear-gradient(135deg, #071b32, #1266a8); }
.s3 { background: linear-gradient(135deg, #0a2616, #16844a); }
.deck-nav {
  position: absolute;
  z-index: 10;
  right: 18px;
  bottom: 18px;
  display: flex;
  gap: 8px;
}
.deck-nav button {
  padding: 7px 11px;
  border: 1px solid rgba(255, 255, 255, 0.24);
  border-radius: 8px;
  background: rgba(4, 6, 20, 0.32);
  color: white;
  font: 600 11px/1 system-ui;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const sections = Motion.utils.toArray(".slide");
let currentIndex = 0;
let animating = false;

sections.forEach((section, index) => {
  Motion.set(section, {
    opacity: index === 0 ? 1 : 0,
    visibility: index === 0 ? "visible" : "hidden",
    zIndex: index === 0 ? 1 : 0,
  });
});

function gotoSection(index, direction) {
  index = (index + sections.length) % sections.length;
  if (animating || index === currentIndex) return;
  animating = true;

  const outgoing = sections[currentIndex];
  const incoming = sections[index];
  Motion.get("deck-out")?.kill(false);
  Motion.get("deck-in")?.kill(false);

  Motion.set(outgoing, { zIndex: 1 });
  Motion.set(incoming, {
    opacity: 0,
    y: direction * 100 + "%",
    visibility: "visible",
    zIndex: 2,
  });

  Motion("deck-out", outgoing, {
    to: { opacity: 0, y: direction * -100 + "%" },
    duration: 0.65,
    ease: "power2.inOut",
  }).play();

  Motion("deck-in", incoming, {
    to: { opacity: 1, y: 0 },
    duration: 0.65,
    ease: "power2.inOut",
  }).onComplete(() => {
    Motion.set(outgoing, { visibility: "hidden", zIndex: 0 });
    Motion.set(incoming, { zIndex: 1 });
    setTimeout(() => { animating = false; }, 350);
  }).play();

  currentIndex = index;
}

const gesture = Motion("deck-gesture");
gesture.onGesture({
  target: ".deck",
  types: ["wheel", "touch", "pointer"],
  events: { Down: "play", Up: "reverse" },
  tolerance: 25,
  dragMinimum: 35,
  preventDefault: true,
});
gesture.play = function () { gotoSection(currentIndex + 1, 1); return gesture; };
gesture.reverse = function () { gotoSection(currentIndex - 1, -1); return gesture; };

document.querySelector('[data-direction="next"]').addEventListener("click", () => gesture.play());
document.querySelector('[data-direction="previous"]').addEventListener("click", () => gesture.reverse());`}
/>

---

## Builder Generator Settings

These settings belong to the Builder and SDK generator, **not** to public `GestureConfig`:

| Generator setting | Type | Default | Generated behavior |
|-------------------|------|---------|--------------------|
| `sectionSelector` | `string` | `'.section'` | Selects the sections to stack. The Builder derives it from the Observer target. |
| `direction` | `'vertical' \| 'horizontal'` | `'vertical'` | Selects the `y` or `x` transition axis. |
| `duration` | `number` | `1` | Sets each incoming/outgoing transition duration in seconds. The Builder constrains it to `0.1–5`. |
| `cooldown` | `number` | `0.5` | Keeps navigation locked for this many additional seconds after the transition. The Builder constrains it to `0.1–5`. |
| `effects` | `('opacity' \| 'translate')[]` | both | Chooses whether generated transitions fade, translate, or do both. |
| `infiniteRepeat` | `boolean` | `false` | Wraps out-of-range indices to the opposite end. |
| `reverseGesture` | `boolean` | `false` | Reverses the generated forward/backward event mapping. |
| `useVerticalWheel` | `boolean` | `false` | Adds `Down`/`Up` mappings to a horizontal deck. |
| `initialSection` | `number` | `0` | Chooses the initially visible zero-based section. This currently remains generator data rather than a visible Builder control. |

Do not copy these keys into `.onGesture()`. In hand-written code they become ordinary variables and branches inside your own navigator.

---

## Direction and Gesture Mapping

The Builder generator maps direction settings to public gesture events:

| Builder setting | Forward action | Backward action |
|-----------------|----------------|-----------------|
| Vertical | `Down → play` | `Up → reverse` |
| Horizontal | `Right → play` | `Left → reverse` |
| Horizontal + Vertical Wheel | Also `Down → play` | Also `Up → reverse` |

**Reverse Gesture** swaps every forward/backward pair. A hand-written implementation can use the same event map or choose its own.

---

## Transition Effects

The Builder's **Opacity** and **Translate** selections decide which properties the generator puts into its transition timelines:

| Builder selection | Outgoing section | Incoming section |
|-------------------|------------------|------------------|
| Opacity + Translate | Fades and moves off-screen | Fades and moves in from off-screen |
| Translate only | Moves off-screen | Moves in from off-screen |
| Opacity only | Fades out in place | Fades in place |

If no effects are selected in the Builder, the adapter restores both defaults. In hand-written SDK code, omit whichever properties you do not want to animate:

```typescript
// Fade-only transition inside your gotoSection() function
Motion.get("deck-out")?.kill(false);
Motion.get("deck-in")?.kill(false);
Motion.set(incoming, { opacity: 0, visibility: "visible" });

Motion("deck-out", outgoing, {
  to: { opacity: 0 },
  duration: 0.8,
}).play();

Motion("deck-in", incoming, {
  from: { opacity: 0 },
  to: { opacity: 1 },
  duration: 0.8,
}).play();
```

---

## Hand-Written Variants

### Horizontal Deck

Animate `x` instead of `y`, then map horizontal events. Add `Down` and `Up` only when you want a vertical mouse wheel to control the horizontal deck:

```typescript
gesture.onGesture({
  target: ".deck",
  types: ["wheel", "touch", "pointer"],
  events: {
    Right: "play",
    Left: "reverse",
    Down: "play",
    Up: "reverse",
  },
  preventDefault: true,
});
```

### Infinite Loop

Normalize the requested absolute index before checking it:

```typescript
index = ((index % sections.length) + sections.length) % sections.length;
```

Without that line, return early when `index < 0 || index >= sections.length`.

### Per-Section Animations

The Builder generator scopes each animation target to the current section. Reproduce that explicitly by resolving descendants from each section element:

<CodeBlock
  filename="per-section.ts"
  lang="typescript"
  code={`const sectionTimelines = sections.map((section, index) =>
  Motion("deck-section-" + index, section.querySelectorAll("[data-reveal]"), {
    from: { opacity: 0, y: 40 },
    duration: 0.7,
    stagger: 0.08,
    ease: "power2.out",
  })
);

// Inside gotoSection():
sectionTimelines[currentIndex]?.reverse();
sectionTimelines[index]?.play();`}
/>

When the configured animation target equals the section selector itself, the generator targets the section element directly. Otherwise it uses `section.querySelectorAll(animationTarget)`.

---

## Builder-Generated External Navigation

Generated presentation code exposes its navigator as `window.__mp_presentation_NAME`. This is a generator convenience, not a public SDK method. The name is derived from the Builder timeline name and sanitized for use as a property.

`gotoSection(index, direction)` expects an **absolute zero-based index** and a transition direction (`1` for forward, `-1` for backward):

```typescript
// Timeline name: "deck"
window.__mp_presentation_deck?.gotoSection(2, 1);
window.__mp_presentation_deck?.gotoSection(0, -1);
```

The function uses the same `animating` guard as gesture navigation, so calls made during the transition or cooldown are ignored. It is not a relative next/previous API.

---

## Builder Usage

In the Motion.page Builder, open **Left Panel → Trigger → Observer**, enable **Trigger each iteration individually**, then enable **Presentation mode (full page sections)**. The first toggle is a UI prerequisite that reveals Presentation Mode; generated `.onGesture()` code still uses the generator-owned section array rather than public `each` mode.

| Builder control | What the generator changes |
|-----------------|----------------------------|
| Presentation Mode | Selects the standalone section-navigator generator path. |
| Observer target | Becomes the section selector. |
| Direction | Chooses `x` or `y` transitions and directional event mappings. |
| Transition Duration | Sets incoming and outgoing timeline durations. |
| Gesture Cooldown | Extends the navigation lock after each transition. |
| Effects | Includes opacity, translation, or both in generated timelines. |
| Infinite Repeat | Enables modulo wrapping. |
| Reverse Gesture | Swaps forward and backward event mappings. |
| Trigger on Vertical Scroll | Adds vertical-wheel mappings in horizontal mode. |

---

## Tips and Gotchas

**Give the container an explicit height.** Generated sections use absolute positioning with `width: 100%` and `height: 100%`; their containing block must establish a height, commonly `100vh`.

**Cooldown starts after the transition.** Navigation remains locked for the transition duration and then for the configured cooldown.

**Builder timing settings are generator metadata.** `duration` and `cooldown` here are not fields on public `GestureConfig`; public `stopDelay` is a separate gesture option.

**Vertical wheel mapping is horizontal-only.** A vertical deck already maps `Down` and `Up`.

**Clean up hand-written decks explicitly.** Kill the transition, section, and gesture timelines and restore the inline section styles when unmounting a component or leaving an SPA route.

---

## Related

- [Observer & Gesture](/docs/sdk/observer-gesture) — public `GestureConfig` and gesture actions
- [Timeline Control](/docs/sdk/timeline-control) — manually play and reverse section timelines
- [SPA Integration](/docs/sdk/spa-integration) — scope and clean up hand-written navigators
- [Presentation Mode — Builder](/docs/builder/presentation-mode) — configure the generator visually

---

## Advanced Targeting

> Target specific pages with post types, custom RegEx URL patterns, and selector strategies.

URL: https://motion.page/docs/sdk/advanced-targeting

import LivePreview from "../../components/docs/blocks/LivePreview";

Targeting controls **which elements** animate and **which pages** an animation runs on. This page covers compound CSS selectors, scoped targeting, dynamic elements, URL-based page matching, and WordPress post type targeting.

---

## CSS Selector Strategies

The SDK accepts any valid CSS selector string as a `TargetInput`. Complex selectors let you target elements precisely without adding extra classes to your HTML.

### Compound Selectors

Combine multiple selector rules to narrow the target:

```typescript
import { Motion } from "@motion.page/sdk";

// Elements that have BOTH classes
Motion("combined", ".card.featured", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
}).onPageLoad();

// Direct children only
Motion("children", ".menu > .menu-item", {
  from: { x: -20, opacity: 0 },
  stagger: 0.06,
  duration: 0.4,
}).onPageLoad();

// Adjacent sibling
Motion("sibling", ".hero + .intro", {
  from: { opacity: 0 },
  duration: 0.8,
}).onPageLoad();
```

<LivePreview client:visible
  height={360}
  title="Compound selector targeting"
  html={`<div class="selector-demo">
  <div class="demo-row">
    <code>.card.featured</code>
    <div class="targets">
      <div class="card">card</div>
      <div class="card featured">card featured</div>
    </div>
  </div>
  <div class="demo-row">
    <code>.menu &gt; .menu-item</code>
    <div class="menu targets">
      <div class="menu-item">direct child</div>
      <div class="menu-group"><div class="menu-item">nested child</div></div>
    </div>
  </div>
  <div class="demo-row">
    <code>.hero + .intro</code>
    <div class="sequence targets">
      <div class="hero">hero</div>
      <div class="intro">adjacent intro</div>
      <div class="gap">gap</div>
      <div class="intro">other intro</div>
    </div>
  </div>
</div>`}
  css={`.selector-demo {
  width: min(620px, 100%);
  display: grid;
  gap: 12px;
}
.demo-row {
  display: grid;
  grid-template-columns: 150px 1fr;
  align-items: center;
  gap: 16px;
  padding: 14px;
  border: 1px solid rgba(153, 102, 255, 0.25);
  border-radius: 14px;
  background: rgba(255, 255, 255, 0.035);
}
code { color: #bda9ff; font-size: 12px; }
.targets { display: flex; align-items: center; gap: 8px; min-width: 0; }
.card, .menu-item, .hero, .intro, .gap {
  padding: 9px 11px;
  border: 1px solid rgba(255, 255, 255, 0.14);
  border-radius: 9px;
  background: #171b33;
  color: #dfe1f4;
  font-size: 11px;
  white-space: nowrap;
}
.featured { border-color: #8f6cff; }
.menu-group {
  padding: 5px;
  border: 1px dashed rgba(255, 255, 255, 0.18);
  border-radius: 11px;
}
.sequence { gap: 5px; }
.sequence > * { padding-inline: 8px; }
.gap { color: #7b819e; border-style: dashed; }
@media (max-width: 520px) {
  .demo-row { grid-template-columns: 112px 1fr; gap: 10px; padding: 11px; }
  .targets { flex-wrap: wrap; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("compound-selector-demo", ".card.featured", {
  to: { scale: 1.08, backgroundColor: "#6f4ee8" },
  duration: 0.55,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("direct-child-demo", ".menu > .menu-item", {
  from: { opacity: 0.3, x: -18 },
  duration: 0.55,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("adjacent-sibling-demo", ".hero + .intro", {
  from: { opacity: 0.3, y: 12 },
  duration: 0.55,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

### `:nth-child` and Structural Selectors

Target elements by their position in the DOM:

```typescript
// Every other card — skip the first
Motion("even-cards", ".grid .card:nth-child(even)", {
  from: { y: 40, opacity: 0 },
  duration: 0.5,
  stagger: 0.07,
}).onScroll({ each: true });

// First three items only
Motion("first-three", ".list-item:nth-child(-n+3)", {
  from: { opacity: 0, x: -20 },
  duration: 0.5,
  stagger: 0.08,
}).onPageLoad();

// Last item in a group
Motion("last-item", ".nav-item:last-child", {
  to: { color: "#9966FF" },
  duration: 0.3,
}).onHover({ onLeave: "reverse" });
```

### Data Attribute Selectors

Target elements by their HTML data attributes — useful when you control the markup but not the class names:

```typescript
// Any element with the attribute present
Motion("data-reveal", "[data-animate]", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.06,
}).onScroll({ each: true });

// Attribute with a specific value
Motion("data-hero", "[data-role='hero']", {
  from: { scale: 0.95, opacity: 0 },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();

// Attribute starting with a prefix — useful for BEM modifiers
Motion("data-prefix", "[data-speed^='fast']", {
  from: { y: 30, opacity: 0 },
  duration: 0.3,
}).onPageLoad();
```

### Selector Arrays

Pass multiple selectors to animate them as one group:

```typescript
// All three animate together as a single timeline
Motion("multi", ["h1", ".subtitle", ".cta-button"], {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.1,
}).onPageLoad();
```

---

## Scoped Targeting

`Motion.utils.toArray(target, scope)` resolves a selector only within a specific container. Use this when your page has repeated components with identical class names and you need to target only the one inside a certain parent.

```typescript
import { Motion } from "@motion.page/sdk";

// Resolve .card only inside #featured-section
const cards = Motion.utils.toArray(".card", "#featured-section");

Motion("scoped-cards", cards, {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
}).onPageLoad();
```

This prevents animations from leaking into other sections that share the same class names.

### Scoping with Refs (React)

In React, pass the ref element as the scope to avoid stale global selectors:

```tsx
import { useEffect, useRef } from "react";
import { Motion } from "@motion.page/sdk";

export function ProductGrid() {
  const gridRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!gridRef.current) return;

    const cards = Motion.utils.toArray(".card", gridRef.current);

    Motion("grid-reveal", cards, {
      from: { opacity: 0, y: 24 },
      duration: 0.5,
      stagger: 0.07,
      ease: "power2.out",
    }).onScroll({ each: true });

    return () => Motion.kill("grid-reveal");
  }, []);

  return (
    <div ref={gridRef} className="product-grid">
      {/* cards rendered here */}
    </div>
  );
}
```

---

## Dynamic Element Targeting

Elements added after the page loads — via AJAX, pagination, or framework rendering — won't be found by selectors that ran at init time. Use `Motion.context()` to scope animations so they can be reinitialized cleanly when the DOM changes.

### Motion.context() for Reinit

```typescript
import { Motion } from "@motion.page/sdk";

let ctx = Motion.context(() => {
  Motion("cards", ".card", {
    from: { opacity: 0, y: 30 },
    duration: 0.5,
    stagger: 0.07,
  }).onScroll({ each: true });
});

// After AJAX inserts new .card elements:
ctx.refresh(); // kills old animations, re-runs init, re-resolves .card
```

`ctx.refresh()` destroys the previous timelines and re-runs the factory function. All selectors are evaluated again against the updated DOM.

### MutationObserver Pattern

Use a `MutationObserver` to detect when new elements appear and reinitialize:

```typescript
import { Motion } from "@motion.page/sdk";

let ctx = Motion.context(() => {
  Motion("dynamic-items", "[data-animate]", {
    from: { opacity: 0, y: 20 },
    duration: 0.4,
    stagger: 0.06,
  }).onPageLoad();
});

const observer = new MutationObserver(() => {
  ctx.refresh();
});

// Watch for added nodes anywhere in the list container
observer.observe(document.querySelector("#results-list")!, {
  childList: true,
  subtree: true,
});

// Clean up when the page unloads
window.addEventListener("pagehide", () => {
  observer.disconnect();
  ctx.revert();
});
```

> **Performance tip:** Debounce the observer callback if the DOM updates frequently in rapid bursts. Call `ctx.refresh()` once after the burst settles rather than on every mutation.

### Debounced Observer

```typescript
import { Motion } from "@motion.page/sdk";

let ctx = Motion.context(() => {
  Motion("feed-items", ".feed-item", {
    from: { opacity: 0, y: 16 },
    duration: 0.35,
    stagger: 0.05,
  }).onPageLoad();
});

let debounceTimer: ReturnType<typeof setTimeout>;

const observer = new MutationObserver(() => {
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(() => ctx.refresh(), 150);
});

observer.observe(document.querySelector("#feed")!, {
  childList: true,
  subtree: true,
});
```

See [SPA Integration](/docs/sdk/spa-integration) for framework-specific lifecycle patterns.

---

## Page-Specific Targeting (URL Matching)

Run an animation only on pages whose URL matches a pattern. Check `window.location` before registering the timeline.

### Exact Path Match

```typescript
import { Motion } from "@motion.page/sdk";

if (window.location.pathname === "/about") {
  Motion("about-hero", ".hero-title", {
    from: { opacity: 0, y: 40 },
    duration: 0.8,
    ease: "power3.out",
  }).onPageLoad();
}
```

### RegEx URL Patterns

Use `RegExp.test()` to match URL patterns — slug fragments, query strings, or path segments:

```typescript
import { Motion } from "@motion.page/sdk";

// Any URL containing "blog"
if (/blog/.test(window.location.pathname)) {
  Motion("blog-reveal", ".post-card", {
    from: { opacity: 0, y: 24 },
    duration: 0.5,
    stagger: 0.08,
  }).onScroll({ each: true });
}

// Case-insensitive match — product pages
if (/\/products?\//i.test(window.location.pathname)) {
  Motion("product-fade", ".product-image", {
    from: { scale: 0.97, opacity: 0 },
    duration: 0.6,
    ease: "power2.out",
  }).onScroll({ each: true });
}

// Homepage only (root path)
if (/^\/$/.test(window.location.pathname)) {
  Motion("home-hero", "#hero", {
    from: { opacity: 0, y: 60 },
    duration: 1,
    ease: "power3.out",
  }).onPageLoad();
}
```

### Multiple Page Conditions

```typescript
import { Motion } from "@motion.page/sdk";

const path = window.location.pathname;
const isLanding = /^\/(home|landing|index)/.test(path);
const isProduct = /\/product\//.test(path);

if (isLanding || isProduct) {
  Motion("conversion-cta", ".cta-block", {
    from: { opacity: 0, scale: 0.96 },
    duration: 0.7,
    ease: "back.out",
  }).onScroll({ toggleActions: "play none none none" });
}
```

---

## WordPress: Post Type Targeting

In the **Motion.page Builder**, the **Advanced Targeting** panel lets you restrict a timeline to specific WordPress post types, template pages, or URL patterns — without writing any code.

### How It Works

Open the **Advanced Targeting** panel in the Left Panel under the timeline name. Use the dropdown to select:

| Option | What it matches |
|--------|-----------------|
| Post type slug (e.g. `post`, `page`, `product`) | All posts of that type |
| `$search` | The WordPress search results page |
| `$404` | The 404 error page |
| Custom RegEx string | Any URL matching the pattern |

Selected post types are stored per timeline and evaluated at runtime — the animation only loads on matching pages.

### RegEx in the Builder

The Advanced Targeting input also accepts custom **RegEx strings**. Enter the pattern without delimiters — the Builder wraps it automatically:

| Input | Matches |
|-------|---------|
| `about` | Any URL containing "about" |
| `\/shop\/.*\/review` | URLs like `/shop/product-name/review` |
| `\?ref=email` | URLs with the `?ref=email` query parameter |

**Rules:**
- Delimiters (`/…/`) are added automatically — do not include them.
- The only supported flag is `i` (case-insensitive). Add it manually if needed.
- Escape special regex characters with `\` — e.g. use `\.` to match a literal dot.

> **Example:** To match all pages with the slug `services` or `service`, enter `services?` — the `?` makes the trailing `s` optional.

### WordPress Code Equivalent

If you're using the SDK directly in a WordPress theme, replicate the same logic with `window.location`:

```typescript
import { Motion } from "@motion.page/sdk";

// Equivalent to targeting the "product" post type
// WordPress adds the slug in the URL — match accordingly
if (/\/product\//.test(window.location.pathname)) {
  Motion("product-reveal", ".entry-content", {
    from: { opacity: 0, y: 20 },
    duration: 0.6,
    ease: "power2.out",
  }).onPageLoad();
}
```

For the full WordPress plugin targeting workflow, see the Builder documentation.

---

## Tips and Gotchas

**Selectors resolve at registration time.** If elements don't exist yet when `Motion()` is called, the timeline targets zero elements. Use `Motion.context()` with `ctx.refresh()` for late-rendered content.

**`each: true` is per-element, not per-page.** The `each` option on triggers creates independent timeline instances for each matched element. It is separate from page-level URL targeting.

**Compound selectors with stagger.** When using stagger across a compound selector, all matched elements animate in DOM order regardless of which sub-selector found them:

```typescript
// All .card and .featured-card elements, staggered together in DOM order
Motion("mixed", [".card", ".featured-card"], {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.06,
}).onPageLoad();
```

**Scoping prevents bleed.** Always use `Motion.utils.toArray(selector, scope)` when the same component renders multiple times on one page. Without a scope, `.card` matches every `.card` on the page.

---

## Related

- [Motion() Factory](/docs/sdk/motion-factory) — `TargetInput` types and `Motion.utils.toArray()`
- [Scroll Trigger](/docs/sdk/scroll-trigger) — `each: true` for per-element scroll instances
- [SPA Integration](/docs/sdk/spa-integration) — `Motion.context()` for framework lifecycle management
- [Responsive Animations](/docs/sdk/responsive) — `matchMedia` for screen-size targeting

---

## Transform Origin

> Set the origin point for scale, rotation, and transform animations.

URL: https://motion.page/docs/sdk/transform-origin

import LivePreview from "../../components/docs/blocks/LivePreview";

**Transform origin** is the pivot point around which `scale`, `rotate`, `skew`, and other transform animations occur. By default every element transforms from its center (`50% 50%`), but you can move that anchor to any corner, edge, or custom position.

## Basic Usage

Pass `transformOrigin` as a string inside `from` or `to`. It can be set on either endpoint or on both — the origin applies for the duration of the animation.

```typescript
import { Motion } from "@motion.page/sdk";

// Rotate around the top-center (pendulum effect)
Motion("pendulum", ".arm", {
  from: { rotate: -30, transformOrigin: "50% 0%" },
  to: { rotate: 30 },
  duration: 1,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

## Accepted Values

`transformOrigin` accepts the same syntax as the CSS `transform-origin` property.

| Format | Example | Description |
|--------|---------|-------------|
| Keywords | `"center"` | Center of the element (same as `"50% 50%"`) |
| Two keywords | `"top left"` | Top-left corner (`"0% 0%"`) |
| Percentages | `"50% 100%"` | Bottom-center |
| Pixels | `"0px 0px"` | Exact pixel coordinates |
| Mixed | `"20px 80%"` | Pixel X, percentage Y |

### Keyword Reference

| Keyword | Equivalent |
|---------|-----------|
| `"top left"` | `"0% 0%"` |
| `"top center"` | `"50% 0%"` |
| `"top right"` | `"100% 0%"` |
| `"center left"` | `"0% 50%"` |
| `"center"` | `"50% 50%"` |
| `"center right"` | `"100% 50%"` |
| `"bottom left"` | `"0% 100%"` |
| `"bottom center"` | `"50% 100%"` |
| `"bottom right"` | `"100% 100%"` |

## Effect on Different Transforms

### Rotation

The element pivots around the origin point. Moving the origin to a corner or edge produces a hinge or pendulum effect.

```typescript
// Hinge from top-left corner
Motion("hinge", ".door", {
  from: { rotate: 0, transformOrigin: "0% 50%" },
  to: { rotate: 90 },
  duration: 0.6,
  ease: "power2.inOut",
}).onClick({ each: true });
```

### Scale

The element grows or shrinks toward the origin point. A corner origin makes the element appear to emerge from that corner rather than its center.

```typescript
// Grow from the bottom-left corner
Motion("corner-pop", ".card", {
  from: { scale: 0, transformOrigin: "0% 100%" },
  duration: 0.5,
  ease: "back.out(1.7)",
}).onPageLoad();
```

### Skew

The shear distortion anchors at the origin, which controls which point of the element stays fixed as the rest of it tilts.

```typescript
// Skew with bottom anchored
Motion("tilt", ".panel", {
  from: { skewX: 15, opacity: 0, transformOrigin: "50% 100%" },
  duration: 0.55,
  ease: "power3.out",
}).onPageLoad();
```

<LivePreview client:load
  height={260}
  title="Transform origin comparison"
  html={`<div class="scene">
  <div class="label">Center (default)</div>
  <div class="box center"></div>
  <div class="label">Bottom left</div>
  <div class="box corner"></div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: flex-start; gap: 4px; padding: 20px 32px; height: 100%; box-sizing: border-box; justify-content: center; }
.label { font: 11px/1 monospace; color: #999; margin-bottom: 2px; }
.box { width: 60px; height: 60px; background: #6633EE; border-radius: 8px; margin-bottom: 12px; }
.box:last-child { margin-bottom: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("center-scale", ".box.center", {
  from: { scale: 0, transformOrigin: "50% 50%" },
  duration: 0.6,
  ease: "back.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("corner-scale", ".box.corner", {
  from: { scale: 0, transformOrigin: "0% 100%" },
  duration: 0.6,
  ease: "back.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Common Patterns

### Corner Pop

Scale an element in from one of its corners — a classic way to make cards, tooltips, or dropdowns feel anchored to a fixed point.

```typescript
// Dropdown opening from its top-left corner
Motion("dropdown", ".dropdown-menu", {
  from: { scale: 0.8, opacity: 0, transformOrigin: "0% 0%" },
  duration: 0.25,
  ease: "power2.out",
}).onClick({ each: true });
```

### Pendulum Swing

Set the origin to the top-center so the element rotates like a pendulum hanging from that point.

```typescript
Motion("swing", ".pendulum", {
  from: { rotate: -25, transformOrigin: "50% 0%" },
  to: { rotate: 25 },
  duration: 1.4,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

### Grow from Bottom

Reveal bar charts, progress indicators, or loaders that rise from the bottom edge.

```typescript
Motion("bar-reveal", ".bar", {
  from: { scaleY: 0, transformOrigin: "50% 100%" },
  duration: 0.7,
  ease: "power3.out",
  stagger: 0.08,
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Click-to-Fold Toggle

Use an edge-anchored origin with `onClick` to make an element fold open and shut like a flap.

```typescript
Motion("flap", ".flap", {
  to: { rotateX: 90, transformOrigin: "50% 0%" },
  duration: 0.35,
  ease: "power2.inOut",
}).onClick({ each: true, onLeave: "reverse" });
```

## Notes

- `transformOrigin` is not animated between `from` and `to` — it sets a fixed anchor for the entire animation. Place it in either endpoint; the value is applied before the tween begins.
- The default is `"50% 50%"` (element center). You only need to set it when you want a non-center pivot.
- Pixel values are relative to the element's top-left corner, not the page.
- For transforms applied across a multi-step timeline, set `transformOrigin` in the first step that needs the custom anchor.

See [Scale](/docs/sdk/scale), [Skew](/docs/sdk/skew), and [Rotation](/docs/sdk/rotation) for the transform properties that `transformOrigin` affects.

---

## Stagger

> Animate multiple targets in sequence with configurable delay, direction, and grid patterns.

URL: https://motion.page/docs/sdk/stagger

import LivePreview from "../../components/docs/blocks/LivePreview";

`stagger` adds a per-element delay offset when animating multiple targets. Instead of all elements moving at once, each one starts slightly after the previous — creating a cascade effect.

## Basic Stagger

Pass a number directly to `stagger`. Each element waits that many seconds more than the one before it.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("list", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.08,
  ease: "power2.out",
}).onPageLoad();
```

Element 1 starts at `0s`, element 2 at `0.08s`, element 3 at `0.16s`, and so on.

<LivePreview client:load
  height={240}
  title="Staggered list reveal"
  html={`<div class="list">
  <div class="item">Item one</div>
  <div class="item">Item two</div>
  <div class="item">Item three</div>
  <div class="item">Item four</div>
  <div class="item">Item five</div>
</div>`}
  css={`.list { display: flex; flex-direction: column; gap: 10px; padding: 20px; }
.item { background: #6633EE; color: white; font-family: sans-serif; font-size: 14px; font-weight: 600; padding: 12px 20px; border-radius: 8px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("list-in", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.08,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## StaggerVars Object

For full control, pass an object instead of a number. The shorthand `stagger: 0.08` is equivalent to `stagger: { each: 0.08, from: 'start' }`.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `each` | `number` | — | Seconds between each element |
| `amount` | `number` | — | Total spread across all elements (alternative to `each`) |
| `from` | `string \| number` | `'start'` | Direction or origin of the stagger |
| `grid` | `'auto' \| [number, number]` | — | Enable 2D grid staggering |
| `axis` | `'x' \| 'y'` | — | Axis to measure distance for grid stagger |
| `ease` | `string` | `'none'` | Easing for stagger delay distribution |

### `each` vs `amount`

Use `each` when you care about the gap between adjacent elements. Use `amount` when you care about the total time the full stagger takes regardless of element count.

```typescript
// Always 0.1s between each element — total time grows with more elements
stagger: { each: 0.1 }

// Always 1s total spread — 10 elements = 0.1s each, 20 elements = 0.05s each
stagger: { amount: 1 }
```

## `from` — Stagger Origin

`from` controls which element starts first and how the cascade radiates outward.

| Value | Description |
|-------|-------------|
| `'start'` | First element leads (default) |
| `'end'` | Last element leads — sequence runs in reverse |
| `'center'` | Middle element leads, radiates outward |
| `'edges'` | Both ends lead simultaneously, meet in the middle |
| `'random'` | Random order on every play |
| `number` | A specific element index leads (0-based) — e.g. `from: 2` starts from the third element |

```typescript
// Default — first to last
Motion("list-start", ".item", {
  from: { opacity: 0, y: 16 },
  duration: 0.5,
  stagger: { each: 0.07, from: "start" },
  ease: "power2.out",
}).onPageLoad();

// Reverse — last to first
Motion("list-end", ".item", {
  from: { opacity: 0, y: 16 },
  duration: 0.5,
  stagger: { each: 0.07, from: "end" },
  ease: "power2.out",
}).onPageLoad();

// Center outward — good for symmetrical layouts
Motion("list-center", ".item", {
  from: { opacity: 0, scale: 0.8 },
  duration: 0.4,
  stagger: { each: 0.06, from: "center" },
  ease: "back.out",
}).onPageLoad();

// Edges inward — both sides converge to the middle
Motion("list-edges", ".item", {
  from: { opacity: 0 },
  duration: 0.4,
  stagger: { each: 0.06, from: "edges" },
}).onPageLoad();

// Random — each play has a different order
Motion("list-random", ".item", {
  from: { opacity: 0, scale: 0.9 },
  duration: 0.4,
  stagger: { each: 0.05, from: "random" },
}).onPageLoad();

// Specific index — ripple from the third card
Motion("list-from-index", ".card", {
  from: { opacity: 0, scale: 0.85 },
  duration: 0.5,
  stagger: { each: 0.06, from: 2 },
  ease: "power2.out",
}).onClick({ each: true });
```

## `ease` — Stagger Distribution

`ease` controls how the delay offsets are **distributed** across elements — not the easing of the animation itself. Without it, delays are evenly spaced. With it, elements bunch up at the start, end, or middle of the sequence.

```typescript
// Delays accelerate — early elements are close together, later ones spread out
Motion("ease-in-stagger", ".dot", {
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: { each: 0.08, ease: "power2.in" },
}).onPageLoad();

// Delays decelerate — quick burst at the start, trailing off
Motion("ease-out-stagger", ".dot", {
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: { each: 0.08, ease: "power2.out" },
}).onPageLoad();
```

## `grid` — 2D Stagger Patterns

Grid stagger measures the 2D distance from the origin element, creating ripple or wave effects across rows and columns.

Set `grid: 'auto'` and the SDK infers the grid dimensions from the layout of elements in the DOM. For irregular or custom grids, pass explicit `[rows, columns]`.

```typescript
// Ripple from center of a CSS grid
Motion("grid-ripple", ".cell", {
  from: { opacity: 0, scale: 0.6 },
  duration: 0.4,
  stagger: {
    each: 0.04,
    from: "center",
    grid: "auto",
  },
  ease: "power2.out",
}).onPageLoad();

// Explicit 3×4 grid, wave from top-left
Motion("grid-wave", ".tile", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: {
    each: 0.05,
    from: "start",
    grid: [3, 4],
  },
  ease: "power2.out",
}).onPageLoad();
```

### `axis` — Directional Grid Waves

Combine `grid` with `axis` to constrain stagger distance to a single axis — producing row-by-row or column-by-column waves instead of true radial ripples.

```typescript
// Animate row by row (top to bottom)
Motion("row-wave", ".cell", {
  from: { opacity: 0, y: 12 },
  duration: 0.4,
  stagger: {
    each: 0.05,
    grid: "auto",
    axis: "y",
  },
  ease: "power2.out",
}).onPageLoad();

// Animate column by column (left to right)
Motion("col-wave", ".cell", {
  from: { opacity: 0, x: 12 },
  duration: 0.4,
  stagger: {
    each: 0.05,
    grid: "auto",
    axis: "x",
  },
  ease: "power2.out",
}).onPageLoad();
```

## Common Patterns

### Staggered Scroll Reveal

```typescript
Motion("cards", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: 0.1,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Text Reveal with Stagger

Split text into words or characters and stagger them for a dramatic entrance.

```typescript
Motion("headline", "h1", {
  split: "words",
  mask: true,
  from: { y: "110%" },
  duration: 0.6,
  stagger: { each: 0.06, from: "start" },
  ease: "power3.out",
}).onPageLoad();
```

See [Text Splitter](/docs/sdk/split-text) for the full text-splitting API.

### Grid Ripple on Hover

```typescript
Motion("grid-hover", ".cell", {
  to: { scale: 1.1, backgroundColor: "#6633EE" },
  duration: 0.3,
  stagger: {
    each: 0.03,
    from: "center",
    grid: "auto",
  },
  ease: "power2.out",
}).onHover({ onLeave: "reverse" });
```

### Scene Delay + Stagger

Add a base `delay` to pause before the staggered sequence begins. The stagger offsets stack on top.

```typescript
// Element 1 starts at 0.3s
// Element 2 starts at 0.38s
// Element 3 starts at 0.46s
Motion("delayed-list", ".item", {
  from: { opacity: 0, x: -20 },
  duration: 0.5,
  delay: 0.3,
  stagger: 0.08,
  ease: "power2.out",
}).onPageLoad();
```

See [Duration & Delay](/docs/sdk/duration-delay) for how `delay` and `stagger` interact.

## API Reference

```typescript
// Shorthand — seconds between each element
stagger?: number

// Full object
interface StaggerVars {
  each?:   number;                                              // Seconds between each element
  amount?: number;                                              // Total spread across all elements
  from?:   'start' | 'end' | 'center' | 'edges' | 'random' | number;
  grid?:   'auto' | [number, number];                          // 2D grid stagger
  axis?:   'x' | 'y';                                         // Grid stagger axis
  ease?:   string;                                              // Easing for delay distribution
}
```

---

Related: [Duration & Delay](/docs/sdk/duration-delay) · [Text Splitter](/docs/sdk/split-text) · [Easing](/docs/sdk/easing)

---

## SPA Integration

> Use the SDK with React, Vue, Next.js, and Astro — cleanup, page transitions, lifecycle.

URL: https://motion.page/docs/sdk/spa-integration

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The SDK is client-side JavaScript — it must run in the browser and always requires cleanup when components unmount or routes change. Each framework has its own lifecycle hooks for this.

---

## React

Use `useEffect` to create animations after mount and return a cleanup function that kills them on unmount. Target elements with `useRef` to avoid stale selectors.

<CodeBlock filename="FadeCard.tsx">
```tsx
import { useEffect, useRef } from "react";
import { Motion } from "@motion.page/sdk";

export function FadeCard() {
  const cardRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!cardRef.current) return;

    Motion("fade-card", cardRef.current, {
      from: { opacity: 0, y: 24 },
      duration: 0.5,
      ease: "power2.out",
    }).onPageLoad();

    return () => {
      Motion.kill("fade-card");
    };
  }, []);

  return <div ref={cardRef}>Hello</div>;
}
```
</CodeBlock>

Use `Motion.kill(name)` to remove a specific timeline, or `Motion.killAll()` to clear every timeline registered on the page.

### Shared cleanup hook

Extract cleanup into a reusable hook when multiple components need the same pattern:

<CodeBlock filename="useMotion.ts">
```ts
import { useEffect } from "react";
import { Motion } from "@motion.page/sdk";

export function useMotion(setup: () => void, deps: React.DependencyList = []) {
  useEffect(() => {
    setup();
    return () => Motion.killAll();
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);
}
```
</CodeBlock>

### Scroll triggers after dynamic content

If your component renders a list from async data, call `Motion.refreshScrollTriggers()` after the data loads so scroll positions are recalculated:

```tsx
useEffect(() => {
  if (!items.length) return;

  Motion("list-reveal", ".list-item", {
    from: { opacity: 0, y: 20 },
    duration: 0.4,
    stagger: 0.08,
  }).onScroll({ each: true });

  Motion.refreshScrollTriggers();

  return () => Motion.kill("list-reveal");
}, [items]);
```

---

## Vue

Use `onMounted` and `onUnmounted` to manage the animation lifecycle. Access elements with `ref` template refs.

<CodeBlock filename="FadeCard.vue">
```vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from "vue";
import { Motion } from "@motion.page/sdk";

const card = ref<HTMLElement | null>(null);

onMounted(() => {
  if (!card.value) return;

  Motion("fade-card", card.value, {
    from: { opacity: 0, y: 24 },
    duration: 0.5,
    ease: "power2.out",
  }).onPageLoad();
});

onUnmounted(() => {
  Motion.kill("fade-card");
});
</script>

<template>
  <div ref="card">Hello</div>
</template>
```
</CodeBlock>

### Vue Router page transitions

Kill all timelines on route leave so animations don't leak between pages:

```ts
// router/index.ts
import { Motion } from "@motion.page/sdk";

router.afterEach(() => {
  Motion.killAll();
});
```

---

## Next.js

The SDK is **client-side only** — it cannot run in Server Components. Any file that imports `Motion` must be a Client Component.

### App Router

Add `"use client"` at the top of any component that uses the SDK:

<CodeBlock filename="HeroSection.tsx">
```tsx
"use client";

import { useEffect } from "react";
import { Motion } from "@motion.page/sdk";

export function HeroSection() {
  useEffect(() => {
    Motion("hero-fade", "#hero-heading", {
      from: { opacity: 0, y: 32 },
      duration: 0.7,
      ease: "power3.out",
    }).onPageLoad();

    return () => Motion.kill("hero-fade");
  }, []);

  return <h1 id="hero-heading">Welcome</h1>;
}
```
</CodeBlock>

### Page transitions with App Router

Next.js App Router navigations unmount the previous page tree. The `useEffect` cleanup above handles this automatically — no extra route-change listener needed.

For shared layout components that persist across navigations (e.g. a nav bar), use `pathname` as a dependency to reinitialise:

```tsx
"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import { Motion } from "@motion.page/sdk";

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();

  useEffect(() => {
    Motion("page-in", "main", {
      from: { opacity: 0 },
      duration: 0.35,
    }).onPageLoad();

    return () => Motion.kill("page-in");
  }, [pathname]);

  return <>{children}</>;
}
```

---

## Astro

Add `client:load` to any Astro component that uses the SDK so it hydrates in the browser. Pure `.astro` files can run the SDK in an inline `<script>` tag.

### Inline script

```astro
---
// HeroSection.astro
---

<section id="hero">
  <h1 class="hero-heading">Welcome</h1>
</section>

<script>
  import { Motion } from "@motion.page/sdk";

  Motion("hero-fade", ".hero-heading", {
    from: { opacity: 0, y: 32 },
    duration: 0.7,
    ease: "power3.out",
  }).onPageLoad();
</script>
```

### View Transitions API

Astro's View Transitions dispatch `astro:page-load` and `astro:before-swap` events. Kill animations before the swap and re-initialise on each new page load:

```astro
<script>
  import { Motion } from "@motion.page/sdk";

  function initAnimations() {
    Motion("page-reveal", ".animate-in", {
      from: { opacity: 0, y: 20 },
      duration: 0.5,
      stagger: 0.1,
    }).onPageLoad();
  }

  // Initial load
  initAnimations();

  // Re-run after each View Transition navigation
  document.addEventListener("astro:page-load", () => {
    initAnimations();
  });

  // Clean up before the DOM is swapped out
  document.addEventListener("astro:before-swap", () => {
    Motion.killAll();
  });
</script>
```

---

## Cleanup reference

| Method | When to use |
|--------|-------------|
| `Motion.kill("name")` | Remove one specific timeline by name |
| `Motion.killAll()` | Remove all timelines — use on route change or full page teardown |
| `Motion.refreshScrollTriggers()` | Recalculate scroll positions after dynamic content renders |
| `Motion.context(() => { ... })` | Scope multiple timelines so they can all be torn down together |

### Motion.context

`Motion.context` is useful when a component creates several timelines and you want a single cleanup call:

```ts
import { Motion } from "@motion.page/sdk";

const ctx = Motion.context(() => {
  Motion("nav-fade", ".nav-item", {
    from: { opacity: 0, x: -12 },
    stagger: 0.06,
    duration: 0.4,
  }).onPageLoad();

  Motion("nav-underline", ".nav-link", {
    to: { scaleX: 1 },
    duration: 0.25,
  }).onHover({ onLeave: "reverse" });
});

// On cleanup — kills both timelines
ctx.revert();
```

---

## Related

- [Timeline Control](/docs/sdk/timeline-control) — `Motion.get()`, `Motion.has()`, manual play/pause
- [Page Load](/docs/sdk/page-load) — `.onPageLoad()` trigger options
- [Scroll Trigger](/docs/sdk/scroll-trigger) — `.onScroll()` and `refreshScrollTriggers()`

---

## ScrollTrigger Advanced

> Pin elements, add spacing, configure snap points, and use scroll markers for debugging.

URL: https://motion.page/docs/sdk/scroll-trigger-advanced

import LivePreview from "../../components/docs/blocks/LivePreview";

Build on the basics of `.onScroll()` with pinning, snap points, custom scroll containers, debug markers, and progress callbacks. These options let you create complex scroll-driven experiences — from sticky sections and horizontal galleries to scroll-linked progress bars.

If you're new to scroll triggers, start with [Scroll Trigger](/docs/sdk/scroll-trigger) first.

---

## Pin

**Pinning** fixes an element in place while the user continues to scroll, keeping it visible throughout the scroll range you define. Set `pin: true` to pin the animation's target element.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("sticky-panel", ".panel", {
  from: { opacity: 0, y: 30 },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  start: "top top",
  end: "+=600",
});
```

<LivePreview client:visible
  height={420}
  title="Pinned progress card in a custom scroll container"
  html={`<div class="scroll-demo">
  <div class="demo-heading">
    <div><span>ADVANCED SCROLL</span><strong>Pin + scrub + onUpdate</strong></div>
    <b class="progress-label">0%</b>
  </div>
  <div class="demo-scroller">
    <div class="scroll-intro">Scroll inside this panel ↓</div>
    <section class="trigger-zone">
      <article class="pin-card">
        <span class="card-step">SCROLL PROGRESS</span>
        <h3>One pinned card.<br />A continuous story.</h3>
        <div class="progress-track"><div class="progress-fill"></div></div>
        <div class="step-row">
          <span class="is-active">Discover</span><span>Build</span><span>Launch</span>
        </div>
      </article>
    </section>
    <div class="scroll-outro">End of the trigger range</div>
  </div>
</div>`}
  css={`.scroll-demo {
  width: min(720px, 100%);
  padding: 18px;
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  background: #080b20;
}
.demo-heading {
  display: flex;
  align-items: flex-end;
  justify-content: space-between;
  gap: 16px;
  margin-bottom: 14px;
}
.demo-heading div { display: grid; gap: 4px; }
.demo-heading span { color: #7f89ad; font-size: 10px; font-weight: 800; letter-spacing: 0.14em; }
.demo-heading strong { color: #f3f4ff; font-size: 16px; }
.progress-label { color: #9e83ff; font-size: 24px; }
.demo-scroller {
  position: relative;
  height: 300px;
  overflow-y: auto;
  overscroll-behavior: contain;
  border: 1px solid rgba(143, 158, 255, 0.16);
  border-radius: 15px;
  background: linear-gradient(180deg, rgba(29, 35, 69, 0.88), rgba(7, 10, 27, 0.98));
  scrollbar-color: #7455e8 transparent;
}
.scroll-intro,
.scroll-outro {
  height: 190px;
  display: grid;
  place-items: center;
  color: #7780a4;
  font-size: 12px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
}
.trigger-zone {
  min-height: 660px;
  padding: 28px 18px;
  background: radial-gradient(circle at 50% 20%, rgba(104, 74, 226, 0.2), transparent 48%);
}
.pin-card {
  width: min(460px, 92%);
  min-height: 220px;
  margin: 0 auto;
  padding: 24px;
  border: 1px solid rgba(164, 178, 255, 0.24);
  border-radius: 18px;
  background: linear-gradient(145deg, rgba(32, 38, 77, 0.97), rgba(12, 16, 41, 0.98));
  box-shadow: 0 24px 70px rgba(0, 0, 0, 0.38);
}
.card-step { color: #9476ff; font-size: 10px; font-weight: 800; letter-spacing: 0.14em; }
.pin-card h3 { margin: 12px 0 25px; color: #f5f6ff; font-size: clamp(23px, 4vw, 34px); line-height: 1.05; }
.progress-track { height: 5px; border-radius: 999px; background: rgba(150, 160, 205, 0.17); overflow: hidden; }
.progress-fill { width: 100%; height: 100%; border-radius: inherit; background: linear-gradient(90deg, #7448ea, #50d5ff); transform-origin: 0 50%; }
.step-row { display: flex; justify-content: space-between; margin-top: 12px; color: #6f789a; font-size: 11px; }
.step-row .is-active { color: #d9d3ff; }
@media (max-width: 520px) {
  .scroll-demo { padding: 12px; }
  .demo-scroller { height: 310px; }
  .pin-card { width: 96%; padding: 20px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const label = document.querySelector(".progress-label");
const steps = [...document.querySelectorAll(".step-row span")];

Motion("advanced-scroll-preview", ".progress-fill", {
  from: { scaleX: 0 },
  duration: 1,
  ease: "none",
  onUpdate: (progress) => {
    label.textContent = Math.round(progress * 100) + "%";
    const active = Math.min(2, Math.floor(progress * 3));
    steps.forEach((step, index) => step.classList.toggle("is-active", index === active));
  },
}).onScroll({
  target: ".trigger-zone",
  scroller: ".demo-scroller",
  start: "top top",
  end: "bottom bottom",
  scrub: true,
  pin: ".pin-card",
  pinSpacing: false,
});`}
/>

The element stays fixed at its `start` position until the scroll distance defined by `end` has been traveled. After that, it unpins and scrolls normally.

### Pin a Different Element

Pass a CSS selector string to `pin` to pin a different element than the one being animated — typically a parent wrapper.

```typescript
// Pin the section while the inner content animates
Motion("reveal-inner", ".content-inner", {
  from: { opacity: 0, y: 60 },
  duration: 1,
  ease: "power2.out",
}).onScroll({
  scrub: true,
  pin: ".section-wrapper",
  start: "top top",
  end: "+=800",
});
```

---

## pinSpacing

When an element is pinned, the page loses that section's natural scroll height. **`pinSpacing`** compensates by adding space below (or around) the pinned element so subsequent content doesn't jump up unexpectedly.

| Value | Behavior |
|-------|----------|
| `true` (default) | Adds `padding-bottom` to push content down |
| `"padding"` | Same as `true` — explicit padding mode |
| `"margin"` | Adds `margin-bottom` instead of padding |
| `false` | Disables spacing entirely — content flows directly under the pinned element |

```typescript
Motion("pinned-hero", ".hero", {
  to: { scale: 0.9, opacity: 0.6 },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  pinSpacing: "margin",
  start: "top top",
  end: "+=500",
});
```

Use `pinSpacing: false` when the pinned element overlaps content intentionally (e.g., sticky overlays, fullscreen covers).

---

## Snap

**Snap** quantizes the animation's scroll-derived progress to discrete points. It does not move or lock the browser's scrollbar. This is useful for step-by-step galleries, onboarding flows, and presentation-style layouts.

### Snap to Even Intervals

Pass a single `number` between 0 and 1. The SDK divides the range into equal steps at that interval.

```typescript
// Snaps to 0, 0.25, 0.5, 0.75, 1.0
Motion("stepped", ".panel", {
  from: { opacity: 0.2 },
  duration: 1,
}).onScroll({
  scrub: true,
  snap: 0.25,
});
```

### Snap to Specific Points

Pass an array of progress values (0–1) to define exact snap positions.

```typescript
// Snap to 3 panels in unequal proportions
Motion("custom-snap", ".panel", {
  from: { x: "0%" },
  to: { x: "-200%" },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  start: "top top",
  end: "+=2000",
  snap: [0, 0.4, 1],
});
```

### Snap with a Custom Function

For dynamic layouts or non-linear snapping, pass a function. It receives the raw scroll progress (0–1) and returns the snapped value.

```typescript
Motion("dynamic-snap", ".slider", {
  to: { x: "-300%" },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  end: "+=3000",
  snap: (progress) => Math.round(progress * 3) / 3,
});
```

### Snapping for Horizontal Scroll

Combine snap with `each` or compute the increment from your section count:

```typescript
const panels = Motion.utils.toArray(".h-panel");
const snapIncrement = 1 / (panels.length - 1);

Motion("h-gallery", ".h-track", {
  to: { x: `-${(panels.length - 1) * 100}%` },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  start: "top top",
  end: `+=${panels.length * 100}vh`,
  snap: snapIncrement,
});
```

---

## Markers

Enable `markers: true` to render visual debug overlays showing exactly where your `start` and `end` positions fall relative to both the scroller and the animated element.

```typescript
Motion("debug-reveal", ".section", {
  from: { opacity: 0, y: 50 },
  duration: 0.8,
}).onScroll({
  scrub: true,
  start: "top 80%",
  end: "top 30%",
  markers: true,
});
```

Two pairs of markers appear:
- **Green lines** — `start` positions (scroller and element)
- **Red lines** — `end` positions (scroller and element)

### Marker Configuration

Pass a `MarkerConfig` object to customize marker colors, size, and horizontal offset.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `startColor` | `string` | `"lime"` | CSS color for start markers |
| `endColor` | `string` | `"red"` | CSS color for end markers |
| `fontSize` | `string` | — | Font size for marker labels, e.g. `"12px"` |
| `fontWeight` | `string` | — | Font weight for marker labels |
| `indent` | `number` | `0` | Horizontal offset in px — use when multiple trigger zones overlap |

```typescript
Motion("debug-custom", ".hero", {
  from: { opacity: 0 },
  duration: 1,
}).onScroll({
  scrub: true,
  markers: {
    startColor: "blue",
    endColor: "orange",
    fontSize: "11px",
    indent: 40,
  },
});
```

> **Remove markers in production.** Delete the `markers` option for a live page. Use `Motion.cleanup()` during teardown only: it safely removes marker/spacer nodes and detaches active ScrollTriggers while leaving their timelines registered.

---

## Horizontal Scrolling

Horizontal scroll scenes require a **pinned container** that holds while the inner track translates on the X axis. The total scroll travel defines how far the track moves.

```typescript
import { Motion } from "@motion.page/sdk";

const panels = Motion.utils.toArray(".panel");

Motion("horizontal-scroll", ".track", {
  to: { x: `-${(panels.length - 1) * 100}%` },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: ".pin-container",
  start: "top top",
  end: `+=${panels.length * 100}vh`,
  snap: 1 / (panels.length - 1),
});
```

**Required CSS:**

```css
.pin-container {
  overflow: hidden;
  height: 100vh;
}

.track {
  display: flex;
  width: calc(100% * var(--panel-count)); /* or set explicitly */
}

.panel {
  width: 100vw;
  height: 100vh;
  flex-shrink: 0;
}
```

The `.track` element moves from `x: 0` to `x: -N * 100%` as the user scrolls through the pinned range, while the container stays fixed at the top of the viewport.

---

## Custom Scroll Container (`scroller`)

By default, scroll triggers listen to the **window** scroll. Use `scroller` to attach a trigger to any scrollable element instead.

```typescript
Motion("inner-scroll", ".list-item", {
  from: { opacity: 0, x: -20 },
  duration: 0.5,
  stagger: { each: 0.08 },
}).onScroll({
  scrub: false,
  toggleActions: "play none none none",
  start: "top 90%",
  scroller: ".sidebar-panel",
});
```

`scroller` accepts either a CSS selector string or a direct `Element` reference:

```typescript
const container = document.querySelector(".modal-body");

Motion("modal-anim", ".modal-item", {
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: 0.05,
}).onScroll({
  toggleActions: "play none none none",
  start: "top 85%",
  scroller: container,
});
```

> The scroller element must have `overflow: scroll` or `overflow: auto` and a fixed height to be scrollable. The window scroll is used as fallback when `scroller` is `undefined`.

---

## Scroll Lifecycle and `toggleActions`

For non-scrub animations, **`toggleActions`** controls exactly what the timeline does at each of the four scroll lifecycle events. It's a space-separated string of four actions:

```
toggleActions: "onEnter onLeave onEnterBack onLeaveBack"
```

| Position | Event | When it fires |
|----------|-------|---------------|
| 1st | `onEnter` | Scrolling **down** into the trigger zone |
| 2nd | `onLeave` | Scrolling **down** past the end of the trigger zone |
| 3rd | `onEnterBack` | Scrolling **up** back into the trigger zone |
| 4th | `onLeaveBack` | Scrolling **up** out the top of the trigger zone |

**Valid actions:** `play` · `pause` · `resume` · `reverse` · `restart` · `reset` · `complete` · `none`

**Default:** `"play none none none"`

### Common Patterns

```typescript
// Play once and stay — never reverse
Motion("once-reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.7,
  ease: "power2.out",
}).onScroll({
  each: true,
  toggleActions: "play none none none",
  start: "top 85%",
});

// Play forward on enter, reverse on leave back (no action when past end)
Motion("in-out", ".feature", {
  from: { opacity: 0, scale: 0.9 },
  duration: 0.6,
}).onScroll({
  each: true,
  toggleActions: "play none none reverse",
  start: "top 80%",
  end: "bottom 20%",
});

// Restart every time the element enters
Motion("repeating-anim", ".highlight", {
  from: { backgroundColor: "transparent" },
  to: { backgroundColor: "#fbbf24" },
  duration: 0.5,
}).onScroll({
  each: true,
  toggleActions: "restart none none reset",
  start: "top 75%",
});
```

---

## Progress Tracking with `onUpdate`

Use the `onUpdate` callback inside `AnimationConfig` to run code every frame as the animation progresses. With scrubbing enabled, this callback fires continuously as the user scrolls — making it ideal for syncing secondary UI elements like reading progress bars, counters, or parallax overlays.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reading-progress", ".progress-bar", {
  from: { width: "0%" },
  to: { width: "100%" },
  duration: 1,
  onUpdate: (progress) => {
    const label = document.querySelector(".progress-label");
    if (label) {
      label.textContent = `${Math.round(progress * 100)}%`;
    }
  },
}).onScroll({
  scrub: true,
  start: "top top",
  end: "bottom bottom",
});
```

`onUpdate` receives a normalized progress value between `0` and `1`.

### Driving Multiple Elements

Because `onUpdate` runs in the animation's update loop, you can drive any number of secondary effects without creating additional timelines.

```typescript
const nav = document.querySelector(".navbar");
const progress = document.querySelector(".nav-progress");

Motion("page-scroll", "body", {
  to: { opacity: 1 },  // dummy — only onUpdate drives behavior
  duration: 1,
  onUpdate: (p) => {
    // Darken navbar as user scrolls down
    const alpha = Math.min(p * 2, 1);
    nav?.style.setProperty("--nav-bg-alpha", String(alpha));

    // Widen progress bar
    progress?.style.setProperty("width", `${p * 100}%`);
  },
}).onScroll({
  scrub: true,
  start: "top top",
  end: "bottom bottom",
});
```

---

## Complete API Reference

### ScrollConfig

```typescript
interface ScrollConfig {
  target?:         string | Element;
  endTarget?:      string | Element;
  start?:          string;
  end?:            string;
  scrub?:          boolean | number;
  pin?:            boolean | string;
  pinSpacing?:     boolean | "margin" | "padding";
  snap?:           number | number[] | ((progress: number) => number);
  markers?:        boolean | MarkerConfig;
  scroller?:       string | Element;
  toggleActions?:  string;
  each?:           boolean;
}
```

### MarkerConfig

```typescript
interface MarkerConfig {
  startColor?:  string;   // CSS color. Default: "lime"
  endColor?:    string;   // CSS color. Default: "red"
  fontSize?:    string;   // e.g. "12px"
  fontWeight?:  string;
  indent?:      number;   // px horizontal offset
}
```

### `onUpdate` in AnimationConfig

```typescript
interface AnimationConfig {
  // ...other properties
  onUpdate?: (progress: number) => void;  // progress: 0–1
}
```

---

## Tips and Gotchas

**Recalculate after layout changes.** If your page layout shifts after initialization (e.g., fonts load, images resize, components mount), scroll trigger positions become stale. Call `Motion.refreshScrollTriggers()` to recompute all positions.

```typescript
window.addEventListener("load", () => {
  Motion.refreshScrollTriggers();
});
```

**Scrub disables `toggleActions`.** When `scrub` is enabled, the animation progress is tied directly to scroll position. Setting `toggleActions` alongside `scrub` has no effect — use scrub OR toggleActions, not both.

**`end` with `+=` is relative to `start`.** `end: "+=800"` means 800px of scroll travel measured from the `start` point, not from the element's position.

```typescript
// 800px of scroll travel from wherever start fires
end: "+=800"

// One full viewport height of travel
end: "+=100vh"
```

**Pin spacing defaults to `true`.** If pinned content is overlapping the next section unexpectedly, confirm `pinSpacing` isn't set to `false`. The default adds padding to preserve document flow.

**Clean up markers before shipping.** Remove the `markers` option from live code. During teardown, `Motion.cleanup()` detaches active ScrollTriggers and safely removes their marker and spacer nodes.

---

Related: [Scroll Trigger](/docs/sdk/scroll-trigger) · [Performance Tips](/docs/sdk/performance)

---

## Debugging Animations

> Debug with markers, console logging, timeline inspection, and common pitfalls.

URL: https://motion.page/docs/sdk/debugging

Animations are invisible by nature — when something goes wrong there's no error to catch, just an element that didn't move. This guide covers the tools available for diagnosing what went wrong.

---

## Scroll Trigger Markers

The fastest way to debug a scroll-triggered animation is to visualise its trigger boundaries. Pass `markers: true` to `.onScroll()` and the SDK renders coloured lines showing exactly where `start` and `end` fire relative to both the element and the viewport.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("debug-reveal", ".section", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({
  start: "top 80%",
  end: "bottom 20%",
  markers: true,
});
```

Two pairs of lines appear in the viewport:
- **scroller-start / scroller-end** — the trigger positions on the viewport (or scroll container)
- **start / end** — the corresponding positions on the target element

If the animation never fires, the start line is likely never crossed. Adjust `start` until the lines align with your intent.

**Remove `markers: true` before shipping.** Markers inject DOM nodes that remain visible to users if left in production.

### Custom Marker Colours

When debugging multiple triggers on the same page, colour-coding them makes the markers distinguishable:

```typescript
Motion("hero-reveal", ".hero", {
  from: { opacity: 0 },
  duration: 0.8,
}).onScroll({
  start: "top 70%",
  markers: {
    startColor: "lime",
    endColor: "red",
    fontSize: "12px",
    indent: 40,
  },
});

Motion("card-reveal", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.5,
}).onScroll({
  each: true,
  start: "top 85%",
  markers: {
    startColor: "cyan",
    endColor: "orange",
    fontSize: "12px",
    indent: 80,
  },
});
```

| Marker option | Type | Description |
|---------------|------|-------------|
| `startColor` | `string` | CSS colour for the start line label |
| `endColor` | `string` | CSS colour for the end line label |
| `fontSize` | `string` | Label font size (e.g. `"12px"`) |
| `indent` | `number` | Horizontal offset in px — stagger triggers so they don't overlap |

---

## Inspecting a Timeline via `Motion("name")`

Every timeline is stored in a named registry. Retrieve any timeline by name using the single-argument overload and inspect its state in the console at any point.

```typescript
import { Motion } from "@motion.page/sdk";

// Create the timeline
Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad({ paused: true });

// Retrieve and inspect
const tl = Motion("hero");

console.log(tl.getName());     // "hero"
console.log(tl.duration());    // 0.8
console.log(tl.progress());    // 0–1
console.log(tl.time());        // seconds elapsed
console.log(tl.isActive());    // true if currently animating
console.log(tl.timeScale());   // playback speed (1 = normal)
```

Use `Motion.get()` for safe retrieval that returns `undefined` instead of throwing when the timeline doesn't exist:

```typescript
const tl = Motion.get("hero");
if (tl) {
  console.log(`progress: ${tl.progress().toFixed(3)}`);
  console.log(`time: ${tl.time().toFixed(3)}s / ${tl.duration()}s`);
  console.log(`active: ${tl.isActive()}`);
}
```

### Listing all registered timelines

`Motion.getNames()` returns an array of every currently registered timeline name. Log it at any point to see exactly what's alive:

```typescript
console.log(Motion.getNames());
// ["hero", "nav-reveal", "card-hover", "footer-fade"]
```

This is useful for catching orphaned timelines in SPAs — if names from previous routes are still listed after navigation, the cleanup logic didn't run.

---

## Console Logging with Callbacks

### `onUpdate` — log progress every frame

Chain `.onUpdate()` on a timeline to receive `progress` (0–1) and `time` (seconds) on every animation frame. Use it to observe exactly how the animation advances.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("loader", ".progress-bar", {
  to: { width: "100%" },
  duration: 2,
})
  .onUpdate((progress, time) => {
    console.log(`progress: ${(progress * 100).toFixed(1)}%  time: ${time.toFixed(3)}s`);
  })
  .onPageLoad();
```

### `onStart` and `onComplete` — confirm the timeline fired

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reveal", ".hero", {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
})
  .onStart(() => console.log("[reveal] started"))
  .onComplete(() => console.log("[reveal] complete"))
  .onPageLoad();
```

If `[reveal] started` never appears in the console, the trigger condition was never met — the page-load event didn't fire (unusual), or a scroll/hover trigger was never activated.

### Per-animation `onUpdate`

Individual animations inside a timeline each expose their own `onUpdate` via `AnimationConfig`. This fires relative to that animation's own 0–1 progress — useful for multi-step timelines where you want to observe one step in isolation:

```typescript
import { Motion } from "@motion.page/sdk";

Motion("sequence", [
  { target: "#title",    from: { opacity: 0 }, duration: 0.5 },
  {
    target: "#subtitle",
    from: { opacity: 0, y: 20 },
    duration: 0.4,
    position: "+=0.1",
    onUpdate: (progress) => {
      console.log(`subtitle progress: ${(progress * 100).toFixed(1)}%`);
    },
  },
]).onPageLoad();
```

---

## `Motion.refreshScrollTriggers()`

**`Motion.refreshScrollTriggers()`** recalculates every scroll trigger's start and end positions. Call it after any layout change that happens after the triggers were created.

```typescript
import { Motion } from "@motion.page/sdk";

Motion.refreshScrollTriggers();
```

This is the fix for scroll triggers that fire at the wrong scroll position after the page layout shifts. See [Common Pitfalls](#common-pitfalls) below for specific scenarios.

### After dynamic content loads

```typescript
async function loadProducts() {
  const products = await fetchProducts();
  renderGrid(products); // new DOM added — page is now taller

  // Recalculate all trigger positions
  Motion.refreshScrollTriggers();
}
```

### After an accordion opens

```typescript
document.querySelectorAll(".accordion-toggle").forEach((toggle) => {
  toggle.addEventListener("click", () => {
    toggle.closest(".accordion")?.classList.toggle("open");
    // Heights have changed — refresh immediately
    Motion.refreshScrollTriggers();
  });
});
```

### Debounced resize handler

Scroll positions are also invalidated by window resizes. Debounce the refresh to avoid excessive recalculations:

```typescript
import { Motion } from "@motion.page/sdk";

let resizeTimer: ReturnType<typeof setTimeout>;

window.addEventListener("resize", () => {
  clearTimeout(resizeTimer);
  resizeTimer = setTimeout(() => {
    Motion.refreshScrollTriggers();
  }, 150);
});
```

---

## Common Pitfalls

### Elements not found — selector timing

Animations that target elements not yet in the DOM are silently ignored. The SDK resolves selectors at the moment `.onPageLoad()` / `.onScroll()` / etc. is called.

```typescript
// ❌ Script runs before the DOM is parsed — selector finds nothing
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
```

The fix is to ensure your script runs after the DOM is ready. `.onPageLoad()` waits for `DOMContentLoaded` and fires immediately if the event has already passed — but the selector is still resolved at call time. Place scripts at the end of `<body>`, use `defer`, or wrap in a `DOMContentLoaded` listener:

```typescript
// ✅ Script deferred — DOM is fully parsed when this runs
document.addEventListener("DOMContentLoaded", () => {
  Motion("hero", "#hero", {
    from: { opacity: 0, y: 40 },
    duration: 0.8,
  }).onPageLoad();
});
```

In frameworks, initialise inside the component's mount lifecycle rather than at module scope:

```typescript
// ✅ React — DOM is available inside useEffect
import { useEffect } from "react";
import { Motion } from "@motion.page/sdk";

function HeroSection() {
  useEffect(() => {
    const ctx = Motion.context(() => {
      Motion("hero", "#hero", { from: { opacity: 0, y: 40 }, duration: 0.8 }).onPageLoad();
    });
    return () => ctx.revert();
  }, []);

  return <section id="hero">{/* ... */}</section>;
}
```

---

### FOUC — flash of unstyled content

Elements that animate in from `opacity: 0` or an offset position will flash at their natural CSS state for a frame before the animation initialises. This is the browser rendering the element before the SDK has applied its initial state.

The fix is `Motion.set()` — apply the initial state immediately, synchronously, so the element is already hidden when the browser first paints it:

```typescript
import { Motion } from "@motion.page/sdk";

// Apply initial state before the browser first paints
Motion.set(".hero-title, .hero-sub, .hero-cta", { opacity: 0, y: 30 });

// Then register the animation
Motion("hero", [
  { target: ".hero-title", to: { opacity: 1, y: 0 }, duration: 0.7 },
  { target: ".hero-sub",   to: { opacity: 1, y: 0 }, duration: 0.6, position: "+=0.1" },
  { target: ".hero-cta",   to: { opacity: 1, y: 0 }, duration: 0.5, position: "+=0.1" },
]).onPageLoad();
```

Alternatively, set the initial state in CSS and use `from`-only animation — the SDK reads the computed CSS as the endpoint:

```css
/* Elements start invisible in CSS — no flash */
.hero-title,
.hero-sub,
.hero-cta {
  opacity: 0;
  transform: translateY(30px);
}
```

```typescript
// from-only — SDK animates FROM these values TO the natural CSS state
Motion("hero", ".hero-title, .hero-sub, .hero-cta", {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
  stagger: 0.12,
}).onPageLoad();
```

---

### Scroll trigger not updating after layout changes

Scroll triggers calculate their positions once at initialisation. If the page layout changes afterwards — fonts render and reflow text, images load and push content down, accordions open, or dynamic content is injected — the calculated positions become stale. Triggers fire too early or too late.

**Symptom:** The animation triggers at the wrong scroll position, or a `markers: true` line is visually misaligned with the element it should track.

**Fix:** Call `Motion.refreshScrollTriggers()` after any layout-affecting change:

```typescript
import { Motion } from "@motion.page/sdk";

// After images load
window.addEventListener("load", () => {
  // All images and fonts have loaded — layout is stable
  Motion.refreshScrollTriggers();
});

// After a tab panel becomes visible
document.querySelectorAll(".tab").forEach((tab) => {
  tab.addEventListener("click", () => {
    showTabPanel(tab);
    Motion.refreshScrollTriggers();
  });
});

// After lazy-loaded content is injected
observer.observe(sentinel);
function onContentLoaded(newItems: Element[]) {
  appendToPage(newItems);
  Motion.refreshScrollTriggers();
}
```

If you're working with a CMS, page builder, or content that loads progressively, calling `Motion.refreshScrollTriggers()` on `window.load` is a reliable safety net that catches most layout-affecting async loads in one call.

---

## Quick Diagnostic Checklist

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| Animation never plays | Selector not found, trigger condition not met | Check `Motion.getNames()`, add `onStart` log, verify selector in DevTools |
| Elements flash before animating | Initial state not applied before first paint | Use `Motion.set()` or set initial state in CSS |
| Scroll trigger fires at wrong position | Layout changed after initialisation | Call `Motion.refreshScrollTriggers()` after layout changes |
| Two timelines stepping on each other | Same name used twice — second appends to first | Call `Motion("name").kill()` before re-registering |
| Timeline not found on retrieval | Timeline was killed or never created | Guard with `Motion.has("name")` or use `Motion.get("name")` |
| Animation plays but wrong element moves | Selector matches more than expected | Inspect matched elements with `Motion.utils.toArray(".selector")` |

```typescript
// Inspect what a selector actually matches at runtime
import { Motion } from "@motion.page/sdk";

const matched = Motion.utils.toArray(".my-selector");
console.log(`matched ${matched.length} elements:`, matched);
```

---

Related: [Scroll Trigger](/docs/sdk/scroll-trigger) · [Timeline Control](/docs/sdk/timeline-control) · [Static Methods](/docs/sdk/static-methods)

---

## What is Motion.page SDK

> Overview of the SDK — a standalone animation engine with named timelines, triggers, and zero dependencies.

URL: https://motion.page/docs/sdk/overview

import LivePreview from "../../components/docs/blocks/LivePreview";

**Motion.page SDK** (`@motion.page/sdk`) is a standalone animation engine purpose-built for the web. It gives you named timelines, implicit value resolution, built-in triggers, and zero dependencies to manage.

## Install

```bash
bun add @motion.page/sdk
# or
npm install @motion.page/sdk
```

## Quick Start

```typescript
import { Motion } from "@motion.page/sdk";

Motion("fade-in", ".hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
}).play();
```

<LivePreview client:visible
  height={250}
  title="Quick start fade-in animation"
  html={`<article class="hero">
  <span class="eyebrow">Motion.page SDK</span>
  <h2>Animate with intent.</h2>
  <p>Named timelines, implicit values, and triggers in one small API.</p>
  <div class="hero-meta"><span>zero dependencies</span><span>web native</span></div>
</article>`}
  css={`.hero {
  width: min(470px, 100%);
  padding: 26px;
  border: 1px solid rgba(153, 102, 255, 0.3);
  border-radius: 20px;
  background: radial-gradient(circle at top right, rgba(102, 51, 238, 0.24), transparent 48%), #11152a;
  box-shadow: 0 24px 70px rgba(0, 0, 0, 0.3);
}
.eyebrow {
  color: #a98dff;
  font-size: 11px;
  font-weight: 700;
  letter-spacing: 0.12em;
  text-transform: uppercase;
}
h2 { margin-top: 9px; color: white; font-size: clamp(25px, 5vw, 38px); line-height: 1; }
p { margin-top: 11px; color: #9ea4c1; font-size: 13px; line-height: 1.5; }
.hero-meta { display: flex; gap: 8px; margin-top: 18px; }
.hero-meta span {
  padding: 5px 8px;
  border-radius: 999px;
  background: rgba(255, 255, 255, 0.06);
  color: #c7cae0;
  font-size: 10px;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("overview-fade-in", ".hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

Three arguments: a **name** for the timeline, a **target** selector or element, and an **animation config**. Call `.play()` and you're done.

---

## Why Motion.page SDK?

### Named timelines

`Motion('name')` always returns the **same `Timeline` instance**. Call it from anywhere in your app to reference, control, or extend the same animation — no need to store references in variables.

```typescript
// Create
Motion("hero", ".hero", { from: { opacity: 0 } }).play();

// Control from anywhere
Motion("hero").pause();
Motion("hero").reverse();
```

### Implicit value resolution

Only specify `from` **or** `to` — the SDK reads the missing endpoint from the element's **current computed CSS**. No need to hard-code both states.

```typescript
// Animates FROM opacity 0 TO whatever the element currently has
Motion("reveal", ".card", { from: { opacity: 0, y: 30 } }).play();
```

### Built-in triggers

Chain triggers directly on timelines instead of wiring up listeners manually:

```typescript
Motion("on-scroll", ".section", { from: { opacity: 0 } }).onScroll();
Motion("on-hover", ".button", { to: { scale: 1.05 } }).onHover({ each: true, onLeave: "reverse" });
Motion("on-click", ".panel", { to: { height: "auto" } }).onClick({ each: true });
Motion("on-load", ".hero", { from: { y: -20 } }).onPageLoad();
```

Available triggers: `.onScroll()`, `.onHover()`, `.onClick()`, `.onPageLoad()`, `.onPageExit()`, `.onMouseMove()`, `.onGesture()`, `.onCursor()`

### Text splitting built-in

Animate by `chars`, `words`, or `lines` with an optional mask effect — no extra plugin or setup:

```typescript
Motion("headline", "h1", {
  from: { opacity: 0, y: "100%" },
  split: "words",
  stagger: 0.05,
}).onPageLoad();
```

### FLIP animations built-in

Morph an element from one position/size to another using the `fit` property:

```typescript
Motion("morph", ".card", {
  fit: { target: ".destination" },
}).onClick({ target: ".card" });
```

### SVG drawing built-in

Animate SVG strokes with `drawSVG` — no plugin needed:

```typescript
Motion("draw", "path", {
  from: { drawSVG: "0%" },
  to: { drawSVG: "100%" },
  duration: 1.2,
}).onScroll();
```

---

## Zero Dependencies

The SDK is a **self-contained animation engine** with no external dependencies. Install the SDK and you're ready — your bundler doesn't need to resolve anything else.

---

## Bundle Formats

| File | Format | Usage |
|------|--------|-------|
| `dist/index.js` | ESM | `import { Motion } from '@motion.page/sdk'` |
| `dist/index.cjs` | CommonJS | `require('@motion.page/sdk')` |
| `dist/motion-sdk.browser.js` | IIFE | `<script>` tag — exposes `window.Motion` |
| `dist/index.d.ts` | TypeScript declarations | Automatic via `moduleResolution: bundler` |

Works out of the box with **Vite**, **webpack**, **Rollup**, **esbuild**, and direct `<script>` tags.

---

## Browser Support

All modern browsers: **Chrome**, **Firefox**, **Safari**, **Edge**. The IIFE build targets any browser with ES2015+ support.

---

## SDK & The Builder

The **Motion.page Builder** is a visual animation design tool (available as a desktop app and WordPress plugin). Design animations with a drag-and-drop timeline editor, configure triggers, adjust easing curves — then **export the result as SDK code** ready to paste into your project.

The SDK is the **runtime**. The Builder is the **design tool**. They're independent — you can use the SDK without the Builder, and vice versa.

---

## Next Steps

- [Getting Started](/docs/sdk/getting-started) — full setup walkthrough
- [Core Concepts](/docs/sdk/core-concepts) — timelines, targets, and config in depth
- [Core Concepts — Triggers](/docs/sdk/core-concepts) — all eight trigger types explained
- [Opacity](/docs/sdk/opacity) — start with the simplest animation property

---

## 3D Transforms

> Rotate elements in 3D space with rotateX, rotateY, rotateZ and perspective.

URL: https://motion.page/docs/sdk/3d-transforms

import LivePreview from "../../components/docs/blocks/LivePreview";

The Motion SDK supports 3D rotation transforms via `rotateX`, `rotateY`, and `rotateZ` properties. Combined with perspective, these create depth effects like card flips, tilts, and spins.

## Parameters

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `rotateX` | `number` | `0` | Rotation around the X axis (horizontal). Positive values tilt the top away from the viewer. In degrees. |
| `rotateY` | `number` | `0` | Rotation around the Y axis (vertical). Positive values turn the left side away from the viewer. In degrees. |
| `rotateZ` | `number` | `0` | Rotation around the Z axis — equivalent to the 2D [`rotate`](/docs/sdk/rotation) property. In degrees. |
| `transformOrigin` | `string` | `'50% 50%'` | Sets the pivot point for all transforms. |

`rotateZ` and `rotate` are interchangeable — they produce identical results.

## Perspective

3D rotations look flat without **perspective**. There are two ways to add it:

- **CSS on the parent** — `perspective: 800px`. All children share a single vanishing point, which looks correct when multiple elements rotate together.
- **Per-element** — set `perspective` inline on the element itself via CSS `transform: perspective(800px) rotateY(45deg)`, or use the SDK's `transformPerspective` property. Each element has its own vanishing point.

For most SDK use cases, setting perspective in CSS on the parent container is the simplest approach:

```typescript
import { Motion } from '@motion.page/sdk';

// Parent needs perspective in CSS: .scene { perspective: 800px; }
Motion('flip', '.card', {
  from: { rotateY: 180 },
  duration: 0.8,
  ease: 'power2.out',
}).play();
```

## Axis Directions

- **rotateX** — positive values tilt the top away (like leaning back in a chair); negative values tilt the top toward the viewer.
- **rotateY** — positive values turn the left side away (like opening a door to the right); negative values turn the right side away.
- **rotateZ** — positive values rotate clockwise; negative values rotate counter-clockwise. Identical to the 2D `rotate` property.

## Combining Axes

You can apply multiple rotation axes simultaneously for compound 3D motion:

```typescript
Motion('tilt', '.box', {
  from: { rotateX: 45, rotateY: -30 },
  duration: 1,
  ease: 'power2.out',
}).onScroll({ scrub: true });
```

<LivePreview client:load
  height={260}
  title="Card flip"
  html={`<div class="scene"><div class="card"><div class="card-face card-front">Front</div><div class="card-face card-back">Back</div></div></div>`}
  css={`.scene { width: 200px; height: 260px; perspective: 800px; margin: 0 auto; }
.card { width: 100%; height: 100%; position: relative; transform-style: preserve-3d; }
.card-face { position: absolute; width: 100%; height: 100%; backface-visibility: hidden; border-radius: 12px; display: flex; align-items: center; justify-content: center; font-family: system-ui; font-size: 1.25rem; font-weight: 600; }
.card-front { background: linear-gradient(135deg, #6633EE, #9966FF); color: white; }
.card-back { background: linear-gradient(135deg, #FF6633, #FF9966); color: white; transform: rotateY(180deg); }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("flip", ".card", {
  to: { rotateY: 180 },
  duration: 0.8,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Common Patterns

### Flip in Y (card flip)

```typescript
Motion('flip-y', '.card', {
  to: { rotateY: 180 },
  duration: 0.8,
  ease: 'power2.inOut',
}).onClick();
```

### Flip in X (top-down flip)

```typescript
Motion('flip-x', '.panel', {
  to: { rotateX: 180 },
  duration: 0.6,
  ease: 'power2.inOut',
}).onClick();
```

### Perspective spin (full 360)

```typescript
Motion('spin', '.logo', {
  to: { rotateY: 360 },
  duration: 1.2,
  ease: 'power1.inOut',
  repeat: -1,
}).play();
```

### 3D tilt on hover

```typescript
Motion('tilt-hover', '.card', {
  to: { rotateX: -8, rotateY: 12 },
  duration: 0.4,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Scroll-driven 3D rotation

```typescript
Motion('scroll-rotate', '.hero-image', {
  from: { rotateX: 25, rotateY: -15 },
  duration: 1,
}).onScroll({ scrub: true });
```

## Tips

- Always set `perspective` on the **parent container** in CSS. Without it, 3D rotations render flat.
- Add `transform-style: preserve-3d` to the rotating element when it has 3D-transformed children (e.g. both faces of a card).
- Use `backface-visibility: hidden` in CSS on card faces to hide the reverse side during a flip.
- `transformOrigin` controls the pivot point — the default `'50% 50%'` works for most 3D rotations, but `'left center'` creates a door-hinge effect.
- Keep `perspective` values between **500–1200px** for natural-looking depth. Lower values create more dramatic distortion; higher values make rotation more subtle.

---

## Dimensions

> Animate width and height of elements.

URL: https://motion.page/docs/sdk/dimensions

import LivePreview from "../../components/docs/blocks/LivePreview";

Animate the `width` and `height` of elements — from pixel values to percentages, viewport units, and `auto`. Ideal for accordions, progress bars, and responsive resize effects.

## Basic Usage

Pass `width` and/or `height` inside `from` or `to`. Numbers are treated as pixels; strings accept any CSS unit.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("expand", ".box", {
  from: { width: 0, height: 0 },
  to: { width: 200, height: 200 },
  duration: 0.5,
  ease: "power2.out",
}).play();
```

Because the SDK auto-resolves the missing endpoint from the element's computed CSS, you only need to specify the side that _differs_ from the element's natural state:

```typescript
// Start at zero height, expand to whatever height the element naturally has
Motion("reveal", ".card", {
  from: { height: 0 },
  duration: 0.4,
  ease: "power2.out",
}).onPageLoad();
```

## Properties

| Property | Type | Description |
|----------|------|-------------|
| `width` | `number \| string` | Target width. Numbers are px. Strings for units: `'100%'`, `'auto'`, `'50vw'`, `'12rem'` |
| `height` | `number \| string` | Target height. Numbers are px. Strings for units: `'100%'`, `'auto'`, `'50vh'`, `'12rem'` |

## String Values & Units

Pass a CSS string whenever you need units other than px:

```typescript
Motion("expand", ".box", {
  to: { width: "100%", height: "50vh" },
  duration: 0.6,
  ease: "power2.out",
}).play();
```

Valid string values: `'200px'`, `'100%'`, `'50vw'`, `'50vh'`, `'4rem'`, `'auto'`.

## Height `auto` — Accordion Pattern

Animating to `height: 'auto'` expands an element to its **natural content height** — the exact pattern for accordions and collapsible sections. The SDK calculates the target height at runtime, so the animation adapts to any content length.

```typescript
Motion("accordion", ".content", {
  from: { height: 0 },
  to: { height: "auto" },
  duration: 0.4,
  ease: "power2.out",
}).play();
```

Add `.onClick()` with `each: true` to make every panel toggle independently:

```typescript
Motion("accordion", ".panel", {
  from: { height: 0 },
  to: { height: "auto" },
  duration: 0.4,
  ease: "power2.out",
}).onClick({ each: true });
```

> **CSS required:** Add `overflow: hidden` to `.panel` so content is clipped cleanly during the animation.

<LivePreview client:load
  height={240}
  title="Accordion expand"
  html={`<div class="scene">
  <button class="btn">Toggle Content</button>
  <div class="panel">
    <p class="content">This content expands and collapses smoothly using height animation. Perfect for FAQs, accordions, and collapsible sections.</p>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 12px; height: 100%; font-family: sans-serif; }
.btn { padding: 10px 20px; background: #6633EE; color: white; border: none; border-radius: 8px; font-size: 14px; cursor: pointer; font-weight: 600; }
.btn:hover { background: #7744ff; }
.panel { overflow: hidden; height: 0; background: #1a1a2e; border-radius: 10px; width: 300px; color: #e0d4ff; }
.content { padding: 16px 20px; font-size: 14px; line-height: 1.5; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("accordion", ".panel", {
  to: { height: "auto" },
  duration: 0.4,
  ease: "power3.out",
}).onClick({ target: ".btn", toggle: "reverse" });`}
/>

## Progress Bar

Animate `width` from `'0%'` to a target percentage for clean loading or progress indicators:

```typescript
Motion("progress", ".bar", {
  from: { width: "0%" },
  to: { width: "75%" },
  duration: 1.2,
  ease: "power2.out",
}).play();
```

<LivePreview client:load
  height={100}
  title="Progress bar"
  html={`<div style="padding: 24px; width: 100%;">
  <div style="width: 100%; background: #e9e3ff; border-radius: 8px; overflow: hidden; height: 24px;">
    <div id="bar" style="width: 0%; height: 100%; background: linear-gradient(90deg, #6633EE, #9966FF); border-radius: 8px;"></div>
  </div>
</div>`}
  css={``}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("progress", "#bar", {
  from: { width: "0%" },
  to: { width: "75%" },
  duration: 1.2,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Responsive Resize on Scroll

Shrink a hero image as the user scrolls, letting surrounding content adapt to the new layout:

```typescript
Motion("resize", ".hero-image", {
  from: { width: "100%", height: "100vh" },
  to: { width: "60%", height: "50vh" },
  duration: 1,
}).onScroll({ scrub: true });
```

## Performance

`width` and `height` animations cause **layout reflows** — the browser recalculates positions and sizes of surrounding elements on every frame. This is more expensive than transform-based animations.

**Prefer [Scale](/docs/sdk/scale) when layout reflow isn't needed.** `scale`, `scaleX`, and `scaleY` run on the GPU compositor and don't affect surrounding elements — they're significantly faster for simple zoom or pop effects.

**Use dimension animations when you _need_ reflow**, for example:

- Accordions where surrounding content must shift to accommodate the expanded panel
- Progress bars that push adjacent content
- Responsive resize where neighboring elements must reposition

**Additional tips:**

- Add `overflow: hidden` on containers to prevent content from spilling during the transition
- Avoid animating `width` and `height` simultaneously on many elements — batch them or use a single container element
- Combine with `will-change: height` (sparingly) on elements that animate frequently to hint GPU promotion ahead of time

---

## Triggers

> Control when and how animations play with built-in trigger types.

URL: https://motion.page/docs/sdk/triggers

import LivePreview from "../../components/docs/blocks/LivePreview";

Triggers determine **when** a timeline plays. Chain a trigger method directly after defining your animation:

```typescript
import { Motion } from "@motion.page/sdk";

Motion("fade", ".hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad(); // ← trigger
```

<LivePreview client:visible
  height={280}
  title="Immediate, hover, and click triggers"
  html={`<div class="trigger-grid">
  <div class="trigger-card trigger-immediate">
    <span class="trigger-label">.play()</span>
    <div class="trigger-dot"></div>
    <strong>Immediate</strong>
    <small>loops automatically</small>
  </div>
  <div class="trigger-card trigger-hover">
    <span class="trigger-label">.onHover()</span>
    <div class="trigger-dot"></div>
    <strong>Hover me</strong>
    <small>leave to reverse</small>
  </div>
  <div class="trigger-card trigger-click">
    <span class="trigger-label">.onClick()</span>
    <div class="trigger-dot"></div>
    <strong>Click me</strong>
    <small>click again to reverse</small>
  </div>
</div>`}
  css={`.trigger-grid {
  width: min(620px, 100%);
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 12px;
}
.trigger-card {
  min-height: 190px;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 10px;
  padding: 18px 12px;
  border: 1px solid rgba(153, 102, 255, 0.24);
  border-radius: 17px;
  background: linear-gradient(180deg, rgba(102, 51, 238, 0.12), rgba(255, 255, 255, 0.025));
  user-select: none;
}
.trigger-label {
  padding: 4px 7px;
  border-radius: 6px;
  background: rgba(255, 255, 255, 0.06);
  color: #bba8ff;
  font: 10px/1.2 ui-monospace, monospace;
}
.trigger-dot {
  width: 48px;
  height: 48px;
  border-radius: 14px;
  background: linear-gradient(135deg, #a981ff, #5a2be2);
  box-shadow: 0 12px 28px rgba(102, 51, 238, 0.32);
}
.trigger-card strong { color: white; font-size: 13px; }
.trigger-card small { color: #7f86a8; font-size: 10px; text-align: center; }
@media (max-width: 500px) {
  .trigger-grid { gap: 7px; }
  .trigger-card { min-height: 174px; padding-inline: 6px; }
  .trigger-label { font-size: 8px; }
  .trigger-card small { font-size: 9px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("trigger-immediate", ".trigger-immediate .trigger-dot", {
  from: { opacity: 0.3, y: 16 },
  duration: 0.55,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("trigger-hover", ".trigger-hover .trigger-dot", {
  to: { scale: 1.25, rotate: 12, backgroundColor: "#d19cff" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ target: ".trigger-hover", onLeave: "reverse" });

Motion("trigger-click", ".trigger-click .trigger-dot", {
  to: { scale: 1.2, rotate: 180, borderRadius: 24 },
  duration: 0.45,
  ease: "back.out",
}).onClick({ target: ".trigger-click", toggle: "reverse" });`}
/>

Every timeline needs exactly one trigger. Without a trigger the timeline is built but never started.

---

## Available Triggers

Motion.page provides 8 trigger methods and 2 specialized modes.

- `.onPageLoad(config?)` — plays when DOM is ready → [Page Load](/docs/sdk/page-load)
- `.onScroll(config?)` — scroll-based playback & scrubbing → [Scroll Trigger](/docs/sdk/scroll-trigger)
- `.onHover(config?)` — plays on mouseenter/mouseleave → [Hover](/docs/sdk/hover)
- `.onClick(config?)` — toggles on click → [Click](/docs/sdk/click)
- `.onMouseMove(config?)` — cursor-driven progress → [Mouse Movement](/docs/sdk/mouse-movement)
- `.onGesture(config)` — pointer, touch & wheel gestures → [Observer & Gesture](/docs/sdk/observer-gesture)
- `.onCursor(config)` — custom animated cursor element → [Custom Cursor](/docs/sdk/custom-cursor)
- `.onPageExit(config?)` — plays before navigating → [Page Exit](/docs/sdk/page-exit)

Specialized modes:
- [ScrollTrigger Advanced](/docs/sdk/scroll-trigger-advanced) — pinning, snap, spacing & markers for `.onScroll()`
- [Presentation Mode](/docs/sdk/presentation-mode) — full-page section scrolling

---

## Quick Examples

### Play on page load

```typescript
Motion("hero", ".hero-title", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();
```

### Animate on scroll

```typescript
Motion("parallax", ".section", {
  to: { y: -100 },
  ease: "none",
}).onScroll({
  start: "top bottom",
  end: "bottom top",
  scrub: true,
});
```

### Toggle on click

```typescript
Motion("menu", "#nav-dropdown", {
  from: { height: 0, opacity: 0 },
  duration: 0.35,
  ease: "power2.inOut",
}).onClick({ target: "#menu-btn", toggle: "reverse" });
```

### React on hover

```typescript
Motion("card-lift", ".card", {
  to: { y: -8, boxShadow: "0 20px 40px rgba(0,0,0,0.2)" },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ onLeave: "reverse" });
```

---

## Related

- [Core Concepts](/docs/sdk/core-concepts) — timelines, animation config, and how triggers fit in
- [Timeline Control](/docs/sdk/timeline-control) — play, pause, seek, and reverse timelines programmatically
- [Duration & Delay](/docs/sdk/duration-delay) — control timing within animations
- [Stagger](/docs/sdk/stagger) — sequence multiple elements

---

## Skew

> Distort elements with skewX and skewY shear transforms.

URL: https://motion.page/docs/sdk/skew

import LivePreview from "../../components/docs/blocks/LivePreview";

Skew applies a **shear mapping** (transvection) that distorts each point within an element by a certain angle — tilting the shape without rotating it. Use `skewX` for horizontal distortion and `skewY` for vertical distortion. Both properties accept degrees.

## Parameters

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `skewX` | `number` | `0` | Horizontal shear angle in degrees. Positive values tilt the top-right, negative values tilt the top-left. |
| `skewY` | `number` | `0` | Vertical shear angle in degrees. Positive values tilt the bottom-left, negative values tilt the bottom-right. |

Because `skewX: 0` and `skewY: 0` are **natural CSS defaults**, you can omit `to` when animating back to the element's un-skewed state — the SDK resolves the missing endpoint automatically.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

// Animate from skewed to natural (un-skewed) state
Motion("card-in", ".card", {
  from: { skewX: 15, opacity: 0 },
  duration: 0.6,
  ease: "power3.out",
}).onPageLoad();
```

```typescript
// Skew on hover, reverse on leave
Motion("tilt", ".button", {
  to: { skewX: -8 },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

<LivePreview client:load
  height={220}
  title="Skew slide entrance"
  html={`<div class="scene"><div class="box"></div><div class="box"></div><div class="box"></div></div>`}
  css={`.scene { display: flex; flex-direction: column; gap: 12px; padding: 24px 32px; width: 100%; height: 100%; justify-content: center; box-sizing: border-box; }
.box { height: 40px; background: #6633EE; border-radius: 8px; }
.box:nth-child(1) { width: 65%; }
.box:nth-child(2) { width: 85%; }
.box:nth-child(3) { width: 52%; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("skew-in", ".box", {
  from: { x: -32, skewX: 18, opacity: 0 },
  duration: 0.55,
  stagger: 0.13,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Common Patterns

### Skew Slide Entrance

Combine `skewX` with `x` (translate) for a dynamic entrance that feels like elements are rushing in from the side.

```typescript
Motion("slide-in", ".card", {
  from: { x: -40, skewX: 20, opacity: 0 },
  duration: 0.55,
  ease: "power3.out",
  stagger: 0.1,
}).onPageLoad();
```

The skew diminishes as the element settles into place, giving it a sense of momentum and deceleration.

### Italic Text Effect

Skew the characters of a heading for a bold, editorial style — a clean alternative to CSS `font-style: italic` on non-italic typefaces.

```typescript
Motion("italic-in", "h1", {
  split: "words",
  from: { skewX: -12, opacity: 0 },
  duration: 0.5,
  ease: "power2.out",
  stagger: 0.07,
}).onPageLoad();
```

### Hover Distortion

Add a subtle skew on hover to make interactive elements feel dynamic and tactile.

```typescript
Motion("hover-skew", ".nav-link", {
  to: { skewX: -6 },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

### Combined Skew Axes

Use `skewX` and `skewY` together for a perspective-like warp effect.

```typescript
Motion("warp", ".panel", {
  from: { skewX: 10, skewY: 4, opacity: 0 },
  duration: 0.7,
  ease: "expo.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Dynamic Distortion on Scroll (Scrub)

Drive skew with scroll progress for a parallax-distortion effect.

```typescript
Motion("scroll-skew", ".hero-title", {
  from: { skewX: 0 },
  to: { skewX: 12 },
  duration: 1,
}).onScroll({ scrub: true });
```

## Combining Skew with Translate

Skew and translate pair naturally because a shear transform shifts the visual center of mass. Offsetting with `x` compensates for that shift and keeps the entrance feeling grounded.

```typescript
// The x offset counters the visual displacement caused by skew
Motion("sweep", ".feature", {
  from: { x: -60, skewX: 25, opacity: 0 },
  duration: 0.6,
  ease: "power3.out",
  stagger: { each: 0.08, from: "start" },
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

See [Translate](/docs/sdk/translate) for `x`, `y`, and `z` offset options.

## Notes

- Skew values are in **degrees**. There are no units to specify — `skewX: 15` means 15 degrees.
- Large skew angles (above ~30°) can make elements illegible. Keep values subtle (5–20°) for most UI use cases.
- `skewX: 0` and `skewY: 0` are natural CSS defaults — do not include them in a `to` block when animating from a skewed state back to normal. The SDK resolves them automatically.
- Skew affects the element's visual bounding box, which can cause it to overflow its container. Use `overflow: hidden` on the parent or pair with a [clip-path](/docs/sdk/clip-path) when needed.

---

## Fit Animation

> Morph one element's position and size to match another using FLIP-style animations.

URL: https://motion.page/docs/sdk/fit-animation

import LivePreview from "../../components/docs/blocks/LivePreview";

**Fit animation** morphs one element's geometry — position and size — to match another element's. The SDK measures both elements' bounding rects at play time and animates the visual delta between them. When `fit` is set, `from` and `to` are ignored.

## Basic Usage

Add a `fit` object to your animation config. Set `target` to a CSS selector pointing to the element you want to morph toward.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("morph", ".card", {
  fit: { target: ".modal" },
  duration: 0.6,
  ease: "power3.inOut",
}).onClick({ toggle: "reverse" });
```

The source element (`.card`) animates toward the position and size of the target element (`.modal`). Geometry is captured at **play time** using `getBoundingClientRect()`, so the page can reflow between setup and play without stale measurements.

<LivePreview client:load
  height={260}
  title="Element morphing from card to expanded view"
  html={`<div class="scene">
  <div class="slot"></div>
  <div class="card" id="card">Click me</div>
</div>`}
  css={`.scene { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; background: #0d0d0d; gap: 0; }
.slot { position: absolute; top: 30px; left: 50%; transform: translateX(-50%); width: 280px; height: 160px; border: 2px dashed #333; border-radius: 12px; }
.card { position: absolute; bottom: 40px; left: 50%; transform: translateX(-50%); width: 100px; height: 60px; background: #6633EE; border-radius: 8px; color: #fff; font-family: sans-serif; font-size: 13px; font-weight: 600; display: flex; align-items: center; justify-content: center; cursor: pointer; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("morph", "#card", {
  fit: { target: ".slot" },
  duration: 0.5,
  ease: "power3.out",
}).onClick({ target: "#card", toggle: "reverse" });`}
/>

---

## `fit` Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `target` | `string` | — | **Required.** CSS selector for the element to morph toward. Measured at play time. |
| `scale` | `boolean` | `true` | Include `scaleX`/`scaleY` transforms. Disable for position-only movement. |
| `resize` | `boolean` | `false` | Animate `width`/`height` instead of scale. No content distortion. Mutually exclusive with `scale`. |
| `absolute` | `boolean` | `false` | Animate CSS `left`/`top`/`width`/`height`. Sets `position: absolute` on the source element. |

---

## Animation Modes

Fit supports three modes depending on which CSS properties you want animated.

### Transform Mode (default)

Animates `x`, `y`, `scaleX`, and `scaleY` CSS transforms. GPU-accelerated and the most performant option. The trade-off: scaling can visually distort text, borders, and box-shadows at intermediate frames.

```typescript
Motion("morph", ".card", {
  fit: { target: ".modal" },
  duration: 0.6,
  ease: "power3.inOut",
}).onClick({ toggle: "reverse" });
```

### Resize Mode

Set `resize: true` to animate `x`, `y`, `width`, and `height` instead of scale transforms. The element physically changes size — no distortion at any point — but it triggers layout reflow on every frame. Mutually exclusive with `scale`.

```typescript
Motion("expand", ".card", {
  fit: { target: ".modal", resize: true },
  duration: 0.5,
  ease: "power2.inOut",
}).onClick({ toggle: "reverse" });
```

Use resize mode for text-heavy cards or elements with prominent borders where scale distortion would be noticeable.

### Absolute Mode

Set `absolute: true` to animate CSS `left`, `top`, `width`, and `height`. The SDK sets `position: absolute` on the source element before animating. This pulls the element out of document flow, preventing it from pushing surrounding content during the animation.

```typescript
Motion("layout", ".panel", {
  fit: { target: ".expanded", absolute: true },
  duration: 0.5,
  ease: "power2.inOut",
}).onClick({ toggle: "reverse" });
```

> **Note:** In the current version, `absolute: true` permanently sets `position: absolute` on the element — it is not reverted after the animation completes.

---

## Position Only (No Size Change)

Set `scale: false` to animate position without changing size. The source element slides to the target's center with no scaling.

```typescript
Motion("slide", ".indicator", {
  fit: { target: ".active-tab", scale: false },
  duration: 0.3,
  ease: "power2.out",
}).onClick({ toggle: "reverse" });
```

---

## Common Patterns

### Tab Indicator

A classic active-state indicator that slides and resizes to match the active tab.

```typescript
const tabs = document.querySelectorAll(".tab");

tabs.forEach((tab) => {
  tab.addEventListener("click", () => {
    Motion("tab-indicator", ".indicator", {
      fit: { target: tab as HTMLElement, resize: true },
      duration: 0.35,
      ease: "power3.inOut",
    }).play();
  });
});
```

### Card Expand to Modal

A card that morphs into a full-screen overlay on click. Use `resize: true` to avoid distorting the card's content at intermediate frames.

```typescript
Motion("card-expand", ".card-thumbnail", {
  fit: { target: ".card-fullscreen", resize: true },
  duration: 0.5,
  ease: "power2.inOut",
}).onClick({ target: ".card-thumbnail" });
```

### Grid Reorder with Stagger

Animate multiple grid items toward their new slot positions with a stagger.

```typescript
Motion("grid-reorder", ".grid-item", {
  fit: { target: ".grid-slot" },
  stagger: 0.08,
  duration: 0.5,
  ease: "power2.inOut",
}).onClick({ target: ".reorder-btn", toggle: "reverse" });
```

### Shared Element Transition

Simulate a shared-element transition between two views — the small thumbnail morphs toward the large detail view.

```typescript
// Trigger when navigating to the detail view
Motion("shared-element", ".thumbnail", {
  fit: { target: ".detail-hero", resize: true },
  duration: 0.6,
  ease: "expo.inOut",
}).play();
```

---

## Limitations

- **SVG not supported** — `fit` only works with HTML elements. Passing an SVG element as source or target logs a `[Motion Fit]` warning and the animation is skipped.
- **`from` and `to` are ignored** — when `fit` is set, any `from` or `to` properties in the config are discarded. Use a multi-step timeline if you need to combine fit with other property changes.
- **`resize` and `scale` are mutually exclusive** — setting both has no defined behavior. Use one or the other.
- **`absolute` side effect** — `absolute: true` permanently changes `position` to `absolute` on the source element, which can affect surrounding layout.

---

## API Reference

```typescript
interface FitConfig {
  /** CSS selector for the target element to morph toward. Measured at play time via getBoundingClientRect(). */
  target: string;
  /** Include scaleX/scaleY transforms. Default: true. May distort text, borders, and shadows. */
  scale?: boolean;
  /** Animate width/height instead of scale. No distortion, but triggers layout reflow. Mutually exclusive with scale. Default: false. */
  resize?: boolean;
  /** Use position: absolute during animation. Animates left/top/width/height. Prevents layout shifts. Default: false. */
  absolute?: boolean;
}

interface AnimationConfig {
  // When set, `from` and `to` are ignored
  fit?: FitConfig;
}
```

---

Related: [Scale](/docs/sdk/scale) · [Translate](/docs/sdk/translate) · [Dimensions](/docs/sdk/dimensions) · [Stagger](/docs/sdk/stagger)

---

## Rotation

> Rotate elements in 2D with degree values.

URL: https://motion.page/docs/sdk/rotation

import LivePreview from "../../components/docs/blocks/LivePreview";

**Rotation** spins elements around a pivot point. Use `rotate` for standard 2D rotation, or `rotateX` / `rotateY` for 3D perspective tilts. All values are in degrees — no unit suffix needed.

## Basic Rotation

Pass `rotate` inside `from` or `to`. Positive values spin **clockwise**, negative values spin **counter-clockwise**.

```typescript
import { Motion } from "@motion.page/sdk";

// Spin in from 90° clockwise
Motion("spin-in", ".icon", {
  from: { rotate: 90, opacity: 0 },
  duration: 0.5,
  ease: "power3.out",
}).onPageLoad();
```

Because `rotate: 0` is a **natural CSS default**, omitting `to` is correct here — the SDK resolves the missing endpoint automatically and animates the element back to its un-rotated state.

## Direction

| Value | Direction |
|-------|-----------|
| Positive (`rotate: 45`) | Clockwise |
| Negative (`rotate: -45`) | Counter-clockwise |

```typescript
// Counter-clockwise entrance
Motion("spin-ccw", ".arrow", {
  from: { rotate: -90, opacity: 0 },
  duration: 0.4,
  ease: "expo.out",
}).onPageLoad();
```

## Full Rotations

Use multiples of `360` to spin the element one or more complete turns.

```typescript
// One full clockwise spin
Motion("spin-once", ".logo", {
  from: { rotate: 0 },
  to: { rotate: 360 },
  duration: 1,
  ease: "power2.inOut",
}).onClick({ each: true });
```

A value of `360` is one full turn, `720` is two full turns, `-360` is one full counter-clockwise turn, and so on.

<LivePreview client:load
  height={200}
  title="Continuous spinner"
  html={`<div class="scene"><div class="box"></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 8px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("spinner", ".box", {
  to: { rotate: 360 },
  duration: 1.2,
  ease: "none",
  repeat: -1,
}).play();`}
/>

## Transform Origin

Rotation always pivots around the **transform origin** — by default the element's center (`50% 50%`). Change this with `transformOrigin` to spin from a corner, edge, or any custom point.

| Value | Pivot point |
|-------|-------------|
| `'center'` | Center of the element (default) |
| `'top left'` | Top-left corner (`0% 0%`) |
| `'bottom right'` | Bottom-right corner (`100% 100%`) |
| `'0% 100%'` | Bottom-left corner |
| `'50% 0%'` | Top center |

```typescript
// Spin from the bottom-left corner (like a clock hand)
Motion("clock-hand", ".needle", {
  from: { rotate: -30, transformOrigin: "0% 100%" },
  to: { rotate: 30 },
  duration: 0.8,
  ease: "power2.inOut",
}).onPageLoad();
```

See the [Transform Origin](/docs/sdk/transform-origin) page for all supported values and examples.

## Combining with Other Transforms

Rotation pairs naturally with `scale` and `opacity` to create richer entrance effects.

```typescript
// Scale + rotate for a spiral entrance
Motion("spiral-in", ".card", {
  from: { scale: 0, rotate: 180, opacity: 0 },
  duration: 0.6,
  ease: "back.out(1.4)",
}).onPageLoad();
```

```typescript
// Fade + rotate for a spin-in reveal
Motion("spin-fade", ".badge", {
  from: { rotate: -45, opacity: 0 },
  duration: 0.4,
  ease: "power3.out",
  stagger: 0.1,
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

## Common Patterns

### Spinner

An infinitely rotating element using `repeat: -1` and a linear ease for constant speed.

```typescript
Motion("spinner", ".loader", {
  from: { rotate: 0 },
  to: { rotate: 360 },
  duration: 1,
  ease: "none",
  repeat: -1,
}).onPageLoad();
```

### Wiggle

Alternate between small positive and negative angles with `yoyo: true` for an attention-grabbing shake.

```typescript
Motion("wiggle", ".notification", {
  to: { rotate: 12 },
  duration: 0.12,
  ease: "power1.inOut",
  repeat: { times: 5, yoyo: true },
}).onPageLoad();
```

`yoyo: true` reverses the animation on each cycle, rocking the element back and forth without any hard reset.

### Spiral In

Combine `scale: 0` with `rotate: 180` so the element grows and unwinds into its natural state simultaneously.

```typescript
Motion("spiral-in", ".icon", {
  from: { scale: 0, rotate: 180, opacity: 0 },
  duration: 0.7,
  ease: "expo.out",
}).onPageLoad();
```

Because `rotate: 0`, `scale: 1`, and `opacity: 1` are all natural CSS defaults, omitting `to` is correct — the SDK fills in the endpoints automatically.

### Hover Spin

Rotate an icon a quarter-turn on hover and reverse on leave.

```typescript
Motion("hover-spin", ".arrow-icon", {
  to: { rotate: 90 },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

### Scroll-Driven Rotation

Drive rotation with scroll progress for a parallax feel.

```typescript
Motion("scroll-rotate", ".decorative-ring", {
  from: { rotate: 0 },
  to: { rotate: 360 },
  duration: 1,
}).onScroll({ scrub: true });
```

## Notes

- Values are in **degrees**. `rotate: 90` means 90 degrees — no unit suffix.
- `rotate: 0` is the natural CSS default. Do not include `to: { rotate: 0 }` when animating from a rotated state back to normal — the SDK resolves it automatically.
- For 3D perspective tilts, use `rotateX` (tilt toward/away) and `rotateY` (tilt left/right). These require a `perspective` set on the parent element in CSS.
- Combining `repeat: -1` with `ease: "none"` (or `ease: "linear"`) produces the smoothest continuous spinner — eased repeats will stutter at the loop boundary.
- Large rotation values on text or images can cause subpixel rendering artifacts. Prefer `will-change: transform` on elements that animate frequently.

---

## CSS Filters

> Apply animated blur, grayscale, brightness, contrast, and other CSS filter effects.

URL: https://motion.page/docs/sdk/filters

import LivePreview from "../../components/docs/blocks/LivePreview";

The `filter` property animates CSS filter effects — blur, brightness, contrast, and more. Pass a standard CSS filter string to `from` or `to`.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

Motion("blur-in", ".element", {
  from: { filter: "blur(10px)" },
  duration: 0.8,
  ease: "power2.out",
}).play();
```

Since an element's natural CSS has no filter applied (equivalent to `none`), using `from` only is sufficient — the SDK reads the current computed state as the `to` endpoint automatically.

<LivePreview client:load
  height={220}
  title="Blur-in reveal"
  html={`<div style="display:flex;gap:16px;justify-content:center;align-items:center;height:100%;padding:20px;"><div class="box" style="width:100px;height:100px;border-radius:12px;background:linear-gradient(135deg,#6633EE,#3366FF);"></div><div class="box" style="width:100px;height:100px;border-radius:12px;background:linear-gradient(135deg,#EE3366,#FF6633);"></div><div class="box" style="width:100px;height:100px;border-radius:12px;background:linear-gradient(135deg,#33EE66,#33BBFF);"></div></div>`}
  css={``}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("blur-in", ".box", {
  from: { opacity: 0, filter: "blur(12px)" },
  duration: 0.6,
  stagger: 0.15,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Available Filter Functions

| Function | Example | Description |
|----------|---------|-------------|
| `blur()` | `blur(10px)` | Gaussian blur |
| `brightness()` | `brightness(1.5)` | Adjust brightness (`1` = normal) |
| `contrast()` | `contrast(200%)` | Adjust contrast (`100%` = normal) |
| `grayscale()` | `grayscale(100%)` | Convert to grayscale (`0%` = normal) |
| `hue-rotate()` | `hue-rotate(90deg)` | Rotate hue along the color wheel |
| `invert()` | `invert(100%)` | Invert colors |
| `saturate()` | `saturate(200%)` | Adjust saturation (`100%` = normal) |
| `sepia()` | `sepia(100%)` | Apply sepia tone |
| `opacity()` | `opacity(50%)` | Adjust opacity via filter (`100%` = fully visible) |
| `drop-shadow()` | `drop-shadow(4px 4px 10px rgba(0,0,0,0.5))` | Add a drop shadow |

> **Note:** In the Motion.page Builder, filters are configured via the Filter property panel where each filter type has its own dedicated control. The SDK accepts the CSS filter string directly.

## Combining Multiple Filters

Chain multiple filter functions in a single string, separated by spaces. The SDK interpolates each function value independently.

```typescript
Motion("dramatic", ".hero-image", {
  from: { filter: "blur(8px) brightness(0.6) saturate(0)" },
  duration: 1.2,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

## Common Patterns

### Blur + Opacity Reveal

The classic "blur in" pattern combines `filter` blur with [opacity](/docs/sdk/opacity) for a polished entrance:

```typescript
Motion("blur-reveal", ".card", {
  from: { opacity: 0, filter: "blur(12px)" },
  duration: 0.8,
  stagger: 0.1,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Grayscale to Color on Hover

```typescript
Motion("colorize", ".photo", {
  from: { filter: "grayscale(100%)" },
  duration: 0.5,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

Using `from` only means the element starts fully grayscale and animates to its natural (unfiltered) state on hover. On leave, the animation reverses back to grayscale.

### Brightness Pulse

```typescript
Motion("pulse", ".cta-button", {
  to: { filter: "brightness(1.3)" },
  duration: 0.6,
  repeat: { times: -1, yoyo: true },
}).play();
```

## Explicit Both Endpoints

When neither endpoint matches the element's natural state, declare both `from` and `to`:

```typescript
Motion("filter-shift", ".banner", {
  from: { filter: "hue-rotate(0deg) saturate(100%)" },
  to: { filter: "hue-rotate(180deg) saturate(200%)" },
  duration: 2,
}).onScroll({ scrub: true });
```

This is the right pattern for scrubbed scroll animations where you want precise control over both the start and end filter state.

## Performance

- CSS filter animations are GPU-accelerated in most browsers, making them performant for visual effects.
- `blur()` and `drop-shadow()` are the most computationally expensive filters — use moderate values and test on lower-end devices.
- When animating opacity alone, prefer the dedicated `opacity` AnimationVar over the `opacity()` filter function — see [Opacity](/docs/sdk/opacity) for details.

---

## Multi-Step Sequencing

> Build complex timelines with multiple steps and the position parameter.

URL: https://motion.page/docs/sdk/sequencing

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

Multi-step timelines let you chain animations on different targets into a single, coordinated sequence. Each step runs on its own element with its own timing, and the `position` parameter gives you precise control over when each step starts relative to the others.

## The array config format

Pass an array of animation entries as the second argument instead of a target and config object. Each entry can target a different element and carry its own `from`, `to`, `duration`, and `ease`.

<CodeBlock
  filename="sequence.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

Motion("intro", [
  { target: ".hero-title",    from: { opacity: 0, y: 40 }, duration: 0.7, ease: "power2.out" },
  { target: ".hero-subtitle", from: { opacity: 0, y: 30 }, duration: 0.6, ease: "power2.out" },
  { target: ".hero-cta",      from: { opacity: 0, y: 20 }, duration: 0.5, ease: "power2.out" },
]).onPageLoad();`}
/>

By default, each step begins immediately after the previous one ends — a pure sequential chain.

## Animation entry shape

Every entry in the array accepts the same properties as a single `AnimationConfig`, plus `target` and `position`:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `target` | `TargetInput` | — | CSS selector, `Element`, `NodeList`, or `Element[]` |
| `from` | `AnimationVars` | — | Start values |
| `to` | `AnimationVars` | — | End values |
| `duration` | `number` | `0.5` | Seconds for this step |
| `delay` | `number` | `0` | Seconds to wait before this step's own start |
| `ease` | `string` | `"power1.inOut"` | Easing for this step |
| `stagger` | `number \| StaggerVars` | — | Per-element stagger when `target` matches multiple elements |
| `position` | `number \| string` | — | When this step starts — see position syntax below |

## Position syntax

`position` controls where in the timeline a step is placed. When omitted, steps play back-to-back.

| Value | Meaning |
|-------|---------|
| `0.5` | 0.5 s from the timeline start (absolute time) |
| `"+=0.5"` | 0.5 s after the previous step ends |
| `"-=0.3"` | 0.3 s before the previous step ends (overlap) |
| `">"` | Immediately after the previous step ends (same as default) |
| `"<"` | Same start time as the previous step (parallel) |
| `"<0.2"` | 0.2 s after the **start** of the previous step |
| `">-0.1"` | 0.1 s before the **end** of the previous step |

## Sequential timing

The default behaviour — each step waits for the previous one to finish:

<CodeBlock
  filename="sequential.ts"
  lang="typescript"
  code={`Motion("sequential", [
  { target: ".box-a", from: { x: -100, opacity: 0 }, duration: 0.5, ease: "power2.out" },
  { target: ".box-b", from: { x: -100, opacity: 0 }, duration: 0.5, ease: "power2.out" },
  { target: ".box-c", from: { x: -100, opacity: 0 }, duration: 0.5, ease: "power2.out" },
]).onPageLoad();
// Total duration: 1.5 s  (0.5 + 0.5 + 0.5)`}
/>

## Overlapping steps

Use `"-=N"` to pull a step back in time so it overlaps the one before it. This tightens the overall feel without making things feel simultaneous:

<CodeBlock
  filename="overlapping.ts"
  lang="typescript"
  code={`Motion("staggered-overlap", [
  { target: ".card-1", from: { opacity: 0, y: 50 }, duration: 0.6, ease: "power2.out" },
  { target: ".card-2", from: { opacity: 0, y: 50 }, duration: 0.6, ease: "power2.out", position: "-=0.4" },
  { target: ".card-3", from: { opacity: 0, y: 50 }, duration: 0.6, ease: "power2.out", position: "-=0.4" },
]).onPageLoad();
// Total duration: 1.0 s  — each card starts 0.2 s after the previous`}
/>

## Parallel steps

`"<"` starts a step at exactly the same time as the previous one. Use it to animate multiple properties or elements simultaneously:

<CodeBlock
  filename="parallel.ts"
  lang="typescript"
  code={`Motion("hero-entrance", [
  // Title fades + slides up
  { target: ".title",    from: { opacity: 0, y: 40 }, duration: 0.8, ease: "power3.out" },
  // Image scales in at the same moment
  { target: ".image",   from: { opacity: 0, scale: 0.9 }, duration: 0.8, ease: "power2.out", position: "<" },
  // Badge appears 0.3 s after both start
  { target: ".badge",   from: { opacity: 0, scale: 0 }, duration: 0.4, ease: "back.out", position: "<0.3" },
]).onPageLoad();`}
/>

## Absolute positioning

An absolute number places a step at a fixed point in the timeline, regardless of what came before:

<CodeBlock
  filename="absolute.ts"
  lang="typescript"
  code={`Motion("timed-sequence", [
  { target: ".step-1", from: { opacity: 0 }, duration: 0.5 },
  // Always starts at exactly 1 s, no matter what step-1 does
  { target: ".step-2", from: { opacity: 0 }, duration: 0.5, position: 1 },
  // Always starts at exactly 2 s
  { target: ".step-3", from: { opacity: 0 }, duration: 0.5, position: 2 },
]).onPageLoad();`}
/>

## Adding a gap between steps

`"+=N"` adds extra breathing room after the previous step ends:

<CodeBlock
  filename="gap.ts"
  lang="typescript"
  code={`Motion("with-pauses", [
  { target: ".reveal-1", from: { opacity: 0, y: 30 }, duration: 0.6, ease: "power2.out" },
  // 0.3 s pause, then the next step plays
  { target: ".reveal-2", from: { opacity: 0, y: 30 }, duration: 0.6, ease: "power2.out", position: "+=0.3" },
]).onPageLoad();`}
/>

<LivePreview
  client:load
  height={220}
  title="Multi-step overlapping sequence"
  html={`<div class="scene">
  <div class="box box-a"></div>
  <div class="box box-b"></div>
  <div class="box box-c"></div>
</div>`}
  css={`.scene {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 20px;
  height: 100%;
}
.box {
  width: 72px;
  height: 72px;
  border-radius: 12px;
}
.box-a { background: #6633EE; }
.box-b { background: #9955FF; }
.box-c { background: #CC88FF; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("sequence", ".box", {
  from: { opacity: 0, y: 40 },
  duration: 0.55,
  stagger: 0.25,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Mixing targets and triggers

Multi-step timelines work with every trigger method. A scroll-triggered sequence, for example:

<CodeBlock
  filename="scroll-sequence.ts"
  lang="typescript"
  code={`Motion("features", [
  { target: ".feature-icon",  from: { opacity: 0, scale: 0.6 }, duration: 0.5, ease: "back.out" },
  { target: ".feature-title", from: { opacity: 0, x: -20 },     duration: 0.4, ease: "power2.out", position: "<0.15" },
  { target: ".feature-body",  from: { opacity: 0, x: -20 },     duration: 0.4, ease: "power2.out", position: "<0.1" },
]).onScroll({ scrub: false, toggleActions: "play none none none" });`}
/>

## Tips

**Each step re-reads natural CSS.** The `from`/`to` resolution rules apply per entry — if you only supply `from`, the SDK reads the element's current computed style as `to`. See [Duration & Delay](/docs/sdk/duration-delay) for timing basics.

**Per-step stagger works normally.** If a step's `target` matches multiple elements, add `stagger` to that entry and it fans out exactly as in a single-animation config.

**`delay` inside an entry is local.** `delay` on an entry shifts that step's start relative to its `position`, not relative to the global timeline. Use `position` for timeline-level placement and `delay` for fine-tuning within a step.

**Looping the whole sequence.** Chain `.withRepeat(-1)` after the `Motion(...)` call to loop the entire multi-step timeline indefinitely:

<CodeBlock
  lang="typescript"
  code={`Motion("looping-sequence", [
  { target: ".dot-1", to: { scale: 1.4 }, duration: 0.3, ease: "power2.out" },
  { target: ".dot-2", to: { scale: 1.4 }, duration: 0.3, ease: "power2.out" },
  { target: ".dot-3", to: { scale: 1.4 }, duration: 0.3, ease: "power2.out" },
])
  .withRepeat({ times: -1, yoyo: true })
  .onPageLoad();`}
/>

---

Related: [Duration & Delay](/docs/sdk/duration-delay) · [Stagger](/docs/sdk/stagger) · [Core Concepts](/docs/sdk/core-concepts)

---

## Colors

> Animate background color, text color, and border color.

URL: https://motion.page/docs/sdk/colors

import LivePreview from "../../components/docs/blocks/LivePreview";

Color animation lets you transition any color property — background, text, border, or SVG — between any two CSS color values. The SDK handles the interpolation, so you can mix formats freely across `from` and `to`.

## Basic Usage

Use `backgroundColor`, `color`, or `borderColor` inside `from` or `to`. Provide only the endpoint that differs from the element's natural CSS state.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("highlight", ".card", {
  from: { backgroundColor: "#1a1a2e" },
  to: { backgroundColor: "#6633EE" },
  duration: 0.6,
}).play();
```

Because neither value matches the element's natural CSS here, both `from` and `to` are specified explicitly. When animating **to** a color that matches the element's existing CSS, omit `to` and let the SDK resolve it automatically.

## Color Properties

| Property | Description |
|----------|-------------|
| `backgroundColor` | Animate the background color |
| `color` | Animate the font color |
| `borderColor` | Animate the border color |
| `fill` | SVG fill color |
| `stroke` | SVG stroke color |

> **Note:** `borderColor` is not listed as a first-class `AnimationVars` property but works seamlessly at runtime through the SDK's CSS property support. Use it the same way as `backgroundColor`.

## Supported Color Formats

The SDK interpolates between any combination of these formats — no conversion needed on your end.

| Format | Example |
|--------|---------|
| Hex (full) | `#6633EE` |
| Hex (short) | `#63E` |
| RGB | `rgb(102, 51, 238)` |
| RGBA | `rgba(102, 51, 238, 0.5)` |
| HSL | `hsl(260, 84%, 57%)` |
| HSLA | `hsla(260, 84%, 57%, 0.5)` |
| Named | `rebeccapurple`, `tomato`, `coral` |

<LivePreview client:load
  height={200}
  title="Background color shift"
  html={`<div class="scene"><div class="box"></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 120px; height: 120px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("color-cycle", ".box", {
  from: { backgroundColor: "#6633EE" },
  to: { backgroundColor: "#00D4FF" },
  duration: 1.5,
  ease: "sine.inOut",
  repeat: { times: -1, yoyo: true },
}).play();`}
/>

## Common Patterns

### Theme Transition

Swap background and text color simultaneously for a dark-to-light effect.

```typescript
Motion("theme", ".section", {
  from: { backgroundColor: "#0f0f0f", color: "#ffffff" },
  to: { backgroundColor: "#ffffff", color: "#0f0f0f" },
  duration: 0.5,
  ease: "power2.inOut",
}).onScroll({ scrub: true });
```

Both properties animate in parallel — the background lightens as the text darkens.

### Hover Color Change

Use `.onHover()` with `each: true` so each element responds to its own hover independently.

```typescript
Motion("btn-color", ".btn", {
  to: { backgroundColor: "#6633EE", color: "#ffffff" },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

`onLeave: "reverse"` plays the animation backwards on mouse out, returning each button to its original CSS color without needing a `from` value.

### Color Cycling with Repeat

Cycle infinitely between colors using `yoyo` to reverse the animation on each pass.

```typescript
Motion("pulse-color", ".badge", {
  from: { backgroundColor: "#6633EE" },
  to: { backgroundColor: "#FF6B6B" },
  duration: 1,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

## SVG Colors

Use `fill` and `stroke` to animate colors on SVG elements. These properties target the SVG paint attributes directly, separate from the CSS `color` and `background`.

```typescript
Motion("icon-fill", "svg path", {
  from: { fill: "#999999" },
  to: { fill: "#6633EE" },
  duration: 0.4,
}).onHover({ each: true, onLeave: "reverse" });
```

You can animate both together — for example, changing `fill` while also revealing a `stroke` outline:

```typescript
Motion("icon-active", "svg path", {
  to: { fill: "#6633EE", stroke: "#ffffff" },
  duration: 0.3,
  ease: "power2.out",
}).onClick({ each: true });
```

## Tips

- The SDK interpolates between **any combination of color formats** — you can go from a hex `from` to an `hsl()` `to` without issues.
- Animate **multiple color properties simultaneously** by including them all in the same `from`/`to` object.
- Use `from`-only when animating **to** the element's natural CSS color — the SDK reads the existing value and uses it as the endpoint automatically.
- To animate color **and** transparency together, use `rgba()` or `hsla()` strings rather than animating `opacity` separately — this avoids affecting child element visibility.

See also: [Opacity](/docs/sdk/opacity) for transparency effects, and [SVG](/docs/sdk/svg) for drawing and path animations on SVG elements.

---

## Clip Path

> Reveal and mask elements with animated CSS clip-path.

URL: https://motion.page/docs/sdk/clip-path

import LivePreview from "../../components/docs/blocks/LivePreview";

**Clip path** masks portions of an element using CSS `clip-path`, letting you reveal or hide content by animating the shape of the visible region. Use it for circle reveals, diagonal wipes, polygon morphs, and any geometry-driven entrance or exit effect.

## Basic Usage

Pass `'clip-path'` (or `clipPath`) inside `from` and/or `to`. Both endpoints must use the **same shape function** for smooth interpolation.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reveal", "#hero", {
  from: { "clip-path": "circle(0% at 50% 50%)" },
  to:   { "clip-path": "circle(75% at 50% 50%)" },
  duration: 1,
  ease: "power2.out",
}).onPageLoad();
```

<LivePreview client:load
  height={220}
  title="Circle reveal from center"
  html={`<div class="scene"><div class="box"><span>Hello</span></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #111; }
.box { width: 160px; height: 160px; background: linear-gradient(135deg, #6633EE, #a855f7); border-radius: 16px; display: flex; align-items: center; justify-content: center; }
.box span { color: #fff; font-size: 18px; font-weight: 600; font-family: sans-serif; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("reveal", ".box", {
  from: { clipPath: "circle(0% at 50% 50%)" },
  to: { clipPath: "circle(75% at 50% 50%)" },
  duration: 0.9,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Supported Shapes

| Shape | Example |
|-------|---------|
| `circle` | `'circle(50% at 50% 50%)'` |
| `ellipse` | `'ellipse(60% 30% at 50% 50%)'` |
| `inset` | `'inset(10px 20px round 8px)'` |
| `polygon` | `'polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)'` |
| `rect` | `'rect(10px 90px 90px 10px)'` |
| `xywh` | `'xywh(10% 10% 80% 80%)'` |

## Property Name

Both forms are equivalent — use whichever fits your style:

```typescript
// kebab-case (quoted)
from: { "clip-path": "circle(0% at 50% 50%)" }

// camelCase
from: { clipPath: "circle(0% at 50% 50%)" }
```

The SDK also automatically writes `-webkit-clip-path` alongside `clip-path` for **Safari compatibility** — you don't need to set it manually.

## Interpolation Rules

For smooth animation between two states:

- **Same shape on both ends** — `circle → circle`, `polygon → polygon`. Mixing shapes (e.g. `circle → inset`) causes a hard swap at progress ≥ 0.5.
- **Polygon vertex counts must match** — `polygon(0% 0%, 100% 0%, 100% 100%)` (3 vertices) cannot smoothly tween to a 4-vertex polygon.
- **Units are preserved** — mix of `%` and `px` values within a shape is fine, but the same unit should be used for each corresponding coordinate between `from` and `to`.

## From-Only / To-Only

Like all SDK properties, you can supply just one endpoint and the SDK reads the other from the element's **computed CSS**:

```typescript
// from-only — element has clip-path set in CSS, animate into it
Motion("reveal", ".card", {
  from: { clipPath: "inset(100% 0% 0% 0%)" },
  duration: 0.7,
  ease: "power3.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });

// to-only — animate away from the element's natural clip-path
Motion("hide", ".card", {
  to: { clipPath: "inset(0% 0% 100% 0%)" },
  duration: 0.5,
  ease: "power2.in",
}).onClick({ each: true });
```

## Shape Examples

### Circle Reveal

Expand a circle from the center — the classic reveal effect.

```typescript
Motion("circle-reveal", "#hero", {
  from: { "clip-path": "circle(0% at 50% 50%)" },
  to:   { "clip-path": "circle(75% at 50% 50%)" },
  duration: 1,
  ease: "power2.out",
}).onPageLoad();
```

### Ellipse

Expand an ellipse from a custom focal point.

```typescript
Motion("ellipse-in", ".banner", {
  from: { clipPath: "ellipse(0% 0% at 50% 50%)" },
  to:   { clipPath: "ellipse(80% 60% at 50% 50%)" },
  duration: 0.9,
  ease: "power3.out",
}).onPageLoad();
```

### Inset

`inset` clips all four edges simultaneously. Shrink from all sides to reveal content.

```typescript
Motion("inset-reveal", ".image", {
  from: { "clip-path": "inset(50% round 8px)" },
  to:   { "clip-path": "inset(0% round 8px)" },
  duration: 0.8,
  ease: "expo.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Polygon Diagonal Wipe (Hover)

Morph a polygon on hover for a sharp diagonal wipe effect.

```typescript
Motion("wipe", ".card", {
  from: { clipPath: "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)" },
  to:   { clipPath: "polygon(100% 0%, 100% 0%, 100% 100%, 100% 100%)" },
  duration: 0.4,
  ease: "power2.inOut",
}).onHover({ each: true, onLeave: "reverse" });
```

### rect

`rect` specifies the clipping rectangle using top, right, bottom, and left edge values.

```typescript
Motion("rect-reveal", ".panel", {
  from: { "clip-path": "rect(50% 50% 50% 50%)" },
  to:   { "clip-path": "rect(0% 100% 100% 0%)" },
  duration: 0.7,
  ease: "power2.out",
}).onPageLoad();
```

### xywh

`xywh` defines the clip region by x offset, y offset, width, and height — useful when you know the dimensions of the visible area you want.

```typescript
Motion("xywh-reveal", ".feature", {
  from: { clipPath: "xywh(50% 50% 0% 0%)" },
  to:   { clipPath: "xywh(0% 0% 100% 100%)" },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();
```

## Common Patterns

### Circle Reveal on Page Load

The most common use case — reveal a hero section or image with an expanding circle.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("hero-reveal", "#hero", {
  from: { "clip-path": "circle(0% at 50% 50%)" },
  to:   { "clip-path": "circle(150% at 50% 50%)" },
  duration: 1.2,
  ease: "power2.out",
}).onPageLoad();
```

Using `150%` guarantees the circle covers the full element regardless of its aspect ratio.

### Diagonal Wipe on Hover

Reveal a card overlay with a triangle wipe driven by hover.

```typescript
Motion("card-wipe", ".card .overlay", {
  from: { clipPath: "polygon(0% 0%, 0% 0%, 0% 100%, 0% 100%)" },
  to:   { clipPath: "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)" },
  duration: 0.5,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

### Polygon Morph (Shape Shifting)

Smoothly morph between two polygon shapes — vertex count must be identical.

```typescript
Motion("morph", ".blob", {
  from: { clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)" },
  to:   { clipPath: "polygon(25% 0%, 75% 25%, 100% 75%, 25% 100%)" },
  duration: 2,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

Both shapes here use 4 vertices — the morph is smooth because the vertex counts match.

## Related

- [Opacity](/docs/sdk/opacity) — fade elements in and out
- [Scale](/docs/sdk/scale) — grow or shrink elements
- [SVG](/docs/sdk/svg) — animate SVG paths and stroke effects

---

## Motion Path

> Animate elements along SVG paths with auto-rotation and alignment.

URL: https://motion.page/docs/sdk/motion-path

import LivePreview from "../../components/docs/blocks/LivePreview";

**Motion path** moves an element along an SVG path during an animation. The element travels from one point on the path to another, optionally rotating to follow the direction of travel.

## Basic Usage

Add a `path` object inside `to` (or `from`). Set `target` to a CSS selector pointing to a `<path>` element in the DOM.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("follow", ".dot", {
  to: { path: { target: "#track" } },
  duration: 2,
  ease: "power2.inOut",
}).onPageLoad();
```

The element moves from the start of the path (`0`) to the end (`1`) over the animation duration.

<LivePreview client:load
  height={260}
  title="Element following a motion path"
  html={`<div class="scene">
  <svg class="track-svg" viewBox="0 0 400 160" xmlns="http://www.w3.org/2000/svg">
    <path id="track" d="M 20 80 C 80 20, 160 140, 240 80 C 320 20, 360 100, 380 80" fill="none" stroke="#2a2a2a" stroke-width="2" stroke-dasharray="6 4"/>
  </svg>
  <div class="dot"></div>
</div>`}
  css={`.scene { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; }
.track-svg { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); width: 400px; }
.dot { width: 18px; height: 18px; border-radius: 50%; background: #6633EE; position: absolute; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("follow", ".dot", {
  to: { path: { target: "#track", align: "#track" } },
  duration: 2,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

---

## `path` Config

The `path` object is set as a property inside `from` or `to`.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `target` | `string \| Element` | — | **Required.** CSS selector pointing to a DOM `<path>`, or raw SVG path data (a string starting with `M` or `m`) |
| `align` | `string \| Element` | — | Snap the element onto the path by aligning its bounding box to this selector or element. Use `"self"` to align to the animated element itself |
| `alignAt` | `[number, number]` | `[50, 50]` | The origin point on the element that aligns to the path, as `[x%, y%]` percentages |
| `start` | `number` | `0` | Path start position as a fraction `0–1` |
| `end` | `number` | `1` | Path end position as a fraction `0–1` |
| `rotate` | `boolean` | — | When `true`, the element auto-rotates to follow the tangent direction of the path |

---

## Targeting a DOM Path

Point `target` at a `<path>` element already in the SVG markup. The element is invisible to the user — it only guides the animation.

```typescript
// HTML: <svg><path id="route" d="M 0 100 C 150 0 300 200 450 100" /></svg>

Motion("car", ".car-icon", {
  to: { path: { target: "#route", rotate: true } },
  duration: 3,
  ease: "power1.inOut",
}).onPageLoad();
```

---

## Raw SVG Path Data

Pass a path `d` attribute string directly as `target` — no DOM element required. The string must start with `M` or `m`.

```typescript
Motion("wave", ".particle", {
  to: {
    path: {
      target: "M 0 200 C 100 100 200 300 300 200 C 400 100 500 300 600 200",
      rotate: false,
    },
  },
  duration: 3,
  ease: "power2.inOut",
}).play();
```

---

## Auto-Rotate

Set `rotate: true` to make the element turn so it always faces along the path's direction of travel. Essential for arrows, cars, planes, or any element where orientation matters.

```typescript
Motion("orbit", ".arrow", {
  to: { path: { target: "#orbit-path", rotate: true } },
  duration: 4,
  ease: "linear",
  repeat: -1,
}).play();
```

<LivePreview client:load
  height={260}
  title="Auto-rotate along path"
  html={`<div class="scene">
  <svg class="track-svg" viewBox="0 0 300 300" xmlns="http://www.w3.org/2000/svg">
    <ellipse cx="150" cy="150" rx="110" ry="70" fill="none" stroke="#222" stroke-width="2" stroke-dasharray="6 4"/>
    <path id="orbit-path" d="M 260 150 A 110 70 0 1 1 259.99 149.99" fill="none" stroke="none"/>
  </svg>
  <div class="arrow">→</div>
</div>`}
  css={`.scene { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; }
.track-svg { position: absolute; width: 300px; height: 300px; }
.arrow { font-size: 22px; position: absolute; color: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("orbit", ".arrow", {
  to: { path: { target: "#orbit-path", align: "#orbit-path", rotate: true } },
  duration: 3,
  ease: "none",
  repeat: -1,
}).play();`}
/>

---

## Align to Path

The `align` property snaps the element's bounding box onto the path, so the animation starts exactly where the path begins. Without it, the element may appear to jump at the start of the animation.

```typescript
Motion("badge", ".badge", {
  to: {
    path: {
      target: "#guide-path",
      align: "#guide-path",  // Align element origin to path origin
      rotate: true,
    },
  },
  duration: 2,
  ease: "power2.inOut",
}).onPageLoad();
```

Use `"self"` to align relative to the animated element itself:

```typescript
to: {
  path: {
    target: "#route",
    align: "self",
  },
}
```

### Origin Point with `alignAt`

`alignAt` controls which point on the element is placed on the path. Values are `[x%, y%]`, defaulting to `[50, 50]` (center). Use `[0, 0]` to align by the top-left corner, or `[50, 100]` to align by the bottom-center.

```typescript
to: {
  path: {
    target: "#route",
    align: "#route",
    alignAt: [50, 100],  // Anchor at bottom-center of the element
    rotate: true,
  },
}
```

---

## Partial Path with `start` and `end`

Use `start` and `end` to animate over only a portion of the path. Both accept fractions from `0` to `1`.

```typescript
// Animate the middle third of the path
Motion("segment", ".dot", {
  to: {
    path: {
      target: "#full-path",
      start: 0.33,
      end: 0.66,
    },
  },
  duration: 1.5,
  ease: "power2.inOut",
}).onPageLoad();
```

This is useful for step-by-step reveals, progress indicators, or multi-stage animations where different elements cover different segments of the same path.

---

## Scrubbed on Scroll

Combine motion path with `.onScroll({ scrub: true })` to drive the element's position along the path with the scrollbar.

```typescript
Motion("scroll-path", ".marker", {
  to: {
    path: {
      target: "#timeline-path",
      rotate: true,
    },
  },
  duration: 1,
}).onScroll({
  scrub: true,
  start: "top center",
  end: "bottom center",
});
```

---

## Looping Orbit

Use `repeat: -1` with `ease: "linear"` for a smooth, infinite loop along a closed path.

```typescript
Motion("orbit", ".satellite", {
  to: { path: { target: "#orbit-path", rotate: true } },
  duration: 6,
  ease: "linear",
  repeat: -1,
}).onPageLoad();
```

For a closed path (one where start and end points meet), `"linear"` easing ensures there is no speed variation and the loop is seamless.

---

## Multi-Step Timeline

Animate multiple elements along paths in sequence using a multi-step timeline.

```typescript
Motion("journey", "#map", [
  {
    target: ".marker",
    to: { path: { target: "#segment-a", rotate: true } },
    duration: 1.5,
    ease: "power2.inOut",
  },
  {
    target: ".marker",
    to: { path: { target: "#segment-b", rotate: true } },
    duration: 1.5,
    ease: "power2.inOut",
    position: "+=0.2",
  },
]).onPageLoad();
```

---

## Tips

- **The SVG `<path>` can be hidden** — set `fill: none; stroke: none; visibility: hidden` in CSS. It only needs to exist in the DOM for its `d` attribute to be read.
- **Raw path data is coordinate-space dependent** — when passing a path string directly, make sure the coordinates match your layout. DOM path selectors are safer because coordinates are resolved from the element's actual position.
- **`rotate: true` is essential for directional elements** — arrows, vehicles, and cursors look wrong without it because they always point the same direction.
- **Combine with `opacity`** — fade the element in at the start of a path animation to avoid a sudden appearance by adding `from: { opacity: 0 }` alongside `to: { path: { ... } }` using a multi-step timeline.
- **For pixel-perfect alignment** use both `align` and `alignAt` together to control exactly which part of the element sits on the path.

---

## Related

- [SVG Animations](/docs/sdk/svg) — draw SVG strokes and animate fill and stroke colors
- [Scroll Trigger](/docs/sdk/scroll-trigger) — scrub animations based on scroll position
- [Repeat & Yoyo](/docs/sdk/repeat-yoyo) — loop and alternate animations

---

## Repeat & Yoyo

> Loop animations with repeat count and yoyo back-and-forth playback.

URL: https://motion.page/docs/sdk/repeat-yoyo

import LivePreview from "../../components/docs/blocks/LivePreview";

`repeat` controls how many times an animation cycles after its first play. Combine it with `yoyo` to reverse direction on alternating cycles, and `delay` to add a pause between each cycle.

## Basic Repeat

Pass `repeat` as a plain number to run the animation that many **additional** times after the first play. A value of `2` plays 3 times total.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("bounce", ".ball", {
  to: { y: -40 },
  duration: 0.4,
  ease: "power2.out",
  repeat: 2,
}).onPageLoad();
```

## Infinite Loop

Use `repeat: -1` to loop forever.

```typescript
Motion("spin", ".loader", {
  to: { rotate: 360 },
  duration: 1,
  ease: "none",
  repeat: -1,
}).onPageLoad();
```

## RepeatConfig Object

For more control, pass an object with `times`, `yoyo`, and `delay` properties.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `times` | `number` | — | Additional repetitions. `-1` = infinite |
| `yoyo` | `boolean` | `false` | Reverse direction on every other cycle |
| `delay` | `number` | `0` | Seconds to pause between each cycle |

```typescript
// Shorthand number
repeat: 3

// Full config object
repeat: { times: 3, yoyo: true, delay: 0.5 }
```

## Yoyo

**`yoyo: true`** reverses the animation on every alternate cycle — forward, backward, forward, backward. This creates smooth back-and-forth playback without a hard reset jump.

```typescript
Motion("pulse", ".badge", {
  to: { scale: 1.15 },
  duration: 0.6,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

Without yoyo, an infinite repeat jumps back to the start after each cycle. With yoyo, the animation reverses smoothly — ideal for breathing, pulsing, and attention effects.

<LivePreview client:load
  height={220}
  title="Yoyo pulse"
  html={`<div class="scene"><div class="box"></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("pulse", ".box", {
  to: { scale: 1.25, opacity: 0.8 },
  duration: 0.6,
  ease: "sine.inOut",
  repeat: { times: -1, yoyo: true },
}).play();`}
/>

## Repeat Delay

**`delay`** inside `RepeatConfig` adds a pause **between cycles** — distinct from the top-level `delay` which only delays the very first play.

```typescript
Motion("blink", ".cursor", {
  to: { opacity: 0 },
  duration: 0.5,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.1 },
}).onPageLoad();
```

This lives inside the `RepeatConfig` object as `delay`.

## Finite Repeat with Yoyo

Combine a finite `times` count with `yoyo` for animations that play a set number of back-and-forth swings, then settle.

```typescript
Motion("shake", ".notification", {
  to: { x: 8 },
  duration: 0.08,
  ease: "power1.inOut",
  repeat: { times: 5, yoyo: true },
}).play();
```

5 additional cycles with yoyo = left, right, left, right, left, right — a natural shake effect.

## Complete Example — All Three Properties

```typescript
import { Motion } from "@motion.page/sdk";

Motion("breathe", ".hero-icon", {
  to: { scale: 1.08, opacity: 0.85 },
  duration: 1.8,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.3 },
}).onPageLoad();
```

The icon gently expands and dims, holds for `0.3s`, then reverses — repeating indefinitely.

## Timeline Repeat with `.withRepeat()`

`repeat` inside `AnimationConfig` loops a **single animation**. To loop an entire multi-step timeline, use the `.withRepeat()` method on the `Timeline` instance instead.

```typescript
// Per-animation repeat — only the individual tween loops
Motion("slide", ".box", {
  from: { x: -100 },
  to: { x: 100 },
  duration: 0.8,
  repeat: -1,
}).onPageLoad();

// Timeline repeat — the whole sequence loops as a group
Motion("sequence", [
  { target: ".box-a", from: { x: -100 }, duration: 0.5 },
  { target: ".box-b", from: { y: 60 }, duration: 0.5 },
])
  .withRepeat({ times: -1, yoyo: true })
  .onPageLoad();
```

`.withRepeat()` accepts the same `number | RepeatConfig` as per-animation `repeat`.

## onRepeat Callback

React to each completed cycle with the `onRepeat` callback. It receives the current repeat count (0-based).

```typescript
Motion("counter", ".ring", {
  to: { rotate: 360 },
  duration: 1,
  ease: "none",
  repeat: -1,
  onRepeat: (count) => {
    console.log(`Cycle ${count + 1} complete`);
  },
}).onPageLoad();
```

## Common Patterns

**Attention pulse** — draw focus to a CTA or notification badge:

```typescript
Motion("cta-pulse", ".cta-button", {
  to: { scale: 1.06, boxShadow: "0 0 0 8px rgba(102, 51, 238, 0.25)" },
  duration: 0.8,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

**Loading spinner** — continuous rotation with no easing for constant speed:

```typescript
Motion("spinner", ".loader-icon", {
  to: { rotate: 360 },
  duration: 0.9,
  ease: "none",
  repeat: -1,
}).onPageLoad();
```

**Looping marquee position** — translate then instantly reset:

```typescript
Motion("marquee", ".track", {
  to: { x: "-50%" },
  duration: 8,
  ease: "none",
  repeat: -1,
}).onPageLoad();
```

**Shake on error** — finite yoyo for form validation feedback:

```typescript
Motion("field-shake", ".input-error", {
  to: { x: 6 },
  duration: 0.07,
  ease: "power1.inOut",
  repeat: { times: 7, yoyo: true },
}).play();
```

## API Reference

```typescript
// Shorthand
repeat?: number;               // -1 = infinite, 3 = 3 extra cycles

// Full config
interface RepeatConfig {
  times:   number;             // Additional repetitions; -1 = infinite
  yoyo?:   boolean;            // Reverse direction each cycle (default: false)
  delay?:  number;             // Seconds to pause between cycles (default: 0)
}

// Timeline-level repeat
tl.withRepeat(config: number | RepeatConfig): this

// Callback on each completed cycle
onRepeat?: (repeatCount: number) => void;
```

## Common Mistakes

**Confusing top-level `delay` with `RepeatConfig.delay`.** `delay: 0.5` at the config root delays the first play only. `repeat: { times: -1, delay: 0.5 }` pauses 0.5s between every cycle. Both can coexist.

**Expecting `repeat: 3` to play 3 times total.** It plays **3 additional times** after the first — 4 plays total. Use `repeat: 2` for 3 total plays.

**Forgetting yoyo on infinite loops.** `repeat: -1` without yoyo creates a visible snap back to the start after each cycle. Add `yoyo: true` for continuous, seamless loops.

---

Related: [Duration & Delay](/docs/sdk/duration-delay) · [Easing](/docs/sdk/easing) · [Stagger](/docs/sdk/stagger)

---

## Mouse Movement

> Animate based on cursor position with axis and distance modes.

URL: https://motion.page/docs/sdk/mouse-movement

import LivePreview from "../../components/docs/blocks/LivePreview";

`.onMouseMove()` maps the cursor position to animation progress in real time — no play/pause, just a continuous value between 0 and 1 driven by the mouse. Use it for parallax depth layers, magnetic follow effects, and interactive tilt animations.

## Basic Usage

Chain `.onMouseMove()` after defining `from` and `to` states. Both endpoints are typically specified because neither represents the element's natural CSS position.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("parallax", ".layer", {
  from: { x: -20 },
  to:   { x: 20  },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.1 });
```

The timeline progress follows the mouse: left edge = 0, right edge = 1 (for x); top edge = 0, bottom edge = 1 (for y).

---

<LivePreview
  client:visible
  height={260}
  title="Mouse parallax depth layers"
  html={`<div class="scene">
  <div class="layer layer-bg">BG</div>
  <div class="layer layer-mid">MID</div>
  <div class="layer layer-fg">FG</div>
  <p class="hint">Move your mouse</p>
</div>`}
  css={`.scene { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; background: #0f0f14; overflow: hidden; gap: 24px; }
.layer { width: 72px; height: 72px; border-radius: 12px; display: flex; align-items: center; justify-content: center; color: white; font-weight: 700; font-size: 13px; will-change: transform; }
.layer-bg  { background: #3b1f8a; transform: translate(0px, 0px); }
.layer-mid { background: #6633EE; transform: translate(0px, 0px); }
.layer-fg  { background: #a066ff; transform: translate(0px, 0px); }
.hint { position: absolute; bottom: 14px; left: 0; right: 0; text-align: center; color: #888; font-size: 12px; pointer-events: none; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("parallax-bg", ".layer-bg", {
  from: { x: -8 },
  to: { x: 8 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.06, target: ".scene" });

Motion("parallax-mid", ".layer-mid", {
  from: { x: -20 },
  to: { x: 20 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.1, target: ".scene" });

Motion("parallax-fg", ".layer-fg", {
  from: { x: -40 },
  to: { x: 40 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.055, target: ".scene" });`}
/>


---

## Options

`.onMouseMove()` accepts an optional `MouseMoveConfig` object:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | `'axis' \| 'distance'` | `'distance'` | How mouse position maps to progress. See [Type Modes](#type-modes--axis-vs-distance). |
| `target` | `string \| Element` | viewport | The element whose bounds define the movement area. Accepts a CSS selector or Element reference. |
| `smooth` | `number` | omitted (instant) | Lag applied to progress tracking. `0` = instant follow, `1` = maximum lag. |
| `startProgress` | `number` | `0.5` | Initial animation progress before the first pointer sample. |
| `leaveProgress` | `number` | `0.5` | Animation progress to return to when the mouse leaves. |
| `each` | `boolean` | `false` | When `true`, every element matching `target` gets its own independent tracking zone. Animated elements must be children of the target. |

---

## Type Modes — Axis vs Distance

### `type: 'axis'`

The axis mode maps mouse position across the full span of the viewport (or `target` element). The start is at one edge and the end is at the opposite edge.

- **Mouse at left edge** → progress `0` → `from` state
- **Mouse at right edge** → progress `1` → `to` state
- Same applies vertically: top → `0`, bottom → `1`

This makes axis mode ideal for parallax depth layers and directional follow effects.

```typescript
Motion("tilt", ".card", {
  from: { rotateY: -15 },
  to:   { rotateY: 15 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.08 });
```

### `type: 'distance'`

The distance mode animates based on how far the cursor is from the center of the viewport (or `target` element). The animation progress reflects distance — not direction — from the center point.

- **Mouse at center** → progress `1` → `to` state
- **Mouse at the farthest corner** → progress `0` → `from` state

This is well-suited for radial proximity effects such as glow halos, magnetic pull, or attention-drawing reveals.

```typescript
Motion("glow", ".glow-ring", {
  from: { opacity: 0, scale: 0.8 },
  to:   { opacity: 1, scale: 1.2 },
}).onMouseMove({ type: "distance", smooth: 0.12 });
```

---

## Per-Animation Axis Binding

When using `type: 'axis'`, you can lock an individual animation node to respond only to a single axis by setting `axis` on the `AnimationConfig` — not on the trigger config. This is separate from the `type` option.

```typescript
// Horizontal axis only — ignores vertical mouse movement
Motion("follow-x", ".marker", {
  from: { x: -30 },
  to:   { x: 30  },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.08, startProgress: 0, leaveProgress: 0 });

// Vertical axis only
Motion("follow-y", ".marker", {
  from: { y: -20 },
  to:   { y: 20  },
  axis: "y",
}).onMouseMove({ type: "axis", smooth: 0.08 });
```

`axis: 'x'` makes the node track horizontal mouse position only; `axis: 'y'` tracks vertical only. Every animation node used with `type: 'axis'` needs an explicit axis binding. To track both axes, use two parallel animation entries — one bound to each axis.

---

## Movement Area

By default, the entire viewport is the movement area — mouse at the left edge of the screen is progress `0`, right edge is progress `1`. Set `target` to restrict tracking to a specific element's bounds.

```typescript
// Only react to mouse within the .hero section
Motion("title", ".hero-title", {
  from: { x: -12 },
  to:   { x: 12 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.1, target: ".hero" });
```

When the cursor leaves the `target` element, the animation eases to `leaveProgress`.

---

## Progress at Rest and on Leave

**`startProgress`** sets the animation's initial progress before the first pointer sample. The default `0.5` places the element at the midpoint between `from` and `to` while the trigger is waiting for movement.

**`leaveProgress`** is where the animation settles after the cursor leaves. The default `0.5` keeps the element at the midpoint.

Set both to `0` to start elements at their `from` state and return there on leave:

```typescript
// Elements rest at `from` position; animate toward `to` as mouse approaches
Motion("magnetic", ".icon", {
  from: { x: 0,  y: 0  },
  to:   { x: 16, y: 16 },
}).onMouseMove({ type: "distance", smooth: 0.1, startProgress: 0, leaveProgress: 0 });
```

Set both to `0.5` (the default) for a centered, symmetrical parallax where elements begin and end in the middle of their range.

---

## Smooth Following

`smooth` controls how quickly the animation catches up to the cursor. Think of it as inertia.

| Value | Effect |
|-------|--------|
| `0` | Instant — animation snaps to cursor with no lag |
| `0.05–0.1` | Subtle easing, natural parallax feel (recommended) |
| `0.15–0.2` | Noticeable lag, dreamy or heavy effect |
| `1` | Maximum lag — very slow to follow |

Use different `smooth` values across depth layers to create convincing parallax — farther layers should feel slower:

```typescript
Motion("bg",  ".layer-bg",  { from: { x: -10 }, to: { x: 10 }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.15 }); // slow background

Motion("mid", ".layer-mid", { from: { x: -25 }, to: { x: 25 }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.1  }); // medium midground

Motion("fg",  ".layer-fg",  { from: { x: -50 }, to: { x: 50 }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.06 }); // snappy foreground
```

---

## Per-Element Instances

Set `each: true` together with a class-based `target` to give every matching element its own independent tracking zone. Animated elements must live **inside** the target container — the target acts as both the movement boundary and the wrapper.

```typescript
// Each .card gets its own mouse zone; the tilt tracks the cursor within that card
Motion("card-tilt", ".card", {
  from: { rotateY: -8 },
  to:   { rotateY: 8 },
  axis: "x",
}).onMouseMove({ type: "axis", smooth: 0.08, target: ".card", each: true });
```

Without `each: true`, all matching elements share a single tracking zone (the viewport, or the single `target` element).

---

## Common Patterns

### Parallax Depth Layers

Multiple timelines at the same `type: 'axis'` with progressively higher `smooth` values and wider offset ranges create convincing depth:

```typescript
Motion("bg",  ".layer-bg",  { from: { x: -8  }, to: { x: 8  }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.15 });

Motion("mid", ".layer-mid", { from: { x: -20 }, to: { x: 20 }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.1  });

Motion("fg",  ".layer-fg",  { from: { x: -40 }, to: { x: 40 }, axis: "x" })
  .onMouseMove({ type: "axis", smooth: 0.06 });
```

### 3D Card Tilt

Combine `rotateX` and `rotateY` with `axis` mode for a classic interactive tilt:

```typescript
Motion("card-3d", [
  {
    target: ".card",
    from: { rotateY: -12 },
    to: { rotateY: 12 },
    axis: "x",
  },
  {
    target: ".card",
    from: { rotateX: 8 },
    to: { rotateX: -8 },
    axis: "y",
    position: "<",
  },
]).onMouseMove({
  type: "axis",
  target: ".card",
  smooth: 0.08,
  startProgress: 0.5,
  leaveProgress: 0.5,
});
```

### Proximity Fade-In

Use `type: 'distance'` with `startProgress: 0, leaveProgress: 0` to reveal elements as the cursor approaches them:

```typescript
Motion("proximity", ".reveal-on-hover", {
  from: { opacity: 0, scale: 0.9 },
  to:   { opacity: 1, scale: 1   },
}).onMouseMove({
  type: "distance",
  smooth: 0.12,
  startProgress: 0,
  leaveProgress: 0,
});
```

### Axis-Locked Horizontal Follow

Lock a follower element to horizontal movement only using `axis: 'x'` on the AnimationConfig:

```typescript
Motion("cursor-x", ".follower", {
  from: { x: -48 },
  to:   { x: 48  },
  axis: "x",
}).onMouseMove({
  type: "axis",
  smooth: 0.06,
  startProgress: 0,
  leaveProgress: 0,
});
```

---

## Related

- [Hover](/docs/sdk/hover) — react to mouse enter and leave events
- [Scroll Trigger](/docs/sdk/scroll-trigger) — drive progress from scroll position
- [3D Transforms](/docs/sdk/3d-transforms) — `rotateX`, `rotateY`, `perspective` for tilt effects
- [Page Load Trigger](/docs/sdk/page-load) — auto-play on DOM ready

---

## Page Exit

> Animate elements before navigating away from the page.

URL: https://motion.page/docs/sdk/page-exit

import LivePreview from "../../components/docs/blocks/LivePreview";

`.onPageExit()` intercepts link clicks, plays the timeline to completion, and then navigates — the go-to trigger for page-out transitions, exit fades, and outgoing slide animations.

## Basic Usage

Chain `.onPageExit()` after defining your animation. When a visitor clicks an eligible navigation link, the SDK plays the timeline and waits for it to finish before following the navigation.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit();
```

## Options

`.onPageExit()` accepts an optional config object:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mode` | `'all' \| 'include' \| 'exclude'` | `'all'` | Which eligible links to intercept. `'all'` catches every eligible `<a>` click; `'include'` only fires on matched selectors; `'exclude'` fires on all links except matched selectors. |
| `selectors` | `string` | — | CSS selector(s) for link filtering. Required when `mode` is `'include'`; used as the exclusion list when `mode` is `'exclude'`. Separate multiple selectors with a comma. |
| `skipHref` | `('anchor' \| 'javascript' \| 'mailto')[]` | — | Href patterns to never intercept. `'anchor'` skips `#hash` links; `'javascript'` skips `javascript:` hrefs; `'mailto'` skips `mailto:` and `tel:` links. |

The trigger always leaves downloads, missing/empty hrefs, non-primary clicks, Ctrl/Cmd/Shift/Alt clicks, and links targeting a context other than `_self` to the browser. While an exit is already playing, the first eligible destination remains authoritative: another ordinary link click is canceled without restarting the timeline or replacing that URL.

Links added after `.onPageExit()` registration are supported automatically, including navigation rendered later by an SPA or CMS. Include/exclude selectors are evaluated against the clicked link and its current ancestor chain, so dynamically added containers and later class changes use the live DOM. Keyboard activation of an eligible link follows the same exit sequence as a pointer click.

An invalid selector never crashes navigation. In `include` mode it matches nothing; in `exclude` mode it excludes nothing and eligible links continue to use the exit animation. Fix invalid-selector warnings in development rather than relying on this fallback.

---

## Skipping Specific Links

By default all eligible links trigger the exit animation. Pass `skipHref` to additionally bypass hash anchors, `javascript:` hrefs, and mailto links — a safe default for most sites.

```typescript
Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });
```

To exclude specific links by class or selector, use `mode: 'exclude'` with a `selectors` list. Any `<a>` element (or a parent element) matching those selectors is skipped.

```typescript
// Skip links inside the nav and any element with .no-exit
Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit({
  mode: "exclude",
  selectors: "nav a, .no-exit",
});
```

The selector format also supports parent-element targeting: `#my-menu.no-animation` will look up the ancestor chain of the clicked `<a>` and skip navigation if any parent has an ID of `my-menu` and a class of `no-animation`.

---

## Specific Links Only

Use `mode: 'include'` with a `selectors` list to only intercept certain links — for example, navigation links or calls-to-action — leaving all other links unaffected.

```typescript
// Only intercept main-nav and CTA links
Motion("exit", ".page-wrapper", {
  to: { opacity: 0, y: -20 },
  duration: 0.35,
  ease: "power2.in",
}).onPageExit({
  mode: "include",
  selectors: ".nav-link, .cta-button",
});
```

---

## Fade-Out Exit

The simplest exit: fade the entire page to black before navigating.

```typescript
Motion("fade-out", "body", {
  to: { opacity: 0 },
  duration: 0.5,
  ease: "power1.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });
```

---

## Slide-Out Exit

Slide the page content upward while fading out — a classic page-transition feel.

```typescript
Motion("slide-out", ".page-wrapper", {
  to: { opacity: 0, y: -40 },
  duration: 0.45,
  ease: "power2.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });
```

---

<LivePreview
  client:visible
  height={240}
  title="Page exit animation"
  html={`<div class="scene"><div class="card"><p class="label">Click to simulate exit</p><button class="btn">Leave page →</button></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.card { background: #18181b; border: 1px solid #27272a; border-radius: 16px; padding: 40px 48px; text-align: center; }
.label { color: #a1a1aa; font-size: 14px; margin: 0 0 20px; }
.btn { background: #6633EE; color: white; border: none; border-radius: 8px; padding: 10px 24px; font-size: 15px; font-weight: 600; cursor: pointer; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("exit", ".card", {
  to: { opacity: 0, y: -32, scale: 0.96 },
  duration: 0.4,
  ease: "power2.in",
}).onClick({ target: ".btn", toggle: "restart" });`}
/>

---

## Pairing with Page Load

`.onPageExit()` and `.onPageLoad()` are natural complements. Combine them to build a full enter/leave transition: elements animate in when the page loads, and animate out when the visitor leaves.

```typescript
import { Motion } from "@motion.page/sdk";

// Animate in on arrival
Motion("enter", ".page-wrapper", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: "power3.out",
}).onPageLoad();

// Animate out on departure
Motion("exit", ".page-wrapper", {
  to: { opacity: 0, y: -30 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });
```

---

## Related

- [Page Load Trigger](/docs/sdk/page-load) — play animations when the page first appears
- [Scroll Trigger](/docs/sdk/scroll-trigger) — animate elements as they enter the viewport
- [Hover Trigger](/docs/sdk/hover) — react to mouse enter and leave
- [Click Trigger](/docs/sdk/click) — toggle animations on click
- [Duration & Delay](/docs/sdk/duration-delay) — control timing within animations

---

## Lottie Integration

> Sync Lottie Player frames with Motion.page timeline progress.

URL: https://motion.page/docs/sdk/lottie

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

Lottie playback can follow any Motion.page timeline by mapping `AnimationConfig.onUpdate` progress to the player's frame API. This makes page-load, hover, click, and scroll-scrub timelines available to Lottie animations without starting a second playback clock.

> `lottie` is Builder metadata, not a property of the core SDK's `AnimationConfig`. The Builder's SDK generator compiles that metadata into the same supported `onUpdate` bridge shown on this page.

## Prerequisites

Load the Lottie Player component before initializing the timeline:

```html
<script src="https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js"></script>
```

Then add a player without `autoplay` or `loop`; Motion.page will own its frame position:

```html
<lottie-player
  id="hero-lottie"
  src="/animations/hero.json"
  background="transparent"
  style="width: 320px; height: 320px;"
></lottie-player>
```

The LottieFiles player exposes its lottie-web `AnimationItem` as `element._lottie`. That object provides `totalFrames` and `goToAndStop()`.

## Basic Usage

Create a small seek helper, then call it from `onUpdate`:

<CodeBlock
  filename="lottie-page-load.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

type LottieElement = HTMLElement & {
  _lottie?: {
    totalFrames: number;
    goToAndStop(frame: number, isFrame: boolean): void;
  };
};

const player = document.querySelector<LottieElement>("#hero-lottie")!;

function seekLottie(
  element: LottieElement,
  progress: number,
  start = 0,
  end = 1
) {
  const animation = element._lottie;
  if (!animation) return;

  const lastFrame = animation.totalFrames - 1;
  const normalized = start + (end - start) * progress;
  animation.goToAndStop(Math.round(normalized * lastFrame), true);
}

Motion("hero-lottie", player, {
  duration: 2,
  ease: "none",
  onUpdate: (progress) => seekLottie(player, progress),
}).onPageLoad();`}
/>

<LivePreview client:visible
  height={390}
  title="Lottie frame bridge driven by SDK progress"
  html={`<div class="lottie-demo">
  <div class="lottie-player" role="img" aria-label="Simulated Lottie orbital animation">
    <svg viewBox="0 0 320 220" aria-hidden="true">
      <defs>
        <radialGradient id="core-gradient" cx="34%" cy="28%">
          <stop offset="0" stop-color="#ffffff" />
          <stop offset="0.22" stop-color="#82e8ff" />
          <stop offset="0.72" stop-color="#586aff" />
          <stop offset="1" stop-color="#242858" />
        </radialGradient>
      </defs>
      <circle class="guide" cx="160" cy="110" r="72" />
      <circle class="progress-ring" cx="160" cy="110" r="72" />
      <g class="orbit">
        <circle class="satellite-glow" cx="232" cy="110" r="13" />
        <circle class="satellite" cx="232" cy="110" r="6" />
      </g>
      <circle class="core" cx="160" cy="110" r="42" fill="url(#core-gradient)" />
      <path class="spark" d="M141 114 L154 91 L165 110 L180 84" />
    </svg>
    <div class="lottie-hud"><span>LOTTIE FRAME</span><strong class="lottie-frame">000</strong><span>/ 089</span></div>
  </div>
  <div class="lottie-caption">
    <span>onUpdate(progress)</span>
    <strong>goToAndStop(frame, true)</strong>
  </div>
</div>`}
  css={`.lottie-demo {
  width: min(640px, 100%);
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  overflow: hidden;
  background: #080b20;
}
.lottie-player {
  position: relative;
  height: 275px;
  padding: 18px;
  background: radial-gradient(circle at 50% 45%, rgba(83, 93, 225, 0.2), transparent 48%), #050713;
}
.lottie-player svg { display: block; width: 100%; height: 100%; overflow: visible; }
.guide,
.progress-ring { fill: none; stroke-width: 2; }
.guide { stroke: rgba(153, 169, 255, 0.13); }
.progress-ring {
  stroke: #7d6cff;
  stroke-linecap: round;
  stroke-dasharray: 452.4;
  stroke-dashoffset: 452.4;
}
.satellite-glow { fill: rgba(87, 218, 255, 0.18); }
.satellite { fill: #7cecff; }
.core { filter: drop-shadow(0 16px 28px rgba(69, 94, 255, 0.4)); }
.spark { fill: none; stroke: rgba(255, 255, 255, 0.82); stroke-width: 4; stroke-linecap: round; stroke-linejoin: round; }
.orbit { transform-origin: 160px 110px; }
.lottie-hud {
  position: absolute;
  top: 15px;
  right: 15px;
  padding: 7px 10px;
  border: 1px solid rgba(173, 184, 255, 0.24);
  border-radius: 999px;
  background: rgba(5, 7, 20, 0.72);
  display: flex;
  align-items: baseline;
  gap: 5px;
  color: #858eaf;
  font-size: 9px;
  letter-spacing: 0.08em;
}
.lottie-hud strong { color: #f4f5ff; font-size: 13px; }
.lottie-caption {
  padding: 18px 20px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 18px;
  color: #7e88ad;
  font-size: 12px;
}
.lottie-caption strong { color: #dfe2ff; }
@media (max-width: 520px) {
  .lottie-player { height: 245px; }
  .lottie-caption { align-items: flex-start; flex-direction: column; gap: 6px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const player = document.querySelector(".lottie-player");
const orbit = document.querySelector(".orbit");
const core = document.querySelector(".core");
const ring = document.querySelector(".progress-ring");
const frameLabel = document.querySelector(".lottie-frame");

player._lottie = {
  totalFrames: 90,
  goToAndStop(frame) {
    const progress = frame / (this.totalFrames - 1);
    const pulse = 42 + Math.sin(progress * Math.PI * 4) * 5;
    orbit.setAttribute("transform", "rotate(" + progress * 360 + " 160 110)");
    core.setAttribute("r", String(pulse));
    ring.style.strokeDashoffset = String(452.4 * (1 - progress));
    frameLabel.textContent = String(frame).padStart(3, "0");
  },
};

Motion("lottie-preview", player, {
  duration: 2.4,
  ease: "none",
  onUpdate: (progress) => {
    const animation = player._lottie;
    const lastFrame = animation.totalFrames - 1;
    animation.goToAndStop(Math.round(progress * lastFrame), true);
  },
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The preview uses a tiny local player stub so it stays self-contained. Its `totalFrames` and `goToAndStop()` contract is the same one used by the LottieFiles player and by Builder-generated code.

## Scroll-Synced Playback

Attach `.onScroll({ scrub: true })` to map scroll position directly to the frame range:

```typescript
Motion("scroll-lottie", player, {
  duration: 1,
  ease: "none",
  onUpdate: (progress) => seekLottie(player, progress),
}).onScroll({
  target: "#hero-lottie",
  start: "top center",
  end: "bottom center",
  scrub: true,
});
```

Scrolling backward naturally sends decreasing progress values, so the Lottie follows in reverse without additional event handling.

## Partial Frame Range

Pass normalized start and end values to the helper. This plays the middle half of the animation:

```typescript
Motion("partial-lottie", player, {
  duration: 1,
  ease: "none",
  onUpdate: (progress) => seekLottie(player, progress, 0.25, 0.75),
}).onScroll({ target: "#hero-lottie", scrub: true });
```

| Start | End | Result |
|-------|-----|--------|
| `0` | `1` | First frame → last frame |
| `0.25` | `0.75` | 25% frame → 75% frame |
| `1` | `0` | Last frame → first frame |
| `0.75` | `0.25` | 75% frame → 25% frame |

Reversing is simply a range whose start is greater than its end; no separate SDK option is required.

## Hover and Click

The same frame bridge works with interaction triggers:

```typescript
Motion("lottie-hover", ".card-lottie", {
  duration: 0.7,
  ease: "none",
  onUpdate: (progress) => {
    document.querySelectorAll<LottieElement>(".card-lottie").forEach((element) => {
      seekLottie(element, progress);
    });
  },
}).onHover({ each: true, onLeave: "reverse" });
```

For independent players, keep `each: true` so hovering one card does not drive every card's timeline instance.

## Builder-Generated Bridge

When Lottie is enabled in the Builder, its SDK generator converts the normalized frame range and reverse toggle into an animation-level callback equivalent to:

```typescript
onUpdate: (progress) => {
  document.querySelectorAll("#hero-lottie").forEach((element) => {
    if (!element._lottie) return;

    const lastFrame = element._lottie.totalFrames - 1;
    const frame = Math.round(0 * lastFrame + (1 - 0) * lastFrame * progress);
    element._lottie.goToAndStop(frame, true);
  });
}
```

This callback is generated from Builder metadata. Handwritten core SDK code should use `onUpdate` directly rather than adding a root-level `lottie` object.

## Limitations

- **Wait for the player to initialize.** The guarded helper safely skips ticks until `element._lottie` exists.
- **Use one animation callback per player target.** An `AnimationConfig` has one `onUpdate` function; combine additional progress-driven work inside that function.
- **Do not enable autoplay.** A player running on its own clock will fight the timeline's frame seeking.
- **Refresh scroll positions after layout shifts.** Call `Motion.refreshScrollTriggers()` if loading the player changes document geometry after trigger creation.

## Related

- [Scroll Trigger](/docs/sdk/scroll-trigger) — drive frames with scroll position
- [Scroll Trigger Advanced](/docs/sdk/scroll-trigger-advanced) — pin and scrub a full-page Lottie story
- [Timeline Control](/docs/sdk/timeline-control) — react to timeline-level progress and lifecycle events

---

## Observer & Gesture

> Respond to pointer, touch, wheel, and scroll gestures with 21 callback events.

URL: https://motion.page/docs/sdk/observer-gesture

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

`.onGesture()` turns any timeline into a gesture-driven animation. It listens to pointer, touch, wheel, and scroll inputs and fires one of 21 callback events — letting you map gestures to animation actions like `play`, `reverse`, `progressUp`, or `playNext`.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

Motion("swipe-panel", ".panel", {
  to: { x: "-100%" },
  duration: 0.4,
  ease: "power2.inOut",
}).onGesture({
  types: ["pointer", "touch"],
  events: {
    LeftComplete: "play",
    RightComplete: "reverse",
  },
});
```

---

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `types` | `GestureInputType[]` | — | **Required.** One or more input types to observe: `'pointer'`, `'touch'`, `'wheel'`, `'scroll'` |
| `events` | `Partial<Record<GestureEvent, GestureAction>>` | — | **Required.** Map of event names to animation actions |
| `target` | `string \| Element` | `window` | Element to observe. Defaults to window for global gestures. Use a selector for element-scoped gestures |
| `tolerance` | `number` | `1` | Minimum distance in pixels before a gesture is recognized |
| `dragMinimum` | `number` | `10` | Minimum drag distance before drag events fire. Applies to `pointer` and `touch` types |
| `wheelSpeed` | `number` | `1` | Sensitivity multiplier for wheel events |
| `scrollSpeed` | `number` | `1` | Sensitivity multiplier for scroll events |
| `stopDelay` | `number` | `150` | **Milliseconds** of inactivity before the `Stop` event fires |
| `smooth` | `number` | `0` | Smoothing factor 0–1. Higher values add lag to progress-based actions |
| `animationStep` | `number \| Partial<Record<GestureEvent, number>>` | `0.1` | How much of the timeline to step per gesture (0.1 = 10%). Pass an object to set per-event steps |
| `preventDefault` | `boolean` | `false` | Call `event.preventDefault()` on observed events. Makes listeners non-passive — required for blocking native scroll on wheel/touch |
| `lockAxis` | `boolean` | `false` | Lock gesture detection to the dominant axis, preventing diagonal gestures from firing both axes |
| `each` | `boolean` | `false` | Create an independent timeline instance per matched element |

> **`stopDelay` is in milliseconds**, not seconds. The default `150` means 150ms of inactivity triggers `Stop`. This is unlike other time values in the SDK which use seconds.

---

## Gesture Types

| Type | Detects | Use for |
|------|---------|---------|
| `'pointer'` | Mouse movement and clicks | Desktop swipe detection, drag interactions, hover-based gestures |
| `'touch'` | Touchscreen swipes and taps | Mobile swipe navigation, touch drag interfaces |
| `'wheel'` | Mouse wheel / trackpad scroll | Wheel-driven animation progress, custom scrolljacking |
| `'scroll'` | Native page scroll direction | Direction-aware scroll reactions (distinct from position-based ScrollTrigger) |

You can combine multiple types in one trigger:

```typescript
// Respond to both touch and pointer with the same callbacks
.onGesture({
  types: ["pointer", "touch"],
  events: { Up: "play", Down: "reverse" },
})
```

---

## Event Reference

Events are the keys in the `events` map. They describe **what gesture was detected** and **when** within the gesture lifecycle.

### Direction Events

These fire **continuously** while the gesture moves in that direction.

| Event | Fires when |
|-------|-----------|
| `Up` | Gesture is actively moving upward |
| `Down` | Gesture is actively moving downward |
| `Left` | Gesture is actively moving left |
| `Right` | Gesture is actively moving right |

### Direction Complete Events

These fire **once on release** for every direction that crossed `tolerance` during the gesture. A gesture that reverses can therefore fire more than one directional complete event. Use `lockAxis: true` when only one axis should qualify.

| Event | Fires when |
|-------|-----------|
| `UpComplete` | Upward movement was activated before release |
| `DownComplete` | Downward movement was activated before release |
| `LeftComplete` | Leftward movement was activated before release |
| `RightComplete` | Rightward movement was activated before release |

### Change Events

| Event | Fires when |
|-------|-----------|
| `Change` | Any gesture movement occurs (any direction) |
| `ChangeX` | Horizontal movement detected |
| `ChangeY` | Vertical movement detected |

### Toggle Events

Toggle events fire once per direction change — when the gesture **switches** from moving in one direction to another.

| Event | Fires when |
|-------|-----------|
| `ToggleX` | Gesture changes horizontal direction (left ↔ right) |
| `ToggleY` | Gesture changes vertical direction (up ↔ down) |

### Press & Drag Events

| Event | Fires when |
|-------|-----------|
| `PressInit` | Immediately on press, before start position is recorded. No delta available yet |
| `Press` | After start position is recorded (delta is available) |
| `Release` | On pointer/touch release |
| `Drag` | During active drag movement (after `dragMinimum` threshold is exceeded) |
| `DragEnd` | When drag movement ends |

### Stop & Hover Events

| Event | Fires when |
|-------|-----------|
| `Stop` | Once after `stopDelay` ms of inactivity. Useful for "idle" state resets |
| `Hover` | Pointer enters the `target` element. **Requires a `target` element — does nothing on `window`** |
| `HoverEnd` | Pointer leaves the `target` element. **Requires a `target` element — does nothing on `window`** |

---

## Action Reference

Actions are the values in the `events` map. They control what the timeline does when that event fires.

| Action | Description |
|--------|-------------|
| `'play'` | Play the timeline forward |
| `'pause'` | Pause playback at current position |
| `'reverse'` | Play the timeline backward |
| `'restart'` | Seek to start and play forward |
| `'toggle'` | Toggle between play and pause |
| `'reset'` | Jump instantly to the start without playing |
| `'complete'` | Jump instantly to the end without playing |
| `'kill'` | Stop and remove the timeline |
| `'playReverse'` | Smart alternate: if at start, play forward; if at end, reverse |
| `'progressUp'` | Step the timeline forward by `animationStep` |
| `'progressDown'` | Step the timeline backward by `animationStep` |
| `'playNext'` | Play the next element's timeline. **Requires `each: true`** |
| `'playPrevious'` | Play the previous element's timeline. **Requires `each: true`** |

---

## Observer vs. ScrollTrigger

Both `.onGesture()` and `.onScroll()` can react to scrolling, but they work very differently:

| | `.onGesture()` with `'scroll'` | `.onScroll()` |
|--|-------------------------------|---------------|
| **Based on** | Scroll **direction** | Scroll **position** |
| **Fires** | When user scrolls up or down | When element reaches a scroll position |
| **Typical use** | Navigation, slide transitions, direction-aware effects | Reveal animations, parallax, scrubbing |
| **Progress tied to scroll?** | No (unless using `progressUp`/`progressDown`) | Yes (with `scrub: true`) |
| **Works with non-scroll inputs?** | Yes (pointer, touch, wheel) | No |

Use `.onGesture()` when you care about **which way** the user is moving. Use [Scroll Trigger](/docs/sdk/scroll-trigger) when you care about **where** they've scrolled to.

---

## Swipe Detection

Detect completed swipe gestures using the `*Complete` events. These fire once per swipe when the finger or pointer lifts — not continuously during movement.

<CodeBlock
  filename="swipe-nav.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Slide a panel in/out with swipe gestures
Motion("drawer", ".drawer", {
  from: { x: "100%" },
  duration: 0.4,
  ease: "power2.inOut",
}).onGesture({
  target: ".drawer-area",
  types: ["pointer", "touch"],
  events: {
    LeftComplete: "play",    // Swipe left → open drawer
    RightComplete: "reverse", // Swipe right → close drawer
  },
  tolerance: 20,       // Require 20px movement before recognizing gesture
  dragMinimum: 30,     // Require 30px drag before firing drag events
  preventDefault: true, // Block default touch scroll during gesture
});`}
/>

---

## Wheel-Driven Animation Progress

Use `progressUp` / `progressDown` with the `'wheel'` type to scrub a timeline with the mouse wheel — without locking the page scroll position the way `onScroll` with `scrub` does.

<CodeBlock
  filename="wheel-progress.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Step through a multi-frame animation with the wheel
Motion("frames", ".illustration", {
  to: { backgroundPosition: "0% 100%" },
  duration: 1,
}).onGesture({
  types: ["wheel"],
  events: {
    Up: "progressUp",
    Down: "progressDown",
  },
  animationStep: 0.05, // Advance 5% of timeline per wheel tick
  wheelSpeed: 1.5,     // Slightly more sensitive
});`}
/>

Per-event step sizes let you make one direction faster than the other:

```typescript
.onGesture({
  types: ["wheel"],
  events: { Up: "progressUp", Down: "progressDown" },
  animationStep: { Up: 0.15, Down: 0.05 },
})
```

---

## Touch Swipe with Live Demo

<LivePreview
	client:visible
  height={280}
  title="Swipe gesture demo"
  html={`<div class="scene">
  <div class="track">
    <div class="card" id="card">Swipe me left or right</div>
  </div>
  <div class="hint">← swipe left &nbsp;|&nbsp; swipe right →</div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; gap: 20px; font-family: sans-serif; user-select: none; }
.track { overflow: hidden; width: 260px; border-radius: 14px; }
.card { width: 260px; height: 120px; background: linear-gradient(135deg, #6633EE, #9966FF); border-radius: 14px; display: flex; align-items: center; justify-content: center; color: white; font-size: 15px; font-weight: 600; cursor: grab; }
.hint { color: #888; font-size: 13px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("swipe", "#card", {
  to: { x: "-120%", opacity: 0 },
  duration: 0.35,
  ease: "power3.out",
}).onGesture({
  target: ".track",
  types: ["touch", "pointer"],
  events: {
    LeftComplete: "play",
    RightComplete: "reverse",
  },
  tolerance: 40,
  dragMinimum: 40,
  preventDefault: true,
});`}
/>

---

## Slide Gallery with `playNext` / `playPrevious`

`playNext` and `playPrevious` advance or retreat through a set of per-element timelines. They **require `each: true`** — the gesture drives each element's own timeline in sequence.

<CodeBlock
  filename="gallery-swipe.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Each slide has its own timeline; gestures step through them in order
Motion("slides", ".slide", {
  from: { opacity: 0, x: 80 },
  duration: 0.5,
  ease: "power2.out",
}).onGesture({
  types: ["pointer", "touch", "wheel"],
  each: true,
  events: {
    LeftComplete: "playNext",
    RightComplete: "playPrevious",
    Up: "progressUp",
    Down: "progressDown",
  },
  animationStep: 0.08,
  lockAxis: true, // Prevent diagonal gesture ambiguity
});`}
/>

---

## Scroll Direction Reactions

Use the `'scroll'` type to fire animations based on the **direction** the user scrolls — not their scroll position. A common pattern: hide a navbar on scroll down, reveal it on scroll up.

<CodeBlock
  filename="scroll-direction.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Hide navbar on scroll down, reveal on scroll up
Motion("navbar", ".navbar", {
  to: { y: "-100%", opacity: 0 },
  duration: 0.35,
  ease: "power2.inOut",
}).onGesture({
  types: ["scroll"],
  events: {
    Down: "play",      // Scrolling down → hide
    Up: "reverse",     // Scrolling up → reveal
  },
  tolerance: 5,
  smooth: 0.1,
});`}
/>

---

## `Stop` Event — Idle Reset

The `Stop` event fires once after `stopDelay` milliseconds of inactivity. Use it to reset the animation when the user stops interacting.

```typescript
Motion("progress-bar", ".bar", {
  to: { scaleX: 1 },
  duration: 1,
  ease: "none",
}).onGesture({
  types: ["wheel"],
  events: {
    Up: "progressUp",
    Down: "progressDown",
    Stop: "reverse",   // Rewind bar when wheel stops
  },
  stopDelay: 800,      // Wait 800ms of stillness before firing Stop
  animationStep: 0.04,
});
```

---

## Hover Gestures on Elements

`Hover` and `HoverEnd` fire when the pointer enters and leaves the **`target`** element. They silently do nothing if `target` is `window`.

```typescript
Motion("card-glow", ".card", {
  to: { boxShadow: "0 0 32px rgba(102, 51, 238, 0.6)", y: -6 },
  duration: 0.3,
  ease: "power2.out",
}).onGesture({
  target: ".card",
  types: ["pointer"],
  events: {
    Hover: "play",
    HoverEnd: "reverse",
  },
});
```

> For hover effects this simple, `.onHover()` is a cleaner choice. Use gesture `Hover`/`HoverEnd` events when you need them **alongside** other gesture callbacks in one config.

---

## `each` — Independent Per-Element Instances

Without `each`, all matched elements share one timeline. With `each: true`, every element gets its own independent instance — essential for gallery navigation with `playNext`/`playPrevious`.

```typescript
// Without each — all cards animate together on any swipe
Motion("cards", ".card", {
  from: { opacity: 0, x: 60 },
  duration: 0.5,
}).onGesture({
  types: ["touch"],
  events: { LeftComplete: "play" },
});

// With each — every card has its own state
Motion("cards", ".card", {
  from: { opacity: 0, x: 60 },
  duration: 0.5,
}).onGesture({
  each: true,
  types: ["touch"],
  events: {
    LeftComplete: "playNext",
    RightComplete: "playPrevious",
  },
});
```

---

## Tips & Gotchas

**`stopDelay` is in milliseconds.** The default `150` means 150ms. Do not pass `1.5` expecting 1.5 seconds — pass `1500`.

**`Hover` / `HoverEnd` require a `target` element.** They silently do nothing when `target` is omitted (which defaults to `window`). Always provide a `target` selector for hover events.

**`preventDefault: true` makes listeners non-passive.** Required to block native browser scroll when using `wheel` or `touch` types. Without it, calling `event.preventDefault()` would throw a warning in modern browsers.

**`lockAxis: true` prevents diagonal gestures.** The first axis of movement is locked in. Useful for sliders and galleries where you want clean horizontal or vertical gestures only.

**`playNext` / `playPrevious` only work with `each: true`.** Without per-element timelines, there is no concept of "next" or "previous" to step through.

---

## Related

- [Scroll Trigger](/docs/sdk/scroll-trigger) — position-based scroll animations with scrub, pin, and snap
- [Scroll Trigger Advanced](/docs/sdk/scroll-trigger-advanced) — pinning, horizontal scroll, and snap
- [Click Trigger](/docs/sdk/click) — toggle animations on click

---

## Scale

> Scale elements uniformly or independently on X/Y axes.

URL: https://motion.page/docs/sdk/scale

import LivePreview from "../../components/docs/blocks/LivePreview";

Scale controls how large or small an element appears during an animation. Use `scale` for uniform scaling, or `scaleX` / `scaleY` for independent axis control. All three are unitless — `1` means normal size.

## Basic Scale

Pass `scale` inside `from` or `to`. A value of `1` is the element's natural size.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("grow", ".box", {
  from: { scale: 0 },
  duration: 0.5,
  ease: "back.out(1.7)",
}).onPageLoad();
```

Because `scale: 1` is a **natural CSS default**, omitting `to` is correct here — the SDK resolves the missing endpoint from the element's current computed style and animates to full size automatically.

<LivePreview client:load
  height={200}
  title="Scale in"
  html={`<div class="scene"><div class="box"></div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scale-in", ".box", {
  from: { scale: 0 },
  duration: 0.6,
  ease: "back.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Common Values

| Value | Result |
|-------|--------|
| `0` | Invisible (zero size) |
| `0.5` | Half size |
| `1` | Normal size (natural default) |
| `1.5` | 150% size |
| `2` | Double size |

## Independent Axes — scaleX and scaleY

Use `scaleX` and `scaleY` when you want non-uniform scaling — stretching or squashing on one axis only.

```typescript
// Squash horizontally
Motion("squash", ".box", {
  to: { scaleX: 0.6, scaleY: 1.2 },
  duration: 0.3,
  ease: "power2.inOut",
}).onHover({ each: true, onLeave: "reverse" });
```

## Common Patterns

### Zoom In on Scroll

Reveal an element by scaling it in as it enters the viewport.

```typescript
Motion("zoom-in", ".card", {
  from: { scale: 0.8, opacity: 0 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Pop In with Opacity

Combine `scale` and `opacity` for a soft, polished entrance effect.

```typescript
Motion("pop-in", ".modal", {
  from: { scale: 0.9, opacity: 0 },
  duration: 0.4,
  ease: "back.out(1.4)",
}).onPageLoad();
```

The two properties animate in parallel — the element fades in while simultaneously growing to its natural size.

### Pulse (Infinite Repeat with Yoyo)

Gently pulse an element to draw attention.

```typescript
Motion("pulse", ".badge", {
  to: { scale: 1.15 },
  duration: 0.6,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

`yoyo: true` reverses the animation on each cycle, producing a continuous breathe effect without any visible jump.

### Rubber Band (scaleX + scaleY)

Animate `scaleX` and `scaleY` in opposite directions for a rubbery, organic feel.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("rubber-band", ".button", [
  {
    target: ".button",
    to: { scaleX: 1.3, scaleY: 0.7 },
    duration: 0.15,
    ease: "power2.out",
  },
  {
    target: ".button",
    to: { scaleX: 0.85, scaleY: 1.15 },
    duration: 0.1,
    ease: "power2.inOut",
  },
  {
    target: ".button",
    to: { scaleX: 1.05, scaleY: 0.95 },
    duration: 0.1,
    ease: "power2.inOut",
  },
  {
    target: ".button",
    duration: 0.15,
    ease: "power2.out",
  },
]).onClick({ each: true });
```

## Transform Origin

Scale always happens **around the transform origin** — by default the element's center (`50% 50%`). Change this with `transformOrigin` to scale from a corner, edge, or any custom point.

```typescript
// Scale up from the bottom-left corner
Motion("corner-scale", ".card", {
  from: { scale: 0, transformOrigin: "0% 100%" },
  duration: 0.5,
  ease: "power3.out",
}).onPageLoad();
```

See the [Transform Origin](/docs/sdk/transform-origin) page for all supported values and examples.

---

## Image Sequence

> Drive frame-by-frame canvas sequences with Motion.page timeline progress.

URL: https://motion.page/docs/sdk/image-sequence

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

An **image sequence** maps timeline progress from `0` to `1` onto numbered image frames and draws the current frame to a `<canvas>`. It is a common pattern for scroll-driven product spins, cinematic reveals, and 3D rotations.

> `imageSequence` is not a property of the core SDK's `AnimationConfig`. The Motion.page Builder owns the image loading runtime and connects it to generated SDK timelines with `onUpdate`. In handwritten SDK code, preload and draw the frames yourself, then use the supported `onUpdate` callback shown below.

## HTML Setup

Give the canvas a stable CSS size and place it inside the section that will drive the scroll range:

```html
<section class="product-section">
  <canvas
    class="sequence"
    width="1920"
    height="1080"
    aria-label="Product rotation"
  ></canvas>
</section>
```

```css
.product-section {
  min-height: 300vh;
}

.sequence {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Basic Usage

Preload the numbered files, draw the first frame, and let `AnimationConfig.onUpdate` select the frame for the current timeline progress:

<CodeBlock
  filename="scroll-sequence.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

const canvas = document.querySelector<HTMLCanvasElement>("canvas.sequence")!;
const context = canvas.getContext("2d")!;
const urls = Array.from(
  { length: 120 },
  (_, index) => "/images/product/" + String(index + 1).padStart(4, "0") + ".jpg"
);

const loadImage = (src: string) =>
  new Promise<HTMLImageElement>((resolve, reject) => {
    const image = new Image();
    image.onload = () => resolve(image);
    image.onerror = reject;
    image.src = src;
  });

const frames = await Promise.all(urls.map(loadImage));

function drawFrame(progress: number) {
  const index = Math.round(progress * (frames.length - 1));
  const image = frames[index];
  context.clearRect(0, 0, canvas.width, canvas.height);
  context.drawImage(image, 0, 0, canvas.width, canvas.height);
}

drawFrame(0);

const playhead = { progress: 0 };
Motion("product-spin", playhead, {
  to: { progress: 1 },
  duration: 1,
  ease: "none",
  onUpdate: drawFrame,
}).onScroll({
  target: ".product-section",
  start: "top top",
  end: "+=300%",
  scrub: true,
  pin: true,
});`}
/>

<LivePreview client:visible
  height={390}
  title="Canvas frame sequence driven by SDK progress"
  html={`<div class="sequence-demo">
  <div class="sequence-stage">
    <canvas class="sequence-canvas"></canvas>
    <div class="frame-hud"><span>FRAME</span><strong class="frame-number">01</strong><span>/ 60</span></div>
  </div>
  <div class="sequence-caption">
    <span>PROGRESS → FRAME INDEX</span>
    <strong>Motion's onUpdate drives every redraw.</strong>
  </div>
</div>`}
  css={`.sequence-demo {
  width: min(680px, 100%);
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  overflow: hidden;
  background: #080b20;
}
.sequence-stage {
  position: relative;
  height: 260px;
  background: radial-gradient(circle at 50% 48%, rgba(82, 111, 255, 0.22), transparent 48%), #050713;
}
.sequence-canvas { display: block; width: 100%; height: 100%; }
.frame-hud {
  position: absolute;
  top: 15px;
  right: 15px;
  padding: 7px 10px;
  border: 1px solid rgba(173, 184, 255, 0.24);
  border-radius: 999px;
  background: rgba(5, 7, 20, 0.72);
  display: flex;
  align-items: baseline;
  gap: 5px;
  color: #858eaf;
  font-size: 9px;
  letter-spacing: 0.08em;
}
.frame-hud strong { color: #f4f5ff; font-size: 13px; }
.sequence-caption {
  padding: 18px 20px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 18px;
}
.sequence-caption span { color: #7e88ad; font-size: 10px; font-weight: 800; letter-spacing: 0.12em; }
.sequence-caption strong { color: #e9ebff; font-size: 13px; text-align: right; }
@media (max-width: 520px) {
  .sequence-stage { height: 230px; }
  .sequence-caption { align-items: flex-start; flex-direction: column; }
  .sequence-caption strong { text-align: left; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const canvas = document.querySelector(".sequence-canvas");
const context = canvas.getContext("2d");
const label = document.querySelector(".frame-number");
const frameCount = 60;

function resizeCanvas() {
  const dpr = Math.min(devicePixelRatio, 2);
  canvas.width = Math.round(canvas.clientWidth * dpr);
  canvas.height = Math.round(canvas.clientHeight * dpr);
}

function renderFrame(progress) {
  const frame = Math.round(progress * (frameCount - 1));
  const width = canvas.width;
  const height = canvas.height;
  const cx = width / 2;
  const cy = height / 2;
  const dpr = Math.min(devicePixelRatio, 2);
  const angle = progress * Math.PI * 2;

  context.clearRect(0, 0, width, height);

  const glow = context.createRadialGradient(cx, cy, 0, cx, cy, 120 * dpr);
  glow.addColorStop(0, "rgba(84, 126, 255, 0.34)");
  glow.addColorStop(1, "rgba(84, 126, 255, 0)");
  context.fillStyle = glow;
  context.fillRect(0, 0, width, height);

  context.save();
  context.translate(cx, cy);
  context.rotate(angle * 0.12);
  context.scale(0.65 + Math.abs(Math.cos(angle)) * 0.35, 1);

  const body = context.createLinearGradient(-90 * dpr, -70 * dpr, 90 * dpr, 70 * dpr);
  body.addColorStop(0, "#d9e7ff");
  body.addColorStop(0.32, "#607cff");
  body.addColorStop(0.72, "#252b64");
  body.addColorStop(1, "#0f1230");
  context.fillStyle = body;
  context.beginPath();
  context.roundRect(-95 * dpr, -67 * dpr, 190 * dpr, 134 * dpr, 36 * dpr);
  context.fill();

  context.strokeStyle = "rgba(223, 232, 255, 0.62)";
  context.lineWidth = 2 * dpr;
  context.beginPath();
  context.ellipse(0, 0, 54 * dpr, 54 * dpr, -angle, 0, Math.PI * 2);
  context.stroke();

  context.fillStyle = "#88ebff";
  context.beginPath();
  context.arc(Math.cos(angle) * 54 * dpr, Math.sin(angle) * 54 * dpr, 6 * dpr, 0, Math.PI * 2);
  context.fill();
  context.restore();

  label.textContent = String(frame + 1).padStart(2, "0");
}

resizeCanvas();
renderFrame(0);
addEventListener("resize", () => {
  resizeCanvas();
  renderFrame(playhead.progress);
});

const playhead = { progress: 0 };
Motion("sequence-preview", playhead, {
  to: { progress: 1 },
  duration: 2.8,
  ease: "none",
  onUpdate: renderFrame,
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The preview generates its frames procedurally so it is self-contained. A production sequence uses the same progress-to-index mapping with decoded image frames.

## Fit Frames Without Stretching

The basic example fills the canvas exactly. For mixed aspect ratios, use a cover-style draw helper:

```typescript
function drawCover(
  context: CanvasRenderingContext2D,
  image: CanvasImageSource,
  width: number,
  height: number
) {
  const source = image as { width: number; height: number };
  const imageWidth = source.width;
  const imageHeight = source.height;
  const scale = Math.max(width / imageWidth, height / imageHeight);
  const drawWidth = imageWidth * scale;
  const drawHeight = imageHeight * scale;

  context.clearRect(0, 0, width, height);
  context.drawImage(
    image,
    (width - drawWidth) / 2,
    (height - drawHeight) / 2,
    drawWidth,
    drawHeight
  );
}
```

Use `Math.min(...)` instead of `Math.max(...)` for contain behavior.

## Frame Ranges and Reverse

Map SDK progress into a normalized sub-range before choosing the image:

```typescript
const start = 0.25;
const end = 0.75;

function drawPartialSequence(progress: number) {
  const rangedProgress = start + (end - start) * progress;
  const index = Math.round(rangedProgress * (frames.length - 1));
  drawCover(context, frames[index], canvas.width, canvas.height);
}
```

For reverse playback, map `1 - progress` instead:

```typescript
const reversedProgress = 1 - progress;
```

## Image URL Pattern

Build predictable filenames from the frame index:

```typescript
const urls = Array.from({ length: 120 }, (_, index) => {
  const frame = String(index + 1).padStart(4, "0");
  return `/images/product/${frame}.webp`;
});
```

The example produces `0001.webp` through `0120.webp`. Keep all frames at the same dimensions and compression settings to avoid visible jumps.

## Loading and Performance

- **Draw frame 1 as soon as it loads.** Do not leave the canvas blank while the rest of the sequence downloads.
- **Decode before interaction.** `HTMLImageElement.decode()` or `createImageBitmap()` moves decode work ahead of the first scrub.
- **Preload near the viewport.** An `IntersectionObserver` can delay the full queue until the section approaches.
- **Use responsive frame sets.** Lower-resolution images save bandwidth and canvas memory on phones.
- **Cap canvas DPR.** `Math.min(devicePixelRatio, 2)` avoids oversized drawing buffers on high-density screens.
- **Skip frames when necessary.** Loading every second frame often preserves the feel while halving requests.
- **Prefer WebP or AVIF.** Use PNG only when lossless alpha is required; JPEG remains useful for opaque photographic frames.

## Builder-Generated Sequences

The Motion.page Builder provides upload/transcode tools, prioritized loading, responsive roots, fallback modes, and its own Image Sequence player. During export, the SDK generator links that player to the timeline with a timeline-level callback equivalent to:

```typescript
Motion("product-spin", [/* timeline entries */])
  .onUpdate((progress) => {
    window._mp_sequence_product?.handleUpdate(progress);
  })
  .onScroll({ scrub: true });
```

That bridge is generated code, not an `imageSequence` field accepted by the core SDK. See [Image Sequence in the Builder](/docs/builder/image-sequence) for the asset pipeline and controls.

## Related

- [Scroll Trigger](/docs/sdk/scroll-trigger) — map sequence progress to scrolling
- [Scroll Trigger Advanced](/docs/sdk/scroll-trigger-advanced) — pin the canvas across a longer scroll range
- [Timeline Control](/docs/sdk/timeline-control) — react to timeline-level progress and lifecycle events

---

## Opacity

> Fade elements in and out with opacity animations.

URL: https://motion.page/docs/sdk/opacity

import LivePreview from "../../components/docs/blocks/LivePreview";

Opacity controls element transparency from fully invisible (`0`) to fully visible (`1`). It's the foundation of fade animations.

## Basic Fade-In

The simplest fade-in pattern uses `from: { opacity: 0 }`. Since `opacity: 1` is the element's natural CSS state, the SDK auto-resolves it as the `to` value — you only need to declare where the animation starts.

<LivePreview
  client:load
  height={200}
  title="Opacity fade-in"
  html={`<div class="box"></div>`}
  css={`.box {
  width: 100px;
  height: 100px;
  background: #6633EE;
  border-radius: 12px;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("fade", ".box", {
  from: { opacity: 0 },
  duration: 0.6,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Implicit Values

`opacity: 1` is the natural CSS default. The SDK reads it from the element's computed style, so you don't need to spell it out.

```typescript
// ✅ Do this — SDK fills in to: { opacity: 1 } automatically
Motion("fade-in", ".element", {
  from: { opacity: 0 },
  duration: 0.6,
}).play();

// ❌ Don't do this — redundant, opacity: 1 is already the natural state
Motion("fade-in", ".element", {
  from: { opacity: 0 },
  to: { opacity: 1 },
  duration: 0.6,
}).play();
```

## Partial Opacity

For ghost or dim effects, animate to values like `0.3` or `0.5`. When neither endpoint is the natural `1`, you need both `from` and `to`.

```typescript
Motion("ghost", ".overlay", {
  from: { opacity: 0 },
  to: { opacity: 0.5 },
  duration: 0.4,
}).play();
```

## Combining with Other Properties

Opacity pairs naturally with movement and other effects. These combos are the bread and butter of polished UI animations.

```typescript
// Fade + slide up — the classic reveal
Motion("reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });

// Fade + scale
Motion("pop", ".badge", {
  from: { opacity: 0, scale: 0.8 },
  duration: 0.5,
  ease: "back.out",
}).play();

// Fade + blur
Motion("blur-in", ".hero", {
  from: { opacity: 0, filter: "blur(10px)" },
  duration: 0.8,
  ease: "power2.out",
}).play();
```

## Common Patterns

**Fade-in on scroll** — the bread and butter of scroll-driven reveals:

```typescript
Motion("scroll-reveal", ".section", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

**Fade-out on page exit:**

```typescript
Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });
```

**Staggered fade-in for lists:**

```typescript
Motion("list", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.1,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

**Crossfade — fade out old, fade in new:**

```typescript
// Fade out the current element
Motion("crossfade-out", ".old", {
  to: { opacity: 0 },
  duration: 0.3,
}).play();

// Fade in the new element
Motion("crossfade-in", ".new", {
  from: { opacity: 0 },
  duration: 0.3,
  delay: 0.3,
}).play();
```

---

## Static Methods

> Motion.set(), Motion.kill(), Motion.killAll(), Motion.reset(), Motion.refreshScrollTriggers().

URL: https://motion.page/docs/sdk/static-methods

import LivePreview from "../../components/docs/blocks/LivePreview";

Static methods on the `Motion` object let you manage the global timeline registry, set properties instantly, and handle cleanup for SPAs and dynamic content.

---

## Overview

| Method | Signature | Description |
|--------|-----------|-------------|
| `Motion.set()` | `set(target: TargetInput, vars: AnimationVars): void` | Immediately apply CSS properties with no animation |
| `Motion.get()` | `get(name: string): Timeline \| undefined` | Safe timeline retrieval — `undefined` if not found |
| `Motion.has()` | `has(name: string): boolean` | Check if a named timeline is registered |
| `Motion.getNames()` | `getNames(): string[]` | Array of all registered timeline names |
| `Motion.kill()` | `kill(name: string): void` | Kill one timeline by name, restore initial CSS |
| `Motion.killAll()` | `killAll(): void` | Kill every registered timeline |
| `Motion.reset()` | `reset(targets: TargetInput): void` | Kill animations, revert text splits, clear transform cache |
| `Motion.refreshScrollTriggers()` | `refreshScrollTriggers(): void` | Recalculate all scroll trigger positions |
| `Motion.cleanup()` | `cleanup(): void` | Detach active ScrollTriggers and safely remove their spacer/marker DOM nodes; timelines remain registered |
| `Motion.context()` | `context(fn: () => void): MotionContext` | Create a scoped context for grouped teardown |
| `Motion.utils` | — | Utility functions |

---

## Motion.set()

**`Motion.set()`** immediately applies CSS properties to one or more elements — a zero-duration snapshot with no animation played.

```typescript
import { Motion } from "@motion.page/sdk";

// Set a single element's initial state
Motion.set("#hero", { opacity: 0, y: 40 });

// Set multiple elements at once
Motion.set(".card", { scale: 0.95, opacity: 0 });

// Set CSS custom properties
Motion.set(":root", { "--accent": "#6633EE" });
```

<LivePreview client:visible
  height={260}
  title="Motion.set() and registry methods"
  html={`<div class="static-demo">
  <div class="method-status">
    <code>Motion.set()</code>
    <span id="registry-status">checking registry…</span>
  </div>
  <div class="set-cards">
    <div class="set-card">set</div>
    <div class="set-card">has</div>
    <div class="set-card">getNames</div>
  </div>
  <p>Colors and corner radii are applied synchronously before the looping reveal starts.</p>
</div>`}
  css={`.static-demo {
  width: min(510px, 100%);
  display: grid;
  gap: 17px;
}
.method-status { display: flex; align-items: center; gap: 12px; }
.method-status code {
  padding: 5px 9px;
  border-radius: 7px;
  background: rgba(102, 51, 238, 0.18);
  color: #c8b9ff;
  font-size: 12px;
}
.method-status span { margin-left: auto; color: #7ee2b8; font-size: 11px; }
.set-cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; }
.set-card {
  min-height: 86px;
  display: grid;
  place-items: center;
  border: 1px solid transparent;
  color: white;
  font-size: 12px;
  font-weight: 700;
  letter-spacing: 0.04em;
}
.static-demo p { color: #858cae; font-size: 11px; line-height: 1.5; text-align: center; }
@media (max-width: 430px) {
  .set-cards { gap: 6px; }
  .set-card { min-height: 72px; font-size: 10px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion.set(".set-card", {
  backgroundColor: "#5130c7",
  borderRadius: 18,
  borderColor: "rgba(255,255,255,0.16)",
});
Motion.set(".set-card:nth-child(2)", { backgroundColor: "#7d4be8" });
Motion.set(".set-card:nth-child(3)", { backgroundColor: "#ad76ff" });

Motion("static-methods-demo", ".set-card", {
  from: { opacity: 0, y: 24, rotate: -4 },
  duration: 0.55,
  stagger: 0.12,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

const registered = Motion.has("static-methods-demo");
const names = Motion.getNames();
document.querySelector("#registry-status").textContent =
  registered ? "registered · " + names.length + " timeline" : "not registered";`}
/>

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | `TargetInput` | CSS selector, `Element`, `NodeList`, or array of elements |
| `vars` | `AnimationVars` | The same property object accepted by `from` / `to` |

### Use cases

**Set initial state before animating** — hide elements before a page-load animation so they don't flash:

```typescript
import { Motion } from "@motion.page/sdk";

// Hide immediately, then animate in
Motion.set(".hero-title, .hero-sub, .hero-cta", { opacity: 0, y: 30 });

Motion("hero", [
  { target: ".hero-title", to: { opacity: 1, y: 0 }, duration: 0.7 },
  { target: ".hero-sub",   to: { opacity: 1, y: 0 }, duration: 0.6, position: "+=0.1" },
  { target: ".hero-cta",   to: { opacity: 1, y: 0 }, duration: 0.5, position: "+=0.1" },
]).onPageLoad();
```

**Reset after animation completes:**

```typescript
Motion("slide", ".panel", { from: { x: -300 }, duration: 0.6 })
  .onComplete(() => {
    // Snap back without a visible animation
    Motion.set(".panel", { x: 0 });
  })
  .onPageLoad();
```

---

## Registry Methods

The timeline registry tracks every named `Motion` timeline. These helpers let you inspect it safely without risking a thrown error.

| Method | Returns | Description |
|--------|---------|-------------|
| `Motion.get(name)` | `Timeline \| undefined` | Returns the timeline, or `undefined` if not registered |
| `Motion.has(name)` | `boolean` | `true` if the timeline exists in the registry |
| `Motion.getNames()` | `string[]` | All currently registered timeline names |

```typescript
import { Motion } from "@motion.page/sdk";

// Safe conditional control
if (Motion.has("hero")) {
  Motion.get("hero")?.pause();
}

// Debug — log all active timelines
console.log(Motion.getNames()); // ["hero", "nav-reveal", "card-hover"]
```

> These are most useful when you need to control a timeline from a different scope than where it was created. See [Timeline Control](/docs/sdk/timeline-control) for the full set of playback and state methods available on a retrieved timeline.

---

## Motion.kill()

**`Motion.kill(name)`** removes a single timeline from the registry by name and, by default, restores all CSS properties the animation touched to their pre-animation values.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("modal-in", "#modal", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.4,
}).onPageLoad({ paused: true });

// Show modal
document.querySelector("#open-modal")?.addEventListener("click", () => {
  Motion("modal-in").play();
});

// Dismiss and clean up
document.querySelector("#close-modal")?.addEventListener("click", () => {
  Motion.kill("modal-in");
});
```

After `Motion.kill("modal-in")`, `Motion.has("modal-in")` is `false` and `Motion.get("modal-in")` returns `undefined`. Calling `Motion("modal-in")` again creates and registers a fresh empty timeline; pass a target and config to rebuild it immediately.

---

## Motion.killAll()

**`Motion.killAll()`** kills every timeline currently in the registry. Use it for full-page teardown — SPA route changes, modal unmounts that own several animations, or any situation where you want a clean slate.

```typescript
import { Motion } from "@motion.page/sdk";

// SPA router — clean up before navigating away
router.beforeEach(() => {
  Motion.killAll();
});
```

```typescript
// Vue Router equivalent
router.afterEach(() => {
  Motion.killAll();
});
```

---

## Motion.reset()

**`Motion.reset(targets)`** is a more thorough cleanup than `kill`. In addition to stopping animations, it:

- Reverts any [Text Splitter](/docs/sdk/split-text) splits on the targets (re-merges characters/words/lines)
- Clears the internal transform cache for those elements
- Restores initial CSS

```typescript
import { Motion } from "@motion.page/sdk";

// After a page section is removed from the DOM
Motion.reset(".hero-section");

// Reset all animated elements before reinitialising
Motion.reset(".animate-in");
Motion("page-reveal", ".animate-in", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.08,
}).onPageLoad();
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `targets` | `TargetInput` | CSS selector, `Element`, `NodeList`, or array of elements |

Use `Motion.reset()` when reinitialising animations on elements that previously had split text or complex transform sequences — it prevents stale state from carrying over.

---

## Motion.refreshScrollTriggers()

**`Motion.refreshScrollTriggers()`** recalculates the start and end scroll positions for all active scroll-based animations. Call it any time the page layout changes after scroll triggers were created.

Common situations that require a refresh:

- Dynamic content finishes loading (images, async data, lazy components)
- An accordion or disclosure opens/closes
- A tab panel becomes visible
- Fonts finish loading and reflow the page
- CSS transitions that change element height complete

```typescript
import { Motion } from "@motion.page/sdk";

// After async content loads
async function loadItems() {
  const items = await fetchItems();
  renderList(items);

  // Layout has changed — recalculate scroll positions
  Motion.refreshScrollTriggers();
}
```

### Debounced resize handler

Scroll trigger positions are also invalidated by window resizes. Wrap in a debounce to avoid excessive recalculations:

```typescript
import { Motion } from "@motion.page/sdk";

let resizeTimer: ReturnType<typeof setTimeout>;

window.addEventListener("resize", () => {
  clearTimeout(resizeTimer);
  resizeTimer = setTimeout(() => {
    Motion.refreshScrollTriggers();
  }, 150);
});
```

> See [Scroll Trigger](/docs/sdk/scroll-trigger) for full documentation on scroll-based animation options.

---

## Motion.cleanup()

**`Motion.cleanup()`** detaches active ScrollTriggers, restores pinned elements through their normal teardown path, and safely removes spacer and debug-marker nodes. The timelines remain registered and other trigger types stay active. Combine it with `Motion.killAll()` when you also want to destroy the animations.

```typescript
import { Motion } from "@motion.page/sdk";

// Full scroll-animation teardown
function teardown() {
  Motion.killAll();
  Motion.cleanup();
}

// E.g., on SPA route change
document.addEventListener("astro:before-swap", teardown);
```

Spacer nodes are only present when `pin` is used on a scroll trigger. Markers are visible only in development. `cleanup()` is safe to call even when neither is present, but call it during teardown because active scroll timelines stop responding to scroll afterward.

---

## Motion.context()

**`Motion.context(fn)`** creates a **scoped context** that tracks every timeline registered inside the callback function. It returns a `MotionContext` object you can use to revert, refresh, or extend the group later.

This is the recommended pattern for SPAs and any component that creates more than one animation — instead of calling `Motion.kill()` individually for each timeline, a single `ctx.revert()` tears them all down.

### MotionContext methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `revert()` | `revert(): void` | Kill all timelines created in this context and restore CSS |
| `refresh()` | `refresh(): void` | Recalculate scroll trigger positions for timelines in this context |
| `add()` | `add(fn: () => void): void` | Register additional timelines into the context after creation |

### Basic usage

```typescript
import { Motion } from "@motion.page/sdk";

const ctx = Motion.context(() => {
  Motion("nav-fade", ".nav-item", {
    from: { opacity: 0, x: -12 },
    stagger: 0.06,
    duration: 0.4,
  }).onPageLoad();

  Motion("nav-underline", ".nav-link", {
    to: { scaleX: 1 },
    duration: 0.25,
  }).onHover({ onLeave: "reverse" });
});

// Tears down both timelines in one call
ctx.revert();
```

### React — useEffect cleanup

```typescript
import { useEffect } from "react";
import { Motion } from "@motion.page/sdk";

export function HeroSection() {
  useEffect(() => {
    const ctx = Motion.context(() => {
      Motion("hero-title", "#hero h1", {
        from: { opacity: 0, y: 40 },
        duration: 0.7,
        ease: "power3.out",
      }).onPageLoad();

      Motion("hero-body", "#hero p", {
        from: { opacity: 0, y: 20 },
        duration: 0.6,
        position: "+=0.1",
      }).onPageLoad();
    });

    // ctx.revert() kills both timelines when the component unmounts
    return () => ctx.revert();
  }, []);

  return (
    <section id="hero">
      <h1>Welcome</h1>
      <p>Subtitle copy here.</p>
    </section>
  );
}
```

### Astro View Transitions

```astro
<script>
  import { Motion } from "@motion.page/sdk";

  let ctx: ReturnType<typeof Motion.context>;

  function initAnimations() {
    ctx = Motion.context(() => {
      Motion("page-reveal", ".animate-in", {
        from: { opacity: 0, y: 20 },
        duration: 0.5,
        stagger: 0.1,
      }).onPageLoad();
    });
  }

  // Initial page load
  initAnimations();

  // Reinitialise after each View Transition
  document.addEventListener("astro:page-load", () => {
    initAnimations();
  });

  // Tear down before the DOM is swapped out
  document.addEventListener("astro:before-swap", () => {
    ctx?.revert();
  });
</script>
```

### Adding timelines after creation

Use `ctx.add()` to register timelines that are created outside the original callback — for example, inside a dynamic content render:

```typescript
import { Motion } from "@motion.page/sdk";

const ctx = Motion.context(() => {
  Motion("list-header", ".list-header", {
    from: { opacity: 0 },
    duration: 0.4,
  }).onPageLoad();
});

// Later — dynamic items loaded; add their animations into the same context
ctx.add(() => {
  Motion("list-items", ".list-item", {
    from: { opacity: 0, y: 12 },
    duration: 0.35,
    stagger: 0.06,
  }).onPageLoad();
});

// ctx.revert() now cleans up all three timelines
```

---

## Motion.utils

`Motion.utils` provides utility functions (`toArray`, `clamp`, `random`, `snap`, `interpolate`, `mapRange`, `normalize`, `wrap`). See [Motion.utils](/docs/sdk/utilities) for the full reference.

---

## Common Patterns

### Full teardown on SPA navigation

```typescript
import { Motion } from "@motion.page/sdk";

// Works with any router that exposes a before-navigate hook
router.beforeEach(() => {
  Motion.killAll();
  Motion.cleanup(); // detaches ScrollTriggers and safely removes their artifacts
});
```

### Debounced resize with scroll refresh

```typescript
import { Motion } from "@motion.page/sdk";

let timer: ReturnType<typeof setTimeout>;

window.addEventListener("resize", () => {
  clearTimeout(timer);
  timer = setTimeout(() => Motion.refreshScrollTriggers(), 150);
});
```

### Reinitialise after dynamic content

```typescript
import { Motion } from "@motion.page/sdk";

async function loadAndAnimate() {
  const data = await fetchProducts();
  renderProductGrid(data);

  // Recalculate scroll positions now that new elements exist
  Motion.refreshScrollTriggers();
}
```

### Generic SPA cleanup with context

```typescript
import { Motion } from "@motion.page/sdk";

let pageCtx: ReturnType<typeof Motion.context> | null = null;

function onPageEnter() {
  pageCtx = Motion.context(() => {
    Motion("page-in", "main", { from: { opacity: 0 }, duration: 0.35 }).onPageLoad();
    Motion("page-items", ".item", {
      from: { opacity: 0, y: 16 },
      stagger: 0.07,
      duration: 0.4,
    }).onPageLoad();
  });
}

function onPageLeave() {
  pageCtx?.revert();
  Motion.cleanup();
  pageCtx = null;
}
```

---

Related: [Timeline Control](/docs/sdk/timeline-control) · [Scroll Trigger](/docs/sdk/scroll-trigger) · [Motion.utils](/docs/sdk/utilities)

---

## SVG Animations

> Draw SVG strokes with DrawSVG and animate stroke and fill colors.

URL: https://motion.page/docs/sdk/svg

import LivePreview from "../../components/docs/blocks/LivePreview";

Animate SVG icons and illustrations by progressively revealing strokes with `drawSVG`, or by transitioning `stroke` and `fill` colors. These properties work on any SVG element with a stroke — `<path>`, `<circle>`, `<line>`, `<polyline>`, and so on.

## DrawSVG

**`drawSVG`** progressively reveals or hides an SVG stroke by controlling where the visible portion starts and ends along the path. Pass it inside `from` or `to`.

```typescript
import { Motion } from "@motion.page/sdk";

// Draw a stroke in from hidden to fully visible
Motion("draw-logo", "#logo path", {
  from: { drawSVG: "0% 0%" },
  to: { drawSVG: "0% 100%" },
  duration: 1.5,
  ease: "power2.inOut",
}).onPageLoad();
```

Because `"0% 100%"` (fully visible) is the natural drawn state, you can use `from`-only and let the SDK resolve the endpoint from the element's current state:

```typescript
// Simpler — from hidden, animate to natural (fully drawn) state
Motion("draw-logo", "#logo path", {
  from: { drawSVG: "0% 0%" },
  duration: 1.5,
  ease: "power2.inOut",
}).onPageLoad();
```

## DrawSVG Format

The `drawSVG` value defines a **window** along the stroke — two points (start and end) expressed as percentages or pixels.

| Value | Meaning |
|-------|---------|
| `"0% 100%"` | Full stroke visible (natural state) |
| `"0% 0%"` | Fully hidden — good draw-in start |
| `"100% 100%"` | Fully hidden from the other end |
| `"20% 80%"` | Middle portion only — edges hidden |
| `"50%"` | Shorthand for `"0% 50%"` — first half visible |
| `"100px 500px"` | Pixel range along the stroke |

```typescript
// Reveal from the end (wipe-out effect)
Motion("wipe", ".icon path", {
  from: { drawSVG: "100% 100%" },
  to: { drawSVG: "0% 100%" },
  duration: 0.8,
  ease: "power2.out",
}).onScroll({ toggleActions: "play none none none" });

// Reveal middle portion
Motion("partial", "circle", {
  from: { drawSVG: "0% 0%" },
  to: { drawSVG: "20% 80%" },
  duration: 1,
}).onPageLoad();
```

### Object Format

Pass an object with `start` and `end` keys. Values are **percentages 0–100** (not 0–1 fractions).

```typescript
// Object format — same as "20% 80%"
Motion("draw-arc", "path", {
  from: { drawSVG: { start: 0, end: 0 } },
  to:   { drawSVG: { start: 20, end: 80 } },
  duration: 1.2,
  ease: "power2.inOut",
}).onPageLoad();
```

> **Caution:** `{ start: 0.2, end: 0.8 }` is **not** `20%–80%` — these are percentages, so `20` and `80` are the correct values. Using `0.2` / `0.8` would give you 0.2%–0.8%, a nearly invisible sliver.

<LivePreview client:load
  height={220}
  title="DrawSVG stroke reveal"
  html={`<div class="scene">
  <svg viewBox="0 0 200 200" width="160" height="160">
    <circle cx="100" cy="100" r="70" class="track" />
    <circle cx="100" cy="100" r="70" class="stroke" />
  </svg>
</div>`}
  css={`.scene { display:flex; align-items:center; justify-content:center; height:100%; }
.track { fill:none; stroke:#222; stroke-width:8; }
.stroke { fill:none; stroke:#6633EE; stroke-width:8; stroke-linecap:round; transform-origin:center; transform:rotate(-90deg); }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("draw-circle", ".stroke", {
  from: { drawSVG: "0% 0%" },
  to: { drawSVG: "0% 100%" },
  duration: 1.4,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Stroke Color

**`stroke`** sets and animates the color of the line drawn around an SVG element. Pass any CSS color string.

```typescript
// Animate stroke color on hover
Motion("stroke-hover", ".icon", {
  to: { stroke: "#6633EE" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

```typescript
// Transition stroke color on page load
Motion("stroke-in", "path", {
  from: { stroke: "#cccccc" },
  to:   { stroke: "#ff4444" },
  duration: 0.8,
}).onPageLoad();
```

Because `stroke` reads the element's current CSS as the missing endpoint, `from`-only and `to`-only both work correctly.

## Fill Color

**`fill`** animates the color painted inside an SVG shape. Same behavior as `stroke` — pass any CSS color string, and use `from` or `to` depending on whether the natural CSS is the start or end state.

```typescript
// Fill a shape on scroll
Motion("fill-in", ".icon-shape", {
  from: { fill: "transparent" },
  to:   { fill: "#6633EE" },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ toggleActions: "play none none none" });
```

```typescript
// Hover color change
Motion("fill-hover", ".nav-icon path", {
  to: { fill: "#0099ff" },
  duration: 0.2,
}).onHover({ each: true, onLeave: "reverse" });
```

## Combining DrawSVG and Color

`drawSVG`, `stroke`, and `fill` all work in the same animation config. Use a multi-step timeline to draw the stroke first, then fill the shape.

```typescript
// Draw the stroke, then fill — sequential with position offset
Motion("draw-and-fill", "#logo", [
  {
    target: "#logo path",
    from: { drawSVG: "0% 0%", stroke: "#aaaaaa" },
    to:   { drawSVG: "0% 100%", stroke: "#6633EE" },
    duration: 1.5,
    ease: "power2.inOut",
  },
  {
    target: "#logo path",
    from: { fill: "transparent" },
    to:   { fill: "#6633EE" },
    duration: 0.6,
    ease: "power2.out",
    position: "+=0.1",
  },
]).onPageLoad();
```

Or animate them in parallel within a single config:

```typescript
// Draw and color-shift simultaneously
Motion("draw-color", "path", {
  from: { drawSVG: "0% 0%", stroke: "#cccccc" },
  to:   { drawSVG: "0% 100%", stroke: "#6633EE" },
  duration: 1.2,
  ease: "power2.inOut",
}).onPageLoad();
```

## Common Patterns

### Logo Draw-In

Stagger multiple paths for a sequential logo reveal. Target all paths in the SVG and use `stagger` to offset each one.

```typescript
Motion("logo-draw", "#logo path", {
  from: { drawSVG: "0% 0%" },
  duration: 1,
  ease: "power2.inOut",
  stagger: 0.15,
}).onPageLoad();
```

### Icon Reveal on Scroll

Trigger the draw when the icon enters the viewport. Each icon animates independently with `each: true`.

```typescript
Motion("icon-reveal", ".feature-icon path", {
  from: { drawSVG: "0% 0%", opacity: 0 },
  duration: 0.8,
  ease: "power2.out",
  stagger: 0.1,
}).onScroll({ each: true, toggleActions: "play none none none" });
```

### Progress Indicator

Scrub `drawSVG` against scroll to show reading progress or step completion.

```typescript
Motion("progress", "#progress-ring circle", {
  from: { drawSVG: "0% 0%" },
  to:   { drawSVG: "0% 100%" },
  duration: 1,
}).onScroll({
  scrub: true,
  start: "top top",
  end: "bottom bottom",
});
```

### Animated Underline on Hover

Draw a stroke underline from left to right on hover, reverse on leave.

```typescript
Motion("underline", ".nav-link", {
  from: { drawSVG: "0% 0%" },
  to:   { drawSVG: "0% 100%" },
  duration: 0.35,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

### Draw with Yoyo Loop

Loop a stroke drawing and erasing for a continuous loading or attention indicator.

```typescript
Motion("loading-ring", ".spinner circle", {
  from: { drawSVG: "0% 0%" },
  to:   { drawSVG: "0% 100%" },
  duration: 1,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

## Tips

- **SVG elements must have a `stroke` CSS property set** (either inline or via CSS) for `drawSVG` to work — it manipulates `stroke-dasharray` and `stroke-dashoffset` under the hood.
- **`fill: "none"`** on a path means the interior is transparent. Animate from `"none"` to a color by setting `from: { fill: "none" }` explicitly.
- **`stroke-linecap: round`** on the SVG element produces smoother draw-in effects at the start and end of strokes.
- Use `transformOrigin` to control the center of rotation if you also rotate SVG elements during the draw animation.

---

## Custom Cursor

> Create custom cursor effects with presets, multiple instances, and state-based styling.

URL: https://motion.page/docs/sdk/custom-cursor

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

Chain `.onCursor()` to any timeline to replace the native OS cursor with a fully animated custom cursor element. The cursor follows mouse movement, transitions between states on hover and click, and supports multiple stacked instances.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

Motion("cursor", "body", { duration: 0 }).onCursor({
  smooth: 0.1,
  hideNative: true,
  default: {
    width: 12,
    height: 12,
    borderRadius: "50%",
    backgroundColor: "#fff",
  },
  hover: {
    targets: ["a", "button", "[data-hover]"],
    width: 40,
    height: 40,
    backgroundColor: "transparent",
    border: "2px solid white",
    duration: 0.2,
  },
  click: { scale: 0.8, duration: 0.1 },
});
```

<LivePreview client:visible
  height={280}
  title="Interactive custom cursor"
  html={`<div class="cursor-stage">
  <div class="stage-copy">
    <span class="stage-kicker">Interactive preview</span>
    <strong>Move, hover, and click</strong>
    <p>The cursor eases toward the pointer, expands over the target, and compresses on click.</p>
  </div>
  <button class="cursor-target">Hover target</button>
  <span class="click-note">Click anywhere in the preview</span>
</div>`}
  css={`.cursor-stage {
  width: min(620px, 100%);
  min-height: 220px;
  position: relative;
  display: grid;
  grid-template-columns: 1fr auto;
  align-items: center;
  gap: 24px;
  padding: 28px;
  overflow: hidden;
  border: 1px solid rgba(153, 102, 255, 0.3);
  border-radius: 22px;
  background: radial-gradient(circle at 80% 20%, rgba(102, 51, 238, 0.3), transparent 38%), #0f1328;
}
.stage-copy { max-width: 330px; }
.stage-kicker { color: #a98dff; font-size: 10px; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; }
.stage-copy strong { display: block; margin-top: 8px; color: white; font-size: 25px; }
.stage-copy p { margin-top: 9px; color: #9da3bf; font-size: 12px; line-height: 1.55; }
.cursor-target {
  width: 112px;
  height: 112px;
  border: 1px solid rgba(255, 255, 255, 0.22);
  border-radius: 50%;
  background: rgba(255, 255, 255, 0.06);
  color: #f4f1ff;
  font: 600 12px/1.2 inherit;
}
.click-note { position: absolute; left: 28px; bottom: 18px; color: #666e91; font-size: 10px; }
@media (max-width: 520px) {
  .cursor-stage { grid-template-columns: 1fr 80px; gap: 14px; padding: 22px; }
  .cursor-target { width: 80px; height: 80px; }
  .click-note { left: 22px; bottom: 13px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("cursor-preview", "body", { duration: 0 }).onCursor({
  smooth: 0.3,
  squeeze: true,
  hideNative: true,
  default: {
    width: 14,
    height: 14,
    borderRadius: "50%",
    backgroundColor: "#ffffff",
    boxShadow: "0 0 20px rgba(153, 102, 255, 0.65)",
    zIndex: 999999,
  },
  hover: {
    targets: [".cursor-target"],
    width: 68,
    height: 68,
    backgroundColor: "rgba(102, 51, 238, 0.2)",
    border: "2px solid #b69cff",
    duration: 0.25,
  },
  click: { scale: 0.65, duration: 0.1 },
});`}
/>

The timeline target (`"body"`) determines which element hides the native cursor when `hideNative: true`. The animation config (`{ duration: 0 }`) is a required placeholder — the cursor appearance is driven entirely by the `.onCursor()` config.

---

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | `'basic' \| 'text' \| 'media'` | `'basic'` | Cursor variant. `'text'` renders a label from an HTML attribute; `'media'` renders an image or video |
| `smooth` | `number` | — | Follow lag. Lower = more delayed (fluid); higher = more responsive. Range `0–1` |
| `squeeze` | `boolean \| CursorSqueezeConfig` | `false` | Scale the cursor down based on follow distance/velocity |
| `hideNative` | `boolean` | `false` | Hide the OS cursor on the timeline's target element |
| `default` | `CursorStateVars` | — | **Required.** CSS properties for the cursor's idle state |
| `hover` | `CursorStateVars` | — | CSS properties applied when the cursor enters a hover target |
| `click` | `CursorStateVars` | — | CSS properties applied while the mouse button is pressed |
| `text` | `Record<string, string \| number>` | — | CSS for the inner text node. Only used with `type: 'text'` |
| `media` | `Record<string, string \| number>` | — | CSS for the inner `<img>`/`<video>` node. Only used with `type: 'media'` |

---

## State Configuration

Each state (`default`, `hover`, `click`) accepts a `CursorStateVars` object. This is a flat mix of layout options and any CSS properties you want applied.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `targets` | `string[]` | — | CSS selectors whose hover activates the `hover` state. Only valid on `hover` |
| `duration` | `number` | `0.15` | Transition duration in seconds when entering this state |
| `ease` | `string` | `'power3.inOut'` | Easing for the state transition |
| `enabled` | `boolean` | `true` | Toggle this state on or off |
| `[css property]` | `string \| number` | — | Any CSS property using camelCase (e.g. `backgroundColor`, `borderRadius`, `width`) |

CSS values follow the same camelCase convention as inline styles. Numbers without units default to `px` for dimension properties.

```typescript
Motion("cursor", "body", { duration: 0 }).onCursor({
  smooth: 0.08,
  hideNative: true,
  default: {
    width: 14,
    height: 14,
    borderRadius: "50%",
    backgroundColor: "rgba(255,255,255,0.9)",
  },
  hover: {
    targets: ["a", "button", ".card"],
    width: 48,
    height: 48,
    backgroundColor: "transparent",
    border: "2px solid rgba(255,255,255,0.9)",
    duration: 0.25,
    ease: "power2.out",
  },
  click: {
    scale: 0.75,
    duration: 0.08,
    ease: "power1.in",
  },
});
```

---

## Squeeze Effect

Set `squeeze: true` to enable velocity-based compression as the cursor moves. A cursor that is lagging farther behind the pointer scales down, then returns toward its resting scale as it catches up.

```typescript
Motion("cursor", "body", { duration: 0 }).onCursor({
  smooth: 0.12,
  hideNative: true,
  squeeze: true,
  default: { width: 16, height: 16, borderRadius: "50%", backgroundColor: "#6633EE" },
  hover: { targets: ["a"], scale: 2, duration: 0.2 },
  click: { scale: 0.8, duration: 0.1 },
});
```

Use `CursorSqueezeConfig` for precise control:

| Property | Type | Description |
|----------|------|-------------|
| `min` | `number` | Minimum overall scale factor |
| `max` | `number` | Maximum overall scale factor |
| `multiplier` | `number` | Distance sensitivity. Lower values compress more aggressively |

```typescript
Motion("cursor", "body", { duration: 0 }).onCursor({
  smooth: 0.1,
  hideNative: true,
  squeeze: { min: 0.7, max: 1.4, multiplier: 1.5 },
  default: { width: 12, height: 12, borderRadius: "50%", backgroundColor: "#ff0066" },
});
```

---

## Cursor Types

### `type: 'text'` — Label Cursor

The `text` type adds an inner text node to the cursor. The text content is read from the `mp-cursor-text` or `mp-cursor-tooltip` HTML attribute on elements as the cursor hovers over them.

```typescript
Motion("cursor-text", "body", { duration: 0 }).onCursor({
  type: "text",
  smooth: 0.08,
  hideNative: true,
  default: { width: 10, height: 10, borderRadius: "50%", backgroundColor: "#fff" },
  hover: {
    width: 80,
    height: 80,
    backgroundColor: "rgba(255,255,255,0.1)",
    duration: 0.3,
  },
  text: {
    fontSize: "11px",
    fontWeight: "600",
    color: "#fff",
    letterSpacing: "0.05em",
  },
});
```

Add the attribute to any element you want to trigger the label:

```html
<a href="/work" mp-cursor-text="View">Our Work</a>
<button mp-cursor-tooltip="Submit">Send</button>
```

Both `mp-cursor-text` and `mp-cursor-tooltip` are supported. The cursor transitions to the `hover` state as it enters the element and renders the label text.

### `type: 'media'` — Image/Video Cursor

The `media` type adds an inner `<img>` or `<video>` element to the cursor. The media source is read from the `mp-cursor-media` attribute on hovered elements.

```typescript
Motion("cursor-media", "body", { duration: 0 }).onCursor({
  type: "media",
  smooth: 0.12,
  hideNative: true,
  default: { width: 14, height: 14, borderRadius: "50%", backgroundColor: "#fff" },
  hover: { width: 100, height: 70, borderRadius: "8px", duration: 0.3 },
  media: { objectFit: "cover", borderRadius: "8px" },
});
```

```html
<div class="project" mp-cursor-media="/img/project-1.jpg">Project One</div>
<div class="project" mp-cursor-media="https://cdn.example.com/clip.mp4">Project Two</div>
```

Supported sources: relative paths, `http://`, `https://` URLs. `.mp4` and `.webm` pathnames are rendered as looping muted videos (including signed URLs with query strings); all other URLs render as images. `file://` and `data:` URLs are blocked.

---

## Multiple Instances

Create multiple cursor elements by calling `.onCursor()` on separate timelines. Each instance is an independent DOM element with its own smooth value and state config. Use different `smooth` values to create a trailing effect.

```typescript
import { Motion } from "@motion.page/sdk";

// Slow-following outer ring
Motion("cursor-ring", "body", { duration: 0 }).onCursor({
  smooth: 0.4,
  default: {
    width: 40,
    height: 40,
    border: "1px solid black",
    borderRadius: "50%",
    backgroundColor: "transparent",
    zIndex: 999998,
  },
  hover: {
    targets: ["a", "button"],
    width: 80,
    height: 80,
    duration: 0.3,
  },
  click: {
    width: 10,
    height: 10,
    backgroundColor: "black",
    duration: 0.15,
  },
});

// Snappy center dot
Motion("cursor-dot", "body", { duration: 0 }).onCursor({
  smooth: 0.42,
  hideNative: true,
  default: {
    width: 2,
    height: 2,
    borderRadius: "50%",
    backgroundColor: "black",
    zIndex: 999999,
  },
});
```

Set `hideNative: true` on **only one** instance — whichever instance represents the primary cursor is enough to hide the OS cursor. Set it on multiple instances and the effect is the same, but it's redundant.

Use `zIndex` in each instance's `default` state to control the stacking order of overlapping cursor elements.

---

## Presets Reference

The following presets are available in the Builder UI. Each represents a pre-configured cursor setup you can use as a starting point.

| Preset | Instances | Description |
|--------|-----------|-------------|
| `basic` | 2 | Semi-transparent 30px circle (snappy dot center). The circle grows and darkens on hover; the dot is always at pointer position. |
| `empty` | 1 | Minimal 5px dot with no hover or click states. Good starting point for fully custom cursors. |
| `outline` | 2 | 40px outline ring that expands to 80px on link hover, collapses to a filled dot on click. Paired with a 2px center dot. |
| `multiOutline` | 4 | Four concentric outline rings (40px, 30px, 20px, 10px) trailing at different speeds, all expanding to 80px on hover. |
| `multiSolid` | 7 | Seven solid circles of equal size trailing with staggered smooth values. The lead circle uses `mix-blend-mode: difference` on hover; trailing circles fade out. |
| `outlineCross` | 3 | Outline circle combined with a vertical line and a horizontal line forming a crosshair. All three scale on hover and react on click. |
| `cross` | 2 | Pure crosshair: a vertical bar and a horizontal bar with no circle, using `squeeze: true`. |
| `differenceBlend` | 2 | Two circles (40px and 10px) both styled `white` with `mix-blend-mode: difference`, creating a color-inversion effect over page content. |
| `blurred` | 2 | Frosted glass circle using `backdrop-filter: blur(4px)` paired with a solid black dot. The blurred circle expands on hover. |
| `invert` | 1 | Single circle using `backdrop-filter: invert(100%)` to invert page colors inside the cursor boundary. Scales up on hover. |
| `radialGradient` | 1 | Full-viewport element with a `radial-gradient` background that follows the mouse, creating a spotlight glow effect. Shrinks on link hover. |
| `tooltip` | 1 | Zero-size cursor that reads from `mp-cursor-tooltip` attributes and renders a floating label — no visible cursor element otherwise. |
| `text` | 1 | Invisible-by-default cursor that reveals a styled floating label on hover targets, reading text from `mp-cursor-text` or `mp-cursor-tooltip`. |
| `media` | 1 | Cursor that shows a circular image or video preview from `mp-cursor-media` attributes when hovering designated elements. |

---

## Difference Blend Example

The `differenceBlend` style is a popular effect where white cursor elements invert page colors on contact, making the cursor visible on any background.

<CodeBlock
  filename="difference-blend.ts"
  lang="typescript"
  code={`import { Motion } from "@motion.page/sdk";

// Large outer circle — slow follow
Motion("cursor-blend-outer", "body", { duration: 0 }).onCursor({
  smooth: 0.4,
  squeeze: true,
  default: {
    width: 40,
    height: 40,
    borderRadius: "50%",
    backgroundColor: "white",
    mixBlendMode: "difference",
    zIndex: 999998,
  },
  hover: {
    targets: ["a", "img"],
    transform: "scale(2)",
    duration: 0.6,
  },
  click: { transform: "scale(1.5)", duration: 0.1 },
});

// Small center dot — snappier follow
Motion("cursor-blend-dot", "body", { duration: 0 }).onCursor({
  smooth: 0.42,
  hideNative: true,
  squeeze: true,
  default: {
    width: 10,
    height: 10,
    borderRadius: "50%",
    backgroundColor: "white",
    mixBlendMode: "difference",
    zIndex: 999999,
  },
  hover: {
    targets: ["a", "img"],
    transform: "scale(0.25)",
    duration: 0.6,
  },
  click: { transform: "scale(0.5)", duration: 0.1 },
});`}
/>

---

## Radial Gradient Spotlight

Use a full-viewport cursor element to create a spotlight that follows the mouse without replacing the visible cursor.

```typescript
Motion("cursor-spotlight", "body", { duration: 0 }).onCursor({
  smooth: 0.25,
  default: {
    width: "100vw",
    height: "100vh",
    opacity: 0.15,
    background: "radial-gradient(circle at center, orange 0%, transparent 40%)",
    transform: "scale(1)",
  },
  hover: {
    targets: ["a"],
    transform: "scale(0.5)",
    duration: 0.5,
  },
});
```

The cursor element covers the viewport and moves so that `center` aligns with the pointer. The `smooth` value controls how smoothly the gradient follows the mouse.

---

## Tips

**Always set `duration: 0`** on the animation config — the cursor appearance is driven by `.onCursor()` states, not by the timeline animation.

**One `hideNative` is enough.** With multiple instances, only one call needs `hideNative: true`. Typically set it on the instance with the highest `zIndex`.

**Use `zIndex` in default state** to control stacking when using multiple instances. Common values: `999999` for the front dot, `999998` for a trailing ring.

**`smooth` range guide:**

| Value | Feel |
|-------|------|
| `1.0` | Instant — snaps directly to pointer |
| `0.4–0.8` | Responsive with slight lag |
| `0.1–0.3` | Fluid, noticeable trailing effect |
| `0.05–0.1` | Very smooth, significant delay |

**Cursor is not visible on touch-only devices** — `.onCursor()` only activates when `(any-pointer: fine)` matches (mouse/trackpad). It creates no cursor DOM, ticker work, or native-cursor CSS on touch-only devices; hybrid devices still activate when a fine pointer is available.

**`targets` on `hover` state only** — the `targets` array is only valid inside the `hover` state. It is ignored in `default` and `click`.

---

## Text Splitter

> Split text into characters, words, or lines and animate them individually with stagger.

URL: https://motion.page/docs/sdk/split-text

import LivePreview from "../../components/docs/blocks/LivePreview";

**Text Splitter** breaks a text element into individual `<span>` nodes — one per character, word, or line — so you can animate each unit independently with stagger.

## Basic Usage

Add `split` to your animation config. The SDK wraps each unit in a `<span>`, then applies the animation to those spans instead of the parent element.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("headline", "h1", {
  split: "chars",
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: 0.03,
  ease: "power2.out",
}).onPageLoad();
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `split` | `string` | Split type — see values below |
| `mask` | `boolean` | Wrap each unit in an `overflow: hidden` container for clip-path-style reveals |
| `maskPadding` | `number \| string \| { inline?: number \| string; block?: number \| string }` | Extra mask clip-area bleed for cursive and display fonts |

### `split` Values

| Value | Description |
|-------|-------------|
| `'chars'` | Each character becomes a separate animatable span |
| `'words'` | Each word becomes a separate animatable span |
| `'lines'` | Each line (based on line wrapping) becomes a separate animatable span |
| `'chars,words'` | Split into both chars and words — chars are nested inside word spans |
| `'words,lines'` | Split into both words and lines — words are nested inside line spans |
| `'chars,words,lines'` | All three levels — chars inside words inside lines |

For most text reveal animations, `'chars'`, `'words'`, or `'lines'` is all you need.

<LivePreview client:load
  height={220}
  title="Character-by-character reveal with mask"
  html={`<div class="scene"><h1 class="headline">Hello World</h1></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #0d0d0d; }
.headline { color: #fff; font-family: sans-serif; font-size: 2.5rem; font-weight: 700; margin: 0; letter-spacing: -0.02em; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("headline", ".headline", {
  from: { y: "110%" },
  split: "chars",
  stagger: 0.045,
  duration: 0.55,
  ease: "power3.out",
  mask: true,
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

## Split Types

### Characters

Split into individual characters. Use tight stagger values (`0.02`–`0.05`) so the effect feels snappy.

```typescript
Motion("chars-in", "h1", {
  split: "chars",
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: { each: 0.03, from: "start" },
  ease: "power2.out",
}).onPageLoad();
```

### Words

Split into words. Looser stagger (`0.06`–`0.1`) works well at this scale.

```typescript
Motion("words-in", ".tagline", {
  split: "words",
  from: { opacity: 0, x: -15 },
  duration: 0.5,
  stagger: { each: 0.06, from: "start" },
  ease: "power3.out",
}).onPageLoad();
```

### Lines

Split into lines based on the element's natural line wrapping. Use larger stagger values (`0.1`–`0.2`) since there are typically fewer units.

```typescript
Motion("lines-in", "p", {
  split: "lines",
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: { each: 0.15, from: "start" },
  ease: "power2.out",
}).onPageLoad();
```

## Mask Mode

Set `mask: true` to wrap each split unit in an `overflow: hidden` container. This lets you animate `y: '110%'` to slide text up from behind an invisible clip boundary — a cinematic newspaper-headline effect with no extra CSS required.

```typescript
// Words slide up from behind a clip boundary
Motion("headline", "h1", {
  split: "words",
  mask: true,
  from: { y: "110%" },
  duration: 0.6,
  stagger: { each: 0.06, from: "start" },
  ease: "power3.out",
}).onPageLoad();
```

```typescript
// Lines rise from below the clip
Motion("lines-mask", "h2", {
  split: "lines",
  mask: true,
  from: { y: "110%" },
  duration: 0.7,
  stagger: 0.08,
  ease: "power3.out",
}).onPageLoad();
```

**Why `110%` instead of `100%`?** A small extra offset (`110%`) ensures the starting position clears the clip boundary even with sub-pixel rounding. Use values between `100%` and `120%`.

The mask containers receive a `[data-split-mask]` attribute, so you can target them in CSS if needed.

### Mask Padding

Display and cursive fonts can draw glyphs outside their natural text box. If the mask clips ascenders, descenders, swashes, or italic overhangs, set `maskPadding` to expand the clip area without changing inline layout.

Numbers are interpreted as `em`, so the padding scales with the font size. Strings are used as CSS lengths.

```typescript
// Same bleed on both axes: 0.2em
Motion("script-title", "h1", {
  split: "words",
  mask: true,
  maskPadding: 0.2,
  from: { y: "110%" },
  stagger: 0.08,
}).onPageLoad();
```

```typescript
// Separate horizontal and vertical bleed
Motion("display-title", "h1", {
  split: "words",
  mask: true,
  maskPadding: { inline: 0.25, block: "6px" },
  from: { y: "110%" },
  stagger: { each: 0.06, from: "start" },
}).onPageLoad();
```

Default mask bleed is `0.15em` inline and `0.04em` block. You can also tune the defaults globally with CSS variables:

```css
:root {
  --motion-split-mask-padding-inline: 0.22em;
  --motion-split-mask-padding-block: 0.08em;
}
```

## Combining with Stagger

Split text is most powerful with [Stagger](/docs/sdk/stagger). Stagger controls how each unit enters in sequence — adjust `each`, `from`, and `ease` to shape the cascade.

```typescript
// Classic left-to-right char reveal
Motion("char-reveal", ".hero-title", {
  split: "chars",
  mask: true,
  from: { y: "100%" },
  duration: 0.5,
  stagger: { each: 0.03, from: "start" },
  ease: "expo.out",
}).onPageLoad();

// Center-outward word burst
Motion("word-burst", ".section-title", {
  split: "words",
  from: { opacity: 0, scale: 0.5 },
  duration: 0.5,
  stagger: { each: 0.1, from: "center" },
  ease: "back.out",
}).onPageLoad();

// Random character order — different every play
Motion("char-random", ".scramble", {
  split: "chars",
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: { each: 0.02, from: "random" },
  ease: "power2.out",
}).onPageLoad();
```

## Scroll-Triggered Text Reveal

Combine split text with scroll trigger to reveal text as it enters the viewport.

```typescript
Motion("scroll-title", ".section-title", {
  split: "words",
  mask: true,
  from: { y: "100%", opacity: 0 },
  duration: 0.6,
  stagger: { each: 0.05 },
  ease: "power2.out",
}).onScroll({
  each: true,
  toggleActions: "play none none none",
  start: "top 85%",
});
```

The `each: true` option on `.onScroll()` creates an independent scroll trigger per matched element — useful when the same selector targets multiple section titles.

## CSS Targeting

The SDK adds data attributes to every split span. Use them to apply per-character styles in CSS.

```typescript
Motion("styled-chars", "h1", {
  split: "chars",
  from: { opacity: 0, rotateY: 90 },
  duration: 0.5,
  stagger: 0.04,
}).onPageLoad();
```

```css
/* Target individual split spans */
[data-split-char]:nth-child(3)  { color: #6633EE; }
[data-split-word]:first-child   { font-weight: bold; }
[data-split-line]               { display: block; }

/* The root element is marked too */
[data-split] { /* styles applied to the container */ }
```

| Attribute | Applied to |
|-----------|-----------|
| `data-split` | Root element (the target you passed to `Motion`) |
| `data-split-char` | Each character span |
| `data-split-word` | Each word span |
| `data-split-line` | Each line span |

## Preserved Inline Elements

The splitter only touches bare text nodes. Existing inline elements like `<span>`, `<em>`, and `<strong>` survive splitting intact.

```html
<!-- Input -->
<h1>Hello <span class="accent">World</span></h1>

<!-- After split: 'words' — the accent span is preserved -->
<h1 data-split>
  <span data-split-word>Hello</span>
  <span class="accent" data-split-word>World</span>
</h1>
```

## Cleanup and Revert

Killing the timeline reverts the DOM back to the original text content. No leftover span soup.

```typescript
// Revert a specific element's split
Motion("headline").kill();

// Revert splits by target (without a named timeline)
Motion.reset(".hero-title");
```

## Common Patterns

### Typewriter Effect

Set `duration: 0` for an instant snap per character, then use stagger to control the typing speed.

```typescript
Motion("typewriter", ".terminal-text", {
  split: "chars",
  from: { opacity: 0 },
  duration: 0,
  stagger: { each: 0.07, from: "start" },
}).onPageLoad();
```

### 3D Character Flip

```typescript
Motion("char-flip", ".display-title", {
  split: "chars",
  from: { opacity: 0, rotateX: 90 },
  duration: 0.5,
  stagger: { each: 0.03, from: "start" },
  ease: "power3.out",
}).onPageLoad();
```

### Word Blur In

```typescript
Motion("word-blur", ".subheading", {
  split: "words",
  from: { opacity: 0, filter: "blur(10px)" },
  duration: 0.6,
  stagger: { each: 0.08, from: "start" },
  ease: "power2.out",
}).onPageLoad();
```

### Lines + Mask on Scroll

```typescript
Motion("lines-scroll", ".body-text", {
  split: "lines",
  mask: true,
  from: { y: "110%" },
  duration: 0.7,
  stagger: { each: 0.12, from: "start" },
  ease: "power3.out",
}).onScroll({
  toggleActions: "play none none none",
  start: "top 80%",
});
```

## API Reference

```typescript
interface AnimationConfig {
  split?: 'chars' | 'words' | 'lines' | 'chars,words' | 'words,lines' | 'chars,words,lines';
  mask?:  boolean;  // overflow:hidden clip wrapper per unit
  maskPadding?: number | string | {
    inline?: number | string;
    block?: number | string;
  };
}
```

---

Related: [Stagger](/docs/sdk/stagger) · [Opacity](/docs/sdk/opacity) · [Translate](/docs/sdk/translate)

---

## Custom CSS Properties

> Animate any CSS property using custom key-value pairs and the advanced code field.

URL: https://motion.page/docs/sdk/custom-properties

import LivePreview from "../../components/docs/blocks/LivePreview";

The `from` and `to` objects accept **any animatable CSS property** — not just named shortcuts like `opacity` or `scale`. Pass properties in camelCase (`boxShadow`) or as a quoted kebab-case string (`'box-shadow'`), and the SDK animates them directly.

## Basic Usage

Add any CSS property directly to `from` or `to`:

```typescript
import { Motion } from "@motion.page/sdk";

Motion("card-hover", ".card", {
  to: {
    boxShadow: "0 20px 40px rgba(0, 0, 0, 0.2)",
    outline: "2px solid #6633EE",
    outlineOffset: "4px",
  },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

Quoted kebab-case strings work identically — both forms map to the same CSS property:

```typescript
Motion("shadow-in", ".card", {
  to: { "box-shadow": "0 8px 24px rgba(0, 0, 0, 0.15)" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

<LivePreview client:load
  height={200}
  title="Box shadow and border radius on hover"
  html={`<div class="scene"><div class="card">Hover me</div></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #0d0d14; }
.card { padding: 28px 48px; background: #1e1b38; color: #fff; border-radius: 8px; cursor: pointer; font-family: sans-serif; font-size: 0.95rem; font-weight: 500; letter-spacing: 0.01em; user-select: none; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("card-hover", ".card", {
  to: {
    boxShadow: "0 16px 40px rgba(102,51,238,0.45)",
    borderRadius: "20px",
  },
  duration: 0.3,
  ease: "power3.out",
}).onHover({ each: true, onLeave: "reverse" });`}
/>

## CSS Custom Properties (Variables)

Animate CSS custom properties (CSS variables) using a quoted `'--property-name'` key:

```typescript
Motion("palette-shift", ":root", {
  from: { "--brand-hue": "220" },
  to: { "--brand-hue": "300" },
  duration: 1,
}).onScroll({ scrub: true });
```

```css
@property --brand-hue {
  syntax: "<number>";
  initial-value: 220;
  inherits: true;
}

.button {
  background: hsl(var(--brand-hue), 70%, 55%);
}
```

Registering the variable with `@property` tells the browser its syntax type, enabling smooth CSS-level transitions. Without registration, the SDK still sets the value, but the browser cannot interpolate it — simpler numeric-like strings (e.g. `'220'`, `'0.5'`) that the SDK can parse directly will still tween correctly regardless.

## String vs Numeric Values

| Value | Behavior | Example |
|-------|----------|---------|
| **Number** | The SDK appends `px` for length properties; unitless for others | `borderRadius: 8` → `8px` |
| **String** | Passed verbatim — required for units other than `px` or multi-value properties | `borderRadius: '50%'`, `boxShadow: '0 4px 12px #000'` |

Always use a **string** for:
- Multi-value properties: `boxShadow`, `textShadow`, `backdropFilter`, `backgroundImage`
- Non-`px` units: `'1.5rem'`, `'50%'`, `'0.1em'`

Always use a **number** for:
- Unitless properties: `opacity`, `zIndex`
- Properties where `px` is the correct unit and you don't need to specify it: `outlineOffset: 4`

## Commonly Used Custom Properties

Properties beyond the named SDK shortcuts that animate cleanly:

| Property | camelCase | Example Value |
|----------|-----------|---------------|
| Box shadow | `boxShadow` | `'0 8px 24px rgba(0,0,0,0.15)'` |
| Text shadow | `textShadow` | `'0 2px 8px rgba(0,0,0,0.4)'` |
| Backdrop filter | `backdropFilter` | `'blur(12px)'` |
| Outline | `outline` | `'2px solid #6633EE'` |
| Outline offset | `outlineOffset` | `'4px'` |
| Line height | `lineHeight` | `'1.6'` |
| Max width | `maxWidth` | `'800px'` |
| Border color | `borderColor` | `'rgba(102, 51, 238, 0.6)'` |
| Border width | `borderWidth` | `'2px'` |
| Column gap | `columnGap` | `'32px'` |
| Object position | `objectPosition` | `'50% 0%'` |
| Padding (single side) | `paddingTop` | `'24px'` |
| CSS variable | `'--my-var'` | `'220'` |

> **Named shortcuts** like `borderRadius`, `letterSpacing`, `fontSize`, `filter`, `clipPath`, `backgroundColor`, `color`, `width`, and `height` are already part of `AnimationVars` and work exactly the same way — no special handling needed.

## Common Patterns

### Box Shadow Lift on Hover

The classic card lift effect — start from no shadow and animate to a deep shadow on hover:

```typescript
Motion("lift", ".card", {
  to: { boxShadow: "0 16px 32px rgba(0, 0, 0, 0.18)" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

Because `boxShadow: none` (no shadow) is the element's natural CSS state, omitting `from` lets the SDK read it automatically.

### Frosted Glass Reveal

Animate a backdrop blur overlay into view on scroll:

```typescript
Motion("glass", ".overlay", {
  from: {
    backdropFilter: "blur(0px)",
    opacity: 0,
  },
  to: {
    backdropFilter: "blur(16px)",
    opacity: 1,
  },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Glowing Text Shadow on Scroll

Drive a text glow effect with scroll progress:

```typescript
Motion("glow", ".headline", {
  from: { textShadow: "0 0 0px rgba(102, 51, 238, 0)" },
  to: { textShadow: "0 0 32px rgba(102, 51, 238, 0.8)" },
  duration: 1,
}).onScroll({ scrub: true });
```

For shadow interpolation to tween smoothly, keep the **same number of shadow layers** in both `from` and `to`. Mismatched layer counts cause a hard swap at the midpoint.

### CSS Variable Theme Shift

Drive a hue-based color scheme with scroll, affecting every element that references the variable:

```typescript
Motion("hue-scroll", ":root", {
  from: { "--accent-hue": "200" },
  to: { "--accent-hue": "320" },
  duration: 1,
}).onScroll({ scrub: true });
```

```css
@property --accent-hue {
  syntax: "<number>";
  initial-value: 200;
  inherits: true;
}

a, button, .badge {
  color: hsl(var(--accent-hue), 80%, 60%);
}
```

### Multi-Property Transition (Timeline)

Chain custom properties across multiple animation steps:

```typescript
Motion("reveal-card", ".card", [
  {
    target: ".card",
    from: { opacity: 0, boxShadow: "0 0px 0px rgba(0,0,0,0)" },
    to: { opacity: 1, boxShadow: "0 8px 24px rgba(0,0,0,0.12)" },
    duration: 0.4,
    ease: "power2.out",
  },
  {
    target: ".card",
    to: { borderRadius: "20px", outlineOffset: "6px" },
    duration: 0.3,
    ease: "power2.inOut",
  },
]).onScroll({ scrub: false, toggleActions: "play none none none" });
```

## In the Motion.page Builder

In the builder, the **Custom Property** field lets you add any animatable CSS property as a key-value pair. To remove a custom property in column view, **right-click** the property row and choose Remove from the context menu.

Click the **code field icon** to switch between the standard input and the **Advanced Code Field**. The Advanced Code Field accepts any valid key/value pair from the animation `from`/`to` object — useful for complex multi-value strings like `boxShadow` or `backdropFilter` that are difficult to express in a single-value input.

## Notes

- Use camelCase (`boxShadow`) or a quoted kebab-case string (`'box-shadow'`) — both resolve to the same property.
- For shadow properties (`boxShadow`, `textShadow`), keep the number of shadow layers identical on both ends for smooth interpolation. Mismatched layers hard-swap at progress 0.5.
- CSS custom properties (`'--my-var'`) with numeric string values (e.g. `'220'`) tween correctly without `@property`. Use `@property` registration when you need CSS-level fallback interpolation or when the value is not a simple number.
- Not every CSS property can be animated — only properties the browser can interpolate (numeric, color, or parseable values). Properties like `display`, `position`, or `font-family` cannot be tweened.
- Custom properties work alongside all named shortcuts in the same `from`/`to` object — mix freely.

---

## Getting Started

> Install the SDK, create your first animation, and understand the basic pattern.

URL: https://motion.page/docs/sdk/getting-started

import Tabs from "../../components/docs/blocks/Tabs.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

## Installation

<Tabs items={[
  { label: "npm", code: "npm install @motion.page/sdk", lang: "bash" },
  { label: "bun", code: "bun add @motion.page/sdk", lang: "bash" },
  { label: "pnpm", code: "pnpm add @motion.page/sdk", lang: "bash" },
  { label: "yarn", code: "yarn add @motion.page/sdk", lang: "bash" },
]} />

## Quick Start

<LivePreview client:load
  height={200}
  title="Fade-in animation demo"
  html={`<div class="box"></div>`}
  css={`.box {
  width: 100px;
  height: 100px;
  background: #6633ee;
  border-radius: 12px;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("fade-in", ".box", {
  from: { opacity: 0, y: 30 },
  duration: 0.8,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

`Motion(name, target, config)` creates a **named timeline**. `.play()` triggers it immediately.

## The Core Pattern

Every animation follows the same shape:

```ts
Motion(name, target, config).trigger()
```

- **name** — Registry key. The same name always returns the same `Timeline` instance, so you can reference it from anywhere.
- **target** — CSS selector, `Element`, `NodeList`, or an array of elements.
- **config** — Animation properties: `from`, `to`, `duration`, `ease`, `stagger`, and more.
- **trigger** — How the animation starts.

Common triggers at a glance:

```ts
// Play on page load
Motion('hero', 'h1', { from: { opacity: 0 }, duration: 0.6 }).onPageLoad();

// Scrub on scroll
Motion('parallax', '.bg', { from: { y: -100 }, to: { y: 100 } }).onScroll({ scrub: true });

// Lift on hover (each card independently)
Motion('cards', '.card', { to: { y: -8 }, duration: 0.3 }).onHover({ each: true, onLeave: 'reverse' });
```

## CDN / Script Tag

No bundler? Import the SDK directly from the CDN in a module script:

```html
<script type="module">
  import { Motion } from "https://cloud.motion.page/sdk/latest.js";

  Motion('fade', '.box', {
    from: { opacity: 0, y: 20 },
    duration: 0.6,
  }).onPageLoad();
</script>
```

## Next Steps

- [Opacity](/docs/sdk/opacity) — start with the simplest animation property
- [Page Load Trigger](/docs/sdk/page-load) — auto-play animations when the page loads
- [Text Splitter](/docs/sdk/split-text) — split text into chars, words, or lines for staggered reveals
- [Motion() Factory](/docs/sdk/motion-factory) — complete API reference for the core function

---

## Responsive Animations

> Create animations that adapt to different screen sizes with Motion.responsive and breakpoints.

URL: https://motion.page/docs/sdk/responsive

import LivePreview from "../../components/docs/blocks/LivePreview";

`Motion.responsive()` registers one timeline with a separate variant per device tier and swaps the active variant live as the viewport crosses a breakpoint. It's the modern, reactive way to build responsive animations — define each tier once, and the SDK handles selecting, building, and tearing down the right variant as the screen changes.

## Basic Usage

Pass a name, a map of per-tier variant factories, and your breakpoint pixel boundaries:

```typescript
import { Motion } from "@motion.page/sdk";

Motion.responsive(
  "hero",
  {
    desktop: () =>
      Motion("hero", ".hero-title", {
        from: { opacity: 0, y: 60 },
        duration: 0.9,
        ease: "power2.out",
      }).onPageLoad(),

    laptop: () =>
      Motion("hero", ".hero-title", {
        from: { opacity: 0, y: 40 },
        duration: 0.8,
        ease: "power2.out",
      }).onPageLoad(),

    tablet: () =>
      Motion("hero", ".hero-title", {
        from: { opacity: 0, y: 24 },
        duration: 0.6,
        ease: "power2.out",
      }).onPageLoad(),

    phone: () =>
      Motion("hero", ".hero-title", {
        from: { opacity: 0 },
        duration: 0.4,
      }).onPageLoad(),
  },
  { laptops: 992, tablets: 768, phones: 576 }
);
```

<LivePreview client:visible
  height={340}
  title="Responsive timeline that swaps with viewport width"
  html={`<div class="responsive-scene" data-tier="">
  <div class="responsive-toolbar">
    <span>Active Motion.responsive() tier</span>
    <strong class="active-tier">Detecting…</strong>
  </div>
  <div class="responsive-card">
    <div class="responsive-orb"></div>
    <div>
      <span class="responsive-kicker">ONE COMPONENT</span>
      <h3 class="responsive-title">Different motion at every size.</h3>
      <p>Resize the docs window to cross a breakpoint.</p>
    </div>
  </div>
</div>`}
  css={`.responsive-scene {
  --accent: #8b65ff;
  width: min(720px, 100%);
  padding: 18px;
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  background: radial-gradient(circle at 15% 0%, color-mix(in srgb, var(--accent) 25%, transparent), transparent 38%), #080b20;
}
.responsive-toolbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  margin-bottom: 14px;
  color: #969fc4;
  font-size: 12px;
}
.active-tier {
  padding: 6px 10px;
  border: 1px solid color-mix(in srgb, var(--accent) 70%, white 10%);
  border-radius: 999px;
  color: #f5f6ff;
  background: color-mix(in srgb, var(--accent) 22%, transparent);
  text-transform: capitalize;
}
.responsive-card {
  min-height: 210px;
  padding: 24px;
  border: 1px solid rgba(154, 168, 255, 0.18);
  border-radius: 17px;
  background: linear-gradient(145deg, rgba(25, 30, 61, 0.94), rgba(8, 11, 31, 0.96));
  display: grid;
  grid-template-columns: auto 1fr;
  align-items: center;
  gap: 22px;
  overflow: hidden;
}
.responsive-orb {
  width: 82px;
  aspect-ratio: 1;
  border-radius: 28px;
  background: radial-gradient(circle at 30% 24%, white, var(--accent) 24%, #1c2259 74%);
  box-shadow: 0 18px 55px color-mix(in srgb, var(--accent) 42%, transparent);
}
.responsive-kicker {
  color: var(--accent);
  font-size: 10px;
  font-weight: 800;
  letter-spacing: 0.14em;
}
.responsive-title {
  max-width: 430px;
  margin: 6px 0 8px;
  color: #f4f5ff;
  font-size: clamp(24px, 4.4vw, 40px);
  line-height: 1.02;
}
.responsive-card p { color: #979fbe; font-size: 13px; }
@media (max-width: 520px) {
  .responsive-toolbar { align-items: flex-start; flex-direction: column; }
  .responsive-card { grid-template-columns: 1fr; gap: 14px; padding: 20px; }
  .responsive-orb { width: 58px; border-radius: 20px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const scene = document.querySelector(".responsive-scene");
const label = document.querySelector(".active-tier");

function buildVariant(tier, from, accent) {
  label.textContent = tier;
  scene.dataset.tier = tier;
  scene.style.setProperty("--accent", accent);

  return Motion("responsive-preview", ".responsive-card", {
    from,
    duration: 0.8,
    ease: "power2.out",
    repeat: { times: -1, yoyo: true, delay: 0.6 },
  }).play();
}

const variants = {
  desktop: () => buildVariant("desktop", { opacity: 0, x: -70 }, "#9b72ff"),
  laptop: () => buildVariant("laptop", { opacity: 0, rotateY: 35 }, "#4f8cff"),
  tablet: () => buildVariant("tablet", { opacity: 0, y: 45 }, "#35d2c8"),
  phone: () => buildVariant("phone", { opacity: 0, scale: 0.86 }, "#ff6da8"),
};
const breakpoints = { laptops: 992, tablets: 768, phones: 576 };

Motion.responsive("responsive-preview", variants, breakpoints);`}
/>

Each variant is a **factory function** that builds and registers the timeline for its tier and returns it. When the viewport enters a tier, the SDK runs that tier's factory; when it leaves, the SDK kills that variant's timeline (cleaning up triggers and restoring element state) before building the next one. Only one variant is ever active.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | Identifier for the responsive timeline. |
| `variants` | `object` | Map of tier → factory. Keys: `desktop`, `laptop`, `tablet`, `phone`. |
| `breakpointConfig` | `object` | Pixel boundaries: `{ laptops, tablets, phones }`. |

### Tiers and ranges

The four tiers are strictly non-overlapping — exactly one matches any width:

| Tier | Range (with defaults) |
|------|------------------------|
| `desktop` | wider than `laptops` (`> 992px`) |
| `laptop` | `tablets + 1` to `laptops` (`769–992px`) |
| `tablet` | `phones + 1` to `tablets` (`577–768px`) |
| `phone` | up to `phones` (`≤ 576px`) |

### Sparse variants cascade up

You don't have to define every tier. Missing tiers **inherit from the closest wider tier**, in the order `desktop → laptop → tablet → phone`. Define only the tiers that actually differ:

```typescript
import { Motion } from "@motion.page/sdk";

Motion.responsive(
  "cards",
  {
    // Full effect on larger screens
    desktop: () =>
      Motion("cards", ".card", {
        from: { opacity: 0, y: 40 },
        duration: 0.6,
        stagger: 0.1,
      }).onScroll({ toggleActions: "play none none none" }),

    // Only phones get a lighter version; tablet inherits desktop
    phone: () =>
      Motion("cards", ".card", {
        from: { opacity: 0 },
        duration: 0.4,
      }).onScroll({ toggleActions: "play none none none" }),
  },
  { laptops: 992, tablets: 768, phones: 576 }
);
```

Here laptop and tablet both fall back to the `desktop` variant, while phone uses its own.

### Disabling a tier

To run **no animation** on a tier, omit it and ensure no wider tier defines one — or have its factory simply not register a timeline. A tier with nothing to inherit just leaves the element in its natural state on those screens.

---

## Default Breakpoint Values

Motion.page uses these defaults (configurable in Builder → Settings → Breakpoints). Pass the same values to `breakpointConfig` so SDK code and the Builder stay in sync:

| Device | Threshold |
|--------|-----------|
| Phones | `max-width: 576px` |
| Tablets | `max-width: 768px` |
| Laptops | `max-width: 992px` |
| Desktop | `min-width: 993px` |

See [Breakpoints](/docs/sdk/breakpoints) for the full threshold reference.

---

## Manual approach

`Motion.responsive()` is the recommended path. If you need full manual control — or want to gate a single animation behind a media query without variants — you can use native `window.matchMedia()` directly.

### Mobile-only animation

```typescript
import { Motion } from "@motion.page/sdk";

if (matchMedia("screen and (max-width: 576px)").matches) {
  Motion("mobile-reveal", ".hero", {
    from: { opacity: 0, y: 30 },
    duration: 0.6,
    ease: "power2.out",
  }).onPageLoad();
}
```

The check runs once at script execution. If it doesn't match, the animation is never registered — no overhead, no cleanup.

### Different animations per screen size

```typescript
import { Motion } from "@motion.page/sdk";

// Desktop: parallax scroll effect
if (matchMedia("screen and (min-width: 993px)").matches) {
  Motion("hero-parallax", ".hero-image", {
    from: { y: -60 },
    to: { y: 60 },
    duration: 1,
  }).onScroll({ scrub: true });
}

// Tablet: simpler fade-in on scroll
if (
  matchMedia("screen and (min-width: 577px) and (max-width: 992px)").matches
) {
  Motion("hero-fade", ".hero-image", {
    from: { opacity: 0 },
    duration: 0.8,
    ease: "power2.out",
  }).onScroll({ toggleActions: "play none none none" });
}

// Mobile: fade in on load
if (matchMedia("screen and (max-width: 576px)").matches) {
  Motion("hero-mobile", ".hero-image", {
    from: { opacity: 0 },
    duration: 0.5,
  }).onPageLoad();
}
```

### Disable an animation on mobile

```typescript
import { Motion } from "@motion.page/sdk";

// Skip on mobile — hover effects don't make sense on touch screens
if (matchMedia("screen and (min-width: 993px)").matches) {
  Motion("card-hover", ".card", {
    to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
    duration: 0.3,
    ease: "power2.out",
  }).onHover({ each: true, onLeave: "reverse" });
}
```

### Handling resize manually

A one-time `matchMedia` check doesn't react to resize. To rebuild on a breakpoint crossing, pair `Motion.context()` with a `matchMedia` change listener:

```typescript
import { Motion } from "@motion.page/sdk";

const mq = matchMedia("screen and (min-width: 993px)");

const build = () =>
  Motion.context(() => {
    if (mq.matches) {
      Motion("desktop-anim", ".card", {
        from: { opacity: 0, y: 40 },
        duration: 0.6,
        stagger: 0.1,
      }).onScroll({ toggleActions: "play none none none" });
    }
  });

let ctx = build();
mq.addEventListener("change", () => {
  ctx.revert();
  ctx = build();
});
```

`ctx.revert()` kills the context's timelines and restores initial CSS. This is exactly the resize handling `Motion.responsive()` does for you automatically — prefer it unless you need bespoke control.

---

## Reduced Motion

Respect the user's system preference with `prefers-reduced-motion`, regardless of which approach you use:

```typescript
import { Motion } from "@motion.page/sdk";

const prefersReduced = matchMedia("(prefers-reduced-motion: reduce)").matches;

Motion("hero", ".hero-title", {
  from: prefersReduced
    ? { opacity: 0 } // Accessibility: fade only, no movement
    : { opacity: 0, y: 60 },
  duration: prefersReduced ? 0.3 : 0.9,
  ease: "power2.out",
}).onPageLoad();
```

Or skip non-essential animations entirely:

```typescript
if (!matchMedia("(prefers-reduced-motion: reduce)").matches) {
  Motion("decorative-parallax", ".bg-shape", {
    from: { y: -80 },
    to: { y: 80 },
    duration: 1,
  }).onScroll({ scrub: true });
}
```

---

## Builder Breakpoints

When using the Motion.page Builder, responsive timelines are edited visually — pick a device, change values, and only the differences are stored per tier. The Builder generates the equivalent `Motion.responsive()` output automatically. Global thresholds live under **Settings → Breakpoints**.

See [Responsive Editing](/docs/builder/responsive-editing) for the full Builder workflow.

---

## Related

- [Core Concepts](/docs/sdk/core-concepts) — `Motion.context()` for lifecycle management
- [Breakpoints](/docs/sdk/breakpoints) — threshold reference
- [Page Load Trigger](/docs/sdk/page-load) — entrance animations on load
- [Scroll Trigger](/docs/sdk/scroll-trigger) — viewport-based triggers

---

## Performance & Best Practices

> Optimize animation performance — will-change, hardware acceleration, batch operations.

URL: https://motion.page/docs/sdk/performance

Smooth animations depend on keeping the browser out of its most expensive work. This guide covers what to animate, what to avoid, and how to get the most out of the SDK at scale.

---

## GPU-accelerated properties

The browser has two paths for rendering changes:

- **Composited path** — the GPU handles it. No layout recalculation, no repaint. Just frame-perfect compositing at 60+ fps.
- **Layout path** — the CPU recalculates the entire document tree, then repaints, then composites. This is expensive and causes jank.

**`transform` and `opacity` are composited.** Animating `x`, `y`, `scale`, `rotate`, `opacity` triggers zero layout work. The GPU promotes the element to its own layer and composites it each frame.

**Layout properties force a reflow.** Animating `width`, `height`, `top`, `left`, `margin`, or `padding` invalidates the document layout. The browser recalculates positions for the element and every element affected by it — every frame.

```typescript
// ❌ Triggers layout recalculation every frame
import { Motion } from "@motion.page/sdk";

Motion("bad-move", ".box", {
  from: { left: "0px" },
  to: { left: "200px" },
  duration: 0.6,
}).onPageLoad();

// ✅ Composited — GPU handles it, zero layout cost
Motion("good-move", ".box", {
  from: { x: 0 },
  to: { x: 200 },
  duration: 0.6,
}).onPageLoad();
```

The same principle applies to size changes. Use `scale` instead of `width`/`height` when you want an element to visually grow or shrink:

```typescript
// ❌ Triggers layout
Motion("bad-grow", ".card", {
  from: { width: "100px", height: "100px" },
  to: { width: "200px", height: "200px" },
  duration: 0.5,
}).onHover({ each: true, onLeave: "reverse" });

// ✅ Composited — visually identical for most hover effects
Motion("good-grow", ".card", {
  to: { scale: 1.08 },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

> **When layout properties are unavoidable** — if you must animate `width` or `height` for structural reasons (e.g., accordion expand), use the `fit` animation to FLIP between two states instead. See [Fit Animation](/docs/sdk/fit-animation).

---

## `will-change`

The `will-change` CSS property tells the browser to prepare for an upcoming animation by promoting the element to a GPU layer ahead of time.

```css
/* Hint that this element will animate */
.sidebar {
  will-change: transform;
}
```

**Use it sparingly.** Promoting too many elements consumes GPU memory and can actually make performance worse. Good candidates are elements that animate on a known trigger — a modal that slides in, a sidebar that opens.

**Do not add it globally or unconditionally.** Setting `will-change: transform` on every `.card` or every `.section` creates hundreds of GPU layers simultaneously, eating memory with no benefit for elements that haven't started animating yet.

```css
/* ❌ Too broad — promotes every card at page load */
.card {
  will-change: transform;
}

/* ✅ Add it just before animation, remove it after */
.card:hover {
  will-change: transform;
}
```

**The SDK does not use `will-change` internally.** When animating transforms, the SDK composes all transform properties into a single `transform` string per frame via an internal cache — which is enough for the browser to composite them on the GPU. `will-change: transform` is intentionally avoided because it pre-rasterizes the element as a bitmap at its current size. If you then scale the element up (e.g., a text block growing from `scale(0.1)` to `scale(1)`), the browser stretches a low-resolution bitmap rather than re-rendering the vector content — producing blurry text.

> **Bottom line:** let the SDK handle GPU promotion. Only add `will-change` to your CSS when you have a measured, specific reason for it.

---

## Batched rendering

The SDK collects all property changes made during an animation frame and flushes them together in a single batch at the end of the frame. This means animating 10 properties on 50 elements doesn't cause 500 DOM writes — it causes 50 (one per element), with each element's full transform composed into a single string before writing.

This happens automatically. You don't need to configure it.

**What you do need to watch: layout thrashing in callbacks.** If you read a layout property (like `getBoundingClientRect()` or `offsetHeight`) and then write to the DOM inside an `onUpdate` callback, you force the browser to recalculate layout mid-frame.

```typescript
// ❌ Reads layout, then writes — forces synchronous layout every frame
Motion("progress-bad", ".progress", {
  from: { width: "0%" },
  to: { width: "100%" },
  duration: 1,
  onUpdate: (progress) => {
    const height = document.querySelector(".container").offsetHeight; // READ — forces layout
    document.querySelector(".label").style.top = height * progress + "px"; // WRITE
  },
}).onScroll({ scrub: true, start: "top top", end: "bottom bottom" });

// ✅ Read layout once at setup, use the cached value in the callback
const container = document.querySelector(".container");
const containerHeight = container.offsetHeight; // READ once

Motion("progress-good", ".progress", {
  from: { width: "0%" },
  to: { width: "100%" },
  duration: 1,
  onUpdate: (progress) => {
    document.querySelector(".label").style.top = containerHeight * progress + "px"; // WRITE only
  },
}).onScroll({ scrub: true, start: "top top", end: "bottom bottom" });
```

The rule: **read before you animate, write inside callbacks**. Cache any layout measurements at setup time so your callbacks only write.

---

## ScrollTrigger performance

### Smooth scrub reduces per-frame cost

`scrub: true` links animation progress to scroll position directly — the animation updates on every scroll event. For complex timelines with many animated elements, this can be expensive.

Pass a number to `scrub` to add lag (in seconds). The animation catches up to the scroll position gradually rather than jumping to it each frame. This trades a little responsiveness for significant smoothing on heavy scenes.

```typescript
// ❌ Updates instantly on every scroll event — expensive for complex animations
Motion("parallax", ".layers", {
  from: { y: "-20%" },
  to: { y: "20%" },
  duration: 1,
}).onScroll({ scrub: true });

// ✅ Smoothing lag — animation chases scroll position at 0.5s
Motion("parallax", ".layers", {
  from: { y: "-20%" },
  to: { y: "20%" },
  duration: 1,
}).onScroll({ scrub: 0.5 });
```

### Play once, don't reverse

When elements don't need to reverse on scroll-out, use `toggleActions: "play none none none"`. This prevents the SDK from tracking the reverse state and re-playing the timeline on scroll-up.

```typescript
// ❌ Tracks enter/leave states — more work per scroll event
Motion("reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: 0.08,
}).onScroll({ each: true });

// ✅ Plays once and stops — no reverse tracking overhead
Motion("reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: 0.08,
}).onScroll({
  each: true,
  toggleActions: "play none none none",
  start: "top 85%",
});
```

### Recalculate after layout changes

Scroll trigger positions are calculated once at initialization. If your layout shifts after the page loads (fonts rendering, images loading, components mounting), those positions go stale. Call `Motion.refreshScrollTriggers()` after any layout-affecting operation.

```typescript
// After a layout change (e.g., accordion opened, content injected)
document.querySelector(".accordion").addEventListener("click", () => {
  openAccordion();
  Motion.refreshScrollTriggers();
});

// Or after all page resources finish loading
window.addEventListener("load", () => {
  Motion.refreshScrollTriggers();
});
```

### Use `each` carefully with large element sets

`each: true` creates an independent scroll trigger instance per element. Animating 200 cards with `each: true` creates 200 scroll listeners. For large sets, consider triggering the entire group at once and using `stagger` for the visual cascade:

```typescript
// ❌ 200 independent scroll trigger instances
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.5,
  stagger: 0.05,
}).onScroll({
  each: true,
  toggleActions: "play none none none",
  start: "top 85%",
});

// ✅ One scroll trigger fires for the group, stagger handles sequencing
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.5,
  stagger: 0.05,
  ease: "power2.out",
}).onScroll({
  toggleActions: "play none none none",
  start: "top 85%",
});
```

---

## Stagger over multiple timelines

Creating a separate timeline for each element is the slowest way to animate a group. Each timeline registers its own name, tracks its own state, and participates in the RAF loop independently.

One timeline with `stagger` is always more efficient than N timelines without it.

```typescript
// ❌ 6 timelines — 6x the state tracking, 6x the overhead
["#step-1", "#step-2", "#step-3", "#step-4", "#step-5", "#step-6"].forEach(
  (selector, i) => {
    Motion(`step-${i}`, selector, {
      from: { opacity: 0, y: 20 },
      duration: 0.5,
      delay: i * 0.1,
    }).onPageLoad();
  }
);

// ✅ One timeline — same visual result, fraction of the overhead
Motion("steps", ".step", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.1,
  ease: "power2.out",
}).onPageLoad();
```

For complex multi-phase sequences where different elements have different animations, use a [multi-step timeline](/docs/sdk/sequencing) instead of separate named timelines:

```typescript
// ❌ Three timelines — disjointed sequencing, harder to coordinate
Motion("hero-bg", ".hero-bg", { from: { opacity: 0 }, duration: 0.4 }).onPageLoad();
Motion("hero-title", ".hero-title", { from: { y: 40, opacity: 0 }, duration: 0.6, delay: 0.3 }).onPageLoad();
Motion("hero-cta", ".hero-cta", { from: { scale: 0.9, opacity: 0 }, duration: 0.4, delay: 0.7 }).onPageLoad();

// ✅ One timeline — coordinated, one RAF participant
Motion("hero", [
  { target: ".hero-bg",    from: { opacity: 0 },               duration: 0.4 },
  { target: ".hero-title", from: { y: 40, opacity: 0 },        duration: 0.6, position: "+=0.1" },
  { target: ".hero-cta",   from: { scale: 0.9, opacity: 0 },   duration: 0.4, position: "+=0.1" },
]).onPageLoad();
```

---

## Memory management

Each named timeline stays in the registry until explicitly killed. In long-running applications — especially SPAs — failing to clean up old timelines leads to memory leaks and stale scroll triggers attached to removed DOM nodes.

### Kill a single timeline

```typescript
// Kill a timeline when it's no longer needed — restores original CSS
Motion.kill("hero");

// Rebuild it fresh
Motion("hero", ".hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
```

### Kill all timelines

```typescript
// Full teardown — use before a major navigation or reset
Motion.killAll();
Motion.cleanup(); // Detaches ScrollTriggers and safely removes their spacer/marker nodes
```

### SPA cleanup with `Motion.context()`

**`Motion.context()`** is the right tool for React, Vue, Svelte, and any framework that mounts and unmounts components. It tracks every timeline created inside the factory function and reverts them all on `ctx.revert()`.

```typescript
// React — clean up on unmount
import { useEffect } from "react";
import { Motion } from "@motion.page/sdk";

function HeroSection() {
  useEffect(() => {
    const ctx = Motion.context(() => {
      Motion("hero-title", ".hero-title", {
        from: { opacity: 0, y: 30 },
        duration: 0.7,
        ease: "power2.out",
      }).onPageLoad();

      Motion("hero-cards", ".hero-card", {
        from: { opacity: 0, y: 40 },
        duration: 0.5,
        stagger: 0.1,
      }).onScroll({ toggleActions: "play none none none", start: "top 80%" });
    });

    return () => ctx.revert(); // kills all timelines created above
  }, []);

  return <section className="hero">{/* ... */}</section>;
}
```

```typescript
// Vue — cleanup in onUnmounted
import { onMounted, onUnmounted } from "vue";
import { Motion, type MotionContext } from "@motion.page/sdk";

let ctx: MotionContext | undefined;

onMounted(() => {
  ctx = Motion.context(() => {
    Motion("card-hover", ".card", {
      to: { y: -6, boxShadow: "0 8px 20px rgba(0,0,0,0.12)" },
      duration: 0.3,
    }).onHover({ each: true, onLeave: "reverse" });
  });
});

onUnmounted(() => {
  ctx?.revert();
});
```

```typescript
// Astro View Transitions — revert on each page swap
import { Motion, type MotionContext } from "@motion.page/sdk";

let ctx: MotionContext | undefined;

document.addEventListener("astro:page-load", () => {
  ctx?.revert();
  ctx = Motion.context(() => {
    Motion("page-intro", ".page-content", {
      from: { opacity: 0, y: 20 },
      duration: 0.5,
    }).onPageLoad();
  });
});
```

> **Calling `Motion(name, ...)` on an existing name appends, not replaces.** If a timeline with that name already exists (e.g., after a hot reload or SPA navigation without cleanup), new entries are added to the existing timeline. Call `Motion.kill(name)` first, or use `Motion.context()` which handles this automatically via `ctx.revert()`.

---

## Quick reference

| Situation | Recommendation |
|-----------|---------------|
| Moving elements | Use `x`/`y`, not `top`/`left` |
| Resizing elements | Use `scale`, or `fit` for structural changes |
| Fading elements | `opacity` — always composited |
| Many elements entering on scroll | One trigger + `stagger`, not `each: true` |
| Complex entry sequence | Multi-step timeline, not multiple named timelines |
| Smooth parallax scrub | `scrub: 0.3` – `scrub: 1` |
| Play-once scroll reveal | `toggleActions: "play none none none"` |
| React/Vue unmount | `Motion.context()` + `ctx.revert()` |
| SPA navigation | `Motion.killAll()` + `Motion.cleanup()` |
| Layout changed after init | `Motion.refreshScrollTriggers()` |

---

Related: [Sequencing](/docs/sdk/sequencing) · [Stagger](/docs/sdk/stagger) · [Scroll Trigger](/docs/sdk/scroll-trigger) · [Fit Animation](/docs/sdk/fit-animation)

---

## Hover Trigger

> Play animations on mouse enter with reverse or restart on leave.

URL: https://motion.page/docs/sdk/hover

import LivePreview from "../../components/docs/blocks/LivePreview";

`.onHover()` plays a timeline when the pointer enters a target element and reacts when the pointer leaves — reversing by default, or pausing, stopping, restarting, or doing nothing based on your configuration.

## Basic usage

Chain `.onHover()` after defining your animation. By default, leaving the element smoothly reverses the timeline back to its start state.

<LivePreview
  client:load
  height={200}
  title="Hover lift effect"
  html={`<div class="card">Hover me</div>`}
  css={`.card {
  width: 160px;
  height: 80px;
  background: #6633EE;
  border-radius: 12px;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  font-family: sans-serif;
  font-size: 15px;
  font-weight: 600;
  cursor: pointer;
  box-shadow: 0 4px 12px rgba(102,51,238,0.3);
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("lift", ".card", {
  to: { y: -8, boxShadow: "0 16px 32px rgba(102,51,238,0.35)" },
  duration: 0.28,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });`}
/>

---

## Options

| Option       | Type                                                    | Default                | Description                                                                        |
| ------------ | ------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `target`     | `string \| Element`                                     | First animated element | Element or selector whose pointer area triggers the timeline.                      |
| `each`       | `boolean`                                               | `false`                | Create an independent timeline instance per matched element.                       |
| `onEnter`    | `'play' \| 'restart'`                                   | `'play'`               | Resume from the current position, or restart a completed one-shot animation.       |
| `onLeave`    | `'reverse' \| 'pause' \| 'stop' \| 'restart' \| 'none'` | `'reverse'`            | What to do when the pointer leaves the element.                                    |
| `leaveDelay` | `number`                                                | `0`                    | Seconds to wait before running `onLeave`; re-entering during the delay cancels it. |

---

## `onLeave` behavior

Control what happens when the pointer leaves the element:

- **`'reverse'`** (recommended) — smoothly plays the timeline in reverse back to the start state.
- **`'pause'`** — holds the timeline at its current position; entering again resumes it.
- **`'stop'`** — pauses and resets the timeline to progress `0`.
- **`'restart'`** — snaps immediately to the start state and replays the animation forward.
- **`'none'`** — does nothing; an in-flight animation continues naturally after the pointer leaves.

```typescript
// Smoothly reverses on leave — feels natural for most hover effects
Motion("btn", ".btn", {
  to: { scale: 1.05, backgroundColor: "#7744FF" },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ onLeave: "reverse" });

// Snaps back and replays — good for looping-style feedback
Motion("badge", ".badge", {
  to: { rotate: 10 },
  duration: 0.2,
}).onHover({ onLeave: "restart" });

// Stays at end state — useful when hover reveals persistent UI
Motion("tooltip", ".tooltip", {
  from: { opacity: 0, y: 4 },
  duration: 0.2,
}).onHover({ onLeave: "none" });
```

---

## `each` — independent per-element instances

When a selector matches multiple elements, all elements share **one timeline** by default. To let hovering any matched element play that group timeline, pass the same selector as `target`. Use `each: true` to give every element its own independent timeline instance.

```typescript
// Without each — hovering any card affects all cards simultaneously
Motion("cards", ".card", {
  to: { y: -8 },
  duration: 0.3,
}).onHover({ target: ".card", onLeave: "reverse" });

// With each — each card responds independently
Motion("cards", ".card", {
  to: { y: -8 },
  duration: 0.3,
}).onHover({ each: true, onLeave: "reverse" });
```

`each: true` is almost always what you want when the selector targets a list of interactive items like cards, buttons, nav links, or gallery items.

---

## Card lift with shadow

```typescript
Motion("card-hover", ".card", {
  to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

---

## Scale on hover

```typescript
Motion("scale-hover", ".thumb", {
  to: { scale: 1.06 },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

---

## Background color change

```typescript
Motion("color-hover", ".nav-link", {
  to: { backgroundColor: "#f0ebff", color: "#6633EE" },
  duration: 0.2,
  ease: "power1.out",
}).onHover({ each: true, onLeave: "reverse" });
```

---

## Reveal an overlay on hover

```typescript
Motion("overlay-hover", ".gallery-item", {
  to: { opacity: 1 },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });
```

---

## Staggered grid ripple on hover

```typescript
Motion("grid-hover", ".cell", {
  to: { scale: 1.1, backgroundColor: "#6633EE" },
  duration: 0.3,
  stagger: {
    each: 0.03,
    from: "center",
    grid: "auto",
  },
  ease: "power2.out",
}).onHover({ onLeave: "reverse" });
```

---

## Using `to` for hover effects

Hover effects typically use `to` rather than `from` — the element starts at its natural CSS state and animates to the hover state. The SDK reads the current computed styles as the `from` automatically.

```typescript
// ✅ to-only — starts at natural state, animates to hover values
Motion("btn-hover", ".btn", {
  to: { scale: 1.08, letterSpacing: "0.05em" },
  duration: 0.25,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });

// ❌ Unnecessary — natural defaults (scale: 1) don't need to be declared in from
Motion("btn-hover", ".btn", {
  from: { scale: 1 },
  to: { scale: 1.08 },
  duration: 0.25,
}).onHover({ each: true, onLeave: "reverse" });
```

---

## Related

- [Click Trigger](/docs/sdk/click) — toggle animations on click
- [Mouse Movement](/docs/sdk/mouse-movement) — animate based on cursor position
- [Scroll Trigger](/docs/sdk/scroll-trigger) — trigger animations on scroll

---

## Motion() Factory

> Complete reference for the Motion() function — retrieve, create, and configure timelines.

URL: https://motion.page/docs/sdk/motion-factory

import LivePreview from "../../components/docs/blocks/LivePreview";

`Motion()` is the single entry point for every animation in the SDK. Call it to create a **named timeline**, retrieve an existing one, or build a multi-step sequence — then chain a trigger to activate it.

---

## Import

```typescript
import { Motion } from "@motion.page/sdk";
```

No-bundler environments can import `Motion` directly from the CDN:

```html
<script type="module">
  import { Motion } from "https://cloud.motion.page/sdk/latest.js";

  Motion("fade", ".box", { from: { opacity: 0 }, duration: 0.6 }).onPageLoad();
</script>
```

---

## Function Signatures

`Motion` has three call signatures:

```typescript
// 1. Retrieve an existing timeline by name
Motion(name: string): Timeline

// 2. Single-animation timeline — one target, one config object
Motion(name: string, target: TargetInput, config: AnimationConfig): Timeline

// 3. Multi-step timeline — array of animation entries
Motion(name: string, animations: AnimationEntry[]): Timeline
```

The `name` is a **registry key**. The same name always returns the same `Timeline` instance, anywhere in your code. Passing `target` and `config` with an already-registered name **appends** to that timeline rather than replacing it — see [Appending Warning](#appending-warning).

---

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

// Create and play immediately
Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).play();

// Create and play on page load
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
  ease: "power2.out",
}).onPageLoad();

// Retrieve an existing timeline later by name
const tl = Motion("hero");
tl.pause();
```

---

<LivePreview client:load
  height={220}
  title="Motion() factory — sequential fade in"
  html={`<div class="scene">
  <div class="box box-a"></div>
  <div class="box box-b"></div>
  <div class="box box-c"></div>
</div>`}
  css={`.scene {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 24px;
  height: 100%;
}
.box {
  width: 72px;
  height: 72px;
  border-radius: 14px;
}
.box-a { background: #6633EE; }
.box-b { background: #9955FF; }
.box-c { background: #CC88FF; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("factory-demo", ".box", {
  from: { opacity: 0, y: 30 },
  duration: 0.55,
  stagger: 0.16,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

---

## TargetInput

The `target` parameter (overload 2) and the `target` field in each `AnimationEntry` (overload 3) accept a **`TargetInput`**:

| Type | Example |
|------|---------|
| CSS selector string | `"#hero"`, `".card"`, `"[data-animate]"` |
| `string[]` | `["#title", "#subtitle"]` |
| `Element` | `document.querySelector(".box")` |
| `NodeList` | `document.querySelectorAll(".item")` |
| `Element[]` | Array of DOM elements |
| Plain object | `{ value: 0 }` — for non-DOM tweening |
| Array of plain objects | `[{ count: 0 }, { count: 100 }]` |

CSS selectors are the most common form. Plain objects are useful for tweening arbitrary JS values — for example, driving a canvas counter or animating a custom data property:

```typescript
const counter = { value: 0 };

Motion("count-up", counter, {
  to: { value: 1000 },
  duration: 2,
  ease: "power2.out",
  onUpdate: () => {
    document.querySelector("#counter")!.textContent =
      Math.round(counter.value).toString();
  },
}).onPageLoad();
```

---

## AnimationConfig

The config object passed to overload 2, and embedded in each `AnimationEntry` in overload 3.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `from` | `AnimationVars` | — | Start values. SDK reads current CSS as `to` when only `from` is specified |
| `to` | `AnimationVars` | — | End values. SDK reads current CSS as `from` when only `to` is specified |
| `duration` | `number` | `0.5` | Animation duration in seconds |
| `delay` | `number` | `0` | Seconds to wait before the animation starts |
| `ease` | `string` | `"power1.inOut"` | Easing curve — e.g. `"power2.out"`, `"elastic.out"` |
| `stagger` | `number \| StaggerVars` | — | Per-element delay when target matches multiple elements |
| `repeat` | `number \| RepeatConfig` | — | Repeat count for this animation. `-1` = infinite |
| `split` | `SplitType` | — | Split text into chars, words, or lines before animating |
| `mask` | `boolean` | `false` | Wraps split elements in `overflow: hidden` containers for reveal effects |
| `flap` | `FlapConfig` | — | Split-flap / character-scramble effect. Requires `split: 'chars'` |
| `fit` | `FitConfig` | — | FLIP-style morph between two elements. Overrides `from`/`to` |
| `axis` | `'x' \| 'y'` | — | Axis binding for `.onMouseMove()` trigger |
| `onStart` | `() => void` | — | Fired when the animation begins |
| `onUpdate` | `(progress: number) => void` | — | Fired on every frame with current progress (0–1) |
| `onComplete` | `() => void` | — | Fired when the animation finishes |
| `onRepeat` | `(repeatCount: number) => void` | — | Fired after each repeat cycle |
| `onReverseComplete` | `() => void` | — | Fired when animation completes in reverse |

Full TypeScript shape:

```typescript
interface AnimationConfig {
  from?:              AnimationVars;
  to?:                AnimationVars;
  duration?:          number;
  delay?:             number;
  ease?:              string;
  stagger?:           number | StaggerVars;
  repeat?:            number | RepeatConfig;
  split?:             SplitType;
  mask?:              boolean;
  flap?:              FlapConfig;
  fit?:               FitConfig;
  axis?:              'x' | 'y';
  onStart?:           () => void;
  onUpdate?:          (progress: number) => void;
  onComplete?:        () => void;
  onRepeat?:          (repeatCount: number) => void;
  onReverseComplete?: () => void;
}
```

---

## AnimationVars

All properties that can appear in `from` and `to` blocks.

### Transforms

| Property | Type | Notes |
|----------|------|-------|
| `x` | `number \| string` | Translate X — pixels by default (`50` = `50px`) |
| `y` | `number \| string` | Translate Y — pixels by default |
| `z` | `number \| string` | Translate Z — pixels by default |
| `rotate` | `number \| string` | Rotation in degrees (`90` = `90deg`) |
| `rotateX` | `number \| string` | 3D rotation around X axis |
| `rotateY` | `number \| string` | 3D rotation around Y axis |
| `rotateZ` | `number \| string` | 3D rotation around Z axis (same as `rotate`) |
| `scale` | `number` | Uniform scale — unitless (`1.5` = 150%) |
| `scaleX` | `number` | Horizontal scale |
| `scaleY` | `number` | Vertical scale |
| `scaleZ` | `number` | Depth scale |
| `skewX` | `number \| string` | Horizontal skew in degrees |
| `skewY` | `number \| string` | Vertical skew in degrees |
| `perspective` | `number \| string` | CSS perspective depth |
| `transformOrigin` | `string` | Transform origin — e.g. `"50% 50%"`, `"top left"`, `"0% 100%"` |

### Visual

| Property | Type | Notes |
|----------|------|-------|
| `opacity` | `number` | `0` (transparent) to `1` (fully visible) |
| `backgroundColor` | `string` | Any CSS color string |
| `color` | `string` | Text / foreground color |
| `filter` | `string` | CSS filter string — e.g. `"blur(4px) brightness(0.8)"` |
| `clipPath` | `string` | CSS clip-path shape function (camelCase form) |
| `'clip-path'` | `string` | CSS clip-path shape function (kebab-case, must be quoted) |
| `boxShadow` | `string` | CSS box-shadow string |
| `borderRadius` | `number \| string` | Border radius — px or string |
| `borderColor` | `string` | Border color |
| `outlineColor` | `string` | Outline color |

### Layout

| Property | Type | Notes |
|----------|------|-------|
| `width` | `number \| string` | Element width — px or string with unit |
| `height` | `number \| string` | Element height — px or string with unit |
| `top` | `number \| string` | CSS `top` |
| `left` | `number \| string` | CSS `left` |
| `right` | `number \| string` | CSS `right` |
| `bottom` | `number \| string` | CSS `bottom` |
| `margin` | `string` | Shorthand margin |
| `padding` | `string` | Shorthand padding |
| `zIndex` | `number` | Stacking order |
| `backgroundPosition` | `string` | Background position |

### Typography

| Property | Type | Notes |
|----------|------|-------|
| `fontSize` | `number \| string` | Font size |
| `lineHeight` | `number \| string` | Line height |
| `letterSpacing` | `number \| string` | Letter spacing |

### SVG

| Property | Type | Notes |
|----------|------|-------|
| `fill` | `string` | SVG fill color |
| `stroke` | `string` | SVG stroke color |
| `drawSVG` | `string \| DrawSVGObject` | Animate SVG stroke — see [drawSVG](#drawsvg) |

### Motion Path

```typescript
path: {
  target:   string | Element;  // CSS selector, Element, or raw path data (M/m commands)
  align?:   string | Element;  // Align bounding box to this element
  alignAt?: [number, number];  // Origin point [x%, y%]; default [50, 50]
  start?:   number;            // Path start fraction 0–1; default 0
  end?:     number;            // Path end fraction 0–1; default 1
  rotate?:  boolean;           // Auto-rotate along the path tangent
}
```

### CSS Custom Properties

Any CSS custom property — prefix with `--`:

```typescript
to: { '--accent-color': '#9966FF', '--spacing': '24px' }
```

---

## from / to Resolution

The SDK **auto-resolves** the missing endpoint from the element's computed CSS at build time. Specify only what's different from the natural state.

| Config | Behavior |
|--------|----------|
| `from` only | SDK reads current CSS as `to`. Start at custom values, animate into natural state — use for **reveals** |
| `to` only | SDK reads current CSS as `from`. Start at natural state, animate to custom values — use for **hover/exit effects** |
| Both | Both endpoints explicit — use when neither endpoint matches the element's natural CSS |

**Natural CSS defaults** — the SDK treats these as the element's rest state. Omit them from `to` when they're the target endpoint:

`opacity: 1` · `x: 0` · `y: 0` · `z: 0` · `scale: 1` · `scaleX: 1` · `scaleY: 1` · `rotate: 0`

```typescript
// ✅ from-only — SDK fills in opacity:1, y:0 from the element's CSS
Motion("reveal", ".card", {
  from: { opacity: 0, y: 50 },
  duration: 0.6,
}).onPageLoad();

// ✅ to-only — start at natural state, hover to raised state
Motion("lift", ".card", {
  to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
  duration: 0.3,
}).onHover({ each: true, onLeave: "reverse" });

// ✅ both — parallax where neither endpoint is the natural state
Motion("parallax", ".bg", {
  from: { y: -60 },
  to:   { y: 60 },
}).onScroll({ scrub: true });

// ❌ redundant — opacity:1 and y:0 are natural defaults
Motion("bad", ".card", {
  from: { opacity: 0, y: 50 },
  to:   { opacity: 1, y: 0 },
}).onPageLoad();
```

---

## Multi-Step Timelines

Pass an array of `AnimationEntry` objects as the second argument to build coordinated sequences across multiple targets.

```typescript
Motion("intro", [
  { target: ".hero-title",    from: { opacity: 0, y: 40 }, duration: 0.7, ease: "power2.out" },
  { target: ".hero-subtitle", from: { opacity: 0, y: 30 }, duration: 0.6, ease: "power2.out" },
  { target: ".hero-cta",      from: { opacity: 0, y: 20 }, duration: 0.5, ease: "power2.out" },
]).onPageLoad();
```

By default, each step starts immediately after the previous one ends. Control timing with the `position` field.

### AnimationEntry

Every entry extends `AnimationConfig` with two additional fields:

| Field | Type | Description |
|-------|------|-------------|
| `target` | `TargetInput` | **Required.** CSS selector, `Element`, `NodeList`, or `Element[]` |
| `position` | `number \| string` | When in the timeline this step starts. Omit for sequential playback |

```typescript
interface AnimationEntry extends AnimationConfig {
  target:    TargetInput;
  position?: number | string;
}
```

---

## Position Syntax

Used in `AnimationEntry.position`, `tl.call()`, and scroll trigger `end` values.

| Value | Meaning |
|-------|---------|
| `0.5` | Absolute — 0.5 s from the timeline start |
| `"+=0.5"` | 0.5 s after the previous entry ends |
| `"-=0.3"` | 0.3 s before the previous entry ends (overlap) |
| `">"` | Immediately after the previous entry ends (same as default) |
| `"<"` | Same start time as the previous entry (parallel) |
| `"<0.2"` | 0.2 s after the **start** of the previous entry |
| `">-0.1"` | 0.1 s before the **end** of the previous entry |

```typescript
Motion("hero", [
  // Title and image start at the same time (parallel)
  { target: ".title", from: { opacity: 0, y: 40 }, duration: 0.8, ease: "power3.out" },
  { target: ".image", from: { opacity: 0, scale: 0.9 }, duration: 0.8, ease: "power2.out", position: "<" },
  // Badge appears 0.3 s after both start
  { target: ".badge", from: { opacity: 0, scale: 0 }, duration: 0.4, ease: "back.out", position: "<0.3" },
  // Footer enters with a gap after everything else
  { target: ".footer", from: { opacity: 0 }, duration: 0.4, position: "+=0.2" },
]).onPageLoad();
```

---

## Timeline Object

Every `Motion()` call returns a `Timeline` instance with the following methods.

### Playback

```typescript
tl.play(from?: number): this       // Play forward; optional start time in seconds
tl.pause(atTime?: number): this    // Pause; optional snap-to time
tl.reverse(from?: number): this    // Play backward; optional start time
tl.restart(): this                 // Seek to 0, restore initial CSS, play forward
tl.seek(position: number): this    // Jump to time without playing
```

### State — Getter / Setter

Call with no argument to **read**; call with argument to **set** and return `this` for chaining.

```typescript
tl.duration(): number
tl.progress(value?: number): number | this   // Normalized 0–1
tl.time(value?: number): number | this       // Current time in seconds
tl.timeScale(value?: number): number | this  // Speed multiplier (2 = double speed)
tl.isActive(): boolean                       // True while playing
tl.getName(): string | undefined             // Registered name
```

### Callbacks at Positions

Insert callback functions at specific points in the timeline:

```typescript
tl.call(callback: (...args: unknown[]) => void, params?: unknown[], position?: string | number): this
```

```typescript
Motion("sequence", [
  { target: ".step-1", from: { opacity: 0 }, duration: 0.5 },
  { target: ".step-2", from: { opacity: 0 }, duration: 0.5 },
])
  .call(() => console.log("halfway"), [], 0.5)
  .call(() => console.log("done"))
  .onPageLoad();
```

### Lifecycle Callbacks

```typescript
tl.onStart(cb: () => void): this
tl.onUpdate(cb: (progress: number, time: number) => void): this
tl.onComplete(cb: () => void): this
tl.onRepeat(cb: (count: number) => void): this
```

### Cleanup

```typescript
tl.kill(clearProps?: boolean): void  // clearProps=true (default) restores initial CSS
tl.clear(): this                     // Reset and rebuild without destroying the instance
```

---

## Timeline Repeat

`.withRepeat()` loops the **entire timeline** — all steps replay as a group. This is different from per-animation `repeat`, which loops only one individual animation.

```typescript
tl.withRepeat(config: number | RepeatConfig): this
```

```typescript
// Infinite loop
Motion("pulse", ".dot", {
  from: { scale: 0.8, opacity: 0.6 },
  to:   { scale: 1.2, opacity: 1 },
  duration: 0.6,
}).withRepeat({ times: -1, yoyo: true }).onPageLoad();

// 3 times with yoyo + delay between cycles
Motion("bounce", [
  { target: ".box-a", to: { y: -40 }, duration: 0.4, ease: "power2.out" },
  { target: ".box-b", to: { y: -40 }, duration: 0.4, ease: "power2.out" },
]).withRepeat({ times: 3, yoyo: true, delay: 0.5 }).onPageLoad();
```

---

## Appending Warning

Calling `Motion(name, target, config)` when `name` already exists in the registry **appends** new entries to that timeline — it does **not** replace it.

> This is intentional for building multi-step timelines across multiple calls, but it will surprise you when trying to rebuild a timeline in response to a state change.

```typescript
// ❌ Wrong — appends a second animation to the existing "hero" timeline
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
// (somewhere later)
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();

// ✅ Correct — kill first, then rebuild from scratch
Motion("hero").kill();
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
```

---

## Static Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `Motion.set` | `(target: TargetInput, vars: AnimationVars): void` | Zero-duration property apply. Processes through the full engine pipeline — values persist on DOM |
| `Motion.get` | `(name: string): Timeline \| undefined` | Get a timeline by name; `undefined` if not registered |
| `Motion.has` | `(name: string): boolean` | Check whether a named timeline is registered |
| `Motion.getNames` | `(): string[]` | Array of all currently registered timeline names |
| `Motion.kill` | `(name: string): void` | Kill one timeline by name and restore initial CSS |
| `Motion.killAll` | `(): void` | Kill every registered timeline |
| `Motion.reset` | `(targets: TargetInput): void` | Kill animations, revert text splits, clear transform cache and inline styles |
| `Motion.refreshScrollTriggers` | `(): void` | Recalculate all scroll trigger positions after layout changes |
| `Motion.cleanup` | `(): void` | Detach active ScrollTriggers and safely remove their spacer/marker nodes; timelines remain registered |
| `Motion.context` | `(fn: () => void): MotionContext` | Create a scoped context tracking all timelines created inside `fn()` |
| `Motion.utils` | `MotionUtils` | Utility functions — see below |

### Motion.set

`Motion.set` immediately applies CSS properties with no animation, no timeline. Use it to set initial element states before animations run, preventing flashes of unstyled content:

```typescript
// Hide before page loads — no flash
Motion.set(".card", { opacity: 0, y: 30 });

// Reveal on scroll
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

### Motion.context

Creates a scoped context that tracks all timelines created inside the callback. Returns a `MotionContext` object for clean teardown and reinitialisation — essential for SPA navigation, AJAX pagination, and React effects.

```typescript
const ctx = Motion.context(() => {
  Motion("hero", ".title", { from: { opacity: 0, y: 30 }, duration: 0.8 }).onPageLoad();
  Motion("cards", ".card", { from: { y: 100 }, duration: 1 }).onScroll({ scrub: true });
});

// After dynamic content change (AJAX filter, pagination, etc.)
ctx.refresh();   // kills old animations, re-runs init, re-resolves selectors

// Add more animations to the context later
ctx.add(() => {
  Motion("footer", ".footer-item", { from: { opacity: 0 }, duration: 0.4 }).onPageLoad();
});

// Full cleanup (React unmount, route change, etc.)
ctx.revert();
```

**React pattern:**

```typescript
useEffect(() => {
  const ctx = Motion.context(() => {
    Motion("fade", ".box", { from: { opacity: 0 }, duration: 0.6 }).onScroll({ scrub: true });
  });
  return () => ctx.revert();
}, []);
```

**Astro View Transitions:**

```typescript
let ctx: MotionContext | undefined;

document.addEventListener("astro:page-load", () => {
  ctx?.revert();
  ctx = Motion.context(() => {
    Motion("page-reveal", ".animate-in", { from: { opacity: 0, y: 20 }, duration: 0.5 }).onPageLoad();
  });
});
```

---

## Motion.utils

A collection of mathematical utilities. Also importable as a named export:

```typescript
import { MotionUtils } from "@motion.page/sdk";
```

| Method | Signature | Description |
|--------|-----------|-------------|
| `toArray` | `(target, scope?) → Element[]` | Convert selector / NodeList / HTMLCollection / Element to a flat array |
| `clamp` | `(min, max, value?) → number \| fn` | Clamp value within range. Curried when `value` is omitted |
| `random` | `(min, max, snap?) → number` | Random number with optional snap increment |
| `snap` | `(snapTo, value?) → number \| fn` | Snap to nearest increment or array value. Curried when `value` is omitted |
| `interpolate` | `(start, end, progress) → number` | Linear interpolation (lerp) between two values |
| `mapRange` | `(inMin, inMax, outMin, outMax, value?) → number \| fn` | Map a value from one range to another. Curried when `value` is omitted |
| `normalize` | `(min, max, value?) → number \| fn` | Normalize a value to 0–1. Curried when `value` is omitted |
| `wrap` | `(min, max, value?) → number \| fn` | Modular wrap within a range. Curried when `value` is omitted |

```typescript
// toArray — convert selector to elements for manual iteration
const panels = Motion.utils.toArray(".panel");

// clamp — keep a value within bounds
const clamped = Motion.utils.clamp(0, 100, 150); // → 100

// Curried form — create a reusable clamp function
const clamp0to1 = Motion.utils.clamp(0, 1);
clamp0to1(1.5); // → 1

// mapRange — convert scroll progress to rotation
const progress = Motion.utils.mapRange(0, window.innerHeight, 0, 360, scrollY);

// interpolate — lerp between colors or numbers
const value = Motion.utils.interpolate(0, 100, 0.75); // → 75

// wrap — loop an index within a range
const index = Motion.utils.wrap(0, slides.length, currentIndex + 1);
```

---

## Trigger Methods

Timelines are **inert until a trigger is chained**. Creating a timeline with `Motion(name, target, config)` builds the animation but does not play or attach it.

| Method | Description |
|--------|-------------|
| `.play()` | Play immediately, right now |
| `.onPageLoad(config?)` | Play when DOM is ready — fires immediately if already loaded |
| `.onHover(config?)` | Play on `mouseenter`, react on `mouseleave` |
| `.onClick(config?)` | Play/replay on click; optionally reverse or restart |
| `.onScroll(config?)` | Scrub or snap animation to scroll position |
| `.onMouseMove(config?)` | Drive progress from mouse position |
| `.onPageExit(config?)` | Intercept link clicks, play animation, then navigate |
| `.onGesture(config)` | Map pointer / touch / wheel / scroll gestures to animation progress |
| `.onCursor(config)` | Replace the native cursor with an animated custom cursor |

Each trigger has its own configuration options — see the dedicated pages: [Page Load](/docs/sdk/page-load) · [Hover](/docs/sdk/hover) · [Click](/docs/sdk/click) · [Scroll Trigger](/docs/sdk/scroll-trigger) · [Mouse Movement](/docs/sdk/mouse-movement) · [Page Exit](/docs/sdk/page-exit) · [Gesture](/docs/sdk/observer-gesture) · [Custom Cursor](/docs/sdk/custom-cursor).

### each: true — Independent Per-Element Instances

Without `each`, all matched elements share one timeline instance (group behaviour). With `each: true`, every element gets its own independent timeline.

```typescript
// Group — hovering any card animates all of them
Motion("cards", ".card", { to: { y: -8 }, duration: 0.3 }).onHover({ target: ".card", onLeave: "reverse" });

// Independent — each card animates on its own hover
Motion("cards", ".card", { to: { y: -8 }, duration: 0.3 }).onHover({ each: true, onLeave: "reverse" });
```

`each: true` is supported in: `.onHover()`, `.onClick()`, `.onScroll()`, `.onMouseMove()`, `.onGesture()`.

---

## Stagger

`stagger` delays the start of each matched element's animation, creating cascade effects.

### Shorthand

Pass a number — each element waits that many seconds more than the previous:

```typescript
Motion("list", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.08,
}).onPageLoad();
// Element 1 at 0s, element 2 at 0.08s, element 3 at 0.16s …
```

### StaggerVars Object

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `each` | `number` | — | Seconds between each element |
| `amount` | `number` | — | Total spread across all elements (alternative to `each`) |
| `from` | `'start' \| 'end' \| 'center' \| 'edges' \| 'random' \| number` | `'start'` | Which element starts first |
| `grid` | `'auto' \| [number, number]` | — | Enable 2D grid staggering |
| `axis` | `'x' \| 'y'` | — | Axis to measure distance for grid stagger |
| `ease` | `string` | `'none'` | Easing for the stagger delay distribution |

```typescript
// Center-outward ripple on a grid
Motion("grid", ".cell", {
  from: { opacity: 0, scale: 0.6 },
  duration: 0.4,
  stagger: { each: 0.04, from: "center", grid: "auto" },
  ease: "power2.out",
}).onPageLoad();
```

See [Stagger](/docs/sdk/stagger) for the full stagger reference.

---

## Repeat Config

The `repeat` option on individual animations. For repeating the whole timeline, use [`.withRepeat()`](#timeline-repeat).

```typescript
// Shorthand number
repeat: 3     // 3 additional cycles after the first play
repeat: -1    // Infinite

// Full config object
interface RepeatConfig {
  times:  number;    // Additional repetitions; -1 = infinite
  delay?: number;    // Seconds between each repetition
  yoyo?:  boolean;  // Alternate direction each cycle
}
```

```typescript
// Infinite yoyo
Motion("breathe", ".logo", {
  to: { scale: 1.08 },
  duration: 1.2,
  ease: "sine.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();

// 3 times with yoyo + rest delay
Motion("shake", ".error-field", {
  from: { x: -6 },
  to:   { x:  6 },
  duration: 0.06,
  ease: "none",
  repeat: { times: 7, yoyo: true, delay: 0 },
}).play();
```

---

## Text Splitter

Split a text element into individual spans before animating. Each part becomes independently animatable.

### split values

| Value | Effect |
|-------|--------|
| `'chars'` | Wrap each character in a `<span>` |
| `'words'` | Wrap each word in a `<span>` |
| `'lines'` | Wrap each line in a `<span>` (layout-dependent) |
| `'chars,words'` | Both chars and words wrapped |
| `'words,lines'` | Both words and lines wrapped |
| `'chars,words,lines'` | All three levels wrapped |

```typescript
Motion("headline", "h1", {
  split: "words",
  from: { opacity: 0, y: "110%" },
  duration: 0.6,
  stagger: { each: 0.06, from: "start" },
  ease: "power3.out",
}).onPageLoad();
```

Split elements receive data attributes for CSS targeting:

| Attribute | Set on | Index attribute |
|-----------|--------|-----------------|
| `[data-split-char]` | Each character span | `data-char-index` |
| `[data-split-word]` | Each word span | `data-word-index` |
| `[data-split-line]` | Each line span | `data-line-index` |
| `[data-split]` | Root element | — |

Inline elements (e.g. `<span class="accent">`) are **preserved** during splitting.

See [Text Splitter](/docs/sdk/split-text) for the full text splitter reference.

---

## Mask

`mask: true` wraps each split element in an `overflow: hidden` container. The container clips the element during animation, creating a reveal effect where text appears to rise from beneath a surface.

Requires `split` to be set — `mask` has no effect without text splitting.

```typescript
// Lines slide up from behind a clip — classic editorial reveal
Motion("reveal", ".tagline", {
  split: "lines",
  mask: true,
  from: { y: "100%" },
  duration: 0.7,
  stagger: 0.1,
  ease: "power3.out",
}).onPageLoad();
```

The mask wrapper receives `[data-split-mask]` for CSS targeting.

---

## Flap (Text Flapper)

A split-flap display effect that cycles through intermediate characters before landing on the real text. Requires `split: 'chars'` on the same animation.

```typescript
Motion("scramble", ".tagline", {
  split: "chars",
  flap: {
    type: "flip",
    charset: "alphanumeric",
    cycles: [2, 5],
  },
  from: { opacity: 0 },
  duration: 1.2,
  stagger: 0.04,
}).onPageLoad();
```

### FlapConfig

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | `FlapType` | — | **Required.** Visual effect for each cycle |
| `charset` | `CharsetPreset \| string` | `'alphanumeric'` | Characters to cycle through. Pass a string for a custom set |
| `cycles` | `number \| [number, number]` | `3` | Intermediate characters before landing. Tuple = random range per cell |
| `perspective` | `number` | `400` | CSS perspective depth in px — applies to `flip` and `board` only |
| `styledBoard` | `boolean` | `false` | Render decorative flip-board cell UI — applies to `board` only |
| `stableWidth` | `boolean \| 'cells' \| 'container'` | `true` when `styledBoard` | Layout-shift strategy. `true`/`'cells'` pins each char cell to the widest glyph; `'container'` pins only the parent element's outer width so letters flow naturally inside |
| `preserveWhitespaceCells` | `boolean` | `false` | Animate whitespace characters as cycling placeholder cells |

### FlapType values

| Value | Description |
|-------|-------------|
| `'flip'` | 3D `rotateX` card flip. Composable with `from`/`to` transforms |
| `'fade'` | Opacity crossfade. **Owns `opacity`** — do not set `opacity` in `from`/`to` |
| `'slide'` | Characters slide in/out vertically |
| `'blur'` | Blur dissolve. **Owns `filter`** — do not set `filter` in `from`/`to` |
| `'scale'` | Characters scale in/out |
| `'board'` | Decorative split-flap board cells — use with `styledBoard: true` |
| `'none'` | No built-in style — run cycles only, drive visuals entirely via CSS |

### CharsetPreset values

| Value | Characters |
|-------|------------|
| `'alphanumeric'` | A–Z, 0–9 |
| `'alpha'` | A–Z only |
| `'numeric'` | 0–9 only |
| `'symbols'` | Punctuation and special characters |
| `'binary'` | `0` and `1` only |
| `'hex'` | 0–9, A–F |
| `'katakana'` | Japanese katakana characters |
| `'braille'` | Braille dot patterns |

See [Text Flapper](/docs/sdk/text-flapper) for the full reference.

---

## Fit (FLIP Morphing)

Measure both elements' bounding rects and animate the visual delta between them — a FLIP-style morph. When `fit` is set, `from` and `to` are ignored.

```typescript
Motion("morph", ".source", {
  fit: { target: ".destination", resize: true },
  duration: 0.5,
  ease: "power2.inOut",
}).play();
```

### FitConfig

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `target` | `string` | — | **Required.** CSS selector for the destination element |
| `absolute` | `boolean` | `false` | Convert source to absolute positioning during animation |
| `scale` | `boolean` | `true` | Use `scaleX`/`scaleY` — GPU-accelerated but distorts text and borders |
| `resize` | `boolean` | `false` | Animate actual `width`/`height` — no distortion, triggers layout reflow. **Mutually exclusive with `scale`** |

See [Fit Animation](/docs/sdk/fit-animation) for the full reference.

---

## drawSVG

Animate the visible portion of an SVG stroke. The element must have a `stroke` — the SDK auto-computes `stroke-dasharray` if not set.

| Input | Meaning |
|-------|---------|
| `"0% 100%"` | Full stroke visible |
| `"0% 0%"` | Fully hidden (start state for draw-in) |
| `"20% 80%"` | Middle portion only |
| `"50%"` | Shorthand for `"0% 50%"` |
| `"100px 500px"` | Pixel range along the stroke length |
| `"true"` | Full stroke (keyword) |
| `"false"` / `"none"` | Hidden |
| `{ start: 20, end: 80 }` | Object — values are **percentages 0–100** (not 0–1) |

```typescript
// Draw a path from left to right
Motion("draw", "path.line", {
  from: { drawSVG: "0% 0%" },
  to:   { drawSVG: "0% 100%" },
  duration: 1.2,
  ease: "power2.inOut",
}).onScroll({ scrub: true });
```

> Object form: `{ start: 20, end: 80 }` means 20% to 80% — values are percentages `0–100`, not fractions `0–1`.

See [SVG Animations](/docs/sdk/svg) for the full drawSVG reference.

---

## clip-path

Animate the CSS `clip-path` property between matching shape functions. Both `clipPath` (camelCase) and `'clip-path'` (kebab-case, quoted) keys are accepted. The renderer writes both `clip-path` and `-webkit-clip-path` automatically.

| Shape | Example |
|-------|---------|
| `circle` | `'circle(50% at 50% 50%)'` |
| `ellipse` | `'ellipse(60% 30% at 50% 50%)'` |
| `inset` | `'inset(10px 20px round 8px)'` |
| `polygon` | `'polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)'` |
| `rect` | `'rect(10px 90px 90px 10px)'` |
| `xywh` | `'xywh(10% 10% 80% 80%)'` |

**Interpolation rules:**
- **Same shape on both ends** for smooth interpolation. Cross-shape (e.g. `circle → inset`) hard-swaps at progress ≥ 0.5.
- **`polygon` vertex counts must match** between `from` and `to` for smooth morphing.
- Units are preserved (`%`, `px`).

```typescript
// Circular reveal — expand from center
Motion("reveal", "#hero", {
  from: { 'clip-path': 'circle(0% at 50% 50%)' },
  to:   { 'clip-path': 'circle(75% at 50% 50%)' },
  duration: 1,
  ease: "power2.out",
}).onPageLoad();

// Diagonal wipe on hover
Motion("wipe", ".card-image", {
  from: { clipPath: 'polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)' },
  to:   { clipPath: 'polygon(0% 0%, 0% 0%, 100% 100%, 0% 100%)' },
  duration: 0.5,
  ease: "power2.inOut",
}).onHover({ onLeave: "reverse" });
```

See [Clip Path](/docs/sdk/clip-path) for the full reference.

---

## Easing Reference

The `ease` string follows the format **`"family.direction"`** — lowercase, e.g. `"power2.out"`. Unknown strings fall back to `"power1.out"`. Easing names are case-insensitive.

| Family | Variants | Best for |
|--------|----------|---------|
| `power1` | `.in` · `.out` · `.inOut` | Subtle UI motion, understated transitions |
| `power2` | `.in` · `.out` · `.inOut` | Scroll reveals, card entrances — the everyday workhorse |
| `power3` | `.in` · `.out` · `.inOut` | Hero sections, modals, bold entrances |
| `power4` | `.in` · `.out` · `.inOut` | Cinematic moments, high-impact exits |
| `sine` | `.in` · `.out` · `.inOut` | Delicate fades, floating loops |
| `expo` | `.in` · `.out` · `.inOut` | Drawers, command palettes, snap-open UI |
| `circ` | `.in` · `.out` · `.inOut` | Sorting animations, mechanical / precision UI |
| `back` | `.in` · `.out` · `.inOut` | Playful cards, buttons — mild overshoot |
| `elastic` | `.in` · `.out` · `.inOut` | Badges, tooltips, success states — spring energy |
| `bounce` | `.in` · `.out` · `.inOut` | Game UI, mascots — discrete ball-drop bounces |
| `rough` | — | Glitch effects, error shakes, organic feel |
| `slow` | `.in` · `.out` · `.inOut` | Dramatic pauses, attention-drawing loops |
| `none` | — | Scrub animations, progress bars — constant speed |

Omitting `ease` uses the SDK default: equivalent to `"power1.inOut"`.

See [Easing Functions](/docs/sdk/easing) for visual comparison and usage guidance.

---

## Callbacks

Lifecycle callbacks can be defined inline in `AnimationConfig` or chained on the `Timeline`:

```typescript
// Inline in config
Motion("reveal", ".box", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  onStart:           () => console.log("started"),
  onUpdate:          (progress) => console.log(`progress: ${progress.toFixed(2)}`),
  onComplete:        () => console.log("done"),
  onRepeat:          (count) => console.log(`repeat #${count}`),
  onReverseComplete: () => console.log("reversed"),
}).onPageLoad();

// Chained on the timeline
Motion("counter", "#count", {
  from: { opacity: 0 },
  duration: 0.4,
})
  .onStart(() => startTracking())
  .onUpdate((progress, time) => updateProgress(progress))
  .onComplete(() => finishTracking())
  .play();
```

| Callback | Signature | Fires when |
|----------|-----------|-----------|
| `onStart` | `() => void` | Animation begins playing |
| `onUpdate` | `(progress: number, time: number) => void` | Every animation frame |
| `onComplete` | `() => void` | Animation reaches the end |
| `onRepeat` | `(count: number) => void` | After each repeat cycle |
| `onReverseComplete` | `() => void` | Animation completes while playing in reverse |

---

## Dynamic Content & SPA

Use `Motion.context()` to scope animations for clean teardown and reinitialisation when DOM content changes — AJAX filters, pagination, SPA navigation, infinite scroll.

```typescript
// Create a context — all timelines created inside are tracked
const ctx = Motion.context(() => {
  Motion("hero", ".title", { from: { opacity: 0, y: 30 }, duration: 0.8 }).onPageLoad();
  Motion("cards", ".card", { from: { y: 100 }, duration: 1 }).onScroll({ scrub: true });
});

// After dynamic content change (filter, pagination, etc.)
ctx.refresh();  // kills old animations, re-runs init, re-resolves all selectors

// Add more animations to the same context
ctx.add(() => {
  Motion("new-section", ".new-item", { from: { opacity: 0 }, duration: 0.4 }).onPageLoad();
});

// Full cleanup — React unmount, route change, etc.
ctx.revert();
```

Both published targets — the **WordPress plugin** and **standalone / CDN exports** — wrap your page's animation code in `Motion.context()` automatically and expose `MOTIONPAGE_FRONT.reinit()`. Call it after AJAX or other dynamic content changes to silently re-initialise animations (including on newly added elements):

```js
MOTIONPAGE_FRONT.reinit();
```

See [SPA Integration](/docs/sdk/spa-integration) for framework-specific patterns (React, Vue, Next.js, Astro).

---

## Anti-Patterns

| DON'T | DO instead |
|-------|-----------|
| `from: { opacity: 0, y: 50 }, to: { opacity: 1, y: 0 }` | `from: { opacity: 0, y: 50 }` — `opacity:1` and `y:0` are natural defaults |
| `import { Motion } from '@motion/sdk'` | `import { Motion } from '@motion.page/sdk'` |
| Call `Motion("name", ...)` twice expecting replacement | Call `Motion("name").kill()` first, then rebuild |
| Target multiple independent elements without `each: true` | Add `each: true` to the trigger config |
| `querySelectorAll(".card").forEach(el => Motion(..., el, ...))` | `Motion("cards", ".card", {...}).onHover({ each: true })` |
| Mix external animation libraries with Motion SDK | Use Motion SDK exclusively |
| `drawSVG: { start: 0.2, end: 0.8 }` expecting fractions | Object values are **percentages 0–100**: `{ start: 20, end: 80 }` |
| Use `playNext`/`playPrevious` without `each: true` | Always combine `playNext`/`playPrevious` actions with `each: true` |
| `Hover`/`HoverEnd` gesture events on `window` | Always specify a `target` element for hover events |
| Set `flap.type: 'fade'` and also animate `opacity` | `fade` type owns `opacity` — drop `opacity` from `from`/`to` |

---

## TypeScript Types

All types are importable from `@motion.page/sdk`:

```typescript
import type {
  // Core
  AnimationVars,
  AnimationConfig,
  AnimationEntry,
  TargetInput,
  ObjectTarget,
  AnimationTarget,
  EasingFunction,

  // Config options
  StaggerVars,
  RepeatConfig,
  SplitType,
  PathConfig,
  FitConfig,
  FlapConfig,

  // Trigger configs
  HoverConfig,
  ClickConfig,
  ScrollConfig,
  MouseMoveConfig,
  MarkerConfig,
  PageLoadConfig,
  PageExitConfig,

  // Gesture
  GestureConfig,
  GestureEvent,
  GestureAction,
  GestureInputType,
  TimelineAction,

  // Cursor
  CursorConfig,
  CursorStateVars,
  CursorSqueezeConfig,

  // Context
  MotionContext,
} from "@motion.page/sdk";

// Namespace import — all types under Types.*
import { Types } from "@motion.page/sdk";
```

---

## Browser Support

Chrome 90+ · Firefox 90+ · Safari 15+ · Edge 90+

---

Related: [Core Concepts](/docs/sdk/core-concepts) · [Getting Started](/docs/sdk/getting-started) · [Sequencing](/docs/sdk/sequencing) · [Stagger](/docs/sdk/stagger) · [Easing](/docs/sdk/easing) · [SPA Integration](/docs/sdk/spa-integration)

---

## Timeline Control

> Play, pause, reverse, seek, and inspect timeline state programmatically.

URL: https://motion.page/docs/sdk/timeline-control

import LivePreview from "../../components/docs/blocks/LivePreview";

Every `Motion` timeline is a named, registry-backed instance you can retrieve and control from anywhere — event handlers, framework lifecycle hooks, or user interactions.

---

## Retrieving a Timeline

Use the single-argument overload to get or lazily create a timeline by name. If the name is already registered, it returns that same `Timeline` instance. If the name is missing, it registers a new inactive, duration-zero timeline — useful for trigger-only timelines such as custom cursors or pin-only scroll scenes.

```typescript
import { Motion } from "@motion.page/sdk";

// Create a timeline on page load, paused
Motion("hero", "#hero", { from: { opacity: 0, y: 40 }, duration: 0.8 })
  .onPageLoad({ paused: true });

// Later — retrieve by name and play manually
const tl = Motion("hero");
tl.play();
```

The static helpers `Motion.get()` and `Motion.has()` are safer for conditional retrieval:

| Method | Returns | Description |
|--------|---------|-------------|
| `Motion("name")` | `Timeline` | Get an existing timeline, or create and register an empty one if missing |
| `Motion.get("name")` | `Timeline \| undefined` | Safe retrieval — returns `undefined` if not found |
| `Motion.has("name")` | `boolean` | Check if a timeline is registered |
| `Motion.getNames()` | `string[]` | All registered timeline names |

```typescript
// Guard before accessing
if (Motion.has("hero")) {
  Motion.get("hero")?.pause();
}
```

---

## Playback Methods

All playback methods return `this` for chaining.

| Method | Signature | Description |
|--------|-----------|-------------|
| `.play()` | `play(from?: number): this` | Play forward. Optional `from` jumps to that time in seconds first |
| `.pause()` | `pause(atTime?: number): this` | Pause. Optional `atTime` seeks to that time before pausing |
| `.reverse()` | `reverse(from?: number): this` | Play backward from the current position. Optional `from` jumps first |
| `.restart()` | `restart(): this` | Reset to time 0 and play forward |
| `.seek()` | `seek(position: number): this` | Jump to a time in seconds without changing play state |
| `.kill()` | `kill(clearProps?: boolean): void` | Destroy the timeline. `clearProps: true` (default) restores CSS |
| `.clear()` | `clear(): this` | Remove all animations without destroying the timeline instance |

```typescript
import { Motion } from "@motion.page/sdk";

Motion("banner", "#banner", { from: { opacity: 0, y: 30 }, duration: 1 })
  .onPageLoad({ paused: true });

const tl = Motion("banner");

tl.play();          // play from current position
tl.pause();         // freeze
tl.seek(0.5);       // jump to 0.5s, stay paused
tl.reverse();       // play backward from current position
tl.restart();       // reset to 0 and play
```

### Killing a Timeline

`.kill()` removes the timeline from the registry and — by default — restores all animated CSS properties to their pre-animation values.

```typescript
// Kill and restore CSS (default)
Motion("hero").kill();

// Kill but leave element in its current animated state
Motion("hero").kill(false);
```

After `.kill()`, `Motion.has("hero")` is `false` and `Motion.get("hero")` returns `undefined`. Calling `Motion("hero")` again creates and registers a fresh empty timeline; pass a target and config when you want to rebuild the animation immediately.

---

## State Inspection

Read timeline state at any point. Methods marked as getter/setter accept an optional value — call with no argument to read, with an argument to set and return `this`.

| Method | Signature | Description |
|--------|-----------|-------------|
| `.isActive()` | `isActive(): boolean` | `true` if the timeline is currently animating |
| `.progress()` | `progress(value?: number): number \| this` | Progress as 0–1. Pass a value to seek by progress |
| `.time()` | `time(value?: number): number \| this` | Elapsed time in seconds. Pass a value to seek to that time |
| `.duration()` | `duration(): number` | Total timeline duration in seconds (read-only) |
| `.timeScale()` | `timeScale(value?: number): number \| this` | Playback speed multiplier. `1` = normal, `2` = double, `0.5` = half |
| `.getName()` | `getName(): string \| undefined` | The timeline's registered name |

```typescript
const tl = Motion("sequence");

// Read current state
console.log(tl.isActive());   // true | false
console.log(tl.progress());   // 0–1
console.log(tl.time());       // seconds elapsed
console.log(tl.duration());   // total seconds
console.log(tl.timeScale());  // 1 (normal speed)
console.log(tl.getName());    // "sequence"

// Seek to 50% progress
tl.progress(0.5);

// Jump to 2 seconds
tl.time(2);

// Slow down to half speed
tl.timeScale(0.5);
```

---

## Callbacks

### Timeline-Level Callbacks

Chain callback methods on the `Timeline` instance to react to lifecycle events. These are separate from the trigger — chain them before or after:

| Method | Signature | Description |
|--------|-----------|-------------|
| `.onStart(cb)` | `onStart(cb: () => void): this` | Fires when the timeline begins playing |
| `.onUpdate(cb)` | `onUpdate(cb: (progress: number, time: number) => void): this` | Fires every frame with current `progress` (0–1) and `time` (seconds) |
| `.onComplete(cb)` | `onComplete(cb: () => void): this` | Fires when the timeline finishes |
| `.call(cb, params?, position?)` | `call(cb, params?, position?): this` | Insert a function call at a specific position in the timeline |

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reveal", ".hero", { from: { opacity: 0, y: 40 }, duration: 0.8 })
  .onStart(() => {
    console.log("Animation started");
  })
  .onUpdate((progress, time) => {
    console.log(`Progress: ${(progress * 100).toFixed(1)}%  Time: ${time.toFixed(2)}s`);
  })
  .onComplete(() => {
    console.log("Animation complete");
  })
  .onPageLoad();
```

Use `.call()` to trigger a function at a precise moment within a multi-step timeline:

```typescript
Motion("sequence", [
  { target: "#title",    from: { opacity: 0 }, duration: 0.5 },
  { target: "#subtitle", from: { opacity: 0 }, duration: 0.4, position: "+=0.1" },
])
  .call(() => console.log("Title appeared"), [], 0.5)
  .call(() => console.log("Sequence complete"), [], ">")
  .onPageLoad();
```

### Per-Animation Callbacks

Individual animations inside a timeline also support callbacks via `AnimationConfig`. These fire relative to each animation rather than the timeline as a whole.

| Property | Type | Description |
|----------|------|-------------|
| `onStart` | `() => void` | Fires when this animation begins |
| `onUpdate` | `(progress: number) => void` | Fires every frame for this animation |
| `onComplete` | `() => void` | Fires when this animation finishes |
| `onRepeat` | `(repeatCount: number) => void` | Fires at the start of each repeat cycle |
| `onReverseComplete` | `() => void` | Fires when this animation completes in reverse |

```typescript
Motion("loader", ".bar", {
  to: { width: "100%" },
  duration: 2,
  ease: "power1.inOut",
  onUpdate: (progress) => {
    document.querySelector<HTMLElement>("#label")!.textContent =
      `${Math.round(progress * 100)}%`;
  },
  onComplete: () => {
    document.querySelector<HTMLElement>("#label")!.textContent = "Done";
  },
}).play();
```

---

<LivePreview client:load
  height={240}
  title="Play, pause, and restart"
  html={`<div class="scene">
  <div class="box"></div>
  <div class="controls">
    <button id="btn-play">Play</button>
    <button id="btn-pause">Pause</button>
    <button id="btn-restart">Restart</button>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 28px; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; }
.controls { display: flex; gap: 8px; }
button { padding: 8px 18px; border: 1px solid #6633EE; background: transparent; color: #6633EE; border-radius: 6px; cursor: pointer; font-size: 13px; }
button:hover { background: #6633EE; color: white; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const tl = Motion("demo", ".box", {
  from: { opacity: 0, y: 30 },
  duration: 0.8,
  ease: "power2.out",
});

document.getElementById("btn-play").onclick = () => Motion("demo").play();
document.getElementById("btn-pause").onclick = () => Motion("demo").pause();
document.getElementById("btn-restart").onclick = () => Motion("demo").restart();`}
/>

---

## Common Patterns

### Play/Pause Toggle

```typescript
import { Motion } from "@motion.page/sdk";

Motion("panel", "#panel", { from: { opacity: 0, y: 20 }, duration: 0.8 })
  .onPageLoad({ paused: true });

document.querySelector("#toggle")?.addEventListener("click", () => {
  const tl = Motion("panel");
  tl.isActive() ? tl.pause() : tl.play();
});
```

### Progress Bar Driven by Timeline

```typescript
import { Motion } from "@motion.page/sdk";

const bar = document.querySelector<HTMLElement>("#progress-bar")!;

Motion("hero-sequence", [
  { target: "#title",    from: { opacity: 0, y: 30 }, duration: 0.6 },
  { target: "#subtitle", from: { opacity: 0 },         duration: 0.5, position: "+=0.1" },
  { target: "#cta",      from: { opacity: 0, y: 10 }, duration: 0.4, position: "+=0.1" },
])
  .onUpdate((progress) => {
    bar.style.width = `${progress * 100}%`;
  })
  .onPageLoad();
```

### Scrubbing with seek()

Bind `.seek()` to a range input to let users scrub through a timeline manually:

```typescript
import { Motion } from "@motion.page/sdk";

Motion("scrub-demo", "#card", {
  from: { x: -200, opacity: 0 },
  to:   { x:  200, opacity: 1 },
  duration: 2,
}).onPageLoad({ paused: true });

document.querySelector<HTMLInputElement>("#scrubber")?.addEventListener("input", (e) => {
  const input = e.target as HTMLInputElement;
  const tl = Motion("scrub-demo");
  tl.seek((Number(input.value) / 100) * tl.duration());
});
```

### Slowing Down or Speeding Up

`timeScale` adjusts playback speed without changing any configured durations:

```typescript
import { Motion } from "@motion.page/sdk";

Motion("entrance", ".modal", { from: { opacity: 0, scale: 0.92 }, duration: 0.6 })
  .onPageLoad({ paused: true });

// Slow motion preview
Motion("entrance").timeScale(0.25).play();

// Normal speed
Motion("entrance").timeScale(1).restart();
```

### Stopping a Repeating Animation

Use `onRepeat` on a per-animation basis to stop after a set number of observed cycles:

```typescript
import { Motion } from "@motion.page/sdk";

let cycles = 0;

Motion("pulse", ".badge", {
  to: { scale: 1.2 },
  duration: 0.4,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
  onRepeat: () => {
    cycles++;
    if (cycles >= 6) Motion("pulse").kill();
  },
}).play();
```

---

Related: [Core Concepts](/docs/sdk/core-concepts) · [Duration & Delay](/docs/sdk/duration-delay)

---

## Easing Functions

> All easing curves — power, sine, expo, circ, back, elastic, bounce — with visual reference.

URL: https://motion.page/docs/sdk/easing

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

**Easing** shapes the acceleration curve of an animation — whether it glides smoothly, snaps sharply, overshoots, or bounces. Every `AnimationConfig` accepts an `ease` string.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

## The `ease` Property

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ease` | `string` | `"power1.inOut"` | Easing curve — lowercase family name + direction suffix |

The format is **`"family.direction"`** in lowercase: `"power2.out"`, `"elastic.inOut"`, `"back.in"`. Two values skip the direction suffix: `"none"` (linear, constant speed) and omitting `ease` entirely (uses the SDK default, equivalent to `"power1.inOut"`).

## Directions

All families except `none` accept three direction suffixes:

| Suffix | Meaning | Use when |
|--------|---------|----------|
| `.in` | Accelerates — slow start, fast end | Exits, elements leaving the screen |
| `.out` | Decelerates — fast start, slow end | Entrances, reveals — most natural direction |
| `.inOut` | Slow start, fast middle, slow end | Repositioning, looping, symmetric transitions |

```typescript
ease: "power2.out"   // fast to slow — standard reveal ease
ease: "power2.in"    // slow to fast — exits and aggressive enters
ease: "power2.inOut" // symmetric — good for repositioning and loops
```

## All Easing Families

| Family | Feel | Best for |
|--------|------|----------|
| `power1` | Gentle — closest to CSS `ease` | Subtle UI motion, body text reveals |
| `power2` | Moderate — the everyday workhorse | Scroll reveals, card entrances, most animations |
| `power3` | Strong — punchy, confident | Hero sections, modals, bold entrances |
| `power4` | Very strong — dramatic onset/cutoff | Cinematic moments, high-impact exits |
| `sine` | Smooth sinusoidal — lightest of all | Delicate fades, floating loops |
| `expo` | Extreme — near-instant snap | Drawers, command palettes, high-contrast UIs |
| `circ` | Circular arc — mechanical, abrupt | Sorting animations, precise layout changes |
| `back` | Slight overshoot then settles | Playful cards, buttons, landing animations |
| `elastic` | Multi-oscillation spring | Badges, tooltips, success states |
| `bounce` | Discrete ball-drop bounces | Game UI, mascots, high-energy moments |
| `rough` | Jitter/shaking motion | Glitch effects, error shakes, organic feel |
| `slow` | Pauses mid-range — emphasis beat | Dramatic pauses, attention-drawing loops |
| `none` | Linear — constant speed | Scrub animations, progress bars |

## Visual Comparison

<LivePreview client:load
  height={300}
  title="Easing comparison"
  html={`<div class="scene">
  <div class="row"><span class="label">power2.out</span><div class="track"><div class="dot"></div></div></div>
  <div class="row"><span class="label">back.out</span><div class="track"><div class="dot"></div></div></div>
  <div class="row"><span class="label">elastic.out</span><div class="track"><div class="dot"></div></div></div>
  <div class="row"><span class="label">bounce.out</span><div class="track"><div class="dot"></div></div></div>
  <div class="row"><span class="label">none</span><div class="track"><div class="dot"></div></div></div>
</div>`}
  css={`.scene { padding: 20px 20px 20px 16px; display: flex; flex-direction: column; gap: 12px; height: 100%; box-sizing: border-box; }
.row { display: flex; align-items: center; gap: 12px; }
.label { width: 90px; font-size: 11px; font-family: monospace; color: #888; flex-shrink: 0; text-align: right; }
.track { flex: 1; height: 34px; background: rgba(255,255,255,0.05); border-radius: 8px; position: relative; overflow: visible; }
.dot { width: 26px; height: 26px; background: #6633EE; border-radius: 50%; position: absolute; top: 4px; left: 4px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const eases = ["power2.out", "back.out", "elastic.out", "bounce.out", "none"];
const dots = document.querySelectorAll(".dot");

dots.forEach((dot, i) => {
  Motion("ease-" + i, dot, {
    to: { x: 220 },
    duration: 0.95,
    ease: eases[i],
    repeat: { times: -1, delay: 1.5 },
  }).play();
});`}
/>

## Code Examples by Family

### Power1–4

The `power` family covers the vast majority of UI animations. Strength scales with the number — `power1` is barely perceptible, `power4` has an almost instant onset or cutoff.

<CodeBlock lang="typescript" code={`import { Motion } from "@motion.page/sdk";

// power2.out — the default choice for scroll reveals
Motion("reveal", ".section", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });

// power3.out — punchy hero entrance
Motion("hero", ".headline", {
  from: { opacity: 0, y: 60 },
  duration: 0.8,
  ease: "power3.out",
}).onPageLoad();

// power4.in — aggressive exit for page transitions
Motion("exit", "body", {
  to: { opacity: 0, y: -20 },
  duration: 0.4,
  ease: "power4.in",
}).onPageExit({ skipHref: ["anchor", "mailto"] });`} />

### Sine & Expo

`sine` is the gentlest curve of all families — nearly imperceptible at short durations. `expo` is the sharpest, producing a near-instant snap quality.

<CodeBlock lang="typescript" code={`// sine.out — light, airy entrance for delicate elements
Motion("float", ".caption", {
  from: { opacity: 0, y: 12 },
  duration: 0.9,
  ease: "sine.out",
}).play();

// expo.out — snappy drawer or panel that pops open
Motion("drawer", ".sidebar", {
  from: { x: -320 },
  duration: 0.5,
  ease: "expo.out",
}).play();`} />

### Circ

`circ` follows a circular arc — sharper than `power` curves and more mechanical in feel.

<CodeBlock lang="typescript" code={`// circ.inOut — list reordering with a crisp pivot
Motion("sort", ".item", {
  to: { y: 80 },
  duration: 0.45,
  ease: "circ.inOut",
}).play();`} />

### Back — Overshoot

`back.out` travels slightly past the destination, then snaps back to rest. Creates a satisfying landing or pop effect.

<CodeBlock lang="typescript" code={`// Pop-in with overshoot — modal or badge appears with snap
Motion("pop", ".badge", {
  from: { opacity: 0, scale: 0.82 },
  duration: 0.5,
  ease: "back.out",
}).play();

// Hover lift with overshoot — cards feel springy on enter
Motion("lift", ".card", {
  to: { y: -8 },
  duration: 0.35,
  ease: "back.out",
}).onHover({ each: true, onLeave: "reverse" });`} />

### Elastic — Spring

`elastic.out` oscillates multiple times before settling. Draws significant attention — use it for moments that deserve a spotlight.

<CodeBlock lang="typescript" code={`// Notification badge springs into view
Motion("ping", ".notification-badge", {
  from: { scale: 0, opacity: 0 },
  duration: 0.7,
  ease: "elastic.out",
}).play();

// Tooltip pops in with a spring
Motion("tooltip", ".tooltip", {
  from: { opacity: 0, scale: 0.88 },
  duration: 0.6,
  ease: "elastic.out",
}).play();`} />

### Bounce — Ball Drop

`bounce.out` simulates discrete ball-bouncing steps. More mechanical and playful than `elastic`.

<CodeBlock lang="typescript" code={`// Icon drops in with a bounce
Motion("drop", ".icon", {
  from: { y: -60, opacity: 0 },
  duration: 0.8,
  ease: "bounce.out",
}).play();`} />

### Rough & Slow

`rough` adds jitter — useful for shaky, glitchy, or organic motion. `slow` decelerates strongly through the middle of its range, creating a natural pause for emphasis.

<CodeBlock lang="typescript" code={`// Error shake — rough jitter on validation failure
Motion("shake", ".form-field", {
  from: { x: -5 },
  to: { x: 5 },
  duration: 0.06,
  ease: "rough",
  repeat: { times: 8, yoyo: true },
}).play();

// Slow pulse — emphasis beat that draws the eye
Motion("pulse", ".cta-button", {
  from: { scale: 1 },
  to: { scale: 1.06 },
  duration: 0.8,
  ease: "slow.inOut",
  repeat: { times: -1, yoyo: true },
}).play();`} />

### None — Linear

`"none"` moves at constant speed with no acceleration. The right choice for scrub animations and any motion where the position should map directly to a value without distortion.

<CodeBlock lang="typescript" code={`// Scrubbed parallax — scroll position maps 1:1
Motion("parallax", ".bg-layer", {
  from: { y: -80 },
  to: { y: 80 },
  ease: "none",
}).onScroll({ scrub: true });

// Progress bar — constant speed is the point
Motion("progress", ".bar", {
  from: { width: "0%" },
  to: { width: "100%" },
  duration: 3,
  ease: "none",
}).play();`} />

## When to Use Which Ease

**Scroll reveals and entrances** → `power2.out` or `power3.out`. A decelerating ease reads as the element arriving and coming to rest naturally.

**Exits and page transitions** → `power2.in` or `power3.in`. An accelerating ease looks like the element flying away rather than disappearing mid-movement.

**Hover effects** → `power2.out` on enter, `power1.inOut` or `power2.in` on leave. Keep hover duration short: `0.2–0.35s`.

**Looping and yoyo animations** → `sine.inOut` or `power2.inOut`. Symmetric curves restart without a jarring speed discontinuity.

**Scrub / scroll-driven** → `none`. Any other ease creates uneven, rubber-banding scrubbing.

**Playful moments** → `back.out` for mild snap, `elastic.out` for spring energy. Reserve these for moments that genuinely deserve attention.

**Dramatic and cinematic** → `expo.out` or `power4.out`. High-contrast onset/cutoff creates energy and intentionality.

**Mechanical / precision UI** → `circ.inOut` or `expo.out`. These feel direct and purposeful rather than casual.

## API Reference

```typescript
interface AnimationConfig {
  ease?: string;
  // "power1.out" | "power2.out" | "power3.out" | "power4.out"
  // "power1.in"  | "power2.in"  | "power3.in"  | "power4.in"
  // "power1.inOut" | "power2.inOut" | "power3.inOut" | "power4.inOut"
  // "sine.in"  | "sine.out"  | "sine.inOut"
  // "expo.in"  | "expo.out"  | "expo.inOut"
  // "circ.in"  | "circ.out"  | "circ.inOut"
  // "back.in"  | "back.out"  | "back.inOut"
  // "elastic.in" | "elastic.out" | "elastic.inOut"
  // "bounce.in"  | "bounce.out"  | "bounce.inOut"
  // "rough.in"   | "rough.out"   | "rough.inOut"
  // "slow.in"    | "slow.out"    | "slow.inOut"
  // "none"
}
```

Omitting `ease` uses the SDK default: equivalent to `"power1.inOut"`.

---

Related: [Duration & Delay](/docs/sdk/duration-delay) · [Stagger](/docs/sdk/stagger) · [Repeat & Yoyo](/docs/sdk/repeat-yoyo)

---

## Scroll Trigger

> Trigger or scrub animations based on scroll position with start, end, and toggleActions.

URL: https://motion.page/docs/sdk/scroll-trigger

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

Chain `.onScroll()` to any timeline to activate it based on scroll position. Use it to play an animation when an element enters the viewport, or to scrub animation progress directly with the scrollbar.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

Motion("reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll();
```

Without options, `.onScroll()` plays the animation the first time the element enters the trigger range. Later scroll boundaries take no action unless you provide `toggleActions`.

---

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `target` | `string \| Element` | First animated element | Element whose scroll position drives the trigger |
| `endTarget` | `string \| Element` | `target` | Element used to resolve an absolute `end` position; relative ends ignore it |
| `start` | `string` | `"top bottom"` | Position string: when trigger fires on scroll down |
| `end` | `string` | `"bottom top"` | Position string: when trigger ends / leaves |
| `scrub` | `boolean \| number` | `false` | Sync animation to scrollbar. `true` = instant; `number` = smoothing seconds |
| `toggleActions` | `string` | `"play none none none"` | Four-part string controlling playback at each scroll state |
| `markers` | `boolean \| MarkerConfig` | — | Show debug markers for start and end positions |
| `scroller` | `string \| Element` | `window` | Custom scroll container |
| `pin` | `boolean \| string` | — | Fix an element in place during the scroll range |
| `pinSpacing` | `boolean \| "margin" \| "padding"` | — | How space is added around a pinned element |
| `snap` | `number \| number[] \| function` | — | Quantize animation progress to fixed points |
| `each` | `boolean` | `false` | Create independent trigger instances per matched element |

---

## Start and End Position Syntax

`start` and `end` take a two-part string: **`"element-edge viewport-edge"`**.

The **element edge** is where on the target element the trigger fires:

| Value | Meaning |
|-------|---------|
| `top` | Top edge of the element |
| `center` | Vertical midpoint of the element |
| `bottom` | Bottom edge of the element |
| `top+100px` | 100px below the element's top edge |
| `bottom-50px` | 50px above the element's bottom edge |

The **viewport edge** is where on the viewport (or scroll container) the trigger fires:

| Value | Meaning |
|-------|---------|
| `top` | Top of the viewport |
| `center` | Vertical midpoint of the viewport |
| `bottom` | Bottom of the viewport |
| `80%` | 80% from the top of the viewport |
| `200px` | 200px from the top of the viewport |

Combine them to describe exactly when the trigger fires:

```typescript
// Fire when element top hits viewport bottom (default — starts just off-screen)
.onScroll({ start: "top bottom" })

// Fire when element center crosses viewport center
.onScroll({ start: "center center" })

// Fire when element top is 20% from the top of the viewport
.onScroll({ start: "top 20%" })

// Fire when element top+100px hits the viewport 80% mark
.onScroll({ start: "top+100px 80%" })
```

**Relative end positions** with `+=` measure from the start position, not the element:

```typescript
// End 500px of scroll travel after start
.onScroll({ scrub: true, end: "+=500" })

// End one full viewport height after start
.onScroll({ scrub: true, end: "+=100vh" })

// End halfway through the viewport after start
.onScroll({ scrub: true, end: "+=50%" })
```

---

## Scrub

`scrub` ties the animation's progress directly to the scrollbar position. As the user scrolls forward the animation advances; as they scroll back it reverses.

```typescript
// Instant scrub — animation progress matches scroll position exactly
Motion("parallax", ".hero-bg", {
  from: { y: -50 },
  to: { y: 50 },
  duration: 1,
}).onScroll({ scrub: true });
```

Pass a number to add **smoothing** — the animation takes that many seconds to "catch up" to the scrollbar. Higher values feel floatier.

```typescript
// Smooth scrub — 1 second lag behind the scrollbar
Motion("smooth-parallax", ".section-image", {
  from: { y: -30 },
  to: { y: 30 },
  duration: 1,
}).onScroll({ scrub: 1 });
```

| `scrub` value | Behaviour |
|---------------|-----------|
| `false` (default) | Animation uses `toggleActions` (`play` once by default), not scroll-linked progress |
| `true` | Animation progress mirrors scroll position exactly |
| `0.5` | Smooth scrub, 0.5s lag |
| `2` | Very smooth scrub, 2s lag |

> `toggleActions` is ignored when `scrub` is enabled — they are mutually exclusive.

---

## toggleActions

`toggleActions` controls what happens at each of the four scroll states. It takes a space-separated string of four action keywords:

```
"onEnter  onLeave  onEnterBack  onLeaveBack"
```

| Position | Fires when |
|----------|-----------|
| `onEnter` | Scrolling **down** into the trigger zone |
| `onLeave` | Scrolling **down** past the trigger zone |
| `onEnterBack` | Scrolling **up** back into the trigger zone |
| `onLeaveBack` | Scrolling **up** out of the trigger zone |

**Valid actions:** `play`, `pause`, `resume`, `reverse`, `restart`, `reset`, `complete`, `none`

```typescript
// Play only once when entering — never reverse (the classic reveal)
Motion("reveal", ".section", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ toggleActions: "play none none none" });

// Reverse on scroll back up
Motion("fade", ".card", {
  from: { opacity: 0, scale: 0.95 },
  duration: 0.5,
}).onScroll({ toggleActions: "play none reverse none" });

// Restart every time the element enters — useful for looping effects
Motion("pop", ".badge", {
  from: { opacity: 0, scale: 0.8 },
  duration: 0.4,
  ease: "back.out",
}).onScroll({ toggleActions: "restart none restart none" });
```

**Common presets:**

| `toggleActions` string | Behaviour |
|------------------------|-----------|
| `"play none none none"` | Play once on first scroll down |
| `"restart none none none"` | Restart each time element enters scrolling down |
| `"restart none restart none"` | Restart when entering from either direction |
| `"play none reverse none"` | Play down, reverse when scrolling back |
| `"play none none reverse"` | Play down, reverse when leaving on scroll back |
| `"play reverse play reverse"` | Reverse whenever the trigger range is left |

---

<LivePreview
  client:load
  height={420}
  title="Scroll trigger reveal"
  html={`<div class="scene">
  <div class="card" style="--i:0">Card One</div>
  <div class="card" style="--i:1">Card Two</div>
  <div class="card" style="--i:2">Card Three</div>
  <div class="card" style="--i:3">Card Four</div>
  <div class="card" style="--i:4">Card Five</div>
</div>`}
  css={`.scene {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 16px;
  height: 380px;
  overflow-y: scroll;
  overflow-x: hidden;
  border-radius: 12px;
}
.card {
  flex-shrink: 0;
  height: 80px;
  background: linear-gradient(135deg, #6633EE, #9966FF);
  border-radius: 10px;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  font-family: sans-serif;
  font-weight: 600;
  font-size: 15px;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scroll-reveal", ".card", {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: 0.15,
  ease: "power2.out",
}).onScroll({ toggleActions: "play none none reverse", start: "top 80%" });`}
/>

---

## Play Once on Scroll

The most common reveal pattern: play when the element enters, never reverse.

<CodeBlock
  filename="play-once.ts"
  lang="typescript"
  code={`Motion("reveal", ".section", {
  from: { opacity: 0, y: 40 },
  duration: 0.7,
  ease: "power2.out",
  stagger: 0.1,
}).onScroll({ toggleActions: "play none none none" });`}
/>

---

## Per-Element Triggers with `each`

By default, all elements matching the selector share a **single** ScrollTrigger driven by the first element. Set `each: true` to give every element its own independent trigger, so each one fires when it individually enters the viewport.

```typescript
// ❌ Without each — all cards trigger when the first card enters the viewport
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.5,
  stagger: 0.1,
}).onScroll({ toggleActions: "play none none none" });

// ✅ With each — every card triggers independently as it scrolls into view
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.5,
}).onScroll({ each: true, toggleActions: "play none none none" });
```

Use `each: true` when elements are spread across the page rather than grouped together. Combine with a `stagger` only in the non-`each` case — with per-element triggers, each animation runs independently so stagger has no effect on sequencing.

---

## Debug Markers

Pass `markers: true` to render visual start and end lines in the browser. Remove before shipping.

```typescript
Motion("debug", ".section", {
  from: { opacity: 0 },
  duration: 0.6,
}).onScroll({
  start: "top 80%",
  end: "bottom 20%",
  markers: true,
});
```

Customise marker colours for stacked triggers:

```typescript
.onScroll({
  start: "top 80%",
  markers: {
    startColor: "lime",
    endColor: "red",
    fontSize: "12px",
    indent: 40,
  },
})
```

---

## Custom Scroll Container

By default the trigger listens to the window scroll. Use `scroller` to target a scrollable `div` instead.

```typescript
Motion("list-reveal", ".list-item", {
  from: { opacity: 0, x: -20 },
  duration: 0.4,
  stagger: 0.07,
}).onScroll({
  each: true,
  scroller: ".sidebar-scroll",
  start: "top 90%",
  toggleActions: "play none none none",
});
```

---

## Recalculating Positions

Call `Motion.refreshScrollTriggers()` after a layout change — for example after an accordion opens, images load, or dynamic content is injected — to recalculate all trigger positions.

```typescript
accordion.addEventListener("open", () => {
  Motion.refreshScrollTriggers();
});
```

---

## Advanced: Pin, Snap, and Horizontal Scroll

`pin`, `pinSpacing`, and `snap` enable more complex patterns like fixed-position sections, quantized animation steps, and horizontal scroll panels. `snap` changes animation progress; it does not move the browser scrollbar. These options are covered in [Scroll Trigger Advanced](/docs/sdk/scroll-trigger-advanced).

---

## Text Flapper

> Solari split-flap display effect with cycling characters and configurable transition types.

URL: https://motion.page/docs/sdk/text-flapper

import LivePreview from "../../components/docs/blocks/LivePreview";

**Text Flapper** animates text like a mechanical Solari departure board — each character cycles through random intermediate glyphs before landing on its target, with seven built-in transition styles.

Text Flapper **automatically applies `split: 'chars'`** when `flap` is set — you do not need to add it yourself. If you do provide `split`, it overrides the internal default, letting you reconfigure the split (e.g. `split: 'chars,words'`). The SDK also auto-adds a default stagger (`each: 0, from: 'start'`) when none is set. The `flap` config controls the cycling behavior; `from`/`to` handle surrounding motion.

## Basic Usage

```typescript
import { Motion } from "@motion.page/sdk";

// split: 'chars' is auto-applied — no need to add it
Motion("board", ".departure-title", {
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.8,
}).onPageLoad();

// Explicit split overrides the default (e.g. to also split words)
Motion("board", ".departure-title", {
  split: "chars,words",
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.8,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Split-flap character cycling"
  html={`<div class="scene"><h2 class="board">DEPARTURES</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #111; }
.board { font-family: 'Courier New', monospace; font-size: 2rem; font-weight: 700; letter-spacing: 0.12em; color: #e8e8ec; margin: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("board", ".board", {
  split: "chars",
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## The `flap` Property

Set `flap` inside your `AnimationConfig`. All sub-options are optional.

```typescript
Motion("reveal", ".hero-text", {
  split: "chars",
  flap: {
    type: "flip",
    charset: "alphanumeric",
    cycles: [2, 5],
    perspective: 400,
  },
  stagger: 0.04,
  duration: 0.6,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Alphanumeric flip reveal"
  html={`<div class="scene"><h2 class="hero-text">MOTION</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.hero-text { margin: 0; font: 800 2.2rem/1 ui-monospace, monospace; letter-spacing: 0.16em; color: #f2f3ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("reveal-preview", ".hero-text", {
  flap: { type: "flip", charset: "alphanumeric", cycles: [2, 5], perspective: 400 },
  stagger: 0.04,
  duration: 0.8,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | `FlapType` | `'flip'` | Transition style for each character — see [Transition Types](#transition-types) |
| `charset` | `CharsetPreset \| string` | `'alphanumeric'` | Character pool for random intermediate glyphs — see [Charsets](#charsets) |
| `cycles` | `number \| [min, max]` | `[2, 5]` | How many random chars to show before landing. Tuple = random per character |
| `perspective` | `number` | `400` | CSS perspective depth in px. Only affects `flip` and `board` types |
| `styledBoard` | `boolean` | `true` | Dark gradient tiles with split-line divider. Only applies to `board` type |
| `stableWidth` | `boolean \| 'cells' \| 'container'` | `false` | Strategy for preventing layout shift during cycling — see [stableWidth](#stablewidth). Auto-enabled (as `'cells'`) when `board` + `styledBoard: true` |
| `preserveWhitespaceCells` | `boolean` | `false` | Render spaces as empty board cells. Only applies to `board` type |

## Transition Types

Seven styles are available via `flap.type`. The default is `'flip'`.

### `flip` — 3D card rotation

Each character rotates on the X axis like a physical flip card. Composable with `from`/`to` transforms.

```typescript
Motion("flip-in", ".headline", {
  split: "chars",
  flap: { type: "flip", cycles: 6, perspective: 300 },
  stagger: 0.05,
  duration: 0.8,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="3D character flip"
  html={`<div class="scene"><h2 class="headline">FLIP</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.headline { margin: 0; font: 800 2.4rem/1 ui-monospace, monospace; letter-spacing: 0.18em; color: #d9f7ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("flip-preview", ".headline", {
  flap: { type: "flip", cycles: 6, perspective: 300 },
  stagger: 0.05,
  duration: 0.8,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `fade` — opacity crossfade

The outgoing character fades out, the incoming fades in. **`fade` owns the `opacity` property** — do not set `opacity` in `from`/`to` when using this type.

```typescript
Motion("fade-decode", ".status-text", {
  split: "chars",
  flap: { type: "fade", charset: "katakana", cycles: [4, 8] },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Katakana fade decode"
  html={`<div class="scene"><p class="status-text">SYSTEM READY</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.status-text { margin: 0; font: 700 1.65rem/1.2 ui-monospace, monospace; letter-spacing: 0.12em; color: #78f7c5; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("fade-preview", ".status-text", {
  flap: { type: "fade", charset: "katakana", cycles: [4, 8], stableWidth: "container" },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `slide` — vertical slide

Characters slide in and out vertically, clipped by an `overflow: hidden` parent. Composable with other transforms.

```typescript
// Slot machine effect
Motion("slot", ".score", {
  split: "chars",
  flap: { type: "slide", charset: "numeric", cycles: 8 },
  stagger: 0.06,
  duration: 1.2,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Vertical slot roll"
  html={`<div class="scene"><strong class="score">2048</strong></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.score { font: 800 3rem/1 ui-monospace, monospace; letter-spacing: 0.12em; color: #ffd86b; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("slot-preview", ".score", {
  flap: { type: "slide", charset: "numeric", cycles: 8 },
  stagger: 0.06,
  duration: 1.2,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `blur` — blur dissolve

Characters blur in and out. **`blur` owns the `filter` property** — do not set `filter` in `from`/`to` when using this type.

```typescript
Motion("blur-decode", ".classified", {
  split: "chars",
  flap: { type: "blur", cycles: [3, 6] },
  stagger: 0.03,
  duration: 0.8,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Blurred classified decode"
  html={`<div class="scene"><p class="classified">CLASSIFIED</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.classified { margin: 0; font: 800 1.8rem/1 ui-monospace, monospace; letter-spacing: 0.14em; color: #ff8c9a; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("blur-preview", ".classified", {
  flap: { type: "blur", cycles: [3, 6] },
  stagger: 0.03,
  duration: 0.8,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `scale` — scale pop

Characters scale in and out. Composable with other `from`/`to` transforms.

```typescript
Motion("scale-unlock", ".success-text", {
  split: "chars",
  flap: { type: "scale", cycles: [2, 4] },
  stagger: 0.04,
  duration: 0.7,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Scale unlock"
  html={`<div class="scene"><p class="success-text">ACCESS GRANTED</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.success-text { margin: 0; font: 800 1.65rem/1 ui-monospace, monospace; letter-spacing: 0.12em; color: #98ff8c; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scale-preview", ".success-text", {
  flap: { type: "scale", cycles: [2, 4] },
  stagger: 0.04,
  duration: 0.7,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `board` — Solari departure board

Full mechanical split-flap effect: each character element is restructured into layered panels that fold in half. The most realistic — use with `styledBoard: true` for the complete dark-tile look.

```typescript
// Styled departure board
Motion("departures", ".board-title", {
  split: "chars",
  flap: { type: "board", styledBoard: true, perspective: 400 },
  stagger: 0.05,
  duration: 0.9,
}).onPageLoad();

// Unstyled — inherit your own CSS
Motion("gate", ".gate-code", {
  split: "chars",
  flap: { type: "board", styledBoard: false },
  stagger: 0.04,
  duration: 0.7,
}).onPageLoad();
```

<LivePreview client:visible
  height={240}
  title="Styled and unstyled split-flap boards"
  html={`<div class="scene">
  <div class="row"><span class="label">STYLED</span><strong class="board-title">DEPARTURES</strong></div>
  <div class="row"><span class="label">CUSTOM</span><strong class="gate-code">GATE A12</strong></div>
</div>`}
  css={`.scene { display: grid; gap: 1.4rem; width: min(100%, 620px); }
.row { display: grid; grid-template-columns: 4.5rem 1fr; align-items: center; gap: 1rem; }
.label { font: 600 0.68rem/1 ui-monospace, monospace; letter-spacing: 0.14em; color: #6f7490; }
.board-title, .gate-code { font: 800 1.35rem/1 ui-monospace, monospace; letter-spacing: 0.1em; color: #eceefe; }
.gate-code { padding: 0.45rem 0.6rem; border: 1px solid #343956; border-radius: 0.4rem; color: #8ad9ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("styled-board-preview", ".board-title", {
  flap: { type: "board", styledBoard: true, perspective: 400 },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();

Motion("custom-board-preview", ".gate-code", {
  flap: { type: "board", styledBoard: false },
  stagger: 0.04,
  duration: 0.7,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

**Board type ownership:** restructures the character element's DOM into child panels. The original `el.textContent` is cleared; text lives in the generated sub-elements.

### `none` — text cycling only

No built-in visual transition. Characters cycle through the charset without animation. Use this with your own `from`/`to` properties to fully control the effect.

```typescript
// Pure text scramble — visuals come from from/to
Motion("scramble", ".encrypted", {
  split: "chars",
  flap: { type: "none", charset: "symbols", cycles: [6, 12] },
  from: { opacity: 0 },
  stagger: 0.02,
  duration: 0.6,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Custom text scramble"
  html={`<div class="scene"><p class="encrypted">ENCRYPTED</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.encrypted { margin: 0; font: 800 1.9rem/1 ui-monospace, monospace; letter-spacing: 0.16em; color: #c8a7ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scramble-preview", ".encrypted", {
  flap: { type: "none", charset: "symbols", cycles: [6, 12] },
  from: { opacity: 0 },
  stagger: 0.02,
  duration: 0.6,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## Charsets

The `charset` option sets the pool of random intermediate characters. Pass a preset name or any string — every character in the string is drawn from at random.

| Preset | Characters |
|--------|-----------|
| `'alphanumeric'` | `ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789` |
| `'alpha'` | `ABCDEFGHIJKLMNOPQRSTUVWXYZ` |
| `'numeric'` | `0123456789` |
| `'hex'` | `0123456789ABCDEF` |
| `'binary'` | `01` |
| `'katakana'` | Full katakana syllabary (`ア`–`ン`) |
| `'symbols'` | `!@#$%^&*+-=&lt;&gt;?/\|~` |
| `'blocks'` | `░▒▓█▄▀■□▪▫` |
| custom string | Any string — each character is used as a random intermediate |

```typescript
// Custom charset — Greek letters
Motion("greek", ".formula", {
  split: "chars",
  flap: { type: "flip", charset: "αβγδεζηθικλμνξοπρστυφχψω" },
  stagger: 0.04,
  duration: 0.8,
}).onPageLoad();

// Matrix effect
Motion("matrix", ".system-status", {
  split: "chars",
  flap: { type: "fade", charset: "katakana", cycles: [4, 8] },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
}).onPageLoad();
```

<LivePreview client:visible
  height={240}
  title="Custom and preset charsets"
  html={`<div class="scene">
  <p class="formula">EULER</p>
  <p class="system-status">SYSTEM ONLINE</p>
</div>`}
  css={`.scene { display: grid; gap: 1.35rem; text-align: center; }
.formula, .system-status { margin: 0; font: 750 1.55rem/1.1 ui-monospace, monospace; letter-spacing: 0.14em; }
.formula { color: #e1bdff; }
.system-status { color: #62f1ba; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("greek-preview", ".formula", {
  flap: { type: "flip", charset: "αβγδεζηθικλμνξοπρστυφχψω" },
  stagger: 0.04,
  duration: 0.8,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();

Motion("matrix-charset-preview", ".system-status", {
  flap: { type: "fade", charset: "katakana", cycles: [4, 8], stableWidth: "container" },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## Cycles

`cycles` controls how many random characters appear before landing on the target. Use a number for a fixed count or a `[min, max]` tuple for a random range per character — the variation makes the effect feel more organic.

```typescript
// Fixed — every char does exactly 6 cycles
flap: { cycles: 6 }

// Range — each char gets 2–8 random cycles
flap: { cycles: [2, 8] }
```

The builder exposes this as two separate sliders (min / max), range 1–20.

## Combining `flap` with `from`/`to`

For `flip`, `slide`, `scale`, and `none` types, the `from`/`to` properties animate **once per cycle** using a V-curve:

- Phase `0→0.5`: value moves from `to` toward `from` (character becoming hidden)
- Phase `0.5→1`: value moves from `from` back to `to` (new character revealed)

This means `from: { opacity: 0, y: 20 }` rides every cycle, not just the first.

```typescript
// Flip + additional opacity + translate per cycle
Motion("flip-reveal", ".hero-text", {
  split: "chars",
  flap: { type: "flip", cycles: 4 },
  from: { opacity: 0, y: 20 },
  stagger: 0.04,
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Flip reveal with per-cycle motion"
  html={`<div class="scene"><h2 class="hero-text">REVEALED</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.hero-text { margin: 0; font: 800 1.9rem/1 ui-monospace, monospace; letter-spacing: 0.14em; color: #8dc8ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("flip-reveal-preview", ".hero-text", {
  flap: { type: "flip", cycles: 4 },
  from: { opacity: 0, y: 20 },
  to: { opacity: 1, y: 0 },
  stagger: 0.04,
  duration: 0.8,
  ease: "power2.out",
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

**Property conflicts to avoid:**

| Type | Owned property | Don't use in `from`/`to` |
|------|---------------|--------------------------|
| `fade` | `opacity` | `opacity` |
| `blur` | `filter` | `filter` |
| `flip` | `rotateX` (composable) | safe to add other transforms |
| `slide` | `translateY` (composable) | safe to add other transforms |
| `scale` | `scale` (composable) | safe to add other transforms |

## The Board Type in Detail

`type: 'board'` restructures each character element into layered sub-elements that replicate the mechanics of a physical split-flap display:

```
container
├─ staticTop     — top half of incoming character (revealed as flap falls)
├─ staticBottom  — shows old char bottom until midpoint, then new char
├─ flapWrap      — rotates 0°→-180° around the center split line
│   ├─ flapFront — old character top half (visible 0°–90°)
│   └─ flapBack  — new character bottom half (visible 90°–180°)
├─ shadow        — opacity driven by sin(phase × π) for depth
└─ splitLine     — permanent 1px center divider (z-index: 3)
```

### `styledBoard`

When `true` (the default), applies departure-board tile styling:
- Dark gradient background (`#2a2a2e → #1e1e22` top, `#1e1e22 → #16161a` bottom)
- `4px` border radius
- Text color `#e8e8ec`
- Split-line color `rgba(0,0,0,0.6)`
- `2px` margin between tiles

When `false`, styling is minimal — only a `rgba(0,0,0,0.15)` split line and `1px` margin. Use this to apply your own tile CSS.

### `preserveWhitespaceCells`

By default, spaces and other whitespace are skipped and never cycled. Set `preserveWhitespaceCells: true` to render them as empty board cells — useful when you need fixed-width rows like a real departure board.

```typescript
Motion("flight-info", ".flight-row", {
  split: "chars",
  flap: {
    type: "board",
    styledBoard: true,
    preserveWhitespaceCells: true,
  },
  stagger: 0.04,
  duration: 1,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Fixed-cell flight row"
  html={`<div class="scene"><p class="flight-row">MAD JFK 12:45</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.flight-row { margin: 0; font: 800 clamp(1rem, 4vw, 1.55rem)/1 ui-monospace, monospace; letter-spacing: 0.08em; color: #edf0ff; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("flight-info-preview", ".flight-row", {
  flap: {
    type: "board",
    styledBoard: true,
    preserveWhitespaceCells: true,
  },
  stagger: 0.04,
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### `stableWidth`

Controls how the flap prevents layout shift while random characters cycle through. Each mode trades a different aesthetic for stability.

| Value | Behavior |
|-------|----------|
| `false` (default) | No pinning. Text width flexes with each rendered glyph. Fine for same-width charsets (Latin → `alphanumeric`). |
| `true` or `'cells'` | Pin each **character cell** to the widest glyph across the target and the charset pool. Every cell is the same width regardless of which glyph renders at the moment. Great for monospace aesthetics (departure boards, counters). Adds visible spacing around narrow Latin letters when paired with wide charsets (katakana, CJK). |
| `'container'` | Pin the **parent element's outer width** only — characters flow naturally inside. Latin letters keep their natural spacing while the surrounding layout (rows, grids) stays rock-steady. Best for inline hover flappers on nav links where cell-pinning would space the letters out unnaturally. |

Automatically enabled (as `'cells'`) when `board` + `styledBoard: true`.

```typescript
// Cell mode — every cell the same width (classic split-flap look)
Motion("counter", ".score", {
  flap: { type: "fade", charset: "numeric", cycles: 8, stableWidth: "cells" },
  duration: 1,
}).onPageLoad();

// Container mode — outer width reserved, letters stay naturally spaced
Motion("nav-flap", ".nav-link", {
  flap: { type: "fade", charset: "katakana", cycles: [3, 6], stableWidth: "container" },
  duration: 0.5,
}).onHover({ each: true, onEnter: "restart", onLeave: "none" });
```

<LivePreview client:visible
  height={240}
  title="Stable cell and container widths"
  html={`<div class="scene">
  <div class="demo-row"><span class="label">CELLS</span><strong class="score">128</strong></div>
  <div class="demo-row"><span class="label">CONTAINER</span><strong class="nav-link">MISSIONS</strong></div>
</div>`}
  css={`.scene { display: grid; gap: 1.4rem; min-width: min(100%, 24rem); }
.demo-row { display: grid; grid-template-columns: 6.5rem 1fr; align-items: center; gap: 1rem; }
.label { font: 600 0.65rem/1 ui-monospace, monospace; letter-spacing: 0.12em; color: #727895; }
.score, .nav-link { font: 800 1.7rem/1 ui-monospace, monospace; letter-spacing: 0.12em; color: #f4d780; }
.nav-link { color: #8bdcff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("counter-width-preview", ".score", {
  flap: { type: "fade", charset: "numeric", cycles: 8, stableWidth: "cells" },
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();

Motion("nav-width-preview", ".nav-link", {
  flap: { type: "fade", charset: "katakana", cycles: [3, 6], stableWidth: "container" },
  duration: 0.5,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## Perspective

`perspective` sets the CSS 3D perspective depth in pixels. Only affects `flip` and `board` types. Lower values create a more dramatic, compressed 3D effect.

```typescript
// Dramatic close perspective
flap: { type: "board", perspective: 60, styledBoard: true }

// Subtle, distant perspective (default feel)
flap: { type: "flip", perspective: 400 }
```

Range: 50–1000 px.

## Use Cases

### Departure Board

```typescript
Motion("departures", ".board-header", {
  split: "chars",
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.9,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Airport departure header"
  html={`<div class="scene"><h2 class="board-header">MADRID IB3170</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.board-header { margin: 0; font: 800 clamp(1rem, 4vw, 1.55rem)/1 ui-monospace, monospace; letter-spacing: 0.08em; color: #edf0ff; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("departures-preview", ".board-header", {
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Countdown / Score Counter

```typescript
Motion("score", ".score-value", {
  split: "chars",
  flap: { type: "slide", charset: "numeric", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Score counter roll"
  html={`<div class="scene"><strong class="score-value">8750</strong></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.score-value { font: 850 3rem/1 ui-monospace, monospace; letter-spacing: 0.1em; color: #ffd974; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("score-preview", ".score-value", {
  flap: { type: "slide", charset: "numeric", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Classified / Decode Reveal

```typescript
Motion("classified", ".secret-text", {
  split: "chars",
  flap: { type: "blur", cycles: [3, 6] },
  stagger: 0.03,
  duration: 0.9,
}).onScroll({ toggleActions: "play none none none", start: "top 80%" });
```

<LivePreview client:visible
  height={200}
  title="Classified message reveal"
  html={`<div class="scene"><p class="secret-text">EYES ONLY</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.secret-text { margin: 0; padding: 0.65rem 0.9rem; border: 1px solid #67343e; font: 800 1.7rem/1 ui-monospace, monospace; letter-spacing: 0.16em; color: #ff909f; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("classified-preview", ".secret-text", {
  flap: { type: "blur", cycles: [3, 6] },
  stagger: 0.03,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Cyber / Matrix Aesthetic

```typescript
Motion("matrix", ".terminal-output", {
  split: "chars",
  flap: { type: "fade", charset: "katakana", cycles: [4, 8] },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Cyber terminal decode"
  html={`<div class="terminal"><span class="prompt">&gt;</span><span class="terminal-output">ACCESS NODE 07</span></div>`}
  css={`.terminal { display: flex; align-items: center; gap: 0.7rem; padding: 1rem 1.2rem; border: 1px solid #184b3a; border-radius: 0.45rem; background: #06120f; }
.prompt { color: #3affad; }
.terminal-output { font: 700 clamp(0.85rem, 3vw, 1.25rem)/1 ui-monospace, monospace; letter-spacing: 0.1em; color: #62f1ba; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("matrix-preview", ".terminal-output", {
  flap: { type: "fade", charset: "katakana", cycles: [4, 8], stableWidth: "container" },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Binary Counter

```typescript
Motion("binary", ".bit-display", {
  split: "chars",
  flap: { type: "slide", charset: "binary", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Binary bit display"
  html={`<div class="scene"><code class="bit-display">10110110</code></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.bit-display { font: 800 clamp(1.35rem, 6vw, 2.5rem)/1 ui-monospace, monospace; letter-spacing: 0.18em; color: #79c8ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("binary-preview", ".bit-display", {
  flap: { type: "slide", charset: "binary", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Blocks Loading Indicator

```typescript
Motion("loading", ".loading-text", {
  split: "chars",
  flap: { type: "none", charset: "blocks", cycles: [4, 8] },
  stagger: 0.02,
  duration: 0.8,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Block loading indicator"
  html={`<div class="scene"><p class="loading-text">LOADING</p></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.loading-text { margin: 0; font: 800 1.9rem/1 ui-monospace, monospace; letter-spacing: 0.18em; color: #d3b4ff; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("loading-preview", ".loading-text", {
  flap: { type: "none", charset: "blocks", cycles: [4, 8] },
  stagger: 0.02,
  duration: 0.8,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## Stagger with Flapper

Stagger is the primary way to shape the flapper's cascade feel. All [stagger options](/docs/sdk/stagger) work — `from: 'random'` is particularly effective for organic decode effects.

```typescript
// Left-to-right cascade (default)
stagger: 0.05

// Random order — each char starts at a different time
stagger: { each: 0.03, from: "random" }

// Center outward
stagger: { each: 0.04, from: "center" }
```

## Cleanup

The board type restructures the DOM. Use `Motion.reset()` or `.kill()` to revert character elements back to their original state.

```typescript
// Kill one timeline and revert DOM
Motion("departures").kill();

// Revert by target element
Motion.reset(".board-title");
```

## API Reference

```typescript
interface FlapConfig {
  type?: 'flip' | 'fade' | 'slide' | 'blur' | 'scale' | 'board' | 'none';
  charset?: 'alphanumeric' | 'alpha' | 'numeric' | 'hex' | 'binary' | 'katakana' | 'symbols' | 'blocks' | string;
  cycles?: number | [min: number, max: number];
  perspective?: number;
  styledBoard?: boolean;
  stableWidth?: boolean | 'cells' | 'container';
  preserveWhitespaceCells?: boolean;
}

// Used inside AnimationConfig — split: 'chars' is auto-applied when flap is set
interface AnimationConfig {
  split?: SplitType;  // optional — defaults to 'chars' when flap is present
  flap?: FlapConfig;
}
```

---

Related: [Text Splitter](/docs/sdk/split-text) (optional — auto-applied by flap) · [Stagger](/docs/sdk/stagger) · [Opacity](/docs/sdk/opacity)

---

## Page Load Trigger

> Auto-play animations when the page loads or DOM is ready.

URL: https://motion.page/docs/sdk/page-load

import LivePreview from "../../components/docs/blocks/LivePreview";

`.onPageLoad()` plays a timeline as soon as the DOM is ready — the go-to trigger for entrance animations, hero reveals, and anything that should animate in when the page first appears.

## Basic Usage

Chain `.onPageLoad()` after defining your animation. The timeline plays automatically when `DOMContentLoaded` fires.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad();
```

## Options

`.onPageLoad()` accepts an optional config object:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timing` | `'before' \| 'during' \| 'after'` | `'during'` | Lifecycle event that starts playback: immediately, on `DOMContentLoaded`, or on `window.load`. |
| `paused` | `boolean` | `false` | Build the timeline and apply initial states immediately, but don't auto-play. Start manually with `Motion(name).play()`. |

---

## `.play()` — Immediate Trigger

`.play()` plays the timeline right now, with no event listener involved. Use it when you're calling animation code inside a framework lifecycle hook (`useEffect`, `onMounted`, Astro `page-load`) or after an explicit user action, where the DOM is already ready.

```typescript
Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).play();
```

## `onPageLoad` vs `play` — When to Use Each

| | `.onPageLoad()` | `.play()` |
|---|---|---|
| **Timing** | Defaults to `DOMContentLoaded`; configurable with `timing` | Plays immediately, no event listener |
| **Use when** | Script runs early (e.g. `<head>`, top of `<body>`) | Script runs inside a lifecycle hook or after DOM is ready |
| **Multiple timelines** | Each starts at its selected lifecycle event | Plays immediately in call order |
| **If its event already fired** | Fires immediately on registration | Same — fires immediately |

**Practical rule:** if your code runs inside `window.addEventListener('DOMContentLoaded', ...)`, a framework `useEffect`, or an Astro `page-load` event — use `.play()`. If your `<script>` tag is in `<head>` and runs before the DOM is parsed — use `.onPageLoad()`.

---

## With Delay

Add a `delay` (in seconds) to the `AnimationConfig` to hold before the animation begins. This is useful for staggering multiple independent animations or letting the page "settle" before an entrance.

```typescript
Motion("tagline", ".tagline", {
  from: { opacity: 0, y: 20 },
  duration: 0.6,
  delay: 0.4,
  ease: "power2.out",
}).onPageLoad();
```

---

## Staggered Entrance

Apply `stagger` to animate multiple elements in sequence — the classic staggered card or list reveal on load.

```typescript
Motion("cards", ".feature-card", {
  from: { opacity: 0, y: 30, scale: 0.95 },
  duration: 0.7,
  ease: "power3.out",
  stagger: { each: 0.1, from: "start" },
}).onPageLoad();
```

---

<LivePreview
  client:load
  height={220}
  title="Page load entrance"
  html={`<div class="scene"><div class="box">1</div><div class="box">2</div><div class="box">3</div></div>`}
  css={`.scene { display: flex; gap: 16px; justify-content: center; align-items: center; height: 100%; }
.box { width: 80px; height: 80px; background: #6633EE; border-radius: 12px; display: flex; align-items: center; justify-content: center; color: white; font-weight: bold; font-size: 20px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("entrance", ".box", {
  from: { opacity: 0, y: 32, scale: 0.92 },
  duration: 0.6,
  stagger: 0.12,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

---

## From-Only Pattern

The most common page-load pattern is a `from`-only reveal: start hidden or offset, animate back to the element's natural CSS state. The SDK reads the natural `to` values automatically.

```typescript
// Slide up from below — SDK auto-resolves to: { opacity: 1, y: 0 }
Motion("hero", ".hero-title", {
  from: { opacity: 0, y: 60 },
  duration: 1,
  ease: "power3.out",
}).onPageLoad();

// Scale up from slightly smaller
Motion("cta", ".cta-button", {
  from: { opacity: 0, scale: 0.85 },
  duration: 0.5,
  ease: "back.out",
  delay: 0.6,
}).onPageLoad();
```

---

## Paused Timeline — Manual Trigger

Set `paused: true` to build the timeline and apply initial states immediately without playing. Trigger it later with an explicit `.play()` call.

```typescript
// Register on load — applies from-state immediately, does not play
Motion("modal", ".modal", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.4,
  ease: "power2.out",
}).onPageLoad({ paused: true });

// Play later — e.g. after a button click
document.querySelector("#open-btn").addEventListener("click", () => {
  Motion("modal").play();
});
```

This is useful for modals, drawers, or any element that should start in its hidden state and only animate in on demand.

---

## Lifecycle Timing

The `timing` option selects a real document lifecycle point; it does not wait for an earlier animation to finish:

- **`'before'`** starts immediately when `.onPageLoad()` is registered.
- **`'during'`** (default) starts on `DOMContentLoaded`.
- **`'after'`** starts on the window `load` event, after dependent resources finish loading.

If the selected event has already fired, that timeline starts immediately on registration. Timelines waiting for the same event are started in registration order and can run concurrently.

Killing a waiting timeline unregisters it before the lifecycle event can play it. When the last pending page-load timeline is killed, replaced with another trigger, or removed by `Motion.killAll()`, the SDK also removes its pending `DOMContentLoaded` and `load` listeners. A later `.onPageLoad()` registration safely attaches a fresh listener only for lifecycle phases that have not fired yet.

```typescript
// Starts immediately when registered
Motion("hero", "#hero", {
  from: { opacity: 0, y: 50 },
  duration: 0.8,
}).onPageLoad({ timing: "before" });

// Starts when the DOMContentLoaded event fires
Motion("nav", "nav", {
  from: { opacity: 0, y: -20 },
  duration: 0.5,
}).onPageLoad({ timing: "during" });

// Starts when the window load event fires
Motion("footer-cta", ".footer-cta", {
  from: { opacity: 0 },
  duration: 0.4,
}).onPageLoad({ timing: "after" });
```

---

## SPA and Framework Usage

If your script runs **after the selected lifecycle event** — inside a React `useEffect`, Vue `onMounted`, or Astro `page-load` event — `.onPageLoad()` fires immediately on registration. In these contexts, `.play()` is often the clearer choice. One exception is `timing: "after"` registered after `DOMContentLoaded` but before `window.load`; it still waits for `window.load`.

```typescript
// React
useEffect(() => {
  Motion("hero", ".hero", { from: { opacity: 0, y: 30 }, duration: 0.8 }).play();
}, []);

// Astro (View Transitions)
document.addEventListener("astro:page-load", () => {
  Motion("hero", ".hero", { from: { opacity: 0, y: 30 }, duration: 0.8 }).play();
});
```

For SPA contexts where animations need to be torn down and re-initialized on route change, wrap them in `Motion.context()` for clean lifecycle management. See [Dynamic Content & SPA Pattern](/docs/sdk/core-concepts#dynamic-content--spa-pattern) for the full pattern.

---

## Looping on Page Load

Chain `.withRepeat()` before `.onPageLoad()` to loop the entire timeline continuously after the page loads.

```typescript
Motion("pulse", ".badge", {
  to: { scale: 1.08, opacity: 0.8 },
  duration: 0.8,
  ease: "sine.inOut",
})
  .withRepeat({ times: -1, yoyo: true })
  .onPageLoad();
```

---

## Related

- [Scroll Trigger](/docs/sdk/scroll-trigger) — play when elements enter the viewport
- [Hover](/docs/sdk/hover) — react to mouse enter and leave
- [Click](/docs/sdk/click) — toggle animations on click
- [Duration & Delay](/docs/sdk/duration-delay) — control timing within animations
- [Stagger](/docs/sdk/stagger) — sequence multiple elements

---

## Utility Functions

> Motion.utils helpers — toArray, clamp, random, snap, interpolate, mapRange.

URL: https://motion.page/docs/sdk/utilities

import LivePreview from "../../components/docs/blocks/LivePreview";

`Motion.utils` is a collection of math and DOM helpers for computing dynamic animation values at runtime — converting selectors, clamping progress, mapping ranges for parallax, snapping to grid positions, and more.

## Accessing Utilities

Access via the static `Motion.utils` property, or import `MotionUtils` directly — both are identical.

```typescript
import { Motion, MotionUtils } from "@motion.page/sdk";

// Via the static property
const cards = Motion.utils.toArray(".card");

// Via named import — equivalent
const clamped = MotionUtils.clamp(0, 100, 150); // 100
```

## Quick Reference

| Method | Signature | Returns |
|--------|-----------|---------|
| `toArray` | `(target, scope?)` | `Element[]` |
| `clamp` | `(min, max, value?)` | `number` or curried `fn` |
| `random` | `(min, max, snap?)` | `number` |
| `snap` | `(snapTo, value?)` | `number` or curried `fn` |
| `interpolate` | `(start, end, progress)` | `number` |
| `mapRange` | `(inMin, inMax, outMin, outMax, value?)` | `number` or curried `fn` |
| `normalize` | `(min, max, value?)` | `number` or curried `fn` |
| `wrap` | `(min, max, value?)` | `number` or curried `fn` |

## Curried Functions

Several utilities are **curried** — omit the final `value` argument and they return a reusable function instead of computing a result immediately. This lets you configure a helper once and apply it many times.

```typescript
import { Motion } from "@motion.page/sdk";

// Full call — returns a number immediately
Motion.utils.clamp(0, 100, 150); // 100

// Curried call — returns a configured function
const clamp0to100 = Motion.utils.clamp(0, 100);
clamp0to100(150); // 100
clamp0to100(-50); //   0
clamp0to100(42);  //  42
```

`clamp`, `snap`, `mapRange`, `normalize`, and `wrap` all support this pattern. `toArray`, `random`, and `interpolate` do not — they always return a value directly.

---

## toArray

Convert a CSS selector string, `NodeList`, `HTMLCollection`, or single `Element` into a flat `Element[]`.

```typescript
Motion.utils.toArray(target, scope?: Element | Document): Element[]
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | `string \| Element \| NodeList \| HTMLCollection` | What to convert |
| `scope` | `Element \| Document` | Optional root for the selector query. Defaults to `document` |

```typescript
import { Motion } from "@motion.page/sdk";

// From a CSS selector
const cards = Motion.utils.toArray(".card");

// Scoped query — only searches inside .gallery
const container = document.querySelector(".gallery")!;
const items = Motion.utils.toArray(".item", container);

// From a NodeList
const nodes = document.querySelectorAll("section");
const sections = Motion.utils.toArray(nodes);
```

**Real-world use — horizontal scroll panel count:**

```typescript
import { Motion } from "@motion.page/sdk";

const panels = Motion.utils.toArray(".panel");

Motion("h-scroll", ".panel", {
  to: { x: `-${(panels.length - 1) * 100}%` },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  end: `+=${panels.length * 100}%`,
  snap: 1 / (panels.length - 1),
});
```

---

## clamp

Constrain a number so it never falls below `min` or rises above `max`.

```typescript
Motion.utils.clamp(min: number, max: number, value?: number): number | ((value: number) => number)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `min` | `number` | Lower bound |
| `max` | `number` | Upper bound |
| `value` | `number` | Value to clamp. Omit to get a curried function |

```typescript
import { Motion } from "@motion.page/sdk";

Motion.utils.clamp(0, 100, 150); // 100
Motion.utils.clamp(0, 100, -20); //   0
Motion.utils.clamp(0, 100, 60);  //  60

// Curried — reusable clamp function
const clampProgress = Motion.utils.clamp(0, 1);
clampProgress(1.5);  // 1
clampProgress(-0.2); // 0
clampProgress(0.75); // 0.75
```

**Real-world use — guard scroll progress before seeking a timeline:**

```typescript
import { Motion } from "@motion.page/sdk";

const clampProgress = Motion.utils.clamp(0, 1);

Motion("scrub-bar", ".progress-bar", {
  to: { width: "100%" },
  duration: 1,
}).onPageLoad({ paused: true });

document.addEventListener("scroll", () => {
  const raw = window.scrollY / (document.body.scrollHeight - window.innerHeight);
  Motion("scrub-bar").progress(clampProgress(raw));
});
```

---

## random

Generate a random floating-point number between `min` and `max`. Pass an optional `snap` increment to round the result to the nearest multiple.

```typescript
Motion.utils.random(min: number, max: number, snap?: number): number
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `min` | `number` | Lower bound (inclusive) |
| `max` | `number` | Upper bound (inclusive) |
| `snap` | `number` | Optional snap increment — result rounds to the nearest multiple |

```typescript
import { Motion } from "@motion.page/sdk";

Motion.utils.random(0, 100);       // e.g. 63.27
Motion.utils.random(0, 100, 10);   // e.g. 60  (snapped to nearest 10)
Motion.utils.random(-50, 50);      // e.g. -17.4
Motion.utils.random(0, 1, 0.25);   // 0, 0.25, 0.5, 0.75, or 1
```

**Real-world use — organic scattered entrance:**

```typescript
import { Motion } from "@motion.page/sdk";

const { random } = Motion.utils;

Motion("scattered", ".particle", {
  from: {
    x: random(-200, 200),
    y: random(-100, 100),
    opacity: 0,
    scale: random(0.5, 1.2),
  },
  duration: random(0.5, 1.0),
  stagger: { each: 0.04, from: "random" },
  ease: "power2.out",
}).onPageLoad();
```

**Randomised delay per element:**

```typescript
import { Motion } from "@motion.page/sdk";

const { random, toArray } = Motion.utils;
const items = toArray(".grid-item");

// Each item gets a unique random delay at build time
Motion("grid-in", items, {
  from: { opacity: 0, y: random(20, 60) },
  duration: random(0.4, 0.8),
  stagger: { each: 0.05, from: "random" },
  ease: "power2.out",
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

---

## snap

Snap a number to the nearest multiple of an increment, or to the nearest value within an array.

```typescript
Motion.utils.snap(snapTo: number | number[], value?: number): number | ((value: number) => number)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `snapTo` | `number \| number[]` | Increment to snap to, or an array of allowed values |
| `value` | `number` | Value to snap. Omit to get a curried function |

```typescript
import { Motion } from "@motion.page/sdk";

// Snap to nearest 10
Motion.utils.snap(10, 23); // 20
Motion.utils.snap(10, 25); // 30
Motion.utils.snap(10, 8);  // 10

// Snap to the nearest value in an array
Motion.utils.snap([0, 0.33, 0.66, 1], 0.4); // 0.33
Motion.utils.snap([0, 0.33, 0.66, 1], 0.5); // 0.66

// Curried — reusable snap function
const snapToGrid = Motion.utils.snap(50);
snapToGrid(74);  //  50
snapToGrid(130); // 150
snapToGrid(275); // 300
```

**Real-world use — carousel index snapping:**

```typescript
import { Motion } from "@motion.page/sdk";

const slides = Motion.utils.toArray(".slide");
const snapToSlide = Motion.utils.snap(1); // snap to nearest whole number

let rawIndex = 0;

document.querySelector(".track")?.addEventListener("pointerup", () => {
  const snapped = snapToSlide(rawIndex);
  // jump to the nearest whole slide index
});
```

**Real-world use — scroll with discrete snap points:**

```typescript
import { Motion } from "@motion.page/sdk";

const sections = Motion.utils.toArray("section");
const count = sections.length;

// Evenly distributed snap points: [0, 0.25, 0.5, 0.75, 1] for 5 sections
const snapPoints = sections.map((_, i) => i / (count - 1));

Motion("fullpage", ".page-wrapper", {
  to: { y: `-${(count - 1) * 100}vh` },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  end: `+=${count * 100}vh`,
  snap: snapPoints,
});
```

---

## interpolate

Linearly interpolate between `start` and `end` at a normalized progress value. At `progress = 0` the result equals `start`; at `progress = 1` it equals `end`. Values outside 0–1 extrapolate beyond the endpoints.

```typescript
Motion.utils.interpolate(start: number, end: number, progress: number): number
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `start` | `number` | Value returned when `progress` is `0` |
| `end` | `number` | Value returned when `progress` is `1` |
| `progress` | `number` | Normalized position — typically `0–1` |

```typescript
import { Motion } from "@motion.page/sdk";

Motion.utils.interpolate(0, 100, 0);    //   0
Motion.utils.interpolate(0, 100, 0.5);  //  50
Motion.utils.interpolate(0, 100, 1);    // 100
Motion.utils.interpolate(20, 80, 0.25); //  35
Motion.utils.interpolate(0, 100, 1.5);  // 150 (extrapolates)
```

**Real-world use — drive a CSS variable from scroll progress:**

```typescript
import { Motion } from "@motion.page/sdk";

const { interpolate, clamp } = Motion.utils;
const clampScroll = clamp(0, 1);

document.addEventListener("scroll", () => {
  const progress = clampScroll(window.scrollY / 400);

  // Blend from 0px blur to 12px blur as the user scrolls
  const blur = interpolate(0, 12, progress);
  document.documentElement.style.setProperty("--header-blur", `${blur}px`);
});
```

---

## mapRange

Map a value from one numeric range to another in a single step. Equivalent to normalizing the input then interpolating to the output, but more concise.

```typescript
Motion.utils.mapRange(
  inMin: number,
  inMax: number,
  outMin: number,
  outMax: number,
  value?: number
): number | ((value: number) => number)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `inMin` | `number` | Input range lower bound |
| `inMax` | `number` | Input range upper bound |
| `outMin` | `number` | Output range lower bound |
| `outMax` | `number` | Output range upper bound |
| `value` | `number` | Value to map. Omit to get a curried function |

```typescript
import { Motion } from "@motion.page/sdk";

// Map [0, 500] → [0, 1]
Motion.utils.mapRange(0, 500, 0, 1, 250); // 0.5

// Map [0, 1] → [20, 80]
Motion.utils.mapRange(0, 1, 20, 80, 0.75); // 65

// Inverted range — output decreases as input increases
Motion.utils.mapRange(0, 100, 1, 0, 40); // 0.6

// Curried — scrollY to a parallax offset
const scrollToOffset = Motion.utils.mapRange(0, 600, -60, 60);
scrollToOffset(0);   // -60
scrollToOffset(300); //   0
scrollToOffset(600); //  60
```

**Real-world use — parallax layer driven by scroll:**

```typescript
import { Motion } from "@motion.page/sdk";

const mapParallax = Motion.utils.mapRange(0, window.innerHeight, -80, 80);

window.addEventListener("scroll", () => {
  Motion.set(".bg-layer", { y: mapParallax(window.scrollY) });
});
```

**Real-world use — 3D card tilt from mouse position:**

```typescript
import { Motion } from "@motion.page/sdk";

const mapX = Motion.utils.mapRange(0, window.innerWidth, -20, 20);
const mapY = Motion.utils.mapRange(0, window.innerHeight, -20, 20);

document.addEventListener("mousemove", (e) => {
  Motion.set(".card-3d", {
    rotateY: mapX(e.clientX),
    rotateX: -mapY(e.clientY),
  });
});
```

<LivePreview client:load
  height={280}
  title="mapRange — mouse to rotation"
  html={`<div class="scene">
  <div class="card">
    <div class="label">Move your mouse</div>
  </div>
  <div class="readout">
    <div class="row"><span class="key">mouseX</span><span id="mx">—</span></div>
    <div class="row"><span class="key">rotateY</span><span id="ry">—</span></div>
    <div class="row"><span class="key">rotateX</span><span id="rx">—</span></div>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 24px; height: 100%; background: #0a0a0a; perspective: 600px; }
.card { width: 160px; height: 100px; background: linear-gradient(135deg, #6633EE, #9966ff); border-radius: 14px; display: flex; align-items: center; justify-content: center; transform-style: preserve-3d; box-shadow: 0 12px 40px rgba(102,51,238,0.4); }
.label { color: white; font-family: sans-serif; font-size: 13px; font-weight: 600; letter-spacing: 0.02em; }
.readout { display: flex; flex-direction: column; gap: 6px; }
.row { display: flex; gap: 12px; font-family: monospace; font-size: 12px; }
.key { color: #888; width: 60px; }
#mx, #ry, #rx { color: #9966ff; min-width: 48px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("tilt", ".card", {
  from: { rotateY: -20, rotateX: 20 },
  to: { rotateY: 20, rotateX: -20 },
}).onMouseMove({ type: "axis", smooth: 0.08, target: ".scene" });`}
/>

---

## normalize

Normalize a value within a `[min, max]` range to a `0–1` fraction. Equivalent to `mapRange(min, max, 0, 1, value)` — a dedicated shorthand for the common case.

```typescript
Motion.utils.normalize(min: number, max: number, value?: number): number | ((value: number) => number)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `min` | `number` | Range lower bound — maps to `0` |
| `max` | `number` | Range upper bound — maps to `1` |
| `value` | `number` | Value to normalize. Omit to get a curried function |

```typescript
import { Motion } from "@motion.page/sdk";

Motion.utils.normalize(0, 500, 250);   // 0.5
Motion.utils.normalize(0, 500, 0);     // 0
Motion.utils.normalize(0, 500, 500);   // 1
Motion.utils.normalize(100, 200, 150); // 0.5

// Curried — pre-configured for a specific scroll zone
const normSection = Motion.utils.normalize(200, 800);
normSection(200); // 0
normSection(500); // 0.5
normSection(800); // 1
```

**Real-world use — section-local scroll progress:**

```typescript
import { Motion } from "@motion.page/sdk";

const section = document.querySelector<HTMLElement>(".section")!;
const clamp = Motion.utils.clamp(0, 1);
const normalize = Motion.utils.normalize(
  section.offsetTop,
  section.offsetTop + section.offsetHeight
);

Motion("section-anim", ".section-content", {
  from: { opacity: 0, y: 40 },
  duration: 1,
}).onPageLoad({ paused: true });

document.addEventListener("scroll", () => {
  const progress = clamp(normalize(window.scrollY));
  Motion("section-anim").progress(progress);
});
```

---

## wrap

Wrap a value modularly within a `[min, max]` range. When the value exceeds `max` it loops back to `min`; when it drops below `min` it loops back from `max`. Useful for carousel indices, cyclic progress, and infinite loops.

```typescript
Motion.utils.wrap(min: number, max: number, value?: number): number | ((value: number) => number)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `min` | `number` | Range lower bound |
| `max` | `number` | Range upper bound (exclusive — wraps before reaching it) |
| `value` | `number` | Value to wrap. Omit to get a curried function |

```typescript
import { Motion } from "@motion.page/sdk";

Motion.utils.wrap(0, 4, 0);  // 0
Motion.utils.wrap(0, 4, 3);  // 3
Motion.utils.wrap(0, 4, 4);  // 0  (wraps back to start)
Motion.utils.wrap(0, 4, 5);  // 1
Motion.utils.wrap(0, 4, -1); // 3  (wraps from the other end)

// Curried — loop through 5 slide indices
const wrapSlide = Motion.utils.wrap(0, 5);
wrapSlide(4); // 4
wrapSlide(5); // 0
wrapSlide(6); // 1
```

**Real-world use — infinite carousel next/previous:**

```typescript
import { Motion } from "@motion.page/sdk";

const slides = Motion.utils.toArray(".slide");
const wrapIndex = Motion.utils.wrap(0, slides.length);

let current = 0;

function goTo(index: number) {
  current = wrapIndex(index);
  Motion("carousel").kill();
  Motion("carousel", slides[current], {
    from: { x: "100%", opacity: 0 },
    duration: 0.5,
    ease: "power2.out",
  }).play();
}

document.querySelector(".next")?.addEventListener("click", () => goTo(current + 1));
document.querySelector(".prev")?.addEventListener("click", () => goTo(current - 1));
```

---

## Common Patterns

### Parallax Layers with mapRange

Each layer moves at a different speed relative to scroll, creating depth. Use a curried `mapRange` per layer so the computation is ready before the scroll event fires.

```typescript
import { Motion } from "@motion.page/sdk";

const mapFar    = Motion.utils.mapRange(0, document.body.scrollHeight, -60,  60);
const mapMid    = Motion.utils.mapRange(0, document.body.scrollHeight, -30,  30);
const mapNear   = Motion.utils.mapRange(0, document.body.scrollHeight, -15,  15);

window.addEventListener("scroll", () => {
  const y = window.scrollY;
  Motion.set(".layer-far",  { y: mapFar(y) });
  Motion.set(".layer-mid",  { y: mapMid(y) });
  Motion.set(".layer-near", { y: mapNear(y) });
});
```

### Fluid Values Clamped to a Viewport Range

Compute a responsive value that scales with viewport width but never goes outside safe bounds.

```typescript
import { Motion } from "@motion.page/sdk";

const fluidSize = Motion.utils.mapRange(375, 1440, 16, 24);
const clampSize = Motion.utils.clamp(16, 24);

const fontSize = clampSize(fluidSize(window.innerWidth));
document.documentElement.style.setProperty("--base-size", `${fontSize}px`);
```

### Clamp + Normalize for Safe Timeline Seeking

Combine `normalize` and `clamp` to produce a safe `0–1` progress value from raw `scrollY`, guarding against overscroll or layout-shift edge cases.

```typescript
import { Motion } from "@motion.page/sdk";

const el = document.querySelector<HTMLElement>(".pinned-section")!;
const normalize = Motion.utils.normalize(el.offsetTop, el.offsetTop + el.offsetHeight);
const clamp     = Motion.utils.clamp(0, 1);

Motion("reveal", ".pinned-content", {
  from: { opacity: 0, y: 60 },
  duration: 1,
}).onPageLoad({ paused: true });

document.addEventListener("scroll", () => {
  Motion("reveal").progress(clamp(normalize(window.scrollY)));
});
```

### Snap Points Built from Element Count

Generate evenly distributed snap values for any number of sections without hardcoding fractions.

```typescript
import { Motion } from "@motion.page/sdk";

const sections = Motion.utils.toArray("section");
const count    = sections.length;

// [0, 0.25, 0.5, 0.75, 1] for 5 sections
const snapPoints = sections.map((_, i) =>
  Motion.utils.normalize(0, count - 1, i)
);

Motion("fullpage", ".page-wrapper", {
  to: { y: `-${(count - 1) * 100}vh` },
  duration: 1,
}).onScroll({
  scrub: true,
  pin: true,
  end: `+=${count * 100}vh`,
  snap: snapPoints,
});
```

---

## API Reference

```typescript
import { Motion, MotionUtils } from "@motion.page/sdk";

// Motion.utils and MotionUtils are identical
Motion.utils.toArray(target, scope?)                              // Element[]
Motion.utils.clamp(min, max, value?)                             // number | fn
Motion.utils.random(min, max, snap?)                             // number
Motion.utils.snap(snapTo, value?)                                // number | fn
Motion.utils.interpolate(start, end, progress)                   // number
Motion.utils.mapRange(inMin, inMax, outMin, outMax, value?)      // number | fn
Motion.utils.normalize(min, max, value?)                         // number | fn
Motion.utils.wrap(min, max, value?)                              // number | fn
```

Functions marked `number | fn` are **curried** — omit the final argument to receive a pre-configured function rather than an immediate result.

---

Related: [Core Concepts](/docs/sdk/core-concepts) · [Scroll Trigger](/docs/sdk/scroll-trigger) · [Mouse Movement](/docs/sdk/mouse-movement) · [Timeline Control](/docs/sdk/timeline-control)

---

## Click Trigger

> Play animations on click with toggle support for reverse and restart.

URL: https://motion.page/docs/sdk/click

import LivePreview from "../../components/docs/blocks/LivePreview";

`.onClick()` plays a timeline when an element is clicked. By default every click starts a fresh forward run. Set `toggle: "reverse"` when you want alternating forward and reverse clicks.

## Basic usage

Chain `.onClick()` after defining your animation. By default the click target is the first animated element.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("expand", ".card", {
  to: { height: "240px", paddingBottom: "24px" },
  duration: 0.4,
  ease: "power2.inOut",
}).onClick();
```

---

## Options

| Option           | Type                               | Default                | Description                                                                                                            |
| ---------------- | ---------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `target`         | `string \| Element`                | First animated element | CSS selector or element that triggers the click.                                                                       |
| `secondTarget`   | `string \| Element`                | —                      | Separate element that performs the configured `toggle` action; the primary `target` always starts a fresh forward run. |
| `toggle`         | `'reverse' \| 'restart' \| 'play'` | `'play'`               | Action for an even click on one target, or every click on `secondTarget`.                                              |
| `each`           | `boolean`                          | `false`                | Give each matched element its own independent timeline instance.                                                       |
| `preventDefault` | `boolean`                          | `false`                | Call `event.preventDefault()` on the click event — useful when the trigger is a link or submit button.                 |

---

## Toggle behavior

The `toggle` option controls what the second (and every even) click does:

- **`'reverse'`** — alternates forward/reverse. Click once: starts forward. Click again: plays backward.
- **`'restart'`** — always replays from the start on each click. No reverse.
- **`'play'`** (default) — every primary-target click starts a fresh forward run. On a separate `secondTarget`, it resumes forward from the current position.

```typescript
// reverse — first click plays, second click reverses (accordion, drawer, etc.)
Motion("menu", "#nav-dropdown", {
  from: { height: 0, opacity: 0 },
  duration: 0.35,
  ease: "power2.inOut",
}).onClick({ target: "#menu-btn", toggle: "reverse" });

// restart — replay from scratch on every click
Motion("flash", ".notification", {
  to: { backgroundColor: "#ff4444", scale: 1.04 },
  duration: 0.25,
  ease: "power2.out",
}).onClick({ toggle: "restart" });
```

---

## Separate click target

Use `target` to specify a different element as the trigger — the clicked element doesn't have to be the animated element.

```typescript
// Click the button to expand/collapse the panel
Motion("details", ".details-body", {
  from: { height: 0, opacity: 0 },
  duration: 0.4,
  ease: "power2.inOut",
}).onClick({ target: ".details-toggle", toggle: "reverse" });
```

Add `secondTarget` when one control should start the animation and another should perform its configured follow-up action:

```typescript
// The title opens/restarts the accordion; the icon reverses it
Motion("accordion", ".accordion-body", {
  from: { height: 0 },
  to: { height: "auto" },
  duration: 0.35,
  ease: "power2.inOut",
}).onClick({
  target: ".accordion-title",
  secondTarget: ".accordion-icon",
  toggle: "reverse",
});
```

---

## `each` — independent per-element instances

Without `each`, all matched elements share one timeline. To let clicking any matched element control that group timeline, pass the same selector as `target`. With `each: true`, every element gets its own independent timeline.

```typescript
// Without each — all cards toggle together
Motion("cards", ".card", {
  to: { y: -8 },
  duration: 0.3,
}).onClick({ target: ".card", toggle: "reverse" });

// With each — each card toggles independently
Motion("cards", ".card", {
  to: { y: -8 },
  duration: 0.3,
}).onClick({ each: true, toggle: "reverse" });
```

---

<LivePreview
  client:load
  height={240}
  title="Click to expand"
  html={`<div class="scene">
  <button class="btn">Click me</button>
  <div class="box">
    <p class="content">Hidden content revealed on click.</p>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 16px; height: 100%; font-family: sans-serif; }
.btn { padding: 10px 24px; background: #6633EE; color: white; border: none; border-radius: 8px; font-size: 14px; cursor: pointer; font-weight: 600; }
.btn:hover { background: #7744ff; }
.box { overflow: hidden; height: 0; background: #1a1a2e; border-radius: 10px; width: 220px; color: #e0d4ff; display: flex; align-items: center; justify-content: center; }
.content { padding: 0 20px; text-align: center; font-size: 14px; line-height: 1.5; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("expand", ".box", {
  to: { height: "80px" },
  duration: 0.38,
  ease: "power3.out",
}).onClick({ target: ".btn", toggle: "reverse" });`}
/>

---

## Click to rotate

Rotate an icon on each click — useful for chevrons next to dropdowns, arrows on toggles.

```typescript
Motion("icon-spin", ".chevron", {
  to: { rotate: 180 },
  duration: 0.3,
  ease: "power2.inOut",
}).onClick({ target: ".dropdown-btn", toggle: "reverse" });
```

---

## Prevent default on links

When the click target is an `<a>` tag or a `<button type="submit">`, use `preventDefault: true` to stop the default browser action.

```typescript
Motion("lightbox", ".lightbox", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.35,
  ease: "power2.out",
}).onClick({
  target: "a[data-lightbox]",
  toggle: "reverse",
  preventDefault: true,
});
```

---

## Theme toggle

Animate a color transition driven by a toggle button:

```typescript
Motion("theme", "#banner", {
  to: { backgroundColor: "#1a1a2e", color: "#e0e0ff" },
  duration: 0.5,
  ease: "power2.inOut",
}).onClick({ target: "#dark-toggle", toggle: "reverse" });
```

---

## Related

- [Hover](/docs/sdk/hover) — react to mouse enter and leave
- [Page Load Trigger](/docs/sdk/page-load) — auto-play on DOM ready
- [Timeline Control](/docs/sdk/timeline-control) — play, pause, and seek timelines programmatically

---

## Core Concepts

> Named timelines, from/to resolution, implicit values, and how the SDK works internally.

URL: https://motion.page/docs/sdk/core-concepts

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

The SDK is built around a small set of concepts. Understand these and everything else follows naturally.

---

## Named Timelines

Every animation is a **named timeline**. The name is a registry key — calling `Motion('hero')` always returns the same `Timeline` instance, no matter where in your code you call it.

```typescript
import { Motion } from "@motion.page/sdk";

// Create a timeline named "hero"
Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).onPageLoad();

// Later — retrieve the same instance by name
const tl = Motion("hero");
tl.pause();
```

<LivePreview client:visible
  height={260}
  title="Named timeline controls"
  html={`<div class="named-demo">
  <div class="registry-row">
    <span>Registry key</span>
    <code>named-hero</code>
    <strong id="registry-state">registered</strong>
  </div>
  <div class="timeline-track"><div class="timeline-orb">MP</div></div>
  <div class="controls">
    <button data-action="play">Play</button>
    <button data-action="pause">Pause</button>
    <button data-action="reverse">Reverse</button>
  </div>
</div>`}
  css={`.named-demo {
  width: min(430px, 100%);
  display: grid;
  gap: 16px;
}
.registry-row {
  display: flex;
  align-items: center;
  gap: 10px;
  color: #8f96b6;
  font-size: 12px;
}
.registry-row code {
  color: #c7b8ff;
  padding: 4px 8px;
  border-radius: 6px;
  background: rgba(102, 51, 238, 0.18);
}
.registry-row strong { margin-left: auto; color: #7ee2b8; font-weight: 600; }
.timeline-track {
  height: 82px;
  display: flex;
  align-items: center;
  justify-content: center;
  border: 1px solid rgba(153, 102, 255, 0.28);
  border-radius: 41px;
  background: linear-gradient(90deg, rgba(102, 51, 238, 0.08), rgba(153, 102, 255, 0.2), rgba(102, 51, 238, 0.08));
}
.timeline-orb {
  width: 54px;
  height: 54px;
  display: grid;
  place-items: center;
  border-radius: 50%;
  background: linear-gradient(135deg, #8f6cff, #5b2ee8);
  box-shadow: 0 12px 30px rgba(102, 51, 238, 0.4);
  color: white;
  font-size: 12px;
  font-weight: 800;
}
.controls { display: flex; justify-content: center; gap: 8px; }
.controls button {
  padding: 8px 14px;
  border: 1px solid rgba(255, 255, 255, 0.14);
  border-radius: 8px;
  background: #171b33;
  color: #dfe1f4;
  font: inherit;
}
.controls button:hover { border-color: #8f6cff; background: #201b45; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("named-hero", ".timeline-orb", {
  from: { x: -110, opacity: 0.45, scale: 0.82 },
  to: { x: 110, opacity: 1, scale: 1.05 },
  duration: 1.2,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

const state = document.querySelector("#registry-state");
const setState = (label) => { state.textContent = label; };

document.querySelector('[data-action="play"]').addEventListener("click", () => {
  Motion("named-hero").play();
  setState("playing");
});
document.querySelector('[data-action="pause"]').addEventListener("click", () => {
  Motion("named-hero").pause();
  setState("paused");
});
document.querySelector('[data-action="reverse"]').addEventListener("click", () => {
  Motion("named-hero").reverse();
  setState("reversed");
});`}
/>

The registry exposes three static helpers for inspecting registered timelines:

| Method | Returns | Description |
|--------|---------|-------------|
| `Motion.get(name)` | `Timeline \| undefined` | Get a timeline by name, or `undefined` if it doesn't exist |
| `Motion.has(name)` | `boolean` | Check whether a named timeline is registered |
| `Motion.getNames()` | `string[]` | Array of all currently registered timeline names |

---

## From/To Resolution

The SDK **auto-resolves** the missing endpoint from the element's current computed CSS. You rarely need to specify both `from` and `to`.

| Config | Behavior | Use Case |
|--------|----------|----------|
| `from` only | SDK reads current CSS as `to` | Reveal animations — start hidden/offset, animate into natural state |
| `to` only | SDK reads current CSS as `from` | Hover/exit effects — start at natural state, animate to custom values |
| Both | Both endpoints explicit | When neither endpoint matches the element's natural CSS |

<CodeBlock
  filename="from-only.ts"
  lang="typescript"
  code={`// Reveal — start invisible and shifted, land on the element's natural CSS
Motion("reveal", ".card", {
  from: { opacity: 0, y: 50 },
  duration: 0.6,
  ease: "power2.out",
}).onPageLoad();`}
/>

<CodeBlock
  filename="to-only.ts"
  lang="typescript"
  code={`// Hover lift — start at natural state, animate to raised state on hover
Motion("card-hover", ".card", {
  to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ each: true, onLeave: "reverse" });`}
/>

<CodeBlock
  filename="both.ts"
  lang="typescript"
  code={`// Parallax — neither endpoint matches the element's natural position
Motion("parallax", ".panel", {
  from: { x: -50 },
  to: { x: 50 },
  duration: 1,
}).onScroll({ scrub: true });`}
/>

---

## Natural CSS Defaults

The SDK treats the following values as an element's **natural state**. When they match what you want as the endpoint, omit them — the SDK fills them in automatically from the computed CSS.

`opacity: 1` · `x: 0` · `y: 0` · `z: 0` · `scale: 1` · `scaleX: 1` · `scaleY: 1` · `rotate: 0`

```typescript
// ✅ Correct — from-only; SDK reads opacity:1, y:0 from the element's CSS
Motion("fade-up", ".hero", {
  from: { opacity: 0, y: 50 },
  duration: 0.8,
}).onPageLoad();

// ❌ Redundant — opacity:1 and y:0 are natural defaults, the to: block adds nothing
Motion("fade-up", ".hero", {
  from: { opacity: 0, y: 50 },
  to: { opacity: 1, y: 0 },
  duration: 0.8,
}).onPageLoad();
```

---

## Set Mode

`Motion.set(target, vars)` immediately applies properties with **zero duration** — no animation, no timeline. Use it to initialise element states before an animation runs, or to snap elements back to a specific state.

```typescript
// Hide elements before the page loads so there's no flash of unstyled content
Motion.set(".card", { opacity: 0, y: 30 });

// Then reveal them on scroll
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
}).onScroll({ scrub: false, toggleActions: "play none none none" });
```

---

## Three Overloads

`Motion` has three call signatures:

<CodeBlock
  filename="overloads.ts"
  lang="typescript"
  code={`// 1. Retrieve an existing timeline by name
const tl = Motion("hero");

// 2. Single-animation timeline — one target, one config object
Motion("fade", "#banner", {
  from: { opacity: 0 },
  duration: 0.6,
}).onPageLoad();

// 3. Multi-step timeline — array of animation entries
Motion("sequence", [
  { target: "#title",    from: { opacity: 0, y: 30 }, duration: 0.5 },
  { target: "#subtitle", from: { opacity: 0, y: 20 }, duration: 0.4, position: "-=0.2" },
  { target: "#cta",      from: { opacity: 0, y: 20 }, duration: 0.4, position: "-=0.1" },
]).onPageLoad();`}
/>

Each entry in the multi-step array is an `AnimationEntry` — the same `AnimationConfig` shape extended with a `target` field and an optional `position` for timeline placement.

---

## The TargetInput Type

The `target` parameter (overload 2) and the `target` field in each entry (overload 3) accept a **`TargetInput`**:

| Type | Example |
|------|---------|
| CSS selector string | `"#hero"`, `".card"`, `"[data-animate]"` |
| `string[]` | `["#title", "#subtitle"]` |
| `Element` | `document.querySelector(".box")` |
| `NodeList` | `document.querySelectorAll(".item")` |
| `Element[]` | Array of DOM elements |
| Plain object | `{ value: 0 }` — for non-DOM tweening |
| Array of plain objects | `[{ count: 0 }, { count: 100 }]` |

CSS selectors are the most common form. Plain objects are useful for tweening arbitrary JS values — for example, driving a canvas draw or incrementing a counter:

```typescript
const counter = { value: 0 };

Motion("count-up", counter, {
  to: { value: 1000 },
  duration: 2,
  ease: "power2.out",
  onUpdate: () => {
    document.querySelector("#counter")!.textContent = Math.round(counter.value).toString();
  },
}).onPageLoad();
```

---

## How Triggers Chain

Timelines are **inert until a trigger is chained**. Creating a timeline with `Motion(name, target, config)` builds the animation but does not play or attach it to anything. You activate it by chaining a trigger method:

```typescript
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 })
  .onPageLoad(); // ← trigger

Motion("cards", ".card", { from: { y: 40 }, duration: 0.5, stagger: 0.1 })
  .onScroll({ scrub: false }); // ← trigger
```

Available triggers:

| Method | Description |
|--------|-------------|
| `.play()` | Play immediately, right now |
| `.onPageLoad(config?)` | Play when the DOM is ready; fires immediately if already loaded |
| `.onHover(config?)` | Play on `mouseenter`, react on `mouseleave` |
| `.onClick(config?)` | Play/replay on click; optionally reverse or restart |
| `.onScroll(config?)` | Scrub or snap animation to scroll position |
| `.onMouseMove(config?)` | Drive animation progress from mouse position |
| `.onPageExit(config?)` | Intercept link clicks, play animation, then navigate |
| `.onGesture(config)` | Map pointer/touch/wheel/scroll gestures to animation progress |
| `.onCursor(config)` | Replace the native cursor with an animated custom cursor |

Each trigger has its own configuration options — see the dedicated pages: [Scroll Trigger](/docs/sdk/scroll-trigger), [Hover](/docs/sdk/hover), [Click](/docs/sdk/click), [Mouse Movement](/docs/sdk/mouse-movement), [Page Load](/docs/sdk/page-load), [Page Exit](/docs/sdk/page-exit), [Observer Gesture](/docs/sdk/observer-gesture), [Custom Cursor](/docs/sdk/custom-cursor).

---

## Appending Warning

Calling `Motion(name, target, config)` when `name` already exists in the registry **appends** new entries to that timeline — it does **not** replace it. This is intentional for multi-step sequences built across multiple calls, but it will surprise you if you're trying to rebuild a timeline in response to a state change.

Call `.kill()` first to destroy the existing instance before recreating it:

<CodeBlock
  filename="rebuild.ts"
  lang="typescript"
  code={`// ❌ Wrong — appends a second animation to the existing "hero" timeline
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();

// ✅ Correct — kill first, then rebuild from scratch
Motion("hero").kill();
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();`}
/>

`Motion.killAll()` destroys every registered timeline at once — useful for full teardown before reinitialising (e.g. on SPA navigation).

---

## Timeline Editor

> Visual timeline — nodes, duration, sequencing, drag-to-resize, and playhead controls.

URL: https://motion.page/docs/builder/timeline-editor

The Timeline Editor is the horizontal panel at the bottom of the builder workspace. It gives you a visual representation of your animation sequence — every animated target appears as a **node** on a time axis you can drag, resize, and rearrange.

{/* Screenshot: Full Timeline Editor panel showing multiple nodes at different positions and rows, the ruler with second markers, playback controls, and the playhead */}
![Timeline Editor overview](/images/builder/timeline-editor-overview.webp)

## Nodes

Each **node** represents one animated target — a CSS selector and the animation properties assigned to it. The node's horizontal position sets when the animation starts; its width sets how long it runs.

The node label shows the CSS selector (e.g. `.hero`, `.card, .title`). If no selector has been assigned yet, it reads **"Missing Selector"** as a reminder to wire it up.

Nodes communicate state through their appearance:

| State | Visual |
|-------|--------|
| **Active** — the node currently open in the Left Panel | Highlighted outline |
| **Selected** — part of a multi-select group | Blue outline |
| **Collision** — overlapping another node in the same row | Red "Collision!" warning |
| **Hidden** — the row's visibility is off | Reduced opacity |

Two small icons can appear inside a node:

- **Grid icon** — a stagger with `each` or `amount` is configured
- **Repeat icon** — a `repeat.times` value is set

Click a node to make it active and open its properties in the Left Panel.

## Duration — drag to resize

Drag the **left or right edge** of a node to change its duration. The resize handle is 20px wide, centered on the edge. As you drag, a **duration tooltip** appears above (or below) the node showing the current duration — for example `1.5s`.

Nodes snap to **0.1 second increments** while resizing, so you always land on a clean value. Resizing from the left edge also shifts the node's start position to keep the right edge anchored.

{/* Screenshot: Node being dragged from its right edge with the duration tooltip showing "1.5s" */}
![Resizing a node — duration tooltip shows current length](/images/builder/timeline-editor-resize-duration.webp)

The default node width is **1 second**. Internally, 250 px = 1 second, so `duration = width / 250`.

This maps directly to the `duration` parameter in the SDK:

```typescript
Motion("hero-reveal", ".hero", {
  from: { opacity: 0, y: 40 },
  duration: 1.5,   // ← matches what you set by resizing the node
}).onPageLoad();
```

## Position — drag to move

Drag a node **left or right** to shift its start time. The same 0.1 second snap grid applies. Drag a node **vertically** to move it to a different row — useful for grouping animations or controlling render order.

**Collision detection** prevents nodes from overlapping in the same row. If you drop a node onto another, it shows a red "Collision!" warning and snaps back to the last safe position.

This corresponds to the `position` parameter in the SDK:

```typescript
Motion("stagger-cards", ".card", {
  from: { opacity: 0 },
  duration: 0.6,
  position: 0.3,   // ← start 0.3 s into the timeline, set by dragging the node
}).onPageLoad();
```

## Adding nodes

Click the **+** button in the timeline top bar ("Add an animation node") to add a new node at the beginning of the timeline, then drag it into place.

**Click-to-place mode** (enabled by default) is a faster alternative: a ghost node follows your cursor across empty timeline space, showing a plus icon and "Click to place" text. The ghost snaps to the 0.1 s grid and is collision-aware — it won't appear on occupied positions. Click to create a node at that exact spot.

Toggle click-to-place on or off with the grid-cursor button in the top bar ("Toggle click-to-place nodes on timeline"). The setting is saved to `localStorage` across sessions.

## Deleting and duplicating nodes

**Right-click** a node to open the context menu:

| Action | Description |
|--------|-------------|
| **Delete Animation** | Removes the node from the timeline |
| **Duplicate** | Creates an identical copy directly after the original |

When multiple nodes are selected, both actions apply to **all selected nodes** at once. After a delete, the selection clears and the first remaining node becomes active.

## Playhead and playback controls

The **playhead** is the red vertical line that marks the current playback position. Drag it left or right to scrub through the animation. Click anywhere on the **ruler** — the seconds axis along the top of the timeline — to jump the playhead to that moment.

{/* Screenshot: Playhead during playback with the time display visible showing "0.8s / 2.0s" and the progress bar underneath the Play button */}
![Playhead during playback with time display](/images/builder/timeline-editor-playhead.webp)

The ruler labels each column with its time in seconds: `0s`, `1s`, `2s`, and so on.

### Playback buttons

The top bar contains the full set of playback controls:

| Button | Tooltip | Action |
|--------|---------|--------|
| **Loop** toggle | "Preview in a loop" | When on, the animation restarts at the end |
| **⏮** | "Jump to start" | Seeks to 0 s |
| **▶ / ⏸** | "Play / Pause" | Starts or pauses playback |
| **⏭** | "Jump to end" | Seeks to the last frame |

The Play / Pause button also shows a **time display** — `{current}s / {total}s` — with a thin progress bar running along its bottom edge. When the timeline contains an infinitely repeating animation, the total shows `∞` instead of a number.

### Live mode

The **Live** button (with a dot indicator) plays the animation on the actual page using the real trigger — scroll position, click, or hover — instead of the builder's internal playback engine. Enable Live mode when you need to see exactly how a scroll-linked or interaction animation will feel in context.

> "If enabled, animations are executed live on the page for preview of a trigger (scroll, click, hover)." Live mode is disabled automatically for Page Events triggers.

## Zoom

Use the **Zoom In** (`+`) and **Zoom Out** (`−`) buttons in the top bar to adjust the timeline scale:

| Setting | Value |
|---------|-------|
| Default zoom | `1×` — 250 px = 1 second |
| Minimum | `0.2×` (Zoom Out disabled at this level) |
| Maximum | `3.4×` (Zoom In disabled at this level) |
| Step per click | `0.2` |

Hold the button down for long-press — it repeats every 200 ms so you can sweep across the full range quickly. The zoom level is saved to `localStorage` and restored when you reopen the builder.

Zoom affects the visual width of every node, the drag and resize snap grids, the ruler column labels, and the playhead's pixel position. The underlying `position` and `duration` values in seconds are not changed.

## Multi-select

Select multiple nodes to move or delete them together:

- **Click** a node — selects it and deselects all others
- **Ctrl + Click** (or **Cmd + Click** on Mac) — adds or removes a node from the selection without deselecting others

When you drag one node in a multi-select group, **all selected nodes move together** by the same delta. Collision detection runs per-node during the drag — nodes that would collide revert to their last safe position while the rest keep their new positions.

Right-click context menu actions (Delete, Duplicate) apply to all selected nodes when multi-select is active.

## Row visibility

An **eye icon** appears on the left edge of each row. Click it to show or hide all nodes on that row during preview:

- **Eye open** — row is visible, animations play normally
- **Eye closed** — row is hidden, all nodes appear at reduced opacity and their CSS animations are cleared from the page

Hiding a row calls `clearProps` on every animated selector in that row, resetting the elements to their natural CSS state. The visibility state is stored per-node and round-trips through save/load.

## Timeline length

The timeline defaults to **10 seconds**. Click the **"Max N s"** button in the top bar to extend it:

| Click | Timeline length |
|-------|----------------|
| 1st | 20 s |
| 2nd | 30 s |
| … | … |
| 6th | 70 s (maximum) |
| 7th | Wraps back to 10 s |

The button label always reflects the current maximum — `Max 10 s`, `Max 20 s`, etc.

## Undo and redo

| Action | Shortcut |
|--------|----------|
| Undo | **Cmd+Z** / **Ctrl+Z** |
| Redo | **Cmd+Shift+Z** / **Ctrl+Shift+Z** |
| Clear all history | Button in the top bar ("Clear all undo/redo history") |

## Timeline management

The top bar also contains controls for managing the timeline itself:

| Control | Tooltip | Description |
|---------|---------|-------------|
| Name field | "Rename the timeline." | Click to rename — used as the timeline identifier in the SDK |
| **Global** toggle | "If enabled, the timeline will load on all pages." | When on, the timeline runs everywhere rather than only on the page it was created on |
| **New** button | "Create a new timeline" | Adds a fresh, empty timeline |
| **Duplicate** button | "Duplicate timeline" | Creates an exact copy of the current timeline |

---

Related: [Duration & Delay](/docs/sdk/duration-delay) · [Sequencing](/docs/sdk/sequencing) · [Timeline Control](/docs/sdk/timeline-control) · [Stagger](/docs/sdk/stagger) · [Repeat & Yoyo](/docs/sdk/repeat-yoyo)

---

## Fit Animation

> Morph one element's position and size to match another element on the page.

URL: https://motion.page/docs/builder/fit

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Fit** animates a source element's position and size so it morphs to match a target element anywhere on the page — a declarative layout transition powered by the SDK's Fit engine. Use it for expanding cards, tab indicators, thumbnail-to-lightbox reveals, and any animation where one element needs to travel toward another's geometry.

## Location

**Left Panel → Animation tab → Functional Properties → Fit**

Fit is a **functional property** — it is direction-agnostic and lives in the `FUNCTIONAL_MAPPING_FT` and `ROOT_LEVEL_FUNCTIONAL` sections of the animation config. The internal data key is `fit`. Enabling it on any tab (**From**, **To**, or **Set**) applies it globally to the animation node.


## Enable Fit

Click the toggle next to **Fit** to enable it. The row expands to reveal the **Target Selector**, **Ease**, **Absolute**, and **Scale** controls. The source element is the one selected in the canvas; the target element is whatever you point the selector at.

{/* Screenshot: Fit row fully expanded, showing the Target Selector text input, Ease dropdown, Absolute toggle, and Scale toggle */}
![Fit controls expanded — target selector, ease, and option toggles](/images/builder/fit-controls-expanded.webp)

## Controls

| Control | Type | Default | Description |
|---------|------|---------|-------------|
| **Target Selector** | Text input | _(empty)_ | CSS selector for the target element whose position and size the source element will animate toward. Accepts any valid selector: `#id`, `.class`, `[data-attr]`. |
| **Ease** | Dropdown | _(inherit)_ | Controls the acceleration and deceleration of the Fit animation. Overrides the node's global ease for the Fit transition specifically. |
| **Absolute** | Toggle | Off | Switches the element to `position: absolute` during the animation. Prevents layout shifts and improves GPU-compositing performance on large reflows. |
| **Scale** | Toggle | On | Includes scale transformations in the Fit animation. Disable this for **position-only** animations where you want the element to move but keep its original dimensions. |

> **Target Selector tip:** The selector is evaluated at animation time with `document.querySelector`. Use the most specific selector possible to avoid ambiguity. If the target doesn't exist on the page at animation time, the Fit step is skipped.

## How it works

When a Fit animation plays, Motion.page captures the **source element's current geometry** (position and size) and the **target element's geometry** using the SDK's Fit engine. It then animates the source from its natural state toward the target's bounding rectangle — moving it across the page and resizing it simultaneously in a single, GPU-friendly tween.

The key difference from a standard [Translate](/docs/builder/translate) + [Scale](/docs/builder/scale) combo is that Fit **measures real DOM positions at runtime**. You don't hard-code pixel values — it calculates everything from the actual layout, so it adapts to different screen sizes and dynamic content automatically.

**What gets animated:**
- `x` / `y` position delta between source and target
- Width and height (as scale transforms by default)

**Under the hood:** The SDK's Fit utility is used to calculate and apply the transform. The element is briefly captured in its natural state, the transform is computed, and then the SDK animates it to the target geometry over the animation's duration.

Typical use cases:
- **Expanding card → full-screen overlay** — a card grows and repositions to fill the viewport
- **Tab indicator** — a highlight pill slides and resizes between tab labels
- **Image gallery** — a thumbnail morphs into a full-size lightbox image

<LivePreview client:load
  height={280}
  title="Box morphing from thumbnail to hero"
  html={`<div class="scene">
  <div class="track">
    <div class="thumb" id="source">
      <span>Card</span>
    </div>
    <div class="hero" id="target">
      <span>Hero</span>
    </div>
  </div>
  <button class="btn" id="toggle">Fit → Target</button>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 28px; height: 100%; background: #0d0d0d; font-family: system-ui; }
.track { display: flex; align-items: center; gap: 32px; }
.thumb { width: 80px; height: 80px; border-radius: 10px; background: #6633EE; display: flex; align-items: center; justify-content: center; color: #fff; font-size: 12px; font-weight: 600; }
.hero { width: 200px; height: 130px; border-radius: 14px; background: #2a1a5e; border: 2px dashed #6633EE; display: flex; align-items: center; justify-content: center; color: #6633EE; font-size: 13px; font-weight: 600; }
.btn { padding: 7px 22px; border: none; border-radius: 7px; background: #6633EE; color: #fff; cursor: pointer; font-size: 13px; font-weight: 500; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("card-fit", "#source", {
  fit: {
    target: "#target",
    scale: true,
  },
  duration: 0.55,
  ease: "power3.inOut",
}).onClick({ target: "#toggle", toggle: "reverse" });`}
/>

The purple **Card** box morphs in position and size toward the dashed **Hero** area. This mirrors how Fit works in the builder — the source element animates toward the target's bounding rectangle at runtime.

## Common patterns

### Expanding card to full-screen overlay

Select the card element. Enable **Fit**, set **Target Selector** to `#overlay` (or any full-screen container). Enable **Absolute** to pull the card out of flow during the animation. Set **Scale** on. Combine with [Opacity](/docs/builder/opacity) on a **To** tab to reveal the overlay content as the card expands.

```typescript
import { Motion } from '@motion.page/sdk';

Motion('card-expand', '.card', {
  fit: {
    target: '#overlay',
    absolute: true,
    scale: true,
  },
  duration: 0.6,
  ease: 'power3.inOut',
}).onClick();
```

### Tab indicator sliding between tabs

Select the indicator `<span>`. Enable **Fit**, point **Target Selector** at the active tab's `[data-tab].active` element. Disable **Scale** so the indicator keeps its original height — only position animates. Use a short duration (`0.3 s`) with `power2.out`.

```typescript
Motion('tab-indicator', '.tab-indicator', {
  fit: {
    target: '[data-tab].active',
    scale: false,
    absolute: false,
  },
  duration: 0.3,
  ease: 'power2.out',
}).onClick();
```

### Image gallery — thumbnail to lightbox

Select the thumbnail `<img>`. Enable **Fit**, set **Target Selector** to `#lightbox-image`. Enable **Absolute** and **Scale**. This produces the thumbnail flying across and growing into the lightbox frame before the full image loads.

```typescript
Motion('thumb-to-lightbox', '.gallery-thumb', {
  fit: {
    target: '#lightbox-image',
    absolute: true,
    scale: true,
  },
  duration: 0.55,
  ease: 'expo.inOut',
}).onClick();
```

## SDK equivalent

In the SDK, Fit is configured via the `fit` object on any animation node. All builder toggles map directly to properties.

```typescript
import { Motion } from '@motion.page/sdk';

// Full Fit config
Motion('hero-fit', '.source-card', {
  fit: {
    target: '#target-hero',   // CSS selector
    absolute: true,            // position:absolute during tween
    scale: true,               // include scale transforms
  },
  ease: 'power3.inOut',
  duration: 0.65,
}).onPageLoad();
```

For the full SDK reference, see [Fit Animation in the SDK](/docs/sdk/fit-animation).

## Tips

- **Use Absolute for reflow-heavy layouts.** If the source element participates in flexbox or grid, `position: absolute` during the tween prevents sibling elements from jumping around while the animation plays.
- **Scale off = position only.** If your source and target are the same size (e.g. a tab indicator), disable **Scale** so the SDK doesn't try to apply dimension transforms that would distort the element.
- **Target must exist at playback time.** If the target element is conditionally rendered (e.g. inside a hidden modal), make sure it's in the DOM before the animation fires. Use a Click or Hover trigger on the element that reveals it, then chain the Fit animation after.
- **Test at multiple breakpoints.** Fit measures live DOM positions — make sure the target element exists and is visible at every breakpoint where the animation can fire.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How functional properties apply across animation mode tabs
- [Translate](/docs/builder/translate) — Animating position without a target element
- [Scale](/docs/builder/scale) — Animating dimensions independently
- [Easing](/docs/builder/easing) — All available ease curves for Fit and other properties
- [Click Trigger](/docs/builder/click-trigger) — Common trigger for Fit-based interactions

---

## Animation Presets

> Browse, preview, and apply built-in animation presets.

URL: https://motion.page/docs/builder/animation-presets

**Animation Presets** are ready-made animation configurations. Pick one and it instantly populates the From, To, duration, and ease fields on your animation node — ready to play or tweak.

## Location

**Left Panel → Presets button** (the wand icon in the Animation tab toolbar)

Click the button to open the Presets panel. The panel lists all built-in presets grouped by category.

{/* Screenshot: Left Panel with the Presets panel open, showing category groups and individual preset entries with preview thumbnails */}
![Animation Presets panel in the Left Panel](/images/builder/animation-presets-panel.webp)

## How to use presets

### Preview

**Hover** over any preset name to preview the animation live on the selected element in the builder canvas.

### Apply

**Click** a preset to apply it. The builder immediately writes the corresponding From/To values, duration, and ease into the current animation node.

### Override

Every value the preset writes is fully editable. After applying, adjust any property — opacity, distance, duration, ease — to fit your design. Presets are a starting point, not a lock-in.

There is also a **random preset** button (dice icon in the toolbar) that applies a random preset from the full list.

## Categories

Presets are grouped into five categories.

### Entrances

Entrance presets animate an element **from** a hidden or offset state into its natural position. All 16 presets write From values.

| Preset | What it does |
|--------|-------------|
| **Fade In** | Fades in from `opacity: 0` |
| **Blur In** | Fades in from `opacity: 0` with a `blur(10px)` filter |
| **Fade Up** | Slides up 100 px while fading in |
| **Fade Down** | Slides down 100 px while fading in |
| **Fade Left** | Slides in from 100 px to the right while fading in |
| **Fade Right** | Slides in from 100 px to the left while fading in |
| **Scale In** | Scales up from `scale: 0` |
| **Scale In Soft** | Scales up from `scale: 0.5` with fade |
| **Zoom In** | Zooms in from `scale: 0.3` with fade |
| **Zoom Out** | Zooms in from an oversized `scale: 1.3` with fade |
| **Flip In X** | Flips in on the X axis (rotateX 90°) with fade |
| **Flip In Y** | Flips in on the Y axis (rotateY 90°) with fade |
| **Rise & Fade** | Rises 80 px from a slightly scaled-down state |
| **Skew Slide** | Slides in from the left with a 15° skew and fade |
| **Spiral In** | Scales up from zero while spinning 180° with fade |
| **Corner Pop** | Scales up from the top-left corner with a -90° rotation |

### Loops

Loop presets write **To** values and set repeat to `-1` (infinite) with yoyo. Apply them to any element that should animate continuously.

| Preset | What it does |
|--------|-------------|
| **Pulse** | Scales up to `1.1` and back, infinitely |
| **Shake X** | Shakes 10 px on the X axis |
| **Shake Y** | Shakes 10 px on the Y axis |
| **Wiggle** | Rotates 5° back and forth |
| **Bounce** | Bounces up 20 px with a `bounce.out` ease |
| **Rubber Band** | Stretches horizontally (`scaleX: 1.3`) and squishes vertically (`scaleY: 0.8`) |
| **Swing** | Rotates 15° from the top center — like a hanging sign |
| **Pendulum** | Rotates 20° from the top center with a slower, heavier cadence |
| **Flash** | Pulses opacity to `0.3` and back |
| **Strobe** | Flickers opacity to `0` and back rapidly |
| **Flip Back** | Continuously spins on the Y axis (360°) |

### Text Reveals

Text Reveal presets split the element's text into words, characters, or lines using Text Splitter, then animate each piece in with a stagger. All presets write From values.

**Words presets** — animate word by word:

| Preset | What it does |
|--------|-------------|
| **Words Fade In** | Fades in each word with stagger 0.08s |
| **Words Slide Up** | Each word slides up 20 px while fading in |
| **Words Slide Down** | Each word slides down 20 px while fading in |
| **Words From Left** | Each word arrives from -30 px on the X axis |
| **Words From Right** | Each word arrives from +30 px on the X axis |
| **Words From Center** | Words emerge from `scale: 0.5`, staggered from center outward |
| **Words From Edges** | Words fade in staggered from the edges inward |
| **Words Blur In** | Each word fades in through a `blur(10px)` filter |
| **Words Skew In** | Each word arrives with a 20° X skew while fading in |
| **Words Typewriter** | Words appear one by one, sliding in from -10 px on X |

**Chars presets** — animate character by character:

| Preset | What it does |
|--------|-------------|
| **Chars Fade In** | Each character fades in with stagger 0.03s |
| **Chars Cascade** | Each character drops in from 30 px above |
| **Chars Pop In** | Each character scales up from `scale: 0` |
| **Chars Rotate In** | Each character rotates in from 90° while fading |
| **Chars Random** | Characters rise 20 px and fade in, staggered randomly |
| **Chars 3D Flip** | Each character flips in on the X axis (rotateX 90°) |
| **Chars Wave** | Characters descend from -20 px, creating a wave effect |
| **Typewriter** | Characters appear one by one, fading in with stagger 0.05s |

**Lines presets** — animate line by line:

| Preset | What it does |
|--------|-------------|
| **Lines Rise** | Each line rises 40 px while fading in, stagger 0.2s |
| **Lines Fade** | Each line fades in sequentially, stagger 0.15s |

### Smooth Transitions

Subtle, polished entrance effects suitable for UI elements, cards, and section reveals. All write From values with soft distances and gentle opacity values.

| Preset | What it does |
|--------|-------------|
| **Gentle Fade** | Fades in from `opacity: 0.3` — barely there at the start |
| **Soft Slide Up** | Rises 20 px from `opacity: 0.5` |
| **Float In** | Floats up 15 px from `opacity: 0` |
| **Blur to Focus** | Fades in from `opacity: 0` with a `blur(5px)` filter |
| **Elegant Scale** | Scales up from `0.95` with fade — barely visible change |
| **Drift Right** | Drifts in from -20 px on X with fade |
| **Drift Left** | Drifts in from +20 px on X with fade |
| **Rise Subtle** | Rises 10 px from `opacity: 0` and `scale: 0.98` |
| **Drop Subtle** | Drops in from -10 px (above) with opacity and subtle scale |
| **Grow Subtle** | Scales up from `0.9` with fade |
| **Shrink In** | Scales down from `1.1` with fade |
| **Soft Blur Slide** | Rises 15 px from opacity 0 with a light `blur(3px)` |

### Creative Effects

More expressive presets with dramatic motion, often setting both From **and** To to create a complete transformation.

**From-only effects** — entrance animations:

| Preset | What it does |
|--------|-------------|
| **Spiral In** | Scales up from zero while spinning 180° |
| **Twist In** | Scales up from zero with a full 360° spin |
| **Bounce In** | Scales up from `scale: 0` (pair with a `bounce` ease) |
| **Squeeze In** | Reveals horizontally — `scaleX` starts at `0`, `scaleY` stays at `1` |
| **Morph In** | Scales from `0.5` with a 20° X skew and fade |

**To-only effects** — exit animations:

| Preset | What it does |
|--------|-------------|
| **Spiral Out** | Scales to zero while spinning -180° |
| **Squeeze Out** | Collapses vertically — `scaleY` animates to `0` |

**From + To effects** — both endpoints are explicit:

| Preset | What it does |
|--------|-------------|
| **Slide Through** | Enters from -100 px and exits to +100 px on X |
| **Zoom Through** | Starts at `scale: 0` and ends at `scale: 2` |
| **Flip Full** | Full Y-axis flip — enters at -90° rotateY, exits at +90° |
| **Rotate Through** | Rotates from -180° to +180° |
| **Color Shift** | Background color transitions from red (`#ff0000`) to blue (`#0000ff`) |
| **Skew Transform** | Skews from -30° to +30° while sliding across X |
| **Scale Bounce** | Scales from `0` to `1.2` with a yoyo repeat — a subtle overshoot |
| **Perspective Spin** | Y-axis spin from 180° to 360° while scaling from `0.5` to `1` |

## Modifying preset values

After applying a preset, every written property is available in the normal animation controls. Use the From, To, and timing sections to adjust:

- **From/To values** — change distances, opacity levels, rotation angles
- **Duration** — set in the Timeline Editor or the timing input
- **Ease** — change via the Ease selector in the Left Panel
- **Stagger** — fine-tune `each` delay and `from` direction for text presets

Nothing is locked. Presets just save you the initial setup work.

## SDK equivalent

The same preset configurations are available in the SDK via the `presets` option. See the [SDK Animation Presets](/docs/sdk/animation-presets) reference for the full list and code examples.

## Related

- [From, To & Set](/docs/builder/from-to-set) — understand how From and To work
- [Stagger](/docs/builder/stagger) — fine-tune text and multi-element stagger timing
- [Ease](/docs/builder/easing) — change acceleration curves after applying a preset
- [SDK Animation Presets](/docs/sdk/animation-presets) — use the same presets in code

---

## Translate

> Move elements with the translate controls — X, Y, units.

URL: https://motion.page/docs/builder/translate

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Translate** moves an element along the X and Y axes (and optionally Z). It is the primary tool for slide-in entrances, hover lifts, parallax offsets, and any animation that repositions an element without affecting document flow.

## Where to find it

**Left Panel → Animation tab → Translate**

Enable the **Translate** toggle to expand the controls. The section shows three numeric inputs — X, Y, and Z — each with an independent unit selector.

{/* Screenshot: Translate section expanded in the Left Panel Animation tab, showing X, Y, and Z inputs with unit selectors set to %, %, and px respectively */}
![Translate controls — X, Y, Z inputs with unit selectors](/images/builder/translate-controls.webp)

## Controls

| Control | Description |
|---------|-------------|
| **X** | Horizontal movement. Positive = right, negative = left. |
| **Y** | Vertical movement. Positive = down, negative = up. |
| **Z** | Depth movement on the Z-axis. Requires a 3D transform context. |
| **Unit selector** | Click the unit label to cycle through available units. |

Each axis has its own unit selector. Clicking the unit label cycles through the available options:

| Unit | Description |
|------|-------------|
| `%` | Percentage of the element's own size (default) |
| `px` | Absolute pixels |
| `em` | Relative to the element's font size |
| `rem` | Relative to the root font size |
| `vw` | Percentage of viewport width |
| `vh` | Percentage of viewport height |
| `vmin` | Percentage of the smaller viewport dimension |
| `vmax` | Percentage of the larger viewport dimension |

The slider range is −500 to 500. Type directly into the input for values outside that range.

## From mode — entrance animations

In **From** mode, the values you set are the **starting position**. The element animates from that offset toward its natural CSS position.

Set `y` to `60` in From to make an element slide up from 60 pixels below its resting place. Set `x` to `-100%` to slide in from the left.

{/* Screenshot: Translate section in From mode with Y set to 60 and unit set to px — classic slide-up entrance */}
![Translate in From mode — Y set to 60px for a slide-up entrance](/images/builder/translate-from-y60.webp)

## To mode — exit and hover effects

In **To** mode, the values you set are the **ending position**. The element animates from its natural CSS position toward the offset you specify.

Set `y` to `-10` in To for a hover lift effect — the element moves up 10 units when the animation plays. Combine with a Hover trigger and **Reverse on leave** to create a smooth hover interaction.

{/* Screenshot: Translate section in To mode with Y set to -10 and unit set to px — hover lift setup */}
![Translate in To mode — Y set to -10px for a hover lift](/images/builder/translate-to-y-minus10.webp)

<LivePreview client:load
  height={220}
  title="Slide-up entrance"
  html={`<div class="card">
  <div class="card-title">Motion.page</div>
  <div class="card-sub">Slide-up entrance</div>
</div>`}
  css={`.card {
  background: #13103a;
  border: 1px solid #2d2870;
  border-radius: 12px;
  padding: 24px 36px;
  text-align: center;
}
.card-title {
  font-size: 18px;
  font-weight: 700;
  color: #fff;
  margin-bottom: 4px;
}
.card-sub {
  font-size: 13px;
  color: #8880cc;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("slide-up", ".card", {
  from: { opacity: 0, y: 48 },
  duration: 0.65,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

This effect uses `from: { opacity: 0, y: 48 }` — the card starts transparent and 48 px below its resting position, then animates to its natural state.

## SDK equivalent

Translate maps directly to the `x`, `y`, and `z` properties in the SDK config. Units are appended as a string suffix.

```typescript
import { Motion } from '@motion.page/sdk';

// Slide up from below (From mode)
Motion('hero-reveal', '.hero-card', {
  from: { opacity: 0, y: 48 },
  duration: 0.65,
  ease: 'power3.out',
}).onPageLoad();

// Hover lift (To mode)
Motion('card-hover', '.card', {
  to: { y: -10 },
  duration: 0.3,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });

// Percentage units — slide in from the left
Motion('slide-left', '.panel', {
  from: { x: '-100%' },
  duration: 0.5,
  ease: 'power2.out',
}).onPageLoad();

// Viewport units — parallax strip
Motion('parallax', '.bg-image', {
  from: { y: '-10vh' },
  to:   { y: '10vh' },
  duration: 1,
}).onScroll({ scrub: true });
```

When using a non-`px` unit, pass the value as a string with the unit appended: `'-100%'`, `'10vw'`, `'2rem'`.

## Common patterns

### Slide in from the bottom
```typescript
from: { y: 60 }   // element starts 60 px below, slides up to natural position
```

### Slide in from the left
```typescript
from: { x: '-100%' }   // starts fully off-screen to the left
```

### Horizontal slide
```typescript
from: { x: -40, opacity: 0 }   // slide in from the left while fading in
```

### Hover lift
```typescript
to: { y: -8 }   // pair with Hover trigger + Reverse on leave
```

### Parallax offset
```typescript
from: { y: -40 },
to:   { y: 40 }    // scrub with scroll — element travels 80 px as page scrolls
```

### Staggered list reveal
Enable **Stagger** alongside Translate in From mode. Each list item slides up in sequence rather than all at once.

## Tips

- **Double-click** a slider to reset the value to empty.
- **Positive Y = down**, negative Y = up. This matches CSS transform convention, not mathematical Y-axis convention.
- The `%` unit is relative to the **element's own dimensions**, not the parent. `x: 100%` moves the element exactly one element-width to the right.
- Translate does not affect document flow — surrounding elements stay in place regardless of where the animated element is moved.
- Combine Translate with [Opacity](/docs/builder/opacity) for the most common entrance pattern: `from: { opacity: 0, y: 40 }`.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three modes work and when to use each
- [Opacity](/docs/builder/opacity) — Fade in/out, often combined with Translate
- [Scale](/docs/builder/scale) — Grow or shrink elements
- [Transform Origin](/docs/builder/transform-origin) — Change the anchor point for transforms
- [Stagger](/docs/builder/stagger) — Sequence multiple translated elements
- [Ease](/docs/builder/easing) — Control the motion curve

---

## Breakpoint Sizes

> Set the pixel thresholds that define each device tier across the builder.

URL: https://motion.page/docs/builder/breakpoints

Motion.page uses three named breakpoints — **phones**, **tablets**, and **laptops** — to define the four device tiers (phone, tablet, laptop, desktop). These thresholds drive the device preview in the builder and the device variants on your published site.

> **Editing per device?** This page only covers the pixel sizes. To tune a timeline differently on each device, see [Responsive Editing](/docs/builder/responsive-editing).

---

## Location

**Settings panel → Breakpoints**

Open the Settings panel (gear icon in the top-right toolbar). The **Breakpoints** section shows three pixel inputs, one for each device tier.

{/* Screenshot: Breakpoints section in the Settings panel showing pixel inputs for phones, tablets, and laptops */}
![Breakpoints settings — pixel inputs for phones, tablets, and laptops](/images/builder/breakpoints-settings.webp)

---

## Defaults

| Device | Key | Default (max-width) |
|--------|-----|---------------------|
| **Phones** | `phones` | `576 px` |
| **Tablets** | `tablets` | `768 px` |
| **Laptops** | `laptops` | `992 px` |

All values use a `max-width` query. A viewport narrower than or equal to a value falls into that tier or smaller; anything wider than **laptops** is treated as desktop. The four resulting tiers are strictly non-overlapping, so exactly one applies at any width:

| Tier | Range |
|------|-------|
| **Desktop** | wider than `laptops` |
| **Laptop** | `tablets + 1` up to `laptops` |
| **Tablet** | `phones + 1` up to `tablets` |
| **Phone** | up to `phones` |

---

## Changing the values

Click any input and type a new pixel value, or scroll the mouse wheel over the input to increment or decrement by 1. Changes take effect after a short debounce and are saved as part of the global site options — they apply to **all timelines** and to the device preview.

> **Tip:** Match your theme's grid system — Bootstrap uses 576 / 768 / 992, Tailwind uses 640 / 768 / 1024.

---

## Device preview

The pixel values power the device preview buttons in the **Top Panel**. Clicking a device icon resizes the Frame View to the corresponding width:

| Button | Frame width |
|--------|-------------|
| **Mobile** (phone icon) | `phones` px |
| **Tablet** (tablet icon) | `tablets` px |
| **Laptop** (laptop icon) | `laptops` px |
| **Desktop** (monitor icon) | Full width |

Updating a breakpoint value immediately updates these preview widths, so you always preview at the exact sizes your theme uses.

---

## Related

- [Responsive Editing](/docs/builder/responsive-editing) — Edit a timeline per device using these tiers
- [Breakpoints in the SDK](/docs/sdk/breakpoints) — The same thresholds in SDK code
- [Top Panel](/docs/builder/top-panel) — Device preview controls

---

## Repeat & Yoyo

> Loop animations with repeat count, infinite looping, and yoyo.

URL: https://motion.page/docs/builder/repeat

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Repeat** loops an animation a set number of times — or forever. **Yoyo** makes the animation reverse on each cycle, creating a back-and-forth effect. Both are available at the individual node level and at the timeline level.

> Repeat in a loop or any number of repetitions. Use -1 as a repeat value for infinite loop.

## Location

**Node-level:** Left Panel → Animation tab → Functional Properties → Repeat

**Timeline-level:** Left Panel → Trigger Section → Advanced Options → Loop

Repeat is a **functional property** — it is direction-agnostic. The same value applies whether the **From**, **To**, or **Set** tab is active.


## Enable Repeat

Click the toggle next to **Repeat** to enable it. The row expands to reveal the repeat count input, delay input, and the Yoyo toggle.

{/* Screenshot: Repeat row fully expanded, showing the Repeat count input, Delay input, and Yoyo toggle */}
![Repeat controls expanded — count input, delay input, and Yoyo toggle](/images/builder/repeat-controls-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Repeat count** | Number of additional times the animation plays. Use `-1` for an infinite loop. Use `2` to play 3 times total (initial play + 2 repeats). |
| **Delay** | Pause in seconds between each repeat cycle. |
| **Yoyo** | Toggle that causes the animation to reverse direction on each repeat cycle — playing forward, then backward, then forward, and so on. |

## Node-level vs Timeline-level

There are two places to configure repeat in the builder, and they affect different scopes of the animation:

### Node-level repeat

Set on an individual animation node via **Functional Properties → Repeat**. Only that node's animation loops within the timeline. Other nodes continue playing normally. The timeline itself finishes after all nodes have completed their loops.

Use this when you want one element to pulse or bounce while the rest of the page enters once.

### Timeline-level repeat

Found in **Left Panel → Trigger Section → Advanced Options → Loop** (the toggle labelled with tooltip: "Apply repeat to the entire timeline").

When enabled, the **entire timeline** repeats after all nodes have finished playing — every animation in the sequence restarts together. This is the right choice when you want a complete animation sequence to loop as a unit.


The timeline-level repeat exposes the same three controls: repeat count, delay between cycles, and Yoyo.

## Yoyo

**Yoyo** reverses the animation on each repeat cycle. Instead of snapping back to the start position and replaying forward, the element smoothly animates back to where it started — then forward again — alternating on every cycle.

- **Yoyo off:** forward → reset → forward → reset → …
- **Yoyo on:** forward → backward → forward → backward → …

Yoyo is ideal for looping effects that need to look continuous, like a pulsing button, a bouncing icon, or a breathing glow. Without yoyo, the reset between cycles is a hard jump that often looks unpolished.

<LivePreview client:load
  height={220}
  title="Repeat with Yoyo"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #0d0d0d; }
.box { width: 64px; height: 64px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("yoyo", ".box", {
  to: { x: 100 },
  duration: 0.7,
  ease: "sine.inOut",
  repeat: { times: -1, yoyo: true },
}).play();`}
/>

The box moves right then smoothly reverses back — this is the **Yoyo** effect with an infinite repeat (`-1`). In the builder: **Repeat count: -1**, **Yoyo: on**.

## SDK equivalent

Repeat and Yoyo map to the `repeat` property in the SDK config, which accepts a count number or an object with `times`, `yoyo`, and `delay`.

**Infinite loop (no yoyo):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('spinner', '.spinner', {
  to: { rotation: 360 },
  duration: 1,
  ease: 'none',
  repeat: -1,
}).onPageLoad();
```

**Finite repeat with Yoyo:**

```typescript
Motion('bounce', '.icon', {
  to: { y: -20 },
  duration: 0.5,
  ease: 'power2.inOut',
  repeat: { times: 3, yoyo: true },
}).onPageLoad();
```

**Infinite Yoyo with repeat delay:**

```typescript
Motion('pulse', '.cta-button', {
  to: { scale: 1.08 },
  duration: 0.8,
  ease: 'sine.inOut',
  repeat: { times: -1, yoyo: true, delay: 0.2 },
}).onPageLoad();
```

For the full SDK reference, see [Repeat & Yoyo in the SDK](/docs/sdk/repeat-yoyo).

## Common patterns

### Infinite pulse

Scale an element up and back down forever. Enable **Repeat** with count `-1` and **Yoyo** on. Add **Scale** on the **To** tab.

```typescript
Motion('pulse', '.badge', {
  to: { scale: 1.12 },
  duration: 0.9,
  ease: 'sine.inOut',
  repeat: { times: -1, yoyo: true },
}).onPageLoad();
```

### Bounce with Yoyo

Translate an element up and back down a fixed number of times. Set repeat count to `2` (plays 3 times total) and Yoyo on.

```typescript
Motion('bounce', '.arrow-icon', {
  to: { y: -12 },
  duration: 0.45,
  ease: 'power2.out',
  repeat: { times: 2, yoyo: true },
}).onPageLoad();
```

### Loading spinner

Rotate an element continuously. No yoyo — the rotation accumulates each cycle for a smooth spin.

```typescript
Motion('spinner', '.loading-icon', {
  to: { rotation: 360 },
  duration: 1,
  ease: 'none',
  repeat: -1,
}).onPageLoad();
```

## Tips

- **Use `-1` for infinite loops** — any other negative value is invalid. Zero means the animation plays exactly once (no repeat), which is the default.
- **Yoyo requires repeat.** Enabling Yoyo with repeat count `0` has no visible effect since there is no second cycle to reverse on.
- **Node-level repeat and timeline-level repeat stack differently** — a node set to repeat 2 times inside a timeline set to repeat 2 times will play the node 3 times on the first pass, then 3 times on the second pass (6 node plays total).
- **Add a repeat delay** to give breathing room between cycles — especially useful for infinite pulse animations that would otherwise feel relentless.
- **Avoid Yoyo with Set animations** — `Set` (instant-apply) nodes have zero duration, so yoyo produces no visible reversal effect. Use **From** or **To** instead.

## Related

- [Stagger](/docs/builder/stagger) — Add cascade delay between elements in multi-target animations
- [Ease](/docs/builder/easing) — Control the acceleration curve applied on each repeat cycle
- [From, To & Set](/docs/builder/from-to-set) — How functional properties relate to animation mode tabs
- [Repeat & Yoyo in the SDK](/docs/sdk/repeat-yoyo) — Full SDK reference for the `repeat` option

---

## Duration & Delay

> Control animation timing by setting duration and delay for animation nodes in the timeline.

URL: https://motion.page/docs/builder/duration-delay

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Duration** controls how long an animation takes to complete. **Delay** controls when it starts, relative to the timeline's origin. Both are set visually in the Timeline Editor and numerically in the Left Panel.

## Location

Both values are set visually in the **Timeline Editor**:

- **Width of a node** — represents its duration. Drag the right edge of a node to make it longer or shorter.
- **Horizontal position of a node** — represents its delay. Drag the node body left or right to offset it from the timeline start.

{/* Screenshot: Timeline Editor with an animation node selected — node width represents duration, horizontal offset represents delay */}
![Timeline Editor — node width controls duration, horizontal position controls delay](/images/builder/duration-delay-timeline.webp)

---

## Duration

Duration is the most direct lever on how an animation feels. A long duration feels deliberate and cinematic; a short one feels snappy and responsive.

Drag the right edge of any animation node in the Timeline Editor. The timeline ruler shows the current value in seconds as you drag.

### Practical duration guide

| Range | Best for |
|-------|----------|
| `0.1–0.3s` | Micro-interactions — button presses, tooltips, state changes |
| `0.3–0.5s` | Quick UI transitions — menu opens, tab switches |
| `0.5–0.8s` | Entrance animations — fades, slides, reveals on scroll |
| `0.8–1.5s` | Hero animations, staggered reveals, page transitions |
| `1.5s+` | Dramatic reveals, ambient loops, background motion |

If you don't set a duration, the animation uses the SDK default of **0.5 seconds**.

---

## Delay

Delay offsets when an animation starts relative to the beginning of the timeline. It is the primary tool for sequencing animations that don't overlap — animate heading in first, then subheading, then CTA.

Drag the node body horizontally in the Timeline Editor. Positioning it further right increases the delay.

### Notes on delay

- **Delay stacks with stagger** — if an animation has both a delay and a stagger, the delay fires first and then stagger offsets each child element from that point. See [Stagger](/docs/builder/stagger) for details.

---

Three boxes animate from the same starting state with different durations. The timing difference becomes obvious in motion.

<LivePreview client:load
  height={240}
  title="Duration comparison"
  html={`<div class="scene">
  <div class="row"><span class="label">0.3s</span><div class="box b1"></div></div>
  <div class="row"><span class="label">0.6s</span><div class="box b2"></div></div>
  <div class="row"><span class="label">1.2s</span><div class="box b3"></div></div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; gap: 14px; padding: 20px 24px; font-family: system-ui; background: #0f0f0f; height: 100%; box-sizing: border-box; }
.row { display: flex; align-items: center; gap: 14px; }
.label { font-size: 11px; color: #888; width: 36px; flex-shrink: 0; font-variant-numeric: tabular-nums; }
.box { width: 48px; height: 48px; border-radius: 10px; }
.b1 { background: #6633EE; }
.b2 { background: #9966FF; }
.b3 { background: #33CCFF; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("b1", ".b1", {
  from: { opacity: 0, y: 20 },
  duration: 0.3,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 1.2 },
}).play();

Motion("b2", ".b2", {
  from: { opacity: 0, y: 20 },
  duration: 0.6,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 1.2 },
}).play();

Motion("b3", ".b3", {
  from: { opacity: 0, y: 20 },
  duration: 1.2,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

All three boxes move the same distance — only the duration differs. The `0.3s` box snaps into place; the `1.2s` box drifts in slowly.

---

## SDK equivalent

Duration and delay map directly to top-level properties in the SDK.

<CodeBlock
  filename="Duration and delay in SDK"
  lang="typescript"
  code={`import { Motion } from '@motion.page/sdk';

Motion('example', '.box', {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  delay: 0.2,
  ease: 'power2.out',
}).onPageLoad();`}
/>

Both accept numbers in seconds. A `delay` of `0.2` means the animation waits 200 ms before it begins. If omitted, `duration` defaults to `0.5` and `delay` defaults to `0`.

For the full SDK reference, see [Duration & Delay in the SDK](/docs/sdk/duration-delay).

---

## Related

- [Easing](/docs/builder/easing) — Control acceleration and deceleration over the duration
- [Stagger](/docs/builder/stagger) — Cascade timing across multiple child elements
- [Repeat](/docs/builder/repeat) — Loop animations and control yoyo direction
- [Duration & Delay in the SDK](/docs/sdk/duration-delay) — Full SDK reference with all options

---

## WordPress Integration

> Admin menu, page selection, global timelines, authentication, and WordPress-specific settings.

URL: https://motion.page/docs/builder/wordpress-integration

import Steps from "../../components/docs/blocks/Steps.astro";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

Motion.page installs as a standard WordPress plugin and adds a full visual animation builder directly inside the WordPress admin — no external editor, no code required.

---

## Opening the Builder

### Admin menu

After activation, **Motion.page** appears in the WordPress admin sidebar. Click it to open the builder dashboard.

{/* Screenshot: WordPress admin showing Motion.page menu item and builder */}
![Motion.page in the WordPress admin](/images/builder/wordpress-integration-admin.webp)

The builder renders inside your WordPress admin shell at `wp-admin/?page=motionpage`.

### Edit with Motion.page

Every page and post row in the WordPress admin gets an **Edit with Motion.page** quick link — it opens the builder with that page already loaded in the frame. This link can be shown or hidden from [Global Settings → WordPress](#wordpress-settings).

---

## Authentication

Motion.page uses **email OTP authentication** — no API key or password.

<Steps>

1. Open the builder

   Navigate to **WP Admin → Motion.page**. If no session exists, the login screen appears.

2. Enter your email

   Type the email address associated with your Motion.page account and submit the form.

3. Enter the OTP code

   Check your inbox. Enter the one-time code sent to your email address.

4. Access granted

   Your session is stored in WordPress. The builder opens automatically. The session persists until you log out or the server clears it.

</Steps>

**Logging out** — click the user icon in the Top Panel and choose **Log out**. Your session is cleared from the WordPress database.

**No active plan** — if your account is authenticated but has no active plan, the builder shows a plan selection screen. Free-tier users can start with a demo project.

---

## Page Selection

Every timeline must be assigned to at least one destination before it runs on the frontend.

### Assign a page

**Left Panel → Timeline name → Page selector**

The dropdown at the top of the left panel lists all pages, posts, and custom post types registered in WordPress. Select a page to attach the current timeline to it.

The list groups entries by post type. The **Homepage** always appears first regardless of how your front page is configured.

Post types excluded via [Disabled Post Types](#builder-options) will not appear in this dropdown.

### Global timelines

**Left Panel → Timeline name → Global toggle**

Enable the **Global** toggle to load the timeline on every page of the site — no page assignment needed. Useful for site-wide effects like nav animations, cursor effects, or persistent scroll triggers.

| State | Behaviour |
|-------|-----------|
| **Off** (default) | Timeline runs only on the assigned page |
| **On** | Timeline runs on all pages of the site |

> **Tip:** Global timelines still respect breakpoint settings. Use them together to run site-wide animations only on desktop, for example.

### Advanced targeting

For cases where page-by-page selection isn't precise enough — post categories, custom taxonomies, or URL patterns — use **Advanced Targeting** in the Left Panel. It lets you target posts by type, category, or a custom regex matched against the URL.

→ [Advanced Targeting](/docs/sdk/advanced-targeting)

---

## Global Settings — WordPress

**Top Panel → Settings (gear icon) → Global Settings**

The Settings drawer contains several sections specific to WordPress. Sections not relevant to the current deployment target (WordPress vs. Desktop) are hidden automatically.

---

### WordPress settings

**Section: WordPress**

| Option | Description |
|--------|-------------|
| **Polylang sync** | Sync animation assignments across Polylang translation pages. Only visible when the Polylang plugin is active. |
| **WPML sync** | Sync animation assignments across WPML translation pages. Only visible when WPML is active. |
| **Edit link** | Show or hide the **Edit with Motion.page** quick action link in the WordPress pages and posts list. |
| **Wipe on uninstall** | When enabled, all Motion.page data — animations, database tables, and license — is permanently deleted when the plugin is uninstalled. **Irreversible.** |

> **Note:** **Wipe on uninstall** is off by default. Enable it only when you intend to fully remove Motion.page and all its data. There is no recovery after uninstallation with this option active.

---

### Site options

**Section: Site Options**

| Option | Description |
|--------|-------------|
| **Overflow X** | Adds `overflow-x: hidden` to the `<body>` element. Prevents horizontal scrollbars caused by elements that animate outside the viewport edge. |
| **Hash anchor links** | Enables smooth, gradual scroll-to-section navigation when a URL contains a `#hash` on page load. Linked to `location.hash` detection at runtime. |

---

### White Label

**Section: White Label**

Rename and rebrand the plugin for client-site deployments. Enable the **White Label** toggle to reveal all fields.

| Option | Description |
|--------|-------------|
| **Name** | Replace the plugin name shown in the WP admin. |
| **Description** | Replace the plugin description shown on the Plugins page. |
| **Author** | Replace the author name shown on the Plugins page. |
| **Icon** | Change the plugin icon. Accepts a Dashicon class (e.g. `dashicons-admin-site`), a base64-encoded SVG starting with `data:image/svg+xml;base64,`, or a direct image URL. |
| **Hide version** | Hide the Motion.page version number from the WordPress Plugins page. |
| **Hide from menu** | Remove Motion.page from the WordPress admin sidebar menu. |

> **Tip:** When **Hide from menu** is active, the builder is still accessible directly at `wp-admin/?page=motionpage`. Use **Client Mode** (below) for a more complete lockdown.

---

### Client Mode

**Section: Client Mode**

**Client Mode** hides Motion.page from the admin sidebar and clears the active session. The next person who accesses the plugin must re-authenticate with their email and OTP code before they can edit animations.

This is useful for handing off a site to a client: they can see the site running but cannot accidentally edit animations without credentials.

**To re-enable access:** Go to the WordPress Plugins page (`wp-admin/plugins.php`), find Motion.page, and use the activation link in the plugin row.

---

### Builder options

**Section: Builder Options**

| Option | Description |
|--------|-------------|
| **Tooltips** | Show or hide contextual tooltip hints throughout the builder UI. |
| **Theme** | Switch between dark and light builder themes. |
| **Beta updates** | Opt in to receive beta plugin updates directly from the WordPress Plugins page. |
| **Disabled Post Types** | Select post types to exclude from the page selector dropdown. Posts in excluded types will not appear as assignable destinations for timelines. |

---

## Frontend Script Delivery

Motion.page automatically injects animation scripts into pages that have active timelines. No manual `<script>` tags needed.

### How scripts load

When a visitor loads a page, WordPress checks which timelines are assigned to that page (or marked as global). If any are found and active, the following is injected:

**SDK mode** (recommended) — if `wp-content/uploads/motionpage-sdk/sdk-bundle.js` exists on your server, it loads as the single script. The SDK bundle contains the complete animation engine and all animation code.

**Legacy mode** — if no SDK bundle is present, Motion.page loads the legacy runtime with only the plugins your animations actually use (DrawSVG, ScrollTrigger, etc.). This keeps the payload minimal.

### prefers-reduced-motion

Animation code is wrapped in a `prefers-reduced-motion` media query check by default. Visitors who have enabled reduced motion in their OS accessibility settings will not see the animations. This behaviour can be overridden per-timeline if needed.

### FOUC prevention

For **Page Load** trigger timelines, Motion.page injects a `visibility: hidden` rule on the `<body>` in the `<head>`. Once `DOMContentLoaded` fires and the animations initialise, visibility is restored. This prevents a flash of un-animated content on slow connections.

### Lenis smooth scroll

When Lenis is enabled in [Global Settings → Smooth Scroll](/docs/builder/lenis-smooth-scroll), the Lenis script is injected automatically on all pages (except those in the excluded pages list). The Lenis instance is available at `window._mp_lenis` for programmatic access.

---

## Compatibility

### Caching & optimization plugins

Motion.page scripts are automatically excluded from the optimization pipelines of the most common WordPress performance plugins:

| Plugin | Exclusions applied |
|--------|--------------------|
| **WP Rocket** | Scripts excluded from delay, combine, and minify |
| **SiteGround Optimizer** | Scripts excluded from combine and async processing |
| **WP Meteor** | Scripts excluded from delay execution |

No manual exclusion configuration required on your end.

### Page builders

Motion.page detects active page builders and adjusts its behaviour accordingly:

| Builder | Detection | Effect |
|---------|-----------|--------|
| **Oxygen Builder** | `OxygenElement` class or `ct_template` post type | Footer button → **Open in Oxygen Builder**; scripts not injected into Oxygen editor previews |
| **Bricks Builder** | `BRICKS_DB_TEMPLATE_SLUG` constant | Footer button → **Open in Bricks Builder**; scripts not injected into Bricks editor previews |

### Translation plugins

**Polylang** and **WPML** page syncing can be enabled in [Global Settings → WordPress](#wordpress-settings). When active, timeline-to-page assignments are kept in sync across translated versions of each page.

---

## Database & Maintenance

Motion.page creates two custom database tables on activation:

| Table | Contents |
|-------|----------|
| `wp_motionpage_data` | Timeline metadata — name, trigger config, reload behaviour |
| `wp_motionpage_code` | Animation code — generated script, page assignment, global flag, active state |

### Rebuild database

If the plugin tables become corrupt or out of sync after an interrupted update, use **Rebuild** to recreate them without losing data.

**WP Admin → Motion.page → Settings → Rebuild Database**

### Clear cache

Clears the plugin's internal cache. Use this after making server-side changes that affect timeline availability.

**WP Admin → Motion.page → Settings → Clear Cache**

### Wipe on uninstall

Enable **Wipe on uninstall** in [Global Settings → WordPress](#wordpress-settings) before removing the plugin if you want all Motion.page data permanently deleted. By default, your animations are preserved and can be restored by reinstalling the plugin.

---

## Related

- [Workspace Overview](/docs/builder/workspace-overview) — Full tour of the builder interface
- [Lenis Smooth Scroll](/docs/builder/lenis-smooth-scroll) — Configure smooth scroll settings
- [Breakpoints](/docs/builder/breakpoints) — Set responsive breakpoint widths
- [CDN & SDK Bundles](/docs/builder/cdn-delivery) — Publishing animations and SDK delivery options
- [Left Panel](/docs/builder/left-panel) — Complete Left Panel reference

---

## Lenis Smooth Scroll

> Enable and configure Lenis smooth scrolling — duration, multipliers, easing, and per-page exclusions.

URL: https://motion.page/docs/builder/lenis-smooth-scroll

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Lenis** is a smooth scroll library that intercepts native scroll events and replays them with momentum and easing — replacing the browser's default instant-jump scroll with a fluid, inertia-based movement.

When enabled, Lenis runs site-wide. Every scrollable page gets the same smooth scroll behaviour automatically. Use [Excluded Pages](#excluded-pages) to opt specific pages out.

## Location

**Top Panel → Global Settings → Smooth Scroll**

Open the settings drawer from the top panel, then select the **Smooth Scroll** tab.

{/* Screenshot: Global Settings drawer open with the Smooth Scroll tab active, showing the master toggle and all controls */}
![Smooth Scroll settings panel](/images/builder/lenis-smooth-scroll-settings.webp)

## Enable

The section header contains a master toggle. Flip it on to activate Lenis across the entire site. Flip it off to revert to native browser scrolling.

When enabled, a status indicator on the toggle turns green to confirm Lenis is active.

> **Tip:** Disable Lenis on pages where you use a custom scroll library or full-page scroll plugins (e.g. FullPage.js, Swiper vertical) to avoid conflicts. Use [Excluded Pages](#excluded-pages) for that rather than turning off the global toggle.

## Controls

### Duration

**Duration of the smooth scrolling animation in seconds.**

| Range | Step | Default |
|-------|------|---------|
| `0` – `3` | `0.1` | `1.2 s` |

Controls how long each scroll "pulse" takes to settle. Higher values feel heavier and more cinematic; lower values feel snappier.

Setting Duration to **`0`** enables instant scrolling mode — Lenis uses `lerp: 1` internally and skips duration and easing entirely. This is equivalent to native scroll but routed through Lenis, which is useful when you want Lenis running (for scroll-velocity access or scroll-linked animations) without any perceived lag.

---

### Mouse Multiplier

**Multiplier for mouse wheel scroll sensitivity. Higher values make scrolling faster.**

| Range | Step | Default |
|-------|------|---------|
| `0` – `5` | `0.1` | `1` |

Scales how far the page moves per mouse wheel tick. Values above `1` feel faster than native; values below `1` feel slower. Leave at `1` unless the default feels sluggish or too aggressive on your target audience's hardware.

> In the generated code this maps to `wheelMultiplier`, not `mouseMultiplier`.

---

### Touch Multiplier

**Multiplier for touch scroll sensitivity. Higher values make touch scrolling faster.**

| Range | Step | Default |
|-------|------|---------|
| `0` – `5` | `0.1` | `1.5` |

Scales scroll distance on touch devices. The default `1.5` compensates for the lower scroll velocity typical on touch screens and keeps the feel consistent with desktop.

---

### Easing

**Easing function for the smooth scrolling animation.**

The easing curve shapes how quickly each scroll pulse accelerates and decelerates. All options are ease-out curves — the scroll starts fast and slows to rest.

| Option | Feel |
|--------|------|
| **Ease Out Expo** *(default)* | Sharp deceleration — feels snappy and modern |
| **Ease Out Quart** | Slightly softer than Expo |
| **Ease Out Cubic** | Gentle, natural deceleration |
| **Ease Out Quint** | Steeper than Quart, smoother than Expo |
| **Ease Out Circ** | Circular deceleration — soft landing |
| **Linear** | Constant speed — no deceleration |

> **Tip:** **Ease Out Expo** suits most sites. Switch to **Ease Out Cubic** for content-heavy editorial sites where a softer feel is preferable. Avoid **Linear** in production — without deceleration the scroll feels mechanical.

---

### Smooth Touch

**Enable smooth scrolling for touch devices. Disabled by default for better performance.**

Touch devices natively handle momentum scrolling in hardware. Enabling this option overrides that with Lenis-driven easing, which gives a consistent cross-device feel but uses more CPU on mobile.

Leave this off unless you have a strong reason for touch consistency — native iOS and Android momentum scroll is already polished and expected by mobile users.

---

### Excluded Pages

**Select pages where Lenis smooth scrolling should be disabled. These pages will use default browser scrolling instead.**

A searchable multi-select dropdown listing all pages on your site. Pages you add here will load without Lenis — the rest of the site continues using smooth scroll.

Common reasons to exclude a page:

- The page uses a conflicting scroll library (FullPage.js, Locomotive Scroll, etc.)
- The page is a contact form or checkout where scroll precision matters
- A landing page with custom scroll-jacking animations built in vanilla JS

## Live demo — smooth scroll feel

The demo below simulates the eased deceleration Lenis applies to each scroll pulse. Drag the slider to scroll the content pane — the movement overshoots slightly and eases to rest, matching the **Ease Out Expo** default.

<LivePreview client:load
  height={320}
  title="Lenis-style smooth scroll"
  html={`<div class="scene">
  <div class="viewport">
    <div class="track" id="track">
      <div class="item item-1">Section 01</div>
      <div class="item item-2">Section 02</div>
      <div class="item item-3">Section 03</div>
      <div class="item item-4">Section 04</div>
      <div class="item item-5">Section 05</div>
    </div>
  </div>
  <div class="controls">
    <p class="label">Scroll wheel or drag →</p>
    <input type="range" id="scrubber" min="0" max="100" value="0" />
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; gap: 16px; height: 100%; background: #0d0d0d; font-family: system-ui; padding: 16px; box-sizing: border-box; }
.viewport { width: 100%; max-width: 420px; height: 200px; overflow: hidden; border-radius: 12px; border: 1px solid #222; position: relative; }
.track { display: flex; gap: 0; width: 500%; will-change: transform; }
.item { width: 20%; height: 200px; display: flex; align-items: center; justify-content: center; font-size: 18px; font-weight: 600; color: #fff; letter-spacing: 0.08em; }
.item-1 { background: #6633EE; }
.item-2 { background: #3366EE; }
.item-3 { background: #0099AA; }
.item-4 { background: #009944; }
.item-5 { background: #AA3300; }
.controls { display: flex; flex-direction: column; align-items: center; gap: 6px; width: 100%; max-width: 420px; }
.label { margin: 0; font-size: 12px; color: #666; }
#scrubber { width: 100%; accent-color: #6633EE; cursor: pointer; }`}
  js={`const track = document.getElementById('track');
const scrubber = document.getElementById('scrubber');
let current = 0;
let target = 0;
let raf;

function easeOutExpo(t) { return t === 1 ? 1 : 1 - Math.pow(2, -10 * t); }

function getMax() {
  return track.scrollWidth - track.parentElement.clientWidth;
}

function lerp(a, b, t) { return a + (b - a) * t; }

function tick() {
  current = lerp(current, target, 0.1);
  if (Math.abs(current - target) < 0.1) current = target;
  track.style.transform = 'translateX(-' + current + 'px)';
  scrubber.value = (current / getMax()) * 100;
  raf = requestAnimationFrame(tick);
}
raf = requestAnimationFrame(tick);

scrubber.addEventListener('input', () => {
  target = (scrubber.value / 100) * getMax();
});

track.parentElement.addEventListener('wheel', (e) => {
  e.preventDefault();
  target = Math.max(0, Math.min(getMax(), target + e.deltaY));
}, { passive: false });`}
/>

The eased deceleration is what Lenis applies to the page's scroll position on every wheel or touch event. Increasing **Duration** makes the ease-out last longer; switching to **Ease Out Cubic** gives a softer landing.

## Generated code

Motion.page generates a self-contained script block injected into every page (unless excluded). The script initialises Lenis, starts the `requestAnimationFrame` loop, and attaches cleanup logic:

```js
window._mp_lenis = new Lenis({
  "duration": 1.2,
  "easing": (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
  "smoothTouch": false,
  "wheelMultiplier": 1,
  "touchMultiplier": 1.5
});

function _mp_raf(time) {
  window._mp_lenis.raf(time);
  requestAnimationFrame(_mp_raf);
}
requestAnimationFrame(_mp_raf);
```

When you change settings or disable Lenis, `window._mp_lenis_cleanup()` is called automatically to destroy the instance and remove the RAF loop before the new config is applied.

> **Tip:** The **Mouse Multiplier** setting in the panel maps to `wheelMultiplier` in the generated code — the Lenis API name. The builder uses the friendlier label in the UI.

## Common patterns

### Subtle cinematic feel

Lower the duration and use **Ease Out Quart** for a restrained, editorial look — scroll feels slightly weighted without being sluggish.

| Setting | Value |
|---------|-------|
| Duration | `0.9` |
| Easing | Ease Out Quart |
| Mouse Multiplier | `1` |
| Smooth Touch | off |

### Fast and snappy

For app-like interfaces where responsiveness matters more than feel, keep duration short and multipliers at default.

| Setting | Value |
|---------|-------|
| Duration | `0.6` |
| Easing | Ease Out Expo |
| Mouse Multiplier | `1` |

### Heavy parallax site

Slow, dramatic scrolling for scroll-jacked parallax layouts. High duration, low mouse multiplier.

| Setting | Value |
|---------|-------|
| Duration | `2.0` |
| Easing | Ease Out Cubic |
| Mouse Multiplier | `0.8` |

### Consistent cross-device feel

Enable **Smooth Touch** and align the touch multiplier with the mouse multiplier for identical behaviour on all devices.

| Setting | Value |
|---------|-------|
| Smooth Touch | on |
| Mouse Multiplier | `1` |
| Touch Multiplier | `1` |

## Related

- [Click Trigger](/docs/builder/click-trigger) — Trigger animations from click events, compatible with Lenis-controlled pages
- [Scroll Trigger in the SDK](/docs/sdk/scroll-trigger) — SDK scroll-linked animations that integrate with Lenis scroll events

---

## Hover Trigger

> Configure hover animations with single and multi-target modes, and control what happens on mouse leave.

URL: https://motion.page/docs/builder/hover-trigger

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Hover trigger** plays a timeline when the pointer enters a target element. Configure a separate trigger selector, animate each matched element independently, and control exactly what happens when the pointer leaves — reverse, restart, pause, or stop.

## Location

**Left Panel → Trigger tab → Interactions → Hover**

Select **Hover** from the trigger dropdown to reveal the hover configuration panel.

{/* Screenshot: Left Panel with Trigger tab open, Interactions section expanded, Hover selected from the trigger dropdown */}
![Hover trigger settings panel](/images/builder/hover-trigger-settings.webp)

---

## Mouse Over

The **Mouse Over** section defines which element triggers the animation on pointer enter.

| Control | Description |
|---------|-------------|
| **Trigger selector** | CSS selector for the hover target. Leave empty to use the animation selector. Accepts `.class` or `#id`. |
| **Play each iteration individually** | When enabled, each matched element gets its own independent timeline instance — hovering one does not affect the others. |

**Trigger selector** behavior depends on the mode:

- **Single mode** (`each` off) — pick any selector: `.trigger_class`, `#ID`. Leave empty to default to the animation selector.
- **Each mode** (`each` on) — the selector acts as a **wrapper class**. Elements inside each wrapper are animated individually. Leave empty to use the animation selector as the wrapper.

> Leave empty to use the animation selector as a hover trigger or pick a specific selector that triggers the timeline.

> By enabling **Play each iteration individually**, you can animate each iteration of the class individually one-by-one.

---

## Mouse Leave

The **Mouse Leave** section controls what the timeline does when the pointer exits the trigger element. The options are mutually exclusive — the first enabled option takes effect.

| Control | Default | Description |
|---------|---------|-------------|
| **Pause animation** | off | Pauses the timeline at its current position when the pointer leaves. |
| **Stop animation** | off | Stops the timeline and holds the current position without reversing. |
| **Restart animation** | off | Snaps back to the start state and replays the timeline forward. |
| **Reverse animation** | **on** | Plays the timeline backward to the start state on mouse leave. |
| **Reverse animation after certain time** | off | Waits a set number of seconds before reversing on mouse leave. |

When **Reverse animation after certain time** is enabled, a **Delay** input appears. Set the number of seconds to wait before the reverse begins (default: `0.5s`).

**Priority order** — if multiple leave options are enabled, the first match wins: Pause → Stop → Restart → Reverse.

> Reverse the timeline on mouse leave.

> Restart the timeline on mouse leave.

> Add a delay before the timeline reverse.

---

<LivePreview client:load
  height={200}
  title="Hover to lift card"
  html={`<div class="scene">
  <div class="card">
    <div class="card-icon">✦</div>
    <p class="card-label">Hover me</p>
  </div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; }
.card { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 10px; width: 160px; height: 120px; background: #1a1a2e; border-radius: 14px; border: 1px solid rgba(255,255,255,0.08); cursor: pointer; }
.card-icon { font-size: 28px; color: #a78bfa; }
.card-label { color: #c4b5fd; font-size: 13px; font-weight: 500; margin: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("card-lift", ".card", {
  to: { y: -8, scale: 1.04, boxShadow: "0 20px 40px rgba(0,0,0,0.35)" },
  duration: 0.28,
  ease: "expo.out",
}).onHover({ each: true, onLeave: "reverse" });`}
/>

In the builder this is a **To** animation with `y: -8` and `scale: 1.04`, with **Reverse animation** enabled in the Mouse Leave section.

---

## SDK equivalent

The builder Hover trigger maps directly to `.onHover()` in the SDK.

```typescript
import { Motion } from "@motion.page/sdk";

// Lift on hover, reverse on leave (mirrors builder defaults)
Motion("card-lift", ".card", {
  to: { y: -8, scale: 1.04, boxShadow: "0 20px 40px rgba(0,0,0,0.35)" },
  duration: 0.28,
  ease: "expo.out",
}).onHover({ onLeave: "reverse" });
```

**Each — independent per-element instances:**

```typescript
// Each card in a grid lifts independently
Motion("cards", ".card", {
  to: { y: -8, scale: 1.04 },
  duration: 0.28,
  ease: "expo.out",
}).onHover({ each: true, onLeave: "reverse" });
```

**Separate trigger selector:**

```typescript
// A button triggers an animation on a sibling element
Motion("panel-reveal", ".panel", {
  from: { opacity: 0, y: 12 },
  duration: 0.3,
  ease: "power2.out",
}).onHover({ target: ".panel-trigger", onLeave: "reverse" });
```

**Reverse with delay:**

```typescript
Motion("tooltip", ".tooltip", {
  to: { opacity: 1, y: 0 },
  duration: 0.2,
}).onHover({ onLeave: "reverse", leaveDelay: 0.5 });
```

For the full SDK reference see [Hover Trigger in the SDK](/docs/sdk/hover).

---

## Common patterns

### Per-card independent hover

Enable **Play each iteration individually** so hovering one card in a grid does not affect the others. Leave the trigger selector empty — each card becomes its own trigger and animated target.

### Delayed reverse for tooltips

Enable **Reverse animation after certain time** and set a short delay (e.g. `0.3s`) so the tooltip stays visible briefly after the pointer leaves, preventing it from disappearing too abruptly.

### Hover with a wrapper trigger

In **each** mode the trigger selector acts as a **wrapper**. Set it to `.card-wrapper` and your animation selector to `.card-inner` — hovering anywhere inside `.card-wrapper` triggers the animation on the corresponding `.card-inner` only.

---

## Related

- [Hover Trigger in the SDK](/docs/sdk/hover) — Full SDK reference for `.onHover()`
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on click with toggle support
- [Page Load Trigger](/docs/builder/page-load) — Auto-play animations when the page loads
- [From, To & Set](/docs/builder/from-to-set) — Configure what the animation does

---

## Presentation Mode

> Configure full-page section scrolling with smooth transitions, direction control, and visual effects.

URL: https://motion.page/docs/builder/presentation-mode

import LivePreview from "../../components/docs/blocks/LivePreview";

**Presentation Mode** turns matched page sections into a stacked slide deck. Wheel, touch, and pointer gestures advance the active section through Builder-generated Motion timelines.

## Location

**Left Panel → Trigger tab → trigger type dropdown → Observer → Presentation Mode toggle**

Enable the **Observer** trigger, turn on **Trigger each iteration individually**, then toggle **Presentation Mode** to reveal its controls.

{/* Screenshot: Left Panel with Trigger tab open, Observer selected, and Presentation Mode toggle enabled showing all sub-controls */}
![Presentation Mode settings panel](/images/builder/presentation-mode-settings.webp)

---

## How it works

Each element matched by the Observer target becomes a **full-screen section**. The Builder stacks those sections in one containing block, generates incoming and outgoing Motion timelines, and maps gestures to the next or previous absolute section index.

> Enable full-page section scrolling like a presentation. Each target becomes a full-screen section with smooth transitions between them. Callbacks are handled automatically.

The normal Observer **Callbacks** control is hidden in this mode. The generator derives the necessary `Down`/`Up` or `Right`/`Left` mappings from Direction and Reverse Gesture, so you do not configure callback actions separately.

---

## Settings

| Setting | Default | Description |
|---------|---------|-------------|
| **Presentation Mode** toggle | off | Activates full-screen section snapping. All controls below are hidden when this is off. |
| **Infinite Repeat** | off | When the last section is reached, loop back to the first (and vice versa). |
| **Direction** | `vertical` | Whether sections transition vertically (up/down) or horizontally (left/right). |
| **Duration** | `1` s | How long each incoming and outgoing section transition takes. |
| **Cooldown** | `0.5` s | Additional navigation lock after the transition finishes. Prevents repeated triggers on sensitive trackpads. |
| **Effects** | Opacity + Translate | Visual properties included in the generated transition timelines. |
| **Reverse Gesture** | off | Swap gesture directions: up/left navigates forward, down/right navigates backward. |
| **Use Vertical Wheel** | off | Allow vertical mouse wheel to navigate horizontal sections. Useful for desktop users with traditional mice. |

---

## Effects

> Choose which visual effects to apply during section transitions. Select both for smooth fade and slide animations.

| Effect | Behaviour |
|--------|-----------|
| **Opacity** | The outgoing section fades out while the incoming section fades in. |
| **Translate** | The outgoing section moves off-screen while the incoming section moves in along the selected axis. |
| **Opacity + Translate** | Both properties animate together. |

Both effects are selected by default. If the selection is cleared, the Builder adapter restores both defaults when it generates code.

---

## Direction

> Choose whether sections transition vertically (up/down) or horizontally (left/right).

| Value | Behaviour |
|-------|-----------|
| `vertical` | Users scroll down to advance and up to go back. Works naturally with all scroll input devices. |
| `horizontal` | Right gestures advance and left gestures go back. Combine with **Use Vertical Wheel** for standard mouse-wheel input. |

### Use Vertical Wheel

> Enable vertical mouse wheel scrolling to navigate horizontal sections. Useful for desktop users with traditional mice.

When **Direction** is set to `horizontal`, desktop users without a trackpad cannot naturally swipe left/right with a standard scroll wheel. Enable **Use Vertical Wheel** to map vertical wheel events to horizontal section navigation so all input devices work consistently.

### Reverse Gesture

> Use standard gesture directions. When enabled, up/left gestures navigate forward, down/right navigate backward.

Disabled by default: down/right advances to the next section. Enable **Reverse Gesture** to flip this — up/left advances, down/right goes back. Use this when your layout reads right-to-left or your art direction calls for inverted navigation.

---

<LivePreview client:visible
  height={360}
  title="Presentation Mode — full-screen section snap"
  html={`<div class="stage">
  <div class="slide" style="background:#1a1a2e">
    <span class="label">Section 1</span>
    <span class="sub">↓ Scroll to advance</span>
  </div>
  <div class="slide" style="background:#16213e">
    <span class="label">Section 2</span>
    <span class="sub">↓ Keep scrolling</span>
  </div>
  <div class="slide" style="background:#0f3460">
    <span class="label">Section 3</span>
    <span class="sub">↑ Scroll back</span>
  </div>
</div>`}
  css={`* { box-sizing: border-box; margin: 0; padding: 0; }
.stage { position: relative; width: 100%; height: calc(100vh - 2rem); min-height: 280px; overflow: hidden; font-family: system-ui; }
.slide { position: absolute; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 10px; }
.label { font-size: 28px; font-weight: 700; color: #fff; }
.sub { font-size: 13px; color: rgba(255,255,255,0.45); }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const sections = Motion.utils.toArray(".slide");
let current = 0;
let busy = false;

sections.forEach((section, index) => {
  Motion.set(section, {
    opacity: index === 0 ? 1 : 0,
    visibility: index === 0 ? "visible" : "hidden",
  });
});

function gotoSection(next, direction) {
  next = (next + sections.length) % sections.length;
  if (busy || next === current) return;
  busy = true;

  const outgoing = sections[current];
  const incoming = sections[next];
  Motion.get("slide-out")?.kill(false);
  Motion.get("slide-in")?.kill(false);
  Motion.set(incoming, { opacity: 0, y: direction * 100 + "%", visibility: "visible" });

  Motion("slide-out", outgoing, {
    to: { opacity: 0, y: direction * -100 + "%" },
    duration: 0.6,
    ease: "power2.inOut",
  }).play();

  Motion("slide-in", incoming, {
    to: { opacity: 1, y: 0 },
    duration: 0.6,
    ease: "power2.inOut",
  }).onComplete(() => {
    Motion.set(outgoing, { visibility: "hidden" });
    current = next;
    setTimeout(() => { busy = false; }, 350);
  }).play();
}

const gesture = Motion("slides-gesture");
gesture.onGesture({
  target: ".stage",
  types: ["wheel", "touch", "pointer"],
  events: {
    Down: "play",
    Up: "reverse",
  },
  tolerance: 25,
  dragMinimum: 35,
  preventDefault: true,
});
gesture.play = function () { gotoSection(current + 1, 1); return gesture; };
gesture.reverse = function () { gotoSection(current - 1, -1); return gesture; };`}
/>

This hand-written preview mirrors Builder output with **Direction** set to Vertical, **Effects** set to Opacity and Translate, **Infinite Repeat** enabled, a `0.6s` transition, and a `0.35s` cooldown. The Builder generates the section setup and navigation function automatically.

---

## SDK equivalent

Presentation Mode is a **Builder-generated orchestration layer** on top of the public SDK. It does not map to a `presentation` option in `GestureConfig`. Exported Builder code creates the enter/exit timelines, tracks the active section, then uses `.onGesture()` to call the section-navigation function.

The core pattern looks like this (the preview's **JS** tab contains the complete working version):

```typescript
import { Motion } from "@motion.page/sdk";

const gesture = Motion("slides-gesture");

gesture.onGesture({
  types: ["wheel", "touch", "pointer"],
  events: { Down: "play", Up: "reverse" },
  preventDefault: true,
});

// The generated functions create Motion() enter/exit timelines.
gesture.play = function () {
  gotoSection(currentIndex + 1, 1);
  return gesture;
};
gesture.reverse = function () {
  gotoSection(currentIndex - 1, -1);
  return gesture;
};
```

The Builder writes the longer `gotoSection()` implementation for you, including horizontal/vertical translation, opacity settings, cooldown, and optional wrapping. For the generated-code pattern see [Presentation Mode](/docs/sdk/presentation-mode).

---

## Common patterns

### Vertical storytelling

Set **Direction** to Vertical, enable both **Opacity** and **Translate**, and set **Duration** to `0.8–1s`. Each section becomes a narrative beat that advances on downward gestures.

### Horizontal portfolio

Set **Direction** to `horizontal` and enable **Use Vertical Wheel** so desktop users with traditional mice can navigate. Each panel can showcase a project or case study. Use **Reverse Gesture** if the design reads right-to-left.

### Looping product showcase

Enable **Infinite Repeat** with a short **Duration** (`0.5s`) and minimal **Cooldown** (`0.3s`) so gestures wrap continuously from the final product slide back to the first.

---

## Related

- [Observer Gesture](/docs/builder/observer-gesture) — The parent trigger that Presentation Mode extends
- [Scroll Trigger](/docs/builder/scroll-trigger) — Standard scroll-based animation without section snapping
- [Presentation Mode — SDK pattern](/docs/sdk/presentation-mode) — how Builder output composes core Motion timelines and `.onGesture()`
- [Left Panel](/docs/builder/left-panel) — Full Left Panel reference including the Trigger tab

---

## Advanced Targeting

> Target animations to specific pages using post types, custom URLs, and RegEx patterns.

URL: https://motion.page/docs/builder/advanced-targeting

import CodeBlock from '../../components/docs/blocks/CodeBlock.astro';

By default, a timeline is assigned to a single page. **Advanced Targeting** lets you load it on multiple pages at once — by post type, specific URL patterns, or custom RegEx rules — without duplicating the timeline.

---

## Location

**Left Panel → Settings tab → Advanced Targeting**

Open the Settings tab for any timeline. The Advanced Targeting section sits below the Global toggle and the single-page selector.

{/* Screenshot: Advanced Targeting section in the Settings tab showing post type chips and RegEx input */}
![Advanced Targeting — Settings tab in the Left Panel](/images/builder/advanced-targeting-settings.webp)

---

## Default Behavior

Every timeline starts with a single target:

| Setting | What It Does |
|---------|-------------|
| **Page selector** | Assigns the timeline to one specific page (`tSelectPost`). The baseline — pick the page where the animation lives. |
| **Global toggle** | When enabled, the timeline loads on every page of the site (`tGlobal`). Overrides the page selector and Advanced Targeting. |
| **Advanced Targeting** | Sits between these two extremes — target a specific group of pages without going fully global. |

Use Advanced Targeting when the same animation should appear across a category of pages (all blog posts, all product pages) or on any URL that matches a pattern.

---

## Post Type Targeting

Select one or more **post types** and the timeline loads on every page that belongs to those types — Pages, Posts, Products, or any custom post type registered on your site.

**How to use it:**
1. Open **Left Panel → Settings tab → Advanced Targeting**.
2. Click a post type chip to toggle it on. Selected types are highlighted.
3. The timeline will now load on all pages of that type, in addition to the single page set in the page selector.

This is the fastest way to apply a consistent animation across your entire blog, all WooCommerce products, or any uniform content type.

---

## Custom RegEx Targeting

For URL-based rules, the RegEx input matches the timeline against any page whose URL fits the pattern.

**How it works:**
- Type a valid RegEx string directly — no delimiters needed. Delimiters are inserted automatically.
- The only supported flag is `i` (case-insensitive match). Other flags are not available.
- Special characters (`.`, `?`, `+`, `(`, `)`, etc.) must be **escaped** with a backslash.
- The pattern is matched against the URL **path**, not the full URL (no protocol or domain).

### Pattern Examples

| Pattern | Matches | Description |
|---------|---------|-------------|
| `/about/` | `/about/`, `/about/team/` | Any URL containing `/about/` |
| `^/blog/` | `/blog/post-1`, `/blog/` | URLs starting with `/blog/` |
| `\.html$` | `/page.html` | URLs ending in `.html` |
| `/products/[0-9]+` | `/products/123`, `/products/456` | Product pages with numeric IDs |
| `^/en/` | `/en/home`, `/en/contact` | All pages under a language prefix |

---

## Tips & Gotchas

- **Pattern scope** — RegEx matches the URL path only, not the full address. `/about/` targets paths that contain `/about/`, not `https://example.com/about/`.
- **Broad patterns are risky** — A loose pattern like `/page` will match `/page-one`, `/page-two`, `/contact-page`, and anything else containing "page". Narrow your patterns when possible.
- **Skip `.*` for global** — If you want an animation on every page, use the **Global toggle** instead of writing a catch-all regex. It's more explicit and has no edge-case risk.
- **Case sensitivity** — The `i` flag makes the match case-insensitive. Without it (by default), `/About/` would not match `/about/`. Enable it by appending `i` after the pattern if your site uses mixed-case URLs.
- **Combine with Breakpoints** — Advanced Targeting controls which pages load the animation. [Breakpoints](/docs/builder/breakpoints) control at which viewport widths it runs. Use both together for precise delivery.

---

## Related

- [Advanced Targeting in the SDK](/docs/sdk/advanced-targeting) — Apply post type and URL targeting directly in code
- [Breakpoints](/docs/builder/breakpoints) — Enable or disable animations at specific viewport widths
- [Overview](/docs/builder/overview) — Builder fundamentals and how timelines are structured

---

## Animation Library

> Save, organize, enable/disable, and manage your animation library.

URL: https://motion.page/docs/builder/library

The **Animation Library** is your central list of every saved timeline in the current site or project. Open it by clicking the **Library** tab at the top of the Left Panel.

{/* Screenshot: Library tab open in the Left Panel, showing multiple page headings (folders) each collapsed/expanded with animation rows underneath, and the filter bar and Export All button visible */}
![Animation Library panel](/images/builder/library-panel.webp)

---

## Panel overview

The Library panel has three parts:

1. **Filter bar** — A searchable dropdown at the top for narrowing the list by trigger type or targeting rules.
2. **Page groups** — Timelines are grouped by the page they are assigned to. Each group has a collapsible heading showing the page name. Click the heading to expand or collapse it.
3. **Footer** — Import (drag-and-drop) and **Export All** controls.

Each animation row in a group shows the timeline name, trigger type badge, and action icons for enabling/disabling and toggling global load.

---

## Enable and disable animations

Every animation can be toggled on or off without deleting it. The **enable/disable button** appears on each row.

- **Enable** — activates the timeline so it runs on the page.
- **Disable** — deactivates the timeline; it remains saved but no animation code is executed on the frontend.

This is useful for testing, staging animations before a launch, or turning off seasonal effects without losing the configuration.

---

## Global vs. page-specific

Timelines are assigned to a specific page by default. The **Global** icon on each row controls whether the timeline loads everywhere:

| State | What it does |
|-------|--------------|
| **Load timeline globally** | The timeline will load on every page of the site, regardless of which page it was created on. |
| **Unload timeline globally** | Reverts to page-specific loading. The timeline only loads on its assigned page. |

The same toggle is available in the **Builder** tab under the timeline name — the Library panel reflects that setting.

---

## Context menu

**Right-click** any animation row to open the context menu.

| Action | Description |
|--------|-------------|
| **Duplicate** | Creates a copy of the timeline on the same page. Opens in the Builder tab for immediate editing. |
| **Delete** | First click shows a confirmation prompt ("Are you sure?"). Click again to permanently remove the timeline. |
| **Export** | Downloads the selected timeline as a `.json` file for backup or sharing. |
| **Copy UID** | Copies the timeline's unique identifier to the clipboard (useful for SDK or custom code integration). |
| **Copy DB ID** | Copies the internal database ID to the clipboard. |

> **Caution:** Deletion is permanent. Use **Disable** if you want to keep the animation but stop it from running.

---

## Multi-select

Click and drag across animation rows to select multiple timelines at once. Hold `Shift` to toggle individual items in or out of the selection.

With multiple timelines selected, the context menu offers:

- **Delete Multiple** — removes all selected timelines after confirmation.
- **Export Multiple** — downloads all selected timelines in a single file.

---

## Filters

The **filter bar** at the top of the Library panel is a searchable multi-select dropdown. Use it to narrow the list when you have many animations.

You can filter by:

- **Trigger type** — Page Events, ScrollTrigger, Interactions (Click, Hover), Mouse Movement, Observer, and more.
- **Page Event subtype** — On JS Load, On Page Load.
- **Interaction subtype** — Click, Hover.
- **Advanced Targeting** — Filter by post types or URL RegEx patterns defined in each timeline's Advanced Targeting settings.

Select multiple filters to combine them. Clear all filters to return to the full list.

---

## Import

To import a previously exported timeline:

**Drag and drop** the `.json` export file anywhere onto the Library panel. The footer displays the prompt: _"Drop the animation file to import."_

The imported timeline is added to the library and immediately available for editing.

---

## Export

You have three export options:

| Option | How to access | What it exports |
|--------|--------------|-----------------|
| **Single export** | Right-click → Export | One timeline as a `.json` file |
| **Multi export** | Select multiple → Right-click → Export Multiple | All selected timelines in one file |
| **Export All** | Footer button | Every timeline in the library |

Use exports to back up animations, move them between sites, or share them with other Motion.page users.

---

## Refresh Library

If you have made changes outside the builder (for example, direct database edits or syncing from another environment), click **Refresh Library** in the Left Panel footer to re-fetch all timelines.

---

## Related

- [Workspace Overview](/docs/builder/workspace-overview) — Tour of all four builder regions, including the Left Panel tab switcher
- [Left Panel](/docs/builder/left-panel) — Full reference for the Builder tab and its controls
- [Animation Presets](/docs/builder/animation-presets) — Apply ready-made animations to get started quickly

---

## Transform Origin

> Set the origin point for transform animations in the builder UI.

URL: https://motion.page/docs/builder/transform-origin

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Transform Origin** sets the pivot point for transform animations — the fixed anchor from which Scale expands, Rotation spins, and Skew tilts. Changing it from the default center moves where the motion "starts" without touching the element's position.

## Location

**Left Panel → Animation tab → Visual Properties → Transform Origin**


## Enable Transform Origin

Click the toggle next to **Transform Origin** to enable it. The row expands to reveal the X and Y percentage inputs alongside a **visual 9-point grid**. Click any dot on the grid to snap to a preset origin (corners, edges, or center), or drag the blue dot to set a custom position. The X and Y inputs update automatically as you interact with the grid.

{/* Screenshot: Transform Origin row expanded, showing the X and Y inputs with the visual 9-point grid */}
![Transform Origin control expanded — X and Y inputs with visual grid](/images/builder/transform-origin-controls.webp)

## Controls

| Control | Default | Accepted values | Description |
|---------|---------|-----------------|-------------|
| **X** | `50%` | Keywords, percentages, lengths | Horizontal anchor point. `0%` = left edge, `50%` = center, `100%` = right edge. |
| **Y** | `50%` | Keywords, percentages, lengths | Vertical anchor point. `0%` = top edge, `50%` = center, `100%` = bottom edge. |

**Accepted value formats for X and Y:**

- **Keywords** — `left`, `center`, `right` (for X) and `top`, `center`, `bottom` (for Y)
- **Percentages** — `0%`, `25%`, `50%`, `75%`, `100%`
- **Lengths** — `20px`, `2rem`, `4em`

Keywords and percentages are relative to the element's own bounding box. Length values are absolute offsets from the element's top-left corner.

## How it affects transforms

Transform Origin does not animate the element itself — it changes the fixed point that other transforms revolve around:

- **Scale** — the element grows or shrinks outward from the origin. At `0% 100%` (bottom-left), the element scales up from its bottom-left corner rather than from its center.
- **Rotation** — the element spins around the origin. At `50% 0%` (top-center), the element swings like a pendulum from the top.
- **Skew** — the element shears away from the origin. Changing the origin shifts which part of the element stays anchored.


## From mode — animate the origin itself

Transform Origin can be keyframed like any other property. Switch to the **From** tab, enable Transform Origin, and set a different X/Y than the CSS value on the element. The SDK interpolates the origin point itself over the animation duration.


This is useful when you want the pivot to drift during the animation — for example, a card that starts rotating from its corner and gradually shifts to rotating from its center.

## To mode — shift the anchor at the end

Switch to the **To** tab, enable Transform Origin, and set the destination origin. The anchor moves from the element's natural CSS `transform-origin` to the value you specify as the animation plays.


<LivePreview client:load
  height={260}
  title="Transform origin — corner vs center"
  html={`<div class="scene">
  <div class="row">
    <div class="col">
      <div class="box center"></div>
      <p class="label">Center (default)</p>
    </div>
    <div class="col">
      <div class="box corner"></div>
      <p class="label">Top-left corner</p>
    </div>
  </div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; }
.row { display: flex; gap: 48px; align-items: flex-end; }
.col { display: flex; flex-direction: column; align-items: center; gap: 8px; }
.box { width: 80px; height: 80px; border-radius: 10px; background: #6633EE; }
.box.corner { background: #FF6633; transform-origin: 0% 0%; }
.label { font-size: 12px; color: #888; margin: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("center-spin", ".box.center", {
  to: { rotate: 180 },
  duration: 0.8,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("corner-spin", ".box.corner", {
  to: { rotate: 180 },
  duration: 0.8,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

Both boxes rotate `180deg`. The purple box uses the default `transform-origin: 50% 50%` (center) and spins on the spot. The orange box uses `transform-origin: 0% 0%` (top-left corner) and sweeps in a wide arc around its corner.

## SDK equivalent

`transformOrigin` is a first-class property in the `from`, `to`, and `set` objects. Pass it as a space-separated string, matching CSS `transform-origin` syntax.

**Rotation from top-left corner:**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('corner-spin', '.card', {
  from: { rotation: -15, transformOrigin: '0% 0%' },
  duration: 0.7,
  ease: 'power3.out',
}).onScroll();
```

**Scale from bottom-center (growing bar):**

```typescript
Motion('bar-grow', '.bar', {
  from: { scaleY: 0, transformOrigin: '50% 100%' },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll();
```

**Pendulum swing from top:**

```typescript
Motion('pendulum', '.badge', {
  from: { rotation: -20, transformOrigin: '50% 0%' },
  to:   { rotation:  20, transformOrigin: '50% 0%' },
  duration: 0.9,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

**Animating the origin itself:**

```typescript
// The pivot drifts from the top-left corner to the center as the element rotates
Motion('drifting-spin', '.logo', {
  from: { rotation: 0,   transformOrigin: '0% 0%' },
  to:   { rotation: 360, transformOrigin: '50% 50%' },
  duration: 1.2,
  ease: 'power2.inOut',
}).onPageLoad();
```

For the full SDK reference, see [Transform Origin in the SDK](/docs/sdk/transform-origin).

## Common patterns

### Corner rotation reveal

Enable **Rotation** on the **From** tab (e.g. `-12deg`) and set **Transform Origin** to `0% 0%`. The element swings in from its top-left corner like a door opening.

```typescript
Motion('door-open', '.panel', {
  from: { rotation: -12, opacity: 0, transformOrigin: '0% 0%' },
  duration: 0.65,
  ease: 'power3.out',
}).onScroll();
```

### Bottom-center scale (growing bar / chart column)

Enable **Scale Y** on the **From** tab and set it to `0`. Set **Transform Origin** to `50% 100%`. The element grows upward from its bottom edge — perfect for bar charts or progress indicators.

```typescript
Motion('bar-rise', '.chart-bar', {
  from: { scaleY: 0, transformOrigin: '50% 100%' },
  duration: 0.5,
  ease: 'power2.out',
  stagger: 0.08,
}).onScroll();
```

### Off-center spin

Set **Transform Origin** to a point outside the element (e.g. `50% 200%`) and enable **Rotation**. The element orbits around a point below itself — a planet-around-sun motion.

```typescript
Motion('orbit', '.dot', {
  to: { rotation: 360, transformOrigin: '50% 200%' },
  duration: 2,
  ease: 'none',
  repeat: { times: -1 },
}).onPageLoad();
```

### Hover flip from edge

Set **Transform Origin** to `0% 50%` (left edge). Enable **Rotation Y** on the **To** tab at `180deg`. On hover the card flips away from its left edge. Pair with **Reverse on leave** to flip back.

```typescript
Motion('edge-flip', '.card', {
  to: { rotationY: 180, transformOrigin: '0% 50%' },
  duration: 0.4,
  ease: 'power2.inOut',
}).onHover({ each: true, onLeave: 'reverse' });
```

## Tips

- `50% 50%` is always the default. You only need to set Transform Origin when you want behaviour different from center-based transforms.
- Keywords (`top`, `left`, etc.) and percentages produce identical results — `left` equals `0%`, `center` equals `50%`, `right` equals `100%`.
- Transform Origin is applied per-element. In a staggered group each element pivots around its own origin point — not the group's center.
- Combining an off-canvas origin (e.g. `50% -100%`) with Rotation creates orbiting effects without any position change.

## Related

- [Rotation](/docs/builder/rotation) — Spin elements; Transform Origin determines what they rotate around
- [Scale](/docs/builder/scale) — Grow or shrink elements; Transform Origin determines where they scale from
- [Skew](/docs/builder/skew) — Tilt elements; Transform Origin shifts which part stays anchored
- [3D Transform](/docs/builder/3d-transforms) — Perspective and rotationX/Y/Z; Transform Origin applies to all axes
- [Transform Origin in the SDK](/docs/sdk/transform-origin) — SDK reference for the `transformOrigin` property
- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each

---

## Stagger

> Configure stagger for multiple-target animations.

URL: https://motion.page/docs/builder/stagger

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Stagger** adds a cascading delay between each element in a multi-target animation. Instead of all elements animating at the same time, each one starts slightly after the previous — producing a wave or ripple effect.

> Animate multiple targets in a sequence, by adding delay to each element. Use a common selector or multiple selectors.

## Location

**Left Panel → Animation tab → Functional Properties → Stagger**

Stagger is a **functional property** — it is direction-agnostic. The same value applies whether the **From**, **To**, or **Set** tab is active.


## Enable stagger

Click the toggle next to **Stagger** to enable it. The row expands to reveal the mode label, time input, and direction dropdown.

{/* Screenshot: Stagger row expanded, showing the Each/Amount mode label, number input, and From dropdown */}
![Stagger controls expanded — mode label, time input, and From dropdown](/images/builder/stagger-controls-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Mode label** (Each / Amount) | Click to toggle between the two distribution modes. |
| **Time input** | Delay value in seconds. |
| **From dropdown** | The direction or position from which the stagger originates. |

### Each vs Amount

**Each** sets a fixed delay between consecutive elements. If you have 5 elements and set `each` to `0.1`, the delays are `0s`, `0.1s`, `0.2s`, `0.3s`, `0.4s`.

**Amount** distributes a total duration across all elements. If `amount` is `0.4` and there are 5 elements, each element starts `0.08s` after the previous one.

| Mode | Input step | Best for |
|------|-----------|----------|
| **Each** | `0.01 s` | Consistent per-element timing |
| **Amount** | `0.1 s` | Proportional pacing regardless of element count |

Click the **Each** or **Amount** label to switch modes. The current value moves to the new mode automatically.

### From options

| Value | Behavior |
|-------|----------|
| `start` | Stagger begins at the first element and moves forward. Default. |
| `end` | Stagger begins at the last element and moves backward. |
| `center` | Stagger radiates outward from the middle element. |
| `edges` | Stagger begins at both ends and converges toward the center. |
| `random` | Each element receives a random delay within the stagger range. |

<LivePreview client:load
  height={220}
  title="Stagger entrance"
  html={`<div class="scene">
  <div class="card"></div>
  <div class="card"></div>
  <div class="card"></div>
  <div class="card"></div>
  <div class="card"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; gap: 10px; padding: 20px; height: 100%; }
.card { width: 48px; height: 48px; border-radius: 10px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("cards-in", ".card", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  ease: "power2.out",
  stagger: 0.1,
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

Each card starts `0.1s` after the previous one — equivalent to `stagger: 0.1` in the SDK (Each mode, from `start`).

## SDK equivalent

The `stagger` property maps directly to the SDK's `AnimationConfig.stagger` field.

**Simple (Each, from start):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('cards-in', '.card', {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  ease: 'power2.out',
  stagger: 0.1,
}).onPageLoad();
```

When mode is **Each** and `from` is `start`, the builder outputs a plain number — the most compact form.

**Each with a custom From direction:**

```typescript
Motion('cards-center', '.card', {
  from: { opacity: 0, scale: 0.8 },
  duration: 0.5,
  ease: 'back.out',
  stagger: { each: 0.08, from: 'center' },
}).onScroll();
```

**Amount mode:**

```typescript
Motion('cards-amount', '.card', {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: 'power2.out',
  stagger: { amount: 0.4 },
}).onPageLoad();
```

### SDK-only stagger options

The SDK accepts additional stagger options not exposed in the builder UI. Use [Custom Code](/docs/builder/from-to-set) or the SDK directly when you need these:

| Option | Type | Description |
|--------|------|-------------|
| `grid` | `'auto' \| [rows, cols]` | Enable 2D stagger for grid layouts. `'auto'` reads the layout automatically. |
| `axis` | `'x' \| 'y'` | When using `grid`, restrict the stagger wave to one axis. |
| `ease` | `string` | Ease applied to the stagger distribution itself (not the animation ease). |

```typescript
// 2D grid stagger — ripple from center
Motion('grid-ripple', '.grid-item', {
  from: { opacity: 0, scale: 0.7 },
  duration: 0.4,
  stagger: {
    each: 0.05,
    from: 'center',
    grid: 'auto',
  },
}).onScroll();
```

For the full SDK reference, see [Stagger in the SDK](/docs/sdk/stagger).

## Common patterns

### Cascade on page load

Enable **Stagger** with `each: 0.08`, `from: start`. Add **Opacity** and **Translate** on the **From** tab. Every element in the selector enters in sequence.

```typescript
Motion('list-in', '.list-item', {
  from: { opacity: 0, y: 24 },
  duration: 0.5,
  ease: 'power2.out',
  stagger: 0.08,
}).onPageLoad();
```

### Radiate from center

Set `from: center`. The middle element animates first, followed by its neighbors in both directions — useful for button groups or icon rows.

```typescript
Motion('nav-items', '.nav-item', {
  from: { opacity: 0, y: -10 },
  duration: 0.4,
  ease: 'power1.out',
  stagger: { each: 0.06, from: 'center' },
}).onPageLoad();
```

### Random reveal

Set `from: random` for an organic, unordered entrance. Elements appear in a shuffled sequence on every page load.

```typescript
Motion('gallery', '.gallery-item', {
  from: { opacity: 0, scale: 0.9 },
  duration: 0.5,
  ease: 'power2.out',
  stagger: { each: 0.07, from: 'random' },
}).onScroll();
```

### Stagger with Text Splitter

Combine **Stagger** with [Text Splitter](/docs/builder/split-text) to animate individual characters or words. Set `split: 'words'` and `stagger: 0.05` to reveal each word in sequence.

```typescript
Motion('headline', 'h1', {
  split: 'words',
  mask: true,
  from: { y: '110%' },
  duration: 0.6,
  ease: 'power3.out',
  stagger: { each: 0.06, from: 'start' },
}).onPageLoad();
```

## Related

- [From, To & Set](/docs/builder/from-to-set) — How functional properties relate to the animation mode tabs
- [Text Splitter](/docs/builder/split-text) — Animate individual characters, words, or lines with stagger
- [Ease](/docs/builder/easing) — Control the acceleration of individual elements
- [Repeat](/docs/builder/repeat) — Loop animations with optional yoyo
- [Stagger in the SDK](/docs/sdk/stagger) — Full SDK reference for the `stagger` option

---

## What is the Builder

> Overview of the Motion.page visual animation builder — available as a WordPress plugin and Desktop app.

URL: https://motion.page/docs/builder/overview

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import Steps from "../../components/docs/blocks/Steps.astro";

**Motion.page Builder** is a visual animation editor that lets you design, preview, and publish production-ready animations — no code required. Every animation you configure is powered by the Motion.page SDK.

{/* Screenshot: Full builder workspace showing Left Panel, Frame View, Timeline Editor, and Top Panel */}
![Motion.page Builder workspace — Left Panel, Frame View, Timeline Editor, and Top Panel](/images/builder/overview-workspace.webp)

---

## How It Works

<Steps>

1. **Select an element**

   Click any element in the Frame View. The Left Panel loads its animation settings.

2. **Configure the animation**

   Choose what to animate (opacity, position, scale, color, SVG strokes, text, and more) and set your values in the From, To, or Set tabs.

3. **Pick a trigger**

   Scroll into view, hover, click, page load, mouse movement, gesture, or custom cursor. Each trigger has its own set of controls in the Left Panel.

4. **Publish**

   Hit publish. Motion.page injects the animation runtime and your configuration. Done.

</Steps>

{/* Screenshot: Left Panel showing animation properties configured on an element — opacity, translate Y, and page load trigger selected */}
![Left Panel — animation properties and trigger configured on a selected element](/images/builder/overview-left-panel-configured.webp)

---

## What You Can Animate

### Visual Properties

Configure in the **From**, **To**, or **Set** tabs of any animation node:

| Property | What It Does |
|----------|-------------|
| **Opacity** | Fade in & out |
| **Translate** | Move on X and/or Y axis |
| **Scale** | Grow or shrink — uniform or per-axis |
| **Rotation** | Rotate on any axis; positive = clockwise |
| **3D Transform** | Rotate and transform on the 3D plane |
| **Skew** | Shear distortion on X and/or Y |
| **Dimensions** | Animate width and/or height |
| **Background Color** | Animate the background color |
| **Text Color** | Animate the font color |
| **Border Color** | Animate the border color |
| **Filter** | Blur, grayscale, brightness, and other CSS filters |
| **Background Position** | Animate background-position for parallax effects |
| **Transform Origin** | Set the pivot point for transform animations |
| **Custom** | Any animatable CSS property or CSS variable |

### Special Effects

These live in the **Functional** section — direction-agnostic and shared across From/To:

| Effect | What It Does |
|--------|-------------|
| **Animate SVG** | DrawSVG stroke reveal plus stroke/fill color animation |
| **Lottie** | Sync a Lottie animation with the timeline |
| **Image Sequence** | Play a frame sequence on any trigger |
| **Text Splitter** | Split into chars, words, or lines and stagger each piece |
| **Text Flapper** | Solari split-flap board effect cycling through characters |
| **Fit** | FLIP morphing — animate an element toward another's position and size |
| **Motion Path** | Move any element along an SVG path |
| **Stagger** | Offset timing across multiple targets |
| **Repeat** | Loop any number of times or infinitely, with optional yoyo |
| **Ease** | Choose from any easing curve |

---

## Triggers

Every animation needs a trigger. The builder covers the full set:

| Trigger | Description |
|---------|-------------|
| **Page Load** | Plays as soon as the page JS loads |
| **Scroll** | Plays on scroll-into-view, scrubs with the scrollbar, or pins in place |
| **Hover** | Plays on mouse enter — reverse, restart, or hold on leave |
| **Click** | Plays on click — reverse or restart on second click |
| **Mouse Movement** | Timeline progress tracks cursor position |
| **Gesture / Observer** | Responds to pointer, touch, wheel, and scroll gestures |
| **Cursor** | Custom animated cursor with hover and pressed states |
| **Page Exit** | Plays when a link is clicked, before the page navigates away |
| **Presentation Mode** | Full-page section scrolling with transition effects |

---

This is the kind of animation the Builder produces — a staggered card reveal on page load:

<LivePreview client:load
  height={260}
  title="Staggered card reveal"
  html={`<div class="grid">
  <div class="card">Heading</div>
  <div class="card">Features</div>
  <div class="card">Pricing</div>
</div>`}
  css={`.grid {
  display: flex;
  gap: 16px;
  justify-content: center;
  align-items: center;
  height: 100%;
}
.card {
  width: 100px;
  height: 120px;
  background: #1a1a2e;
  border: 1px solid #6633ee44;
  border-radius: 12px;
  display: flex;
  align-items: center;
  justify-content: center;
  color: #dfe1f4;
  font-family: system-ui;
  font-size: 13px;
  font-weight: 500;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("card-reveal", ".card", {
  from: { opacity: 0, y: 32 },
  duration: 0.6,
  stagger: 0.12,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

In the builder, this is three clicks: select the cards, set `from: { opacity: 0, y: 32 }`, add a stagger, and pick **Page Load** as the trigger.

---

## Two Ways to Run It

### WordPress Plugin

Install Motion.page as a WordPress plugin. The builder opens directly in the admin dashboard — click **Edit with Motion.page** on any page or post. Animations attach to your existing WordPress content and are published alongside it.

→ [WordPress Installation](/docs/builder/wordpress-integration)

### Desktop App

The standalone Electron app works with any website — WordPress, Webflow, custom HTML, or anything else. Open a URL in the Frame View, build animations, and export the output to embed wherever you need it.

→ [Desktop Installation](/docs/builder/desktop-overview)

---

## Under the Hood

The Builder generates **SDK code** for every animation you configure. There is no proprietary runtime format — what gets published is clean `@motion.page/sdk` calls that you can read, copy, and extend.

<CodeBlock
  filename="Generated SDK output"
  lang="typescript"
  code={`Motion('hero-reveal', '.hero-section', {
  from: { opacity: 0, y: 40 },
  split: 'words',
  stagger: 0.06,
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad();`}
/>

If you ever outgrow the builder's UI, take the generated code and continue in your editor. No lock-in.

---

## Next Steps

- [WordPress Installation](/docs/builder/wordpress-integration) — install the plugin and open the builder
- [Desktop Installation](/docs/builder/desktop-overview) — set up the Electron app
- [From, To & Set](/docs/builder/from-to-set) — the three animation modes explained
- [SDK Overview](/docs/sdk/overview) — use the SDK directly without the builder

---

## 3D Transforms

> Apply 3D perspective transforms to elements in the builder.

URL: https://motion.page/docs/builder/3d-transforms

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**3D Transforms** rotate and position elements in three-dimensional space by applying perspective, X/Y/Z rotations, and depth. Use them to build card flips, perspective tilts, barrel rolls, and any effect that makes an element feel like it exists in physical space rather than on a flat screen.

## Where to find it

**Left Panel → Animation tab → 3D Transform**

Enable the **3D Transform** toggle to expand the controls. The section reveals inputs for three rotation axes — X, Y, and Z.

{/* Screenshot: 3D Transform section expanded in the Left Panel Animation tab, showing rotationX, rotationY, and rotationZ controls */}
![3D Transform controls expanded in the Left Panel](/images/builder/3d-transforms-controls.webp)

## Controls

| Control | Unit | Description |
|---------|------|-------------|
| **Rotation X** | `deg` | Tilts the element toward or away from the viewer around the horizontal axis. Positive = top tilts away, negative = top tilts toward the viewer. |
| **Rotation Y** | `deg` | Spins the element around the vertical axis. `180` rotates it to face backward — the back face of a card flip. |
| **Rotation Z** | `deg` | Rotates the element in the flat plane (identical to the 2D `rotation` property). |

Rotation inputs accept values from `−360` to `360`. Type directly into the input for values outside that range (e.g. `−720` for a double spin).

## From mode — 3D entrances

In **From** mode, the values you set are the **starting transform**. The element animates from that 3D state toward its natural CSS position.

Set `rotationY` to `90` in From to make an element swing in from the side — like a door opening. Set `rotationX` to `−30` and add `transformPerspective: 600` in your SDK code for a perspective tilt-down entrance.

{/* Screenshot: 3D Transform section in From mode with rotationY set to 90 — card swing-in setup */}
![3D Transform in From mode — rotationY 90 for a swing-in entrance](/images/builder/3d-transforms-from-rotationY.webp)

## To mode — flips and tilt effects

In **To** mode, the values you set are the **ending transform**. The element animates from its natural CSS position toward the 3D state you define.

Set `rotationY` to `180` in To for a card-flip exit. Combine with a paired second element (the card back) for a classic double-sided flip. Use `rotationX` at a small value like `5` in To with a Hover trigger and **Reverse on leave** for a subtle perspective tilt that responds to mouse hover.

{/* Screenshot: 3D Transform section in To mode with rotationY set to 180 — card flip exit setup */}
![3D Transform in To mode — rotationY 180 for a card flip](/images/builder/3d-transforms-to-flip.webp)

<LivePreview client:load
  height={280}
  title="3D card flip"
  html={`<div class="scene">
  <div class="card-wrap">
    <div class="face front">Front</div>
    <div class="face back">Back</div>
  </div>
  <button class="btn">Flip</button>
</div>`}
  css={`.scene {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 24px;
  height: 100%;
  font-family: system-ui;
  perspective: 800px;
}
.card-wrap {
  width: 140px;
  height: 90px;
  position: relative;
  transform-style: preserve-3d;
}
.face {
  position: absolute;
  inset: 0;
  border-radius: 12px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: 700;
  font-size: 15px;
  backface-visibility: hidden;
}
.front {
  background: #6633ee;
  color: #fff;
}
.back {
  background: #13103a;
  border: 1.5px solid #6633ee;
  color: #a990ff;
  transform: rotateY(180deg);
}
.btn {
  padding: 6px 20px;
  border: none;
  border-radius: 6px;
  background: #222;
  color: #fff;
  cursor: pointer;
  font-size: 13px;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("flip", ".card-wrap", {
  to: { rotateY: 180 },
  duration: 0.7,
  ease: "power2.inOut",
}).onClick({ target: ".btn", toggle: "reverse" });`}
/>

The card uses `transform-style: preserve-3d` so both faces share the same 3D space. The back face starts at `rotateY(180deg)` and `backface-visibility: hidden` keeps each face invisible when it faces away from the viewer.

## SDK equivalent

3D Transform properties map directly to SDK property names. The builder exposes `rotationX`, `rotationY`, and `rotationZ`. The SDK also supports `perspective`, `transformPerspective`, and `transformStyle` — set those in code when you need perspective depth or `preserve-3d`.

**Card flip (From mode — swing in):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('card-flip', '.card', {
  from: { rotationY: 180, transformPerspective: 800 },
  duration: 1,
  ease: 'power2.inOut',
}).onScroll();
```

**Perspective tilt-down entrance:**

```typescript
Motion('tilt-in', '.hero-card', {
  from: { rotationX: -40, transformPerspective: 600, opacity: 0 },
  duration: 0.8,
  ease: 'power3.out',
}).onPageLoad();
```

**Hover perspective tilt (To mode):**

```typescript
Motion('tilt-hover', '.feature-card', {
  to: { rotationX: 6, rotationY: -8, transformPerspective: 700 },
  duration: 0.4,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Full barrel roll on scroll:**

```typescript
Motion('barrel-roll', '.icon', {
  from: { rotationY: -90, opacity: 0, transformPerspective: 500 },
  duration: 0.6,
  ease: 'back.out(1.5)',
}).onScroll();
```

For the complete reference see [3D Transforms in the SDK](/docs/sdk/3d-transforms).

## Common patterns

### Card flip reveal on scroll

Enable **3D Transform** on the **From** tab. Set `rotationY` to `90`. Add **Opacity** at `0` on the same tab. Set the trigger to **Scroll**. In your CSS or SDK code, add `transformPerspective: 800` for depth. Cards swing into view as they enter the viewport.

```typescript
Motion('card-reveal', '.card', {
  from: { rotationY: 90, transformPerspective: 800, opacity: 0 },
  duration: 0.7,
  ease: 'power2.out',
}).onScroll();
```

### Perspective tilt on hover

Set `rotationX` and `rotationY` to small values on the **To** tab with a Hover trigger and **Reverse on leave** enabled. Add `transformPerspective` in your SDK code for depth. The card subtly tilts toward the cursor and snaps back when the mouse leaves.

```typescript
Motion('card-tilt', '.card', {
  to: { rotationX: 8, rotationY: -10, transformPerspective: 600 },
  duration: 0.35,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### 3D staggered list

Combine **3D Transform** with **Stagger**. Set `rotationX` to `−60` in From mode and add `transformPerspective: 500` in your SDK code. Each list item unfolds from above in sequence, like turning pages.

```typescript
Motion('list-unfold', '.list-item', {
  from: { rotationX: -60, transformPerspective: 500, opacity: 0 },
  duration: 0.55,
  ease: 'power3.out',
  stagger: 0.08,
}).onScroll();
```

### Spin-in icon

Set `rotationY` to `−360` in From mode. Add `transformPerspective: 400` in your SDK code for depth. The element completes a full spin before settling into its natural facing direction.

```typescript
Motion('spin-in', '.logo', {
  from: { rotationY: -360, transformPerspective: 400, opacity: 0 },
  duration: 1,
  ease: 'power2.out',
}).onPageLoad();
```

## Tips

- **`perspective` vs `transformPerspective`** (SDK / CSS) — `perspective` is a CSS property applied to the parent; all children share the same vanishing point. `transformPerspective` applies depth independently to each element — useful when elements are far apart in the DOM. Set these in your CSS or SDK code; they are not exposed in the builder UI.
- **Lower perspective = more dramatic depth.** `400px` feels exaggerated; `1200px` feels gentle. Start at `800px` and adjust to taste.
- **`transform-style: preserve-3d`** — set this in CSS on any container whose children need to share a 3D space (e.g. the wrapper of a two-sided card).
- **`backface-visibility: hidden`** (set in CSS, not the builder) hides a face when it rotates past 90°. Essential for clean two-sided card flips.
- **Combine rotations sparingly.** Rotating on multiple axes simultaneously produces gimbal effects that can look unnatural. For most UI work, stick to one or two axes.
- **Double-click** any input to reset its value.
- Pair `rotationX` or `rotationY` entrances with [Opacity](/docs/builder/opacity) at `0` — the fade masks the start of the rotation so it feels less abrupt.

## Related

- [3D Transforms in the SDK](/docs/sdk/3d-transforms) — Full SDK reference for `rotationX`, `rotationY`, `rotationZ`, `transformPerspective`, and `transformStyle`
- [Rotation](/docs/builder/rotation) — Flat 2D rotation (`rotationZ`) without perspective
- [Transform Origin](/docs/builder/transform-origin) — Change the pivot point for rotations and scale
- [Scale](/docs/builder/scale) — Grow or shrink elements; pairs well with 3D entrances
- [Translate](/docs/builder/translate) — Move elements on X, Y, and Z axes
- [Ease](/docs/builder/easing) — Control the motion curve; `power2.inOut` and `back.out` suit most 3D effects

---

## From, To & Set

> Understand the three animation modes and how to switch between them.

URL: https://motion.page/docs/builder/from-to-set

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

Every animation node in the builder operates in one of three modes: **From**, **To**, or **Set**. These modes control which endpoint of the animation you're defining — and which endpoint Motion.page reads automatically from the element's live CSS.

## The From / To / Set toggle

The toggle lives in the **Left Panel → Animation tab**, just above the list of animation properties. It's a three-way switch that shows which mode is currently active.

{/* Screenshot: From/To/Set three-way toggle in the Left Panel Animation tab, showing the active "From" state with a dot indicator on the From button */}
![From/To/Set toggle — three-way switch in the Left Panel Animation tab](/images/builder/from-to-set-toggle.webp)

Click **From**, **To**, or **Set** to switch modes. A dot indicator appears on the button when that mode has properties configured. The property controls below the toggle always reflect the active mode's values.

## The three modes

### From

**From** defines the **starting state** of the animation. The element animates FROM these values toward its natural CSS state (or toward any values you've set in the To tab).

This is the most common mode for **entrance animations** — fade-ins, slide-ins, reveals. Set `opacity` to `0` and the element fades in from invisible to whatever its CSS opacity is. Set `y` to `60` and the element slides up into position.

> Add animation properties as 'FROM'. They will be a starting point of your animation, while an ending point are current values of the element or 'To' properties.

{/* Screenshot: From mode active, with Opacity property expanded and value set to 0 — showing a classic fade-in entrance setup */}
![From mode — opacity set to 0 for a fade-in entrance](/images/builder/from-to-set-from-opacity-0.webp)

SDK equivalent:

```typescript
import { Motion } from '@motion.page/sdk';

// Fade in: element starts at opacity 0, animates to its natural CSS opacity
Motion('fade-in', '.hero', {
  from: { opacity: 0, y: 60 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad();
```

### To

**To** defines the **ending state** of the animation. The element animates FROM its natural CSS state (or From values) TO these values.

Use **To** for **hover effects**, **exit animations**, or any situation where the element starts in its natural position and moves away from it.

> Add animation properties as 'TO'. They will be an ending point of your animation, while a starting point are current values of the element or 'From' properties.

{/* Screenshot: To mode active, with Translate property expanded and Y value set to -10 — showing a hover lift setup */}
![To mode — y set to -10 for a hover lift effect](/images/builder/from-to-set-to-y-minus10.webp)

SDK equivalent:

```typescript
// Lift on hover: element starts at its natural position, moves up 10px
Motion('card-hover', '.card', {
  to: { y: -10, boxShadow: '0 16px 32px rgba(0,0,0,0.15)' },
  duration: 0.3,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Set

**Set** immediately applies property values with **no animation**. It acts as a zero-duration tween — the element snaps to the specified values the instant the timeline runs.

> Add properties as 'SET'. Acts as a zero-duration 'TO' tween, which immediately sets properties of the target(s) with no animation.

Use Set for:
- **Initial state setup** — hide or reposition elements before a sequence begins
- **Instant state changes** — snap to a new state without a visible transition
- **Resetting properties** between animation steps in a multi-node timeline

```typescript
// Immediately set opacity to 0 — no fade, instant hide
Motion.set('.overlay', { opacity: 0 });
```

## Using From and To together

You can configure **both From and To simultaneously** on the same animation node. Switch between the tabs to set values on each side — both will be active at the same time.

Use this when **neither endpoint matches the element's natural CSS state**:

```typescript
// Parallax: element travels from -50px to +50px — neither end is the natural position
Motion('parallax', '.section-image', {
  from: { y: -50 },
  to:   { y: 50 },
  duration: 1,
}).onScroll({ scrub: true });
```

When both are set, the SDK uses your explicit values for both endpoints instead of reading from the element's CSS.

## Implicit values (how the SDK fills in the missing endpoint)

When you configure only **From**, Motion.page reads the element's current CSS as the **To** endpoint automatically. When you configure only **To**, the element's current CSS becomes the **From** endpoint.

This means you almost never need to write redundant natural values:

| What you configure | What the SDK uses |
|--------------------|-------------------|
| `from` only | `to` = element's live CSS |
| `to` only | `from` = element's live CSS |
| Both | Both endpoints are explicit |

**Natural CSS defaults** that you never need to specify in `to`:
`opacity: 1` · `x: 0` · `y: 0` · `z: 0` · `scale: 1` · `rotate: 0`

```typescript
// ✅ Correct — drop the redundant to
Motion('reveal', '.card', {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
});

// ❌ Redundant — opacity:1 and y:0 are natural defaults
Motion('reveal', '.card', {
  from: { opacity: 0, y: 40 },
  to:   { opacity: 1, y: 0 },   // unnecessary
  duration: 0.6,
});
```

<LivePreview client:load
  height={240}
  title="From vs To"
  html={`<div class="demo">
  <div class="label">From (fade in)</div>
  <div class="box from-box"></div>
  <div class="label">To (fade out)</div>
  <div class="box to-box"></div>
</div>`}
  css={`.demo { display: flex; flex-direction: column; align-items: center; gap: 10px; padding: 20px; font-family: system-ui; }
.label { font-size: 12px; color: #888; margin-bottom: -4px; }
.box { width: 160px; height: 36px; border-radius: 8px; }
.from-box { background: #6633EE; }
.to-box { background: #FF6633; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("from-demo", ".from-box", {
  from: { opacity: 0, y: 16 },
  duration: 0.7,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();

Motion("to-demo", ".to-box", {
  to: { opacity: 0.2, y: -12 },
  duration: 0.7,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The **purple box** uses `from: { opacity: 0, y: 16 }` — it starts hidden and slides into its natural position. The **orange box** uses `to: { opacity: 0.2, y: -12 }` — it starts in its natural position and animates away.

## Context menu options

Right-click on the **From** or **To** label to access extra operations:

| Option | Description |
|--------|-------------|
| **Duplicate** | Copy all properties from this tab into the opposite tab (From → To, or To → From) |
| **Toggle** | Swap all properties between From and To — useful when you set them on the wrong tab |
| **Clear** | Remove all properties from this tab |
| **Copy** | Copy the tab's properties to clipboard (compressed) |
| **Paste** | Paste previously copied properties into this tab |

Right-clicking the **Set** tab exposes Duplicate, Clear, Copy, and Paste (Toggle is not applicable to Set).

## Functional properties are shared

Properties in the **Functional** section — such as [Stagger](/docs/builder/stagger), [Repeat](/docs/builder/repeat), [Ease](/docs/builder/easing), [Text Splitter](/docs/builder/split-text), and [Fit](/docs/builder/fit) — are **direction-agnostic**. They appear and behave the same regardless of which tab is active. Changing them on the From tab has the same effect as changing them on the To tab.

## Related

- [Opacity](/docs/builder/opacity) — fade in/out using From or To
- [Translate](/docs/builder/translate) — slide elements on X and Y
- [Scale](/docs/builder/scale) — grow or shrink elements
- [Ease](/docs/builder/easing) — control acceleration and deceleration
- [From / To resolution in the SDK](/docs/sdk/core-concepts)

---

## Dimensions

> Animate width and height of elements in the builder.

URL: https://motion.page/docs/builder/dimensions

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Dimensions** animates the width and/or height of an element — from a fixed value to `auto`, between two explicit sizes, or expanding from zero. Use it to build expand/collapse reveals, content drawers, and size-based entrance effects.

## Where to find it

**Left Panel → Animation tab → Dimensions**

Enable the **Dimensions** toggle to expand the controls. The section shows two numeric inputs — **Width** and **Height** — each paired with its own unit selector.

{/* Screenshot: Dimensions section expanded in the Left Panel Animation tab, showing Width and Height inputs with unit selectors */}
![Dimensions controls — Width and Height inputs with unit selectors](/images/builder/dimensions-controls.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Width** | Target width of the element. Leave empty to leave width unchanged. |
| **Height** | Target height of the element. Leave empty to leave height unchanged. |
| **Unit selector** | Click the unit label next to each input to cycle through available units. |

Each input has its own independent unit selector. Clicking the unit label cycles through the available options:

| Unit | Description |
|------|-------------|
| `px` | Absolute pixels |
| `%` | Percentage of the parent element's dimension |
| `em` | Relative to the element's font size |
| `rem` | Relative to the root font size |
| `vw` | Percentage of viewport width |
| `vh` | Percentage of viewport height |
| `vmin` | Percentage of the smaller viewport dimension |
| `vmax` | Percentage of the larger viewport dimension |
| `auto` | Natural content size — browser resolves the dimension at runtime |

You can animate **Width** only, **Height** only, or both at once. Leave an input empty to keep that dimension unchanged.

## From mode

In **From** mode, the values you set are the **starting dimensions**. The element animates from those sizes toward its natural CSS width and height.

Set **Width** to `0` in From to make an element grow in from nothing horizontally. Combine **Width** and **Height** both at `0` for a corner-expand reveal.


## To mode

In **To** mode, the values you set are the **ending dimensions**. The element animates from its natural CSS size to the values you specify.

Set **Height** to `0` in To for a collapse-out exit. Set **Width** to `auto` in To to let an element expand to its full content width from a fixed starting size — useful for drawers and accordions.


<LivePreview client:load
  height={240}
  title="Dimensions expand"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 220px; height: 120px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("expand", ".box", {
  from: { width: 60, height: 60 },
  duration: 0.8,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts at `60 × 60 px` (the **From** values) and expands to `220 × 120 px` — its natural CSS size.

## SDK equivalent

The `width` and `height` properties map directly to the SDK's `from` and `to` objects.

**Expand from zero (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('expand', '.panel', {
  from: { width: 0, height: 0 },
  to: { width: 300, height: 200 },
  duration: 0.8,
  ease: 'power2.out',
}).onPageLoad();
```

**Collapse to zero (To mode):**

```typescript
Motion('collapse', '.drawer', {
  to: { height: 0 },
  duration: 0.5,
  ease: 'power2.in',
}).onClick({ selector: '.close-btn' });
```

**Animate to `auto` — natural content height:**

```typescript
// Expand an accordion panel to its full content height
Motion('accordion-open', '.panel', {
  from: { height: 0 },
  to:   { height: 'auto' },
  duration: 0.4,
  ease: 'power2.out',
}).onClick({ selector: '.accordion-trigger' });
```

For the full SDK reference, see [Dimensions in the SDK](/docs/sdk/dimensions).

## Common patterns

### Grow in from zero

Enable **Dimensions** on the **From** tab, set both Width and Height to `0`. The element expands from a single point to its natural size.

```typescript
Motion('grow-in', '.card', {
  from: { width: 0, height: 0 },
  duration: 0.6,
  ease: 'power2.out',
}).onPageLoad();
```

### Horizontal wipe reveal

Set **Width** to `0` in From only. The element grows in from left to right, revealing its content. Combine with `overflow: hidden` on the element.

```typescript
Motion('wipe-right', '.banner', {
  from: { width: 0 },
  duration: 0.7,
  ease: 'power3.out',
}).onScroll();
```

### Collapse on exit

Set the trigger to **Click**. Enable **Height** on the **To** tab and set it to `0`. The element collapses vertically when the trigger fires.

```typescript
Motion('dismiss', '.notification', {
  to: { height: 0 },
  duration: 0.35,
  ease: 'power2.in',
}).onClick({ selector: '.dismiss-btn' });
```

### Expand to auto height

Animate from a fixed `height` to `auto` to let an element grow to fit its full content — the ideal pattern for accordions and expandable sections.

```typescript
Motion('accordion', '.panel', {
  from: { height: 0 },
  to:   { height: 'auto' },
  duration: 0.4,
  ease: 'power2.out',
}).onClick({ selector: '.trigger', each: true });
```

## Tips

- **Width and height cause layout reflow** — animating these properties forces the browser to recalculate surrounding layout on every frame. For purely visual size changes (where document flow is not involved), prefer [Scale](/docs/builder/scale), which runs entirely on the GPU without triggering layout.
- **`auto` is supported as a target value** — animate from a fixed value to `auto` for natural content sizing. This is the standard approach for accordion and drawer patterns.
- **Use `overflow: hidden`** on the animated element (or a wrapper) when collapsing to `0`, otherwise content will overflow during the animation.
- **Double-click** an input to clear the value and disable that dimension.
- Dimensions can be combined with [Opacity](/docs/builder/opacity) for a fade-and-expand entrance: `from: { opacity: 0, width: 0 }`.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Dimensions in the SDK](/docs/sdk/dimensions) — SDK reference for `width` and `height` properties
- [Scale](/docs/builder/scale) — GPU-accelerated size change — prefer over Dimensions when layout impact is not needed
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Opacity](/docs/builder/opacity) — Fade in/out, often combined with Dimensions
- [Ease](/docs/builder/easing) — Control the motion curve

---

## Skew

> Apply skew distortion to elements on the 2D plane.

URL: https://motion.page/docs/builder/skew

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Skew** distorts an element by tilting it along the horizontal and vertical axes — a shear mapping (transvection) that shifts each point within the element by a given angle. It is the right tool for diagonal reveals, perspective hints, and motion-design flourishes where a straight element feels too flat.

## Where to find it

**Left Panel → Animation tab → Skew**

Enable the **Skew** toggle to expand the controls. Two numeric inputs appear — **skewX** and **skewY** — each accepting degree values.

{/* Screenshot: Skew section expanded in the Left Panel Animation tab, showing skewX and skewY numeric inputs */}
![Skew controls — skewX and skewY degree inputs](/images/builder/skew-controls.webp)

## Controls

| Control | Description |
|---------|-------------|
| **skewX** | Horizontal shear angle in degrees. Positive values tilt the element's top edge to the right; negative values tilt it to the left. |
| **skewY** | Vertical shear angle in degrees. Positive values tilt the element's left edge downward; negative values tilt it upward. |

Both inputs accept any numeric degree value. Typical working range is `−45` to `45` — values beyond that produce extreme distortions. Double-click an input to clear it.

## From mode — skewed entrance

In **From** mode, the values you set are the **starting distortion**. The element animates from that skewed state toward its natural, undistorted shape.

Set `skewX` to `12` in From mode to make an element appear to slide in at an angle and straighten as it settles. This reads as a confident, directional entrance — common in editorial and hero sections.

{/* Screenshot: Skew section in From mode with skewX set to 12 — angled entrance setup */}
![Skew in From mode — skewX set to 12 for an angled entrance](/images/builder/skew-from-x12.webp)

## To mode — skew on interaction

In **To** mode, the values you set are the **ending distortion**. The element animates from its natural shape toward the skew angle you specify.

Set `skewX` to `−8` in To mode paired with a **Hover** trigger to give a button or card a dynamic lean on hover. Enable **Reverse on leave** to return to the natural shape when the cursor exits.

{/* Screenshot: Skew section in To mode with skewX set to -8 — hover lean setup */}
![Skew in To mode — skewX set to -8 for a hover lean effect](/images/builder/skew-to-x-minus8.webp)

<LivePreview client:load
  height={220}
  title="Skew entrance"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 120px; height: 120px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("skew-in", ".box", {
  from: { skewX: 18, opacity: 0 },
  duration: 0.6,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box uses `from: { skewX: 18, opacity: 0 }` — it starts tilted 18° and invisible, then straightens and fades in as it settles into its natural position.

## SDK equivalent

Skew maps directly to the `skewX` and `skewY` properties in the SDK. Values are plain numbers representing degrees — no unit suffix needed.

```typescript
import { Motion } from '@motion.page/sdk';

// Skewed entrance — straightens on play (From mode)
Motion('skew-in', '.card', {
  from: { skewX: 12 },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll();
```

**Combine with opacity and translate for a fuller entrance:**

```typescript
Motion('skew-reveal', '.hero-title', {
  from: { skewX: 10, opacity: 0, y: 30 },
  duration: 0.7,
  ease: 'power3.out',
}).onPageLoad();
```

**Hover lean (To mode):**

```typescript
Motion('hover-lean', '.cta-button', {
  to: { skewX: -6 },
  duration: 0.25,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Both axes — diagonal warp effect:**

```typescript
// Animate from a diagonal warp to the element's natural shape
Motion('warp-in', '.panel', {
  from: { skewX: 8, skewY: 4, opacity: 0 },
  duration: 0.8,
  ease: 'power3.out',
}).onPageLoad();
```

For the full SDK reference, see [Skew in the SDK](/docs/sdk/skew).

## Common patterns

### Angled scroll reveal

Enable **Skew** on the **From** tab, set `skewX` to `10`. Add **Opacity** at `0` on the same tab. Set the trigger to **Scroll**. Elements tilt in and straighten as they enter the viewport.

```typescript
Motion('scroll-skew', '.feature-card', {
  from: { skewX: 10, opacity: 0 },
  duration: 0.65,
  ease: 'power2.out',
}).onScroll();
```

### Directional slide with skew

Combine **Translate** and **Skew** in From mode so the element moves and straightens simultaneously. The skew reinforces the direction of travel and gives the motion a sense of momentum.

```typescript
Motion('slide-skew', '.section-heading', {
  from: { x: -60, skewX: 12, opacity: 0 },
  duration: 0.7,
  ease: 'power3.out',
}).onScroll();
```

### Hover lean on cards

Set the trigger to **Hover**, enable **Skew** on the **To** tab, set `skewX` to `-5`. Enable **Reverse on leave**. Cards lean slightly as the cursor enters and return to straight on exit.

```typescript
Motion('card-lean', '.card', {
  to: { skewX: -5 },
  duration: 0.3,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Staggered skew list reveal

Enable **Stagger** alongside Skew and Opacity in From mode. Each list item straightens in sequence, creating a cascading wave of motion.

```typescript
Motion('list-reveal', '.list-item', {
  from: { skewX: 8, opacity: 0 },
  duration: 0.5,
  ease: 'power2.out',
  stagger: { each: 0.08 },
}).onScroll();
```

## Tips

- **`skewX` vs `skewY`** — `skewX` is the more visually familiar axis for most UI animations; `skewY` alone can look unnatural unless you're deliberately building a perspective-shift or italic effect.
- **Keep angles modest** — values between `5°` and `20°` read as dynamic; beyond `30°` the distortion becomes hard to read.
- **Skew is applied around the [Transform Origin](/docs/builder/transform-origin)** — adjusting the origin lets you control which part of the element stays anchored during distortion.
- **Pair with Translate** to reinforce directionality: a rightward slide (`x: 60`) reads even more convincingly when paired with a slight `skewX` in the same direction.
- **Combine with Opacity** — a skew alone on an entrance can look abrupt. Adding `opacity: 0` to the From tab softens the start.
- **Double-click** an input to reset the value.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Skew in the SDK](/docs/sdk/skew) — SDK reference for the `skewX` and `skewY` properties
- [Rotation](/docs/builder/rotation) — Rotate elements in 2D and 3D
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Scale](/docs/builder/scale) — Grow or shrink elements
- [Transform Origin](/docs/builder/transform-origin) — Change the anchor point for transforms
- [Ease](/docs/builder/easing) — Control acceleration and deceleration

---

## Desktop App Overview

> Features of the standalone desktop application.

URL: https://motion.page/docs/builder/desktop-overview

import Steps from "../../components/docs/blocks/Steps.astro";

**Motion.page Desktop** is a standalone Electron app that brings the full builder to any website — no WordPress installation required. Point it at any URL, build animations, and publish them to a Convex-backed cloud that serves your site.

{/* Screenshot: Project Dashboard showing the grid of project cards with thumbnails, the sidebar tabs (Projects, Artifacts, Canvas, Community), and the top bar with user avatar and search */}
![Desktop app project dashboard — grid of project cards with thumbnails](/images/builder/desktop-overview-dashboard.webp)

---

## What makes it different

The WordPress plugin attaches to a WordPress site. The desktop app is site-agnostic — it loads any URL in a built-in browser window and layers the animation builder on top. You can use it with:

- Static HTML sites and local development servers
- Webflow, Framer, Shopify, or any hosted platform
- Custom React, Next.js, or Nuxt apps
- WordPress sites (as an alternative to the plugin)

Animations are saved to **Convex** cloud storage and delivered to the site via the [CDN](/docs/builder/cdn-delivery). No plugin, no server-side code needed.

---

## Project dashboard

When the desktop app opens, you land on the **Project Dashboard**. It has five tabs along the left sidebar:

| Tab | What it shows |
|-----|---------------|
| **Projects** | Your animation projects — each tied to a website URL |
| **Artifacts** | Self-contained HTML/CSS/JS components (see below) |
| **Canvas** | WebGPU canvas projects |
| **Community** | Shared community rooms and threads |
| **Notifications** | Alerts and activity for your account |

The **search bar** at the top filters cards in the active tab. Each card shows a live thumbnail captured from the last session.

---

## Projects

A **project** is the top-level unit. Each project stores:

- A **name** and **website URL** — the address loaded in the Frame View
- All **timelines** you create for that site
- A **thumbnail** auto-captured from the last session

Open a project to enter the builder. The Frame View loads the project URL and the Left Panel shows the Library for that site. All changes are synced to Convex and published on save.

Click the Motion.page logo in the Left Panel at any time to return to the Project Dashboard.

See [Workspace Overview](/docs/builder/workspace-overview) for the full builder interface reference.

---

## Artifacts

**Artifacts** are self-contained animation components — each is a bundle of HTML, CSS, and JavaScript that runs in isolation. Use them to:

- Prototype animation ideas without a real website
- Build reusable components (loaders, transitions, micro-interactions)
- Share interactive demos with the community

Each artifact renders in a sandboxed iframe with `@motion.page/sdk` pre-loaded, so you can use `Motion(...)` calls directly in the JS panel.

Artifacts can be kept **private** (only visible to you) or made **public** to appear in the Community tab, where other users can view, fork, and star them.

---

## How it connects to a website

The desktop app loads website URLs using Electron's `<webview>` tag with a custom session. This means:

- **Any URL works** — local (`http://localhost:3000`), staging, or production
- **The builder runtime is injected** automatically into the loaded page, the same way the WordPress plugin works
- **Element selection** works identically — click any element in the Frame View to target it with an animation

For the animations to run on the live site (outside the desktop app), the site must load the Motion.page runtime. See [CDN delivery](/docs/builder/cdn-delivery) for how to add the CDN snippet to any site.

---

## Cloud sync with Convex

All project data is stored in **Convex** — a real-time cloud backend. This means:

- Timelines and artifacts are available on any machine when you sign in
- Changes publish instantly to the CDN without manual exports
- The **Publish** button in the Left Panel footer pushes the current timeline to Convex

Authentication uses email sign-in. Create an account at [motion.page](https://motion.page) before launching the app.

---

## System requirements and platforms

Motion.page Desktop is available for:

| Platform | Format | Architecture |
|----------|--------|-------------|
| **macOS** | DMG | Intel (x64) and Apple Silicon (arm64) |
| **Windows** | NSIS installer | x64 and arm64 |
| **Linux** | AppImage | x64 |

Minimum requirements: a modern 64-bit OS with hardware-accelerated graphics for the WebGPU canvas features.

---

## Download and install

<Steps>

1. Download the installer

   Go to [motion.page](https://motion.page) and download the installer for your platform. Releases are also published on GitHub at [CoreBunch/Motion.page-Releases](https://github.com/CoreBunch/Motion.page-Releases).

2. Install the app

   **macOS** — Open the DMG, drag **Motion.page Desktop** to `/Applications`.

   **Windows** — Run the `.exe` installer and follow the setup wizard.

   **Linux** — Make the AppImage executable (`chmod +x Motion.page-Desktop-linux.AppImage`) and run it.

3. Sign in

   On first launch, enter your Motion.page account credentials. If you don't have an account, sign up at [motion.page](https://motion.page).

4. Create a project

   Click **+** in the Projects tab, enter a name and the URL of the website you want to animate, then click **Create**. The builder opens with the URL loaded in the Frame View.

</Steps>

---

## Next steps

- [Workspace Overview](/docs/builder/workspace-overview) — tour of the builder panels and how they work together
- [CDN delivery](/docs/builder/cdn-delivery) — add the runtime snippet to any site so published animations load

---

## Background Position

> Animate background position for parallax and sliding background effects in the builder.

URL: https://motion.page/docs/builder/background-position

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Background Position** animates the `background-position` CSS property of an element — shifting the background image or gradient along the X and Y axes. It is the primary tool for building parallax depth effects, sliding background reveals, and looping texture animations.

## Location

**Left Panel → Animation tab → Visual Properties → Background Position**


## Enable Background Position

Click the toggle next to **Background Position** to enable it. The row expands to reveal two numeric inputs — one for the X axis and one for the Y axis.

{/* Screenshot: Background Position row expanded, showing X and Y numeric inputs each with a unit toggle (% or px) */}
![Background Position control expanded — X and Y inputs with unit toggles](/images/builder/background-position-controls.webp)

## Controls

| Control | Unit | Default | Description |
|---------|------|---------|-------------|
| **X** | `%` or `px` | — | Horizontal background offset. Click the unit badge to toggle between `%` and `px`. |
| **Y** | `%` or `px` | — | Vertical background offset. Click the unit badge to toggle between `%` and `px`. |

Both inputs accept integers. Use the mouse wheel on a focused input to increment or decrement the value. Click the unit badge on either input to switch between percentage (`%`) and pixel (`px`) units.

`50%` places the background at the horizontal or vertical center. `0%` aligns it to the left/top. `100%` aligns it to the right/bottom. Pixel values shift the background by an absolute amount regardless of element size.

## From mode — parallax entrance

Switch to the **From** tab, enable Background Position, and set a Y value such as `-20` (`%`). The background starts shifted upward and eases into its natural CSS position on scroll or page load — the classic parallax entrance pattern.


Leave the X field empty if you only want vertical movement. Note the tip in the [Tips](#tips) section about setting up both fields for Y-only animations.

## To mode — sliding background

Switch to the **To** tab, enable Background Position, and set an X value such as `100` (`%`). The background slides horizontally from its natural CSS position to the target value. Use this for hover effects, looping marquee-style textures, or exit reveals.


<LivePreview client:load
  height={260}
  title="Background position parallax"
  html={`<div class="scene">
  <div class="panel"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; background: #111; }
.panel { width: 260px; height: 140px; border-radius: 14px; background: linear-gradient(135deg, #6633EE 0%, #FF6633 40%, #33CCFF 100%); background-size: 300% 300%; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("bg-position", ".panel", {
  from: { backgroundPosition: "0% 0%" },
  to: { backgroundPosition: "100% 100%" },
  duration: 1.2,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The gradient background shifts from `0% 0%` (**From** value) to `100% 100%` (**To** value), producing a smooth parallax-style colour sweep across the element.

## SDK equivalent

`background-position` is not directly animatable via the standard `from`/`to` keys. Use custom properties to animate it via the SDK.

See [Custom Properties](/docs/sdk/custom-properties).

## Common patterns

### Vertical parallax on scroll

Set the trigger to **Scroll** with **Scrub** enabled. Enable Background Position on the **From** tab, set Y to `-30` (`%`), and leave X empty. As the user scrolls, the background image shifts upward relative to the element, creating a depth illusion.

```typescript
Motion('parallax-bg', '.hero', {
  from: { backgroundPosition: '50% -30%' },
  duration: 1,
  ease: 'none',
}).onScroll({ scrub: true });
```

### Horizontal sliding background

Enable Background Position on the **To** tab, set X to `100` (`%`). Set the trigger to **Hover** with **Reverse on leave** enabled. The background texture slides horizontally on hover and returns on mouse out.

```typescript
Motion('slide-bg', '.card', {
  to: { backgroundPosition: '100% 50%' },
  duration: 0.6,
  ease: 'power2.inOut',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Looping background animation

Use **Repeat** with **Yoyo** enabled and **Times** set to `-1`. Set Background Position on the **To** tab with Y at `100` (`%`). The background cycles continuously — useful for animated gradients or looping texture panels.

```typescript
Motion('loop-bg', '.banner', {
  to: { backgroundPosition: '50% 100%' },
  duration: 3,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

### Combined parallax and fade entrance

Enable **Opacity** at `0` and **Background Position** Y at `-20` (`%`) on the **From** tab together. The section fades in while the background image rises — a subtle depth cue common in editorial hero sections.

```typescript
Motion('hero-reveal', '.hero-section', {
  from: { opacity: 0, backgroundPosition: '50% -20%' },
  duration: 1,
  ease: 'power3.out',
}).onPageLoad();
```

## Tips

- **Y-only animation requires both fields to be set.** If you only fill in the Y input and leave X empty, the background-position shorthand may resolve unexpectedly. Set the X value to your element's current natural X position (e.g. `50%`) alongside the Y value you want to animate. This is the behavior described in the builder tooltip.
- **`background-size` affects how position reads.** For parallax effects you almost always want `background-size: cover` or a size larger than the element — otherwise there is no overflow to reveal.
- **Percentage values are relative to the overflow area**, not the element. A value of `50%` centers the background regardless of image dimensions.
- **Pixel values** give precise, element-size-independent offsets — useful when you need exactly `20px` of shift rather than a proportional amount.
- Use **Scrub** on the Scroll trigger to tie background movement directly to the scroll position for the smoothest parallax feel.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Custom Properties](/docs/sdk/custom-properties) — SDK approach for animating background-position
- [Opacity](/docs/builder/opacity) — Combine with background position for layered reveal effects
- [Translate](/docs/builder/translate) — Move the element itself instead of its background
- [Repeat](/docs/builder/repeat) — Loop or yoyo background animations
- [Ease](/docs/builder/easing) — Control the motion curve for smooth parallax feel

---

## CDN & SDK Bundles

> Publish animations via CDN and manage custom SDK bundles.

URL: https://motion.page/docs/builder/cdn-delivery

import Steps from "../../components/docs/blocks/Steps.astro";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Publish** panel exports your animations in two ways: a single hosted script tag served via global CDN, or downloadable files you host yourself with a custom-built SDK bundle.

---

## Opening the Publish panel

The **Publish** button appears in the Left Panel footer — desktop app only.

**Left Panel → Footer → Publish**

The button is disabled until the current timeline has at least one animation node with a selector. Click it to open the Publish overlay.

{/* Screenshot: Publish overlay showing Cloud Hosting and Self-Hosted columns */}
![Publish overlay — CDN and self-hosted options](/images/builder/cdn-delivery-publish-overlay.webp)

---

## Cloud hosting (CDN)

The **Cloud Hosting** column is the recommended option. Your animations are bundled, uploaded to Convex storage, and served via a global CDN edge network.

**How it works:**

1. Save your timeline — the animation code is stored in the Convex backend.
2. Open the Publish panel. A ready-made `<script>` tag appears immediately.
3. Copy the tag and paste it into your site's `<head>`.

The tag points to a single JS file named after your project ID:

```html
<script src="https://<your-site>.convex.site/<project-id>.js?v=<version>"></script>
```

**What's inside the bundle:**

- Only the animations saved to the current project are included.
- Path-based filtering is applied at runtime — each page loads only the timelines assigned to it (plus any global timelines).
- The `?v=` cache-buster updates automatically every time you save, so visitors always get the latest version without you manually invalidating caches.

### Pages included

Below the script tag the panel lists every page path that has at least one animation, with a count of how many timelines are assigned to it. Global timelines are shown separately.

| Column | Meaning |
|--------|---------|
| Path | The URL path of the page (e.g. `/`, `/about`) |
| Count | Total number of timelines on that page |
| Global badge | How many of those timelines are marked as global |

---

## Self-hosted

The **Self-Hosted** column gives you the raw files to host on your own server. This is useful when you cannot load external scripts or need full control over asset delivery.

<Steps>

1. Download the SDK runtime

   Click **Download SDK** to get a minified JS file (`motion-sdk-YYYY-MM-DD.min.js`). This is the Motion.page SDK runtime — it must load before your animation code runs.

   Add it to your `<head>`:

   ```html
   <script src="/js/motion-sdk.min.js"></script>
   ```

   The SDK shown here is a **custom bundle** — it contains only the features your animations actually use. See [Custom SDK bundles](#custom-sdk-bundles) below.

2. Copy or download the animation code

   Select the scope from the dropdown, then copy or download the generated JS.

   | Scope | What it includes |
   |-------|-----------------|
   | **Current Timeline** | The timeline currently open in the builder |
   | **Current Page** | All saved timelines assigned to the current page |
   | **Entire Project** | All saved timelines across all pages in the project |

   Add this file before the closing `</body>` tag:

   ```html
   <script src="/js/motion-animation.min.js"></script>
   ```

3. Export image sequences (if present)

   If your timeline uses image sequences, a third step appears. Set the **Images base path** to match where you will place the image folders on your server (default: `/images/sequences/`), then click **Export Image Sequences** to download the folders as a zip.

   The animation code references images relative to the base path you enter here — set it before downloading the animation code.

</Steps>

---

## Custom SDK bundles

When you click **Download SDK** the builder does not give you the full SDK. It generates a **custom bundle** that includes only the modules your project actually uses.

The analysis runs over every saved timeline in the project and detects:

- **Triggers** — `pageLoad`, `scroll`, `hover`, `click`, `mouseMove`, `gesture`, `cursor`
- **Features** — `stagger`, `textSplit`

Unused modules are removed before the bundle is compiled. For simple animations (a few page-load fade-ins with no scroll triggers or text splitting) this can reduce the SDK size by up to **50%** compared to the full bundle.

The bundle info is shown next to the step heading when available:

```
4 modules · 18.3 KB
```

If the SDK bundle is not available, the Download SDK button will be disabled.

> **Tip:** The custom bundle is regenerated each time you open the Publish panel. Save all your timelines before exporting so every animation is reflected in the bundle.

---

## Script tag integration

Place the two tags in the correct order — SDK first, animation code second:

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Option A: CDN (recommended) -->
  <script src="https://<your-site>.convex.site/<project-id>.js?v=<version>"></script>

  <!-- Option B: Self-hosted SDK runtime -->
  <script src="/js/motion-sdk.min.js"></script>
</head>
<body>
  <!-- your page content -->

  <!-- Option B: Self-hosted animation code -->
  <script src="/js/motion-animation.min.js"></script>
</body>
</html>
```

For the CDN option, the single tag in `<head>` is all you need — the bundle includes both the SDK runtime and all animation code.

For the self-hosted option, loading the SDK in `<head>` and the animation code before `</body>` ensures the runtime is ready before the animations initialise.

---

## Related

- [SDK getting started — CDN section](/docs/sdk/getting-started#cdn--script-tag) — Load the SDK from a public CDN without a build step
- [Workspace overview](/docs/builder/workspace-overview) — Tour of all four builder regions including the footer
- [Library](/docs/builder/library) — Manage saved timelines and publish status across projects

---

## Rotation

> Rotate elements on X, Y, and Z axes with the builder rotation controls.

URL: https://motion.page/docs/builder/rotation

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Rotation** rotates an element by a given angle in degrees. Positive values spin clockwise; negative values spin counter-clockwise. The builder exposes a **Both Axis** mode (a single dial that rotates on both axes simultaneously) and a per-axis mode with **Rotate X** and **Rotate Y** inputs — so you can build anything from simple spin entrances to full perspective flips.

## Where to find it

**Left Panel → Animation tab → Rotation**

Enable the **Rotation** toggle to expand the controls. By default a **Both Axis** dial appears — drag it to rotate on both axes at once. Switch to per-axis mode to reveal separate **Rotate X** and **Rotate Y** inputs.

{/* Screenshot: Rotation section expanded in the Left Panel Animation tab, showing Both Axis dial and per-axis Rotate X / Rotate Y inputs */}
![Rotation controls — Both Axis dial and per-axis Rotate X / Rotate Y inputs](/images/builder/rotation-controls.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Both Axis** | A single dial that rotates the element on both axes simultaneously. Drag to set the angle. |
| **Rotate X** | Per-axis input — tilt forward/backward around the horizontal X-axis. Available in per-axis mode. |
| **Rotate Y** | Per-axis input — spin left/right around the vertical Y-axis. Available in per-axis mode. |

All inputs accept any angle in degrees. There is no enforced range — values beyond `360` or below `-360` produce multi-revolution animations. Type directly into the input for precise or fractional values.

{/* Screenshot: Rotation section in the Left Panel with Both Axis set to 360 */}
![Rotation control with Both Axis set to 360 degrees](/images/builder/rotation-z-360.webp)

## From mode — spin in

In **From** mode the values you set are the **starting angle**. The element animates from that rotation toward its natural CSS rotation (typically `0°`).

Set `rotation` to `-90` in From to make an element appear to rotate up into place from a 90° tilt. Set `rotationY` to `90` for a perspective flip-in — the card starts edge-on and swings open.

{/* Screenshot: Rotation section in From mode with Rotation set to -90 — tilt-in entrance setup */}
![Rotation in From mode — Z set to -90° for a tilt-in entrance](/images/builder/rotation-from-minus90.webp)

## To mode — spin out and continuous effects

In **To** mode the values you set are the **ending angle**. The element animates from its natural CSS rotation to the value you specify.

Set `rotation` to `360` in To for a full spin on click. Set `rotationY` to `180` for a card-flip reveal. Use **Repeat** with **Yoyo** disabled for a continuous spin loop.

{/* Screenshot: Rotation section in To mode with Rotation set to 360 — full spin setup */}
![Rotation in To mode — Z set to 360° for a full clockwise spin](/images/builder/rotation-to-360.webp)

<LivePreview client:load
  height={220}
  title="Rotation spin entrance"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 80px; height: 80px; border-radius: 16px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("spin-in", ".box", {
  from: { rotate: -180, scale: 0.6, opacity: 0 },
  duration: 0.7,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box uses `from: { rotation: -180, scale: 0.6, opacity: 0 }` — it starts half-size, transparent, and rotated 180° counter-clockwise, then animates to its natural state.

## SDK equivalent

The `rotation`, `rotationX`, and `rotationY` properties map directly to the SDK config. All values are in degrees.

**Spin in on page load (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('spin-in', '.icon', {
  from: { rotation: -180, opacity: 0 },
  duration: 0.7,
  ease: 'power3.out',
}).onPageLoad();
```

**Full clockwise spin on click (To mode):**

```typescript
Motion('spin', '.logo', {
  to: { rotation: 360 },
  duration: 0.8,
  ease: 'power2.out',
}).onClick({ each: true });
```

**3D flip-in entrance — rotationY:**

```typescript
Motion('flip-in', '.card', {
  from: { rotationY: 90, opacity: 0 },
  duration: 0.6,
  ease: 'power2.out',
}).onPageLoad();
```

**Continuous spin loop:**

```typescript
Motion('spinner', '.loader', {
  to: { rotation: 360 },
  duration: 1.2,
  ease: 'none',
  repeat: { times: -1 },
}).onPageLoad();
```

**Tilt in from above — rotationX:**

```typescript
Motion('tilt-in', '.banner', {
  from: { rotationX: -60, opacity: 0 },
  duration: 0.65,
  ease: 'power3.out',
}).onScroll();
```

For the full SDK reference, see [Rotation in the SDK](/docs/sdk/rotation).

## Common patterns

### Tilt-up entrance
```typescript
from: { rotation: -15, opacity: 0 }   // element tips up into place from a slight tilt
```

### Clockwise spin entrance
```typescript
from: { rotation: 360 }   // element spins one full revolution into its resting angle
```

### Card flip on hover
```typescript
to: { rotationY: 180 }   // pair with Hover trigger + Reverse on leave to flip back
```

### Continuous loader spin
```typescript
to: { rotation: 360 },
// set Repeat → Times to -1 and Ease to Linear for a steady loop
```

### Staggered icon spin-in

Enable **Stagger** alongside Rotation in From mode. Each icon in a row rotates into place in sequence rather than all at once.

### Combined entrance — rotate, scale, and fade

```typescript
Motion('hero-reveal', '.hero-icon', {
  from: { rotation: -90, scale: 0.5, opacity: 0 },
  duration: 0.75,
  ease: 'back.out(1.4)',
}).onPageLoad();
```

## Tips

- **Positive = clockwise, negative = counter-clockwise** — this matches CSS `rotate()` convention.
- Values beyond `±360` produce multi-revolution animations. `rotation: 720` spins two full turns.
- `rotationX` and `rotationY` require a **perspective context** on a parent element to look three-dimensional. Without it the 3D rotation appears flat (identical to a 2D scale). Add `perspective: 800px` to the parent via CSS or use `transformPerspective` in your SDK code.
- The rotation pivot defaults to the **element's center**. To rotate from a corner or edge, change the [Transform Origin](/docs/builder/transform-origin).
- For a continuous spin loop, set **Ease** to `Linear` and **Repeat → Times** to `-1`. Any other ease will accelerate and decelerate each revolution, creating a stuttering effect.
- Combine `rotation` with [Scale](/docs/builder/scale) and [Opacity](/docs/builder/opacity) for richer entrances: `from: { rotation: -90, scale: 0.7, opacity: 0 }`.
- **Double-click** a numeric input to clear the value.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Rotation in the SDK](/docs/sdk/rotation) — SDK reference for `rotation`, `rotationX`, and `rotationY`
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Scale](/docs/builder/scale) — Grow or shrink elements
- [Transform Origin](/docs/builder/transform-origin) — Change the pivot point for rotation
- [3D Transforms](/docs/builder/3d-transforms) — Perspective and 3D context for `rotationX` / `rotationY`
- [Ease](/docs/builder/easing) — Control the motion curve; elastic and back eases complement rotation well

---

## Workspace Overview

> Tour of the builder interface — panels, preview, timeline, and navigation.

URL: https://motion.page/docs/builder/workspace-overview

The Motion.page builder is split into four regions: a **Top Panel** toolbar, a **Left Panel** for configuration, a central **Frame View** with your live site preview, and a **Timeline Editor** at the bottom for arranging animation nodes.

{/* Screenshot: Full builder workspace showing all four regions — Top Panel, Left Panel, Frame View, and Timeline Editor — with labels on each region */}
![Builder workspace overview](/images/builder/workspace-overview.webp)

---

## Top Panel

The Top Panel runs across the full width of the builder and holds global controls.

{/* Screenshot: Top Panel toolbar showing the left icon group, center breakpoint buttons, and right Global Settings button */}
![Top Panel toolbar](/images/builder/workspace-overview-top-panel.webp)

### Left group — History & View

| Button | Shortcut | What it does |
|--------|----------|--------------|
| **Fullscreen** | — | Hides the Left Panel, expanding the preview to fill the full width |
| **Refresh** | — | Reloads the preview iframe with the current page |
| **Undo** | `Ctrl+Z` / `Cmd+Z` | Undoes the last builder action |
| **Redo** | `Ctrl+Shift+Z` / `Cmd+Shift+Z` | Redoes the last undone action |

### Center — Device breakpoints

The four breakpoint buttons (**Mobile**, **Tablet**, **Laptop**, **Desktop**) set the preview iframe width to the corresponding pixel value defined in your site's breakpoint settings. The active breakpoint is highlighted.

Use these to verify that your animation looks correct at each viewport size. The **Breakpoints** section in the Left Panel lets you enable or disable an animation for specific breakpoints.

### Right — Global Settings

The **cog icon** opens the Global Settings fly-out panel. This is where you configure site-wide options: tooltip visibility, builder theme, CDN loading, Lenis smooth scroll, breakpoint widths, WordPress integration, and white-label settings.

---

## Left Panel

The Left Panel holds all animation and trigger configuration. It has three tabs at the top: **Builder**, **Library**, and **Artifact** (desktop only).

{/* Screenshot: Left Panel showing the Builder tab with AnimationName section, Trigger section, Animation section, and Breakpoints section visible */}
![Left Panel — Builder tab](/images/builder/workspace-overview-left-panel.webp)

### Navigation bar

The nav bar at the top of the Left Panel contains the Motion.page logo and the tab switcher.

- **Logo** — On the desktop app, clicking the logo opens the Project Dashboard.
- **Builder** tab — The main configuration view (described below).
- **Library** tab — Lists all saved timelines for the current site or project. Each item shows the timeline name, page, and trigger type, with actions to load, duplicate, or delete it. Use **Refresh Library** (in the footer) to sync after external changes.
- **Artifact** tab (desktop only) — For managing animation artifacts.

### AnimationName section

At the top of the Builder tab:

| Control | What it does |
|---------|--------------|
| **New** (+) | Creates a new timeline |
| **Timeline name** | Editable text input — rename the current timeline |
| **Duplicate** | Duplicates the current timeline |
| **Page selector** | Choose which page this animation loads on |
| **Global** toggle | When enabled, the timeline loads on every page of the site |
| **Advanced Targeting** | Collapsible section — filter by post type, category, or regex URL pattern |

### Trigger section

The **Trigger** section defines what causes the animation to play. Choose a trigger type from the dropdown, then configure its settings:

| Trigger type | When it fires |
|---|---|
| **Page Events** | On page load or when the page is fully loaded |
| **ScrollTrigger** | As the user scrolls — supports scrub, toggle actions, pin, and markers |
| **Interactions** | On hover or click of a target element |
| **Scroll** | Smooth scroll / scrub driven by scroll position |
| **Mouse Follower** | Replaces the cursor with a custom animated element |
| **Cursor Tooltip** | Shows a tooltip that follows the cursor |
| **Gesture** | Responds to swipe and drag gestures via the SDK's gesture engine |

> **Note:** The **Mouse Follower** and **Cursor Tooltip** triggers hide the Timeline Editor — those animations are not time-based.

### Animation section

The **Animation** section is where you define what gets animated and how.

- **Selectors** — One or more CSS selectors identifying the elements to animate. Click the scanner icon (**Selector Detector**) to pick elements interactively in the Frame View.
- **FROM / TO / SET switcher** — Controls the tween type:
  - **FROM** — Properties define the *starting state*; elements animate from these values to their natural state.
  - **TO** — Properties define the *ending state*; elements animate from their natural state to these values.
  - **SET** — Zero-duration instant set. Immediately applies the properties without animation.
- **Animation property panels** — Collapsible sections for each property type: Translate, Rotation, Scale, Skew, Opacity, Filter, Dimensions, Border, Custom CSS, Ease, Repeat, Stagger, Transform Origin, 3D Transform, SVG Draw, Lottie, Class Manipulation, Text Splitter, Background Position, Image Sequence, Motion Path, and more.
- **Presets** — Quick-apply common animation patterns.

> **Tip:** Right-click the **FROM** or **TO** button to reveal additional tween options.

### Breakpoints section

The **Breakpoints** section lets you enable or disable this animation at specific viewport sizes. Useful for mobile-only or desktop-only effects.

### Footer

The footer at the bottom of the Left Panel contains context-sensitive actions:

| Control | Available on | What it does |
|---------|-------------|--------------|
| **WP Dashboard** | WordPress | Opens the WordPress admin dashboard |
| **View Frontend** | WordPress | Opens the live frontend in a new tab |
| **Open in Oxygen / Bricks** | WordPress (if applicable) | Jumps to the page editor |
| **Save Timeline** | All | Saves the current timeline. Shortcut: `Ctrl+S` / `Cmd+S` |
| **Publish** | Desktop | Publishes the timeline to the Convex backend |
| **Refresh Library** | Library tab | Re-fetches all library items |
| **Save Artifact** | Artifact tab | Saves the current artifact |

---

## Frame View

The **Frame View** is the central region — a live preview of your website rendered inside an iframe (or an Electron webview on the desktop app).

{/* Screenshot: Frame View showing a live website inside the preview iframe, with the checkered background visible on the sides when the iframe is narrower than full width */}
![Frame View — live site preview](/images/builder/workspace-overview-frame-view.webp)

- The preview width is controlled by the **breakpoint buttons** in the Top Panel. When the iframe is narrower than the full container, a checkered pattern fills the side gutters.
- **Element selection** — With the Selector Detector enabled in the Animation section, clicking any element in the Frame View inserts its CSS selector into the selectors field.
- **Live preview** — Animations play directly inside the preview iframe. Enable **Live** mode in the Timeline Editor to preview scroll, hover, and click triggers in real time without leaving the builder.

---

## Timeline Editor

The **Timeline Editor** sits at the bottom of the workspace. It is a horizontally scrollable track where each animation node is a draggable, resizable block. Drag the top edge of the panel to resize it vertically.

{/* Screenshot: Timeline Editor showing the top control bar, the ruler in seconds, and several animation nodes (blocks) on the track */}
![Timeline Editor](/images/builder/workspace-overview-timeline.webp)

### Playback controls

| Control | Shortcut | What it does |
|---------|----------|--------------|
| **Add Node** (+) | — | Adds a new animation node to the timeline |
| **Loop** | — | Loops playback continuously for preview |
| **Jump to Start** | — | Moves the playhead to `0s` |
| **Play / Pause** | — | Plays or pauses timeline playback. Shows current time and total duration (e.g. `0.4s / 2.0s`) |
| **Jump to End** | — | Moves the playhead to the last node's end time |
| **Live** | — | Executes animations live on the page, synced to the trigger (scroll, hover, click) |
| **Click to place** | — | When checked, clicking on the timeline track places a new node at that position |

### Timeline view controls

| Control | What it does |
|---------|--------------|
| **Timeline scrollbar** | Scrolls the timeline horizontally when nodes extend past the visible area |
| **Max duration** | Sets the maximum visible duration (10s → 20s → … → 70s). Click and drag to adjust. |
| **Zoom Out / Zoom In** | Changes the horizontal zoom level of the timeline |

### Working with nodes

Each **node** on the timeline represents one animation on one set of elements:

- **Drag** a node to change its start time.
- **Resize** from either edge to change its duration.
- **Click** a node to select it — the Left Panel updates to show that node's animation properties.

The **ruler** at the top of the timeline shows time in seconds, updating dynamically as you zoom.

---

## How the panels work together

The four regions are tightly connected:

1. **Enter a CSS selector** in the Left Panel → Animation section, or click an element in the **Frame View** with the Selector Detector active.
2. **Configure the animation** — set FROM/TO/SET and add property panels in the Left Panel.
3. **See the node** appear (or add one manually with **+**) in the **Timeline Editor**. Drag it to set the start time and resize it to set the duration.
4. **Press Play** in the Timeline Editor to preview the result directly in the **Frame View**.
5. **Save** with `Ctrl+S` / `Cmd+S` when done.

---

## Next steps

- [Left Panel](/docs/builder/left-panel) — Detailed reference for every control in the configuration panel
- [Timeline Editor](/docs/builder/timeline-editor) — Node management, scrubbing, and playback options
- [Scroll Trigger](/docs/builder/scroll-trigger) — Scroll-based triggers and their settings
- [From, To & Set](/docs/builder/from-to-set) — Every animatable property explained

---

## Motion Path

> Animate elements along SVG paths with align, auto-rotate, and range controls.

URL: https://motion.page/docs/builder/motion-path

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Motion Path** moves any element along an SVG path during an animation. The element travels from one point on the path to another, following the exact curve you define — useful for product tours, map routes, animated icons, or any effect where straight-line movement falls short.

> Animate and move any element along a SVG path.

## Location

**Left Panel → Animation tab → Functional Properties → Motion Path**

Motion Path is a **functional property** — it is direction-agnostic. The same path configuration applies whether the **From**, **To**, or **Set** tab is active. Enabling it on any tab automatically enables it on all three.


## Enable Motion Path

Click the toggle next to **Motion Path** to enable it. The row expands to reveal the mode switcher, path input, align input, Auto Rotate toggle, Range slider, and Align Origin controls.

{/* Screenshot: Motion Path row fully expanded showing the SELECTOR/CODE mode switcher, path selector field, align field, Auto Rotate toggle, Range slider, and Align Origin grid */}
![Motion Path controls expanded — mode switcher, path input, and options](/images/builder/motion-path-controls-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Mode** | Switch between **Path Selector** (pick a path from the page) and **Raw SVG Code** (paste path data directly). |
| **Path / Insert SVG path** | The path source — either a CSS selector pointing to a `<path>` element, or raw SVG `d` attribute data. |
| **Align** | A CSS selector (or `self`) used to snap the target element exactly onto the path. Prevents the element from jumping to the path start position. |
| **Auto Rotate** | When on, the element rotates to follow the path's direction of travel as it moves. |
| **Range** | Start and end positions on the path as values from `0` to `100`. Restricts the animation to a portion of the full path. |
| **Align Origin** | The point on the target element that is placed on the path, expressed as X% and Y% from the top-left. Defaults to `50 / 50` (center). |

### Path Selector mode

**Path Selector** mode lets you click a `<path>` element directly on the page to use as the motion guide.

> Animate any object along the SVG path selector that is present on the page.


1. Make sure the page contains an SVG `<path>` element — it can be hidden with CSS (`visibility: hidden` or `opacity: 0`), it only needs to exist in the DOM.
2. Click **Select a path** to open the element picker in the frame view and click the `<path>`.
3. Optionally set **Select an align** to the same path selector (or another element / `self`) to snap the target onto the path start. This eliminates the position jump that occurs when the animation begins.

> Bend coordinates to position the target exactly on top of the path (or move the path to the target). You can use a selector, or 'self'.

### Raw SVG Code mode

**Raw SVG Code** mode lets you paste SVG path data directly — no DOM element required.

> Animate any object along the raw SVG path code.


1. Switch the mode toggle to **CODE**.
2. Paste a valid SVG `d` attribute value into the **Insert SVG path** field. The string must start with `M` or `m`, e.g. `M 10 80 C 40 10, 65 10, 95 80`.
3. Optionally set **Select an align element** to a CSS selector or `self` to position the target on the path.

> Insert a raw SVG path code.

> Bend coordinates to position the target exactly on top of the path (or move the path to the target). You can use a selector, or 'self'.

## Auto Rotate

When **Auto Rotate** is enabled, the target element automatically rotates to face the direction of travel along the path. The rotation tracks the path tangent at each point, so curves and corners are followed naturally.

> Auto rotate makes the target rotate automatically in the direction of the path as it moves.

Turn this on for directional elements — arrows, vehicles, planes, cursors, or any element where orientation matters. Leave it off for symmetric elements like dots or circles where rotation has no visual effect.

## Range

**Range** restricts the animation to a specific segment of the path. The start and end values are **progress percentages from 0 to 100** — where `0` is the beginning of the path and `100` is the end.

> Define specific start and end positions on the path (progress values from 0-100).

| Value | Meaning |
|-------|---------|
| `0` | Start of the path |
| `100` | End of the path |
| `25 → 75` | Middle half of the path only |

Use the dual-handle **Range slider** to drag both endpoints, or type values directly into the number inputs on either side. The default is `0 → 100` (full path). Narrowing the range is useful for multi-step sequences, progress indicators, or when a longer path needs to be shared across multiple animations.

<LivePreview client:load
  height={280}
  title="Element moving along a curved SVG path"
  html={`<div class="scene">
  <svg class="guide-svg" viewBox="0 0 400 160" xmlns="http://www.w3.org/2000/svg">
    <path id="guide" d="M 20 100 C 80 20, 160 140, 240 80 C 320 20, 360 120, 380 80" fill="none" stroke="#2a2a2a" stroke-width="2" stroke-dasharray="6 4"/>
  </svg>
  <div class="dot"></div>
</div>`}
  css={`.scene { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; }
.guide-svg { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); width: 400px; pointer-events: none; }
.dot { width: 20px; height: 20px; border-radius: 50%; background: #6633EE; position: absolute; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("follow", ".dot", {
  to: { path: { target: "#guide", align: "#guide" } },
  duration: 2.4,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The purple dot follows the curved SVG path from left to right — this is **Motion Path** in action, equivalent to Path Selector mode with a `<path>` element on the page. Enable **Auto Rotate** to have a directional element (arrow, car) turn as it moves along the curves.

## SDK equivalent

Motion Path maps to the `path` property inside `from` or `to` in the SDK. The builder outputs a `PathConfig` object with the following shape:

| Property | Type | SDK default | Builder source |
|----------|------|-------------|----------------|
| `target` | `string` | — | CSS selector (Selector mode) or raw path data (Code mode) |
| `align` | `string` | — | Align field in either mode; `"self"` is valid |
| `alignAt` | `[number, number]` | `[50, 50]` | Align Origin X/Y controls |
| `start` | `number` | `0` | Range start ÷ 100 |
| `end` | `number` | `1` | Range end ÷ 100 |
| `rotate` | `boolean` | — | Auto Rotate toggle |

**Selector mode — DOM path element:**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('follow-path', '.dot', {
  to: {
    path: {
      target: '#guide-path',
      align: '#guide-path',
      rotate: true,
    },
  },
  duration: 2,
  ease: 'power2.inOut',
}).onPageLoad();
```

**Code mode — raw SVG path data:**

```typescript
Motion('draw-path', '.marker', {
  to: {
    path: {
      target: 'M 20 100 C 80 20, 160 140, 240 80 C 320 20, 360 120, 380 80',
      rotate: false,
    },
  },
  duration: 2.4,
  ease: 'power2.inOut',
}).onPageLoad();
```

**Partial range — middle 60% of the path:**

```typescript
Motion('segment', '.badge', {
  to: {
    path: {
      target: '#route',
      start: 0.2,
      end: 0.8,
      rotate: true,
    },
  },
  duration: 1.5,
  ease: 'power1.inOut',
}).onScroll({ scrub: true });
```

For the full SDK reference — including raw path strings, `"self"` alignment, and scroll-scrubbing patterns — see [Motion Path in the SDK](/docs/sdk/motion-path).

## Common patterns

### Animated icon following a curve

Use a small SVG icon as the target and a hidden curved `<path>` as the guide. Enable **Auto Rotate** so the icon faces the direction of travel.

```typescript
Motion('icon-curve', '.arrow-icon', {
  to: {
    path: {
      target: '#curve-guide',
      align: '#curve-guide',
      rotate: true,
    },
  },
  duration: 2,
  ease: 'power2.inOut',
}).onPageLoad();
```

### Scroll-driven progress marker

Attach a dot or label to a path that traces a timeline or roadmap on the page. Scrub with scroll to drive it along the route.

```typescript
Motion('map-marker', '.location-dot', {
  to: {
    path: {
      target: '#roadmap-path',
      align: '#roadmap-path',
      rotate: false,
    },
  },
  duration: 1,
}).onScroll({
  scrub: true,
  start: 'top center',
  end: 'bottom center',
});
```

### Looping orbit

Set **Repeat** to infinite (`-1`) with `ease: "linear"` for a seamless loop around a closed path. This is ideal for satellites, badges, or decorative animated rings.

```typescript
Motion('orbit', '.satellite', {
  to: {
    path: {
      target: '#orbit-ellipse',
      rotate: true,
    },
  },
  duration: 6,
  ease: 'linear',
  repeat: -1,
}).onPageLoad();
```

## Tips

- **The guide `<path>` can be invisible** — set `fill: none; stroke: none; visibility: hidden` in CSS. It only needs to exist in the DOM for SELECTOR mode.
- **Code mode is layout-independent** — raw path coordinates are absolute values and don't move with the page layout. Selector mode is safer when you need the path to stay aligned with other elements.
- **Use Align to eliminate jumps** — without an `align` value, the element snaps to the path start when the animation begins. Set **Align** to the same selector as the path (or `self`) to blend in smoothly.
- **Auto Rotate + `alignAt`** — for a car icon where you want the front bumper to lead, shift Align Origin X to `0` so the front edge (not center) follows the path tangent.
- **Combine with Opacity** — fade the element in at the start of a path animation with an opacity tween to avoid a sudden appearance.
- **Range for multi-stage paths** — draw one long path that spans the whole sequence, then assign different elements different Range segments so each covers its own portion of the route.

## Related

- [Motion Path in the SDK](/docs/sdk/motion-path) — Full SDK reference including `PathConfig`, raw path strings, and scroll-scrub examples
- [Easing](/docs/builder/easing) — Control acceleration along the path
- [Scroll Trigger](/docs/builder/scroll-trigger) — Scrub path progress with the scrollbar
- [Repeat](/docs/builder/repeat) — Loop path animations or yoyo back and forth
- [SVG Animations](/docs/builder/svg) — Animate SVG stroke draw-on and fill/stroke color
- [From, To & Set](/docs/builder/from-to-set) — How functional properties apply across animation mode tabs

---

## Mouse Movement

> Animate elements based on cursor position with axis and distance modes, scoped selectors, and smooth transitions.

URL: https://motion.page/docs/builder/mouse-movement

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Mouse Movement trigger** links timeline progress directly to the cursor's position inside a boundary. Use it for parallax effects, eye-tracking animations, card tilts, or any motion that follows the pointer.

## Location

**Left Panel → Trigger tab → Interactions → Mouse Movement**

Select **Mouse Movement** from the trigger dropdown to reveal the mouse movement configuration panel.

{/* Screenshot: Left Panel with Trigger tab open, Interactions section expanded, Mouse Movement selected from the trigger dropdown */}
![Mouse Movement trigger settings panel](/images/builder/mouse-movement-settings.webp)

---

## Selector

The **Selector** defines the boundary used to track the cursor.

> A screen viewport is used as a default value, but you can specify an ID or a class which sets boundaries of the mouse triggered animation.

| Control | Default | Description |
|---------|---------|-------------|
| **Selector** input | *(empty — uses viewport)* | CSS selector for the boundary element. Accepts `.class` or `#id`. Leave empty to use the full viewport. |

When a selector is provided, cursor position is measured relative to that element's bounding box rather than the full viewport. This lets you scope the effect to a card, a section, or any container.

---

## Scoped mode

**Scoped mode** (`tMMScoped`) is available when the selector targets a class. It animates each matched element independently and treats the selector as a wrapper.

> If selector is a class, you can use this option to animate every iteration of this class individually one-by-one. It also is a wrapper for animated elements, so only elements inside of the selector will be animated.

| Control | Default | Description |
|---------|---------|-------------|
| **Scoped** toggle | off | Each instance of the selector class tracks its own cursor independently. The selector also becomes the wrapper — only elements inside it are animated. |

Use scoped mode when you have a grid of cards and want each card to react to the cursor position within its own bounds, not the whole page.

---

## Smooth enter and leave

These two options control how the timeline transitions when the cursor crosses into or out of the selector boundary.

> This option ensures smooth transition to a timeline progress, based on the cursor position when entering the selector.

> This option ensures smooth transition to a timeline progress, based on the cursor position when leaving the selector.

| Control | Default | Description |
|---------|---------|-------------|
| **Smooth enter** toggle | off | Smoothly interpolates the timeline from its current progress to match the cursor position on entry, rather than snapping. |
| **Smooth leave** toggle | off | Smoothly interpolates the timeline from its current progress to the **Leave value** when the cursor exits the boundary. |

Without smooth enter, the timeline jumps immediately to the cursor-mapped progress value on entry. Without smooth leave, the timeline snaps instantly to the leave value on exit.

---

## Before-enter and leave values

These controls set fixed timeline progress values for the idle states — before the cursor enters the boundary and after it leaves.

> Set a specific progress value of the timeline, before mouse enters the selector (0 is start, and 1 is end)

> The timeline will return to a specific progress value, after mouse leaves the selector (0 is start, and 1 is end)

| Control | Default | Description |
|---------|---------|-------------|
| **Before-enter value** slider | `0` | Timeline progress held before the cursor enters the boundary. `0` = start of timeline, `1` = end. Range: 0–1. |
| **Leave value** slider | `0` | Timeline progress the animation returns to after the cursor exits. `0` = start, `1` = end. Range: 0–1. |

Setting the leave value to `0.5` keeps the animation at its midpoint when idle — useful for distance-mode effects that should appear "neutral" at rest rather than fully collapsed.

---

## Animation mode

Two modes control how cursor position maps to timeline progress.

> The axis mode animates objects along the full axis, so the start is on one edge of the viewport / selector, and the end is on the other edge.

> The distance mode animates objects based on their distance from the center of the viewport / selector.

| Mode | SDK value | Mapping |
|------|-----------|---------|
| **Axis** | `"axis"` | Timeline progress is mapped linearly from one edge of the boundary to the opposite edge along a chosen axis. Cursor at the left/top edge = `0`, right/bottom edge = `1`. |
| **Distance** | `"distance"` | Timeline progress is mapped by how far the cursor is from the center. Cursor at center = `0` (start), cursor at any edge = `1` (end). |

**Axis mode** works well for parallax and directional slides where you want a full sweep from one side to the other. **Distance mode** works well for glow effects, spotlights, and radial reveals that grow or shrink around the center.

---

<LivePreview client:load
  height={260}
  title="Cursor-mapped dot"
  html={`<div class="scene">
  <div class="track" id="track">
    <div class="dot" id="dot"></div>
    <p class="hint">Move cursor here</p>
  </div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; background: #0d0d14; }
.track { position: relative; width: 280px; height: 160px; background: #1a1a2e; border-radius: 16px; border: 1px solid rgba(255,255,255,0.08); display: flex; align-items: center; justify-content: center; overflow: hidden; }
.dot { position: absolute; left: 50%; top: 50%; width: 24px; height: 24px; margin-left: -12px; margin-top: -12px; background: #6633EE; border-radius: 50%; pointer-events: none; }
.hint { color: rgba(255,255,255,0.25); font-size: 12px; font-weight: 500; margin: 0; user-select: none; letter-spacing: 0.04em; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("cursor-dot", "#dot", {
  from: { x: -120 },
  to: { x: 120 },
  duration: 1,
}).onMouseMove({
  target: "#track",
  type: "axis",
  smooth: 0.1,
  leaveProgress: 0.5,
});`}
/>

In the builder this is a **To** animation with `x: 120` driven by Mouse Movement in **Axis mode**, with the selector set to the container element.

---

## SDK equivalent

The builder Mouse Movement trigger maps to `.onMouseMove()` in the SDK.

```typescript
import { Motion } from "@motion.page/sdk";

// Parallax — elements shift based on cursor X position across the viewport
Motion("parallax", ".layer", {
  from: { x: -40, y: -20 },
  to: { x: 40, y: 20 },
  duration: 0.6,
}).onMouseMove({ type: "axis", smooth: 0.1 });
```

**With a scoped selector — each card tilts independently:**

```typescript
Motion("card-tilt", ".card-inner", {
  from: { rotateX: -8, rotateY: -8 },
  to: { rotateX: 8, rotateY: 8 },
  duration: 0.4,
}).onMouseMove({
  target: ".card",
  type: "axis",
  each: true,
  smooth: 0.1,
  leaveProgress: 0.5,
});
```

**Distance mode — glow grows from center outward:**

```typescript
Motion("glow", ".glow-ring", {
  from: { scale: 0.7, opacity: 0.2 },
  to: { scale: 1.3, opacity: 1 },
  duration: 0.5,
}).onMouseMove({ type: "distance", smooth: 0.1 });
```

For the full SDK reference see [Mouse Movement in the SDK](/docs/sdk/mouse-movement).

---

## Common patterns

### Parallax hero

Set a **To** animation with a modest `x` and `y` translate on a background layer. Leave the selector empty so the full viewport is used. Keep the values small (e.g. `x: 20, y: 10`) for a subtle depth effect that does not distract from content.

### Card tilt effect

Enable **Scoped mode** with a `.card` selector. Animate `rotateX` and `rotateY` on `.card-inner`. Each card tilts toward the cursor within its own bounds. Set a **Leave value** of `0.5` and enable **Smooth leave** so the card returns to a neutral flat position instead of snapping to one corner.

### Cursor-following spotlight

Use **Distance mode** with a radial-gradient background or a masked highlight element. At the center (distance `0`) the element is fully visible; at the edges (distance `1`) it fades out — giving the impression of a spotlight that follows the pointer.

### Distance-based glow

Animate `box-shadow` or a pseudo-element's `opacity` in **Distance mode** with a **Leave value** of `0`. The glow pulses outward as the cursor moves away from center and returns to baseline on exit.

---

## Related

- [Mouse Movement in the SDK](/docs/sdk/mouse-movement) — Full SDK reference for `.onMouseMove()`
- [Hover Trigger](/docs/builder/hover-trigger) — Trigger animations on pointer enter and leave
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on element click
- [From, To and Set](/docs/builder/from-to-set) — Configure what the animation does

---

## Page Exit

> Run animations when the user navigates away from the page using the Page Exit trigger.

URL: https://motion.page/docs/builder/page-exit

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

**Page Exit** plays a timeline when the user clicks a link to navigate away from the page. The animation runs before the browser navigates, so you can create smooth page transitions that play out fully before the next page loads.

## Location

**Left Panel → Trigger tab → Page Events → Page Exit**

Open the Trigger tab in the Left Panel, then select **Page Exit** from the Page Events section.

{/* Screenshot: Left Panel with the Trigger tab open, showing the Page Events section expanded with Page Exit selected */}
![Page Exit trigger settings panel](/images/builder/page-exit-settings.webp)

> Use the Page Events trigger to play the timeline when the page loads or when the user exits the page.

---

## Ignore exit classes

The **Ignore exit classes** control (`tIgnoreExit`) lets you exclude specific links from triggering the exit animation. Any link that carries one of the listed classes will navigate immediately — the exit animation is skipped entirely for those clicks.

> You can add one or multiple classes that will ignore the exit trigger.

| Control | Default | Description |
|---------|---------|-------------|
| **Ignore exit classes** input | *(empty)* | One or more CSS classes (without the leading dot). Links with these classes bypass the exit animation. |

### Targeting a parent element

Sometimes the class you want to match lives on a parent element rather than on the link itself. Use the `#id.class` shorthand to walk up the DOM and check a parent instead.

> As the ignored class needs to be present on the \<a\> element, you can use a specific format to target any parent element with an ignored class. `#my-menu.no-animation` will look up any parent (of the clicked \<a\> element) element with an ID of `my-menu` and a class of `no-animation`.

For example, entering `#my-menu.no-animation` tells the trigger to look for a parent that has the ID `my-menu` **and** the class `no-animation`. If found, the exit animation is skipped for that click.

---

## Run on selector

The **Run on selector** control (`tRunOnSelector`) restricts the exit animation to fire only when links matching specific CSS selectors are clicked. By default, any link click triggers the animation — this control narrows that to a targeted subset.

> You can add one or multiple selectors that will trigger exit animation.

| Control | Default | Description |
|---------|---------|-------------|
| **Run on selector** input | *(empty)* | One or more CSS selectors. Only clicks on matching links fire the exit animation. Leave empty to match all links. |

Use this when a page contains links that should navigate instantly — for example, anchor links that jump within the same page, or external links that open in a new tab — while still playing the exit animation for internal page navigation.

---

## SDK equivalent

The builder Page Exit trigger maps to `.onPageExit()` in the SDK.

```typescript
import { Motion } from "@motion.page/sdk";

// Fade out the page on exit
Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
  ease: "power2.in",
}).onPageExit();
```

**With ignore classes — skip the animation for certain links:**

```typescript
Motion("exit", "body", {
  to: { opacity: 0 },
  duration: 0.4,
}).onPageExit({
  mode: "exclude",
  selectors: ".no-transition, #my-menu.no-animation",
});
```

**With run on selector — only trigger on specific links:**

```typescript
Motion("exit", ".page-content", {
  to: { opacity: 0, y: -20 },
  duration: 0.35,
}).onPageExit({
  mode: "include",
  selectors: ".nav-link",
});
```

Because a documentation preview must not navigate away, this interactive demo uses the same exit animation with a click trigger. Click **Simulate page exit**, then use the preview's rerun button to reset it.

<LivePreview client:visible
  height={250}
  title="Page exit transition simulation"
  html={`<div class="exit-scene">
  <main class="page-card">
    <span class="eyebrow">CURRENT PAGE</span>
    <h3>Ready for the next view?</h3>
    <button class="exit-button">Simulate page exit →</button>
  </main>
</div>`}
  css={`.exit-scene { display: grid; place-items: center; width: 100%; height: 100%; }
.page-card { width: min(360px, 88vw); padding: 30px; text-align: center; background: #151522; border: 1px solid #2b2b42; border-radius: 18px; }
.eyebrow { color: #8c8fa8; font-size: 10px; font-weight: 800; letter-spacing: .18em; }
h3 { margin: 10px 0 22px; font-size: 20px; }
.exit-button { padding: 10px 18px; color: white; font-weight: 700; background: #6633ee; border: 0; border-radius: 9px; cursor: pointer; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("exit", ".page-card", {
  to: { opacity: 0, y: -36, scale: 0.96 },
  duration: 0.45,
  ease: "power2.in",
}).onClick({
  target: ".exit-button",
  toggle: "restart",
});`}
/>

---

## Common patterns

### Page transition fade

Animate `body` or `.page-wrapper` from full opacity to `0` with a short duration (`0.3–0.5s`) and a ease-in curve. Pair this with a matching **Page Load** entrance animation (`opacity: 0` → `1`) so every navigation feels seamless in both directions.

### Slide-out with selective links

Use **Run on selector** to target only `.internal-link` anchors. Anchor links and external links are left untouched and navigate immediately. The exit slide (`y: -30, opacity: 0`) fires only for genuine page-to-page transitions.

### Combined Page Load and Page Exit transitions

Pair Page Exit with a [Page Load](/docs/builder/page-load) timeline to build a full transition loop:

```typescript
import { Motion } from "@motion.page/sdk";

// Entrance — plays when the new page loads
Motion("enter", ".page-wrap", {
  from: { opacity: 0, y: 20 },
  duration: 0.45,
  ease: "power2.out",
}).onPageLoad();

// Exit — plays before navigating away
Motion("exit", ".page-wrap", {
  to: { opacity: 0, y: -20 },
  duration: 0.35,
  ease: "power2.in",
}).onPageExit();
```

### Excluding menu links from the exit

Add `no-exit` to any navigation links that should not fire the animation — for example, links inside a dropdown that close the menu without leaving the page. Enter `no-exit` in the **Ignore exit classes** field.

---

## Related

- [Page Exit — SDK reference](/docs/sdk/page-exit) — Full `.onPageExit()` API and options
- [Page Load Trigger](/docs/builder/page-load) — Auto-play animations when the page loads
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on element click
- [From, To & Set](/docs/builder/from-to-set) — Configure what the animation does

---

## Lottie Animations

> Sync Lottie Player animations with your Motion.page timeline.

URL: https://motion.page/docs/builder/lottie

import LivePreview from "../../components/docs/blocks/LivePreview";

**Lottie** ties the playback progress of a [Lottie Player](https://lottiefiles.com/web-player) web component to your Motion.page timeline. Instead of running independently, the Lottie animation scrubs forward (or backward) in lock-step with however your timeline progresses — whether that is a scroll scrub, a page-load play-through, or an interaction trigger.

## Location

**Left Panel → Animation tab → Visual Properties → Lottie**

Lottie is a **functional property** — it is direction-agnostic. The same Lottie configuration applies whether the **From**, **To**, or **Set** tab is active. Enabling it on any tab automatically enables it on all three.


## Enable Lottie

Click the toggle next to **Lottie** to enable it. The row expands to reveal a playback range slider and the reverse toggle.

{/* Screenshot: Lottie row fully expanded, showing the 0%–100% range slider and the Reverse toggle */}
![Lottie controls expanded — playback range slider and reverse toggle](/images/builder/lottie-controls-expanded.webp)

## Controls

| Control | Type | Default | Description |
|---------|------|---------|-------------|
| **Start %** | Number input | `0` | Start position of the playback range as a percentage (0–100). |
| **End %** | Number input | `100` | End position of the playback range as a percentage (0–100). |
| **Range slider** | Slider | Full range | Visual slider to drag the start and end points of the Lottie playback range. |
| **Reverse** | Toggle | Off | Play the Lottie sequence in reverse order of playback. |

### Partial playback

By default Motion.page drives the Lottie from its first frame to its last frame across the full timeline duration. Enter a **Start** and **End** percentage to animate only a slice of the Lottie — for example, `30%`–`60%`. Anything outside that range stays frozen at the boundary frame.

> Keep the range at **0%–100%** to animate the full Lottie. You can also move only one boundary — for example, set **End** to `60%` to stop playback three-fifths through without clipping the start.

### Reverse

Enable **Reverse** to invert playback direction. As the timeline progresses forward, the Lottie steps backward through its frames. Combine with partial playback to reverse only a segment of the animation.

## Prerequisites

The Lottie Player web component must be loaded on the page **before** Motion.page attempts to control it.

Add the Lottie Player script to your page's `<head>` or before the closing `</body>` tag:

```html
<script src="https://unpkg.com/@lottiefiles/lottie-player@latest/dist/lottie-player.js"></script>
```

Then place a `<lottie-player>` element somewhere in your page markup:

```html
<lottie-player
  id="my-lottie"
  src="https://assets.lottiefiles.com/packages/lf20_example.json"
  background="transparent"
  speed="1"
  style="width: 300px; height: 300px;"
></lottie-player>
```

Select the Lottie element in Motion.page — for example `#my-lottie` or `.hero-lottie`. Do not add `autoplay` or `loop`; Motion.page takes control of frame playback.

> **WordPress users:** Add the script via a custom HTML block or your theme's `functions.php`. **Desktop users:** paste it into the Custom Code panel in the Settings tab.

## How it works

Motion.page drives the Lottie by setting the player's `seek` position as the timeline progresses. The Lottie never plays on its own clock — it is entirely slaved to the timeline's current progress.

- **Scroll Trigger + Scrub** — the Lottie frames advance and retreat as the user scrolls. The animation literally scrubs with the page position.
- **Page Load trigger** — the Lottie plays from its start frame to its end frame as the timeline plays through its duration.
- **Interactions (Click / Hover)** — the Lottie advances on enter and optionally reverses on leave, depending on your toggle actions.

Partial playback works the same way across all triggers — Motion.page maps the timeline progress `0 → 1` onto the configured frame range rather than the full Lottie duration.

## Common patterns

### Lottie on scroll scrub

The most common use case. A Lottie illustration plays frame by frame as the user scrolls down the page.

1. Add a `<lottie-player>` element with your animation JSON.
2. Select the element in Motion.page and open **Lottie** in the Visual Properties list.
3. Enter the element's selector (e.g. `#hero-lottie`).
4. Set the trigger to **Scroll Trigger** and enable **Scrub**.
5. Adjust **Start / End** scroll positions to control when the animation begins and ends.

The Lottie will scrub forward as the user scrolls into the trigger zone, and backward if they scroll back up.

```javascript
import { Motion } from "@motion.page/sdk";

const player = document.querySelector("#hero-lottie");

Motion("hero-lottie", player, {
  duration: 1,
  ease: "none",
  onUpdate: (progress) => {
    if (!player?._lottie) return;
    const lastFrame = player._lottie.totalFrames - 1;
    player._lottie.goToAndStop(Math.round(progress * lastFrame), true);
  },
}).onScroll({
  target: "#hero-lottie",
  scrub: true,
  start: "top center",
  end: "bottom center",
});
```

<LivePreview client:visible
  height={375}
  title="Builder Lottie frame-range output"
  html={`<div class="builder-lottie-demo">
  <div class="lottie-stage">
    <div class="demo-lottie-player" role="img" aria-label="Simulated Lottie completion animation">
      <svg viewBox="0 0 320 220" aria-hidden="true">
        <circle class="lottie-track" cx="160" cy="110" r="72" />
        <circle class="lottie-progress" cx="160" cy="110" r="72" />
        <path class="lottie-check" d="M119 112 L148 139 L205 78" />
        <circle class="lottie-spark" cx="160" cy="38" r="7" />
      </svg>
      <span class="frame-readout">0%</span>
    </div>
  </div>
  <div class="lottie-settings">
    <span>Range <strong>0% → 100%</strong></span>
    <span>Reverse <strong>Off</strong></span>
    <span>Playback <strong>Timeline</strong></span>
  </div>
</div>`}
  css={`.builder-lottie-demo {
  width: min(620px, 100%);
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  overflow: hidden;
  background: #080b20;
}
.lottie-stage {
  height: 270px;
  padding: 16px;
  background: radial-gradient(circle at 50% 48%, rgba(72, 116, 255, 0.24), transparent 48%), #050713;
}
.demo-lottie-player { position: relative; width: 100%; height: 100%; }
.demo-lottie-player svg { display: block; width: 100%; height: 100%; overflow: visible; }
.lottie-track,
.lottie-progress { fill: none; stroke-width: 8; }
.lottie-track { stroke: rgba(143, 158, 255, 0.13); }
.lottie-progress { stroke: #7367ff; stroke-linecap: round; stroke-dasharray: 452.4; }
.lottie-check { fill: none; stroke: #8cecff; stroke-width: 10; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 120; }
.lottie-spark { fill: #fff; filter: drop-shadow(0 0 12px #69dfff); }
.frame-readout {
  position: absolute;
  top: 14px;
  right: 14px;
  padding: 7px 10px;
  border: 1px solid rgba(173, 184, 255, 0.22);
  border-radius: 999px;
  background: rgba(5, 7, 20, 0.74);
  color: #f4f5ff;
  font-size: 11px;
}
.lottie-settings {
  padding: 16px 18px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  color: #737c9f;
  font-size: 10px;
}
.lottie-settings strong { margin-left: 4px; color: #dfe2ff; }
@media (max-width: 520px) {
  .lottie-settings { align-items: flex-start; flex-direction: column; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const player = document.querySelector(".demo-lottie-player");
const ring = document.querySelector(".lottie-progress");
const check = document.querySelector(".lottie-check");
const spark = document.querySelector(".lottie-spark");
const readout = document.querySelector(".frame-readout");

player._lottie = {
  totalFrames: 101,
  goToAndStop(frame) {
    const progress = frame / (this.totalFrames - 1);
    ring.style.strokeDashoffset = String(452.4 * (1 - progress));
    check.style.strokeDashoffset = String(120 * (1 - progress));
    spark.setAttribute("transform", "rotate(" + progress * 360 + " 160 110)");
    readout.textContent = Math.round(progress * 100) + "%";
  },
};

player._lottie.goToAndStop(0, true);

Motion("builder-lottie-preview", player, {
  duration: 2.2,
  ease: "none",
  onUpdate: (progress) => {
    const lastFrame = player._lottie.totalFrames - 1;
    player._lottie.goToAndStop(Math.round(progress * lastFrame), true);
  },
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

### Partial playback — animate only 30%–60%

A Lottie has three distinct animation phases. Map a single Motion.page timeline to only its middle range.

1. Enable **Lottie** and enter the selector.
2. Set **Start** to `30%` and **End** to `60%`.
3. Attach any trigger — scroll scrub, page load, or interaction.

Only the 30%–60% slice will animate. Everything before and after that slice remains frozen at its boundary position.

```javascript
const partialPlayer = document.querySelector(".lottie-icon");

Motion("lottie-partial", partialPlayer, {
  duration: 1,
  ease: "none",
  onUpdate: (progress) => {
    if (!partialPlayer?._lottie) return;
    const lastFrame = partialPlayer._lottie.totalFrames - 1;
    const normalized = 0.3 + (0.6 - 0.3) * progress;
    partialPlayer._lottie.goToAndStop(Math.round(normalized * lastFrame), true);
  },
}).onScroll({
  target: ".lottie-icon",
  scrub: true,
  start: "top 80%",
  end: "bottom 20%",
});
```

## Generated SDK Bridge

Lottie is **Builder metadata**, not a root-level field in the core SDK's `AnimationConfig`. The SDK generator turns the selected range and Reverse toggle into an animation-level `onUpdate` callback that calls `element._lottie.goToAndStop(...)`.

You do not need to maintain that callback when using the Builder. For the exact handwritten pattern and additional triggers, see [Lottie in the SDK](/docs/sdk/lottie).

## Related

- [Scroll Trigger](/docs/builder/scroll-trigger) — Drive Lottie playback with scroll position using Scrub
- [From, To & Set](/docs/builder/from-to-set) — How functional properties apply across animation mode tabs
- [Image Sequence](/docs/builder/image-sequence) — Similar frame-by-frame scrubbing using a sequence of images instead of Lottie

---

## Observer / Gesture

> Detect pointer, touch, wheel, and scroll gestures to drive animations with configurable axes, tolerance, and presentation mode.

URL: https://motion.page/docs/builder/observer-gesture

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Observer / Gesture trigger** detects pointer, touch, wheel, and scroll gestures to drive timeline playback. Use it for swipe-based navigation, wheel-driven animations, and full-page presentation slides — powered by the SDK's gesture engine.

## Location

**Left Panel → Trigger tab → Interactions → Observer / Gesture**

Select **Observer / Gesture** from the trigger dropdown to reveal the observer configuration panel.

{/* Screenshot: Left Panel with Trigger tab open, Interactions section expanded, Observer / Gesture selected from the trigger dropdown */}
![Observer / Gesture settings panel](/images/builder/observer-gesture-settings.webp)

---

## Target

The **Target** control defines which element is observed for incoming gestures.

> The element to observe for interactions. Defaults to window for global gestures.

| Control | Default | Description |
|---------|---------|-------------|
| **Target selector** (`tObserverTarget`) | *(empty — window)* | CSS selector for the element to observe. Leave empty to observe the browser window. Accepts `.class` or `#id`. |

When empty, gestures are detected anywhere on the page. Set a specific selector to scope gesture detection to a single container — useful for carousels, modals, or embedded scrollable panels.

---

## Interaction types

The **Types** checkboxes choose which kinds of input events the observer monitors. Enable one or more.

> Select which interaction types to detect: Pointer (mouse), Touch, Wheel (scroll wheel), or Scroll.

| Type | Input source | Typical use |
|------|-------------|-------------|
| **Pointer** | Mouse move and drag | Desktop drag gestures |
| **Touch** | Touchscreen swipe | Mobile swipe navigation |
| **Wheel** | Scroll wheel or trackpad | Wheel-driven timeline scrubbing |
| **Scroll** | Native scroll events | Scroll-position based gestures |

You can enable multiple types simultaneously. For example, enable both **Touch** and **Pointer** to support swipe on mobile and drag on desktop with a single animation.

---

## Callbacks

The **Callbacks** section maps gesture directions and events to animation actions. Each callback can trigger a different response on the timeline.

> Choose which gesture events to respond to. Each callback can trigger different animation actions.

### Gesture events

| Callback | Fires when… |
|----------|-------------|
| **onUp** | The gesture moves upward |
| **onDown** | The gesture moves downward |
| **onLeft** | The gesture moves to the left |
| **onRight** | The gesture moves to the right |
| **onStop** | Movement stops (after the onStop delay elapses) |
| **onChange** | The gesture changes in any direction |
| **onClick** | A tap or click is detected |

### Callback action

> Choose what happens when this gesture is detected: play, pause, reverse, or step through the animation.

Each enabled callback has its own **action** dropdown:

| Action | Effect on the timeline |
|--------|----------------------|
| **Play** | Plays the timeline forward from its current position |
| **Pause** | Pauses the timeline at its current position |
| **Reverse** | Plays the timeline backward |
| **Step** | Advances (or rewinds) the timeline by the **Animation step** amount |

A common pairing is **onDown → Play** and **onUp → Reverse** for a bi-directional gesture that scrubs a timeline.

---

## Axis

The **Axis** control restricts gesture detection to one or both directions of movement.

> Restrict gesture detection to horizontal (X), vertical (Y), or both axes (XY).

| Option | Gestures recognized |
|--------|-------------------|
| **XY** | Both horizontal and vertical gestures |
| **X** | Horizontal gestures only (left / right) |
| **Y** | Vertical gestures only (up / down) |

Use **X** for horizontal carousels, **Y** for vertical scroll-driven animations, and **XY** when you need to respond to all directions.

---

## Sensitivity and thresholds

These controls tune how sensitive the observer is and how much timeline progress each gesture produces.

| Control | Default | Description |
|---------|---------|-------------|
| **Tolerance** (`tObserverTolerance`) | `10` px | Minimum distance in pixels required before a gesture is recognized. Increase to ignore accidental micro-movements. |
| **Drag minimum** (`tObserverDragMinimum`) | `0` px | Minimum drag distance before drag gestures register. Prevents unintended drags on slow pointer movements. |
| **Wheel speed** (`tObserverWheelSpeed`) | `1` | Multiplier for wheel scroll sensitivity. Values above `1` make the animation react faster to wheel events; values below `1` slow it down. |
| **Scroll speed** (`tObserverScrollSpeed`) | `1` | Multiplier for native scroll gesture sensitivity. Behaves the same as Wheel speed but applies to Scroll-type events. |
| **Animation step** (`tObserverAnimationStep`) | `0.1` | How much of the timeline to advance per gesture when a callback uses the **Step** action. `0.1` = 10% of the total duration. |

> Minimum distance (in pixels) required before a gesture is recognized. Helps prevent accidental triggers.

> Multiplier for wheel scroll sensitivity. Higher values make animations respond faster to wheel events.

> How much of the timeline to animate through per gesture (0.01 = 1%, 0.1 = 10%).

---

## Behavior options

These toggles modify how the observer handles gestures and timing.

> Prevent default browser behavior for observed gestures (e.g., page scroll on wheel events).

| Control | Default | Description |
|---------|---------|-------------|
| **Prevent default** (`tObserverPreventDefault`) | off | Stops the browser's native behavior for observed events — for example, preventing the page from scrolling when the wheel event drives an animation. Enable when the observer should fully own the gesture. |
| **Lock axis** (`tObserverLockAxis`) | off | Locks gesture tracking to whichever axis moves first. Once locked, diagonal movements are ignored for the duration of that gesture. Prevents ambiguous diagonal gestures from firing both X and Y callbacks. |
| **onStop delay** (`tObserverOnStopDelay`) | `0.25` s | Seconds to wait after movement stops before the **onStop** callback fires. Increase this to debounce rapid gesture bursts. |

> Lock gestures to the initial direction of movement, preventing diagonal gestures.

> Delay (in seconds) before the onStop callback fires after movement stops.

---

## Presentation mode

**Presentation mode** transforms the observer into a full-page section scroller. Each element matched by the animation selector becomes a full-screen section, and gestures navigate between sections with smooth transitions — callbacks are handled automatically.

> Enable full-page section scrolling like a presentation. Each target becomes a full-screen section with smooth transitions between them. Callbacks are handled automatically.

Enable the **Presentation mode** toggle to reveal its sub-controls.

### Presentation mode controls

| Control | Default | Description |
|---------|---------|-------------|
| **Direction** (`tPresentationDirection`) | Vertical | Whether sections transition **vertically** (up / down) or **horizontally** (left / right). |
| **Transition Duration** (`tPresentationDuration`) | `1` s | How long each section transition animation takes. |
| **Gesture Cooldown** (`tPresentationCooldown`) | `0.5` s | Minimum time between section transitions. Prevents rapid firing on sensitive trackpads or fast scroll wheels. |
| **Effects** (`tPresentationEffects`) | Opacity + Translate | Visual effects applied during transitions. Choose **Opacity**, **Translate**, or both for a combined fade-and-slide. Select effects as chips — click the × to remove one. |
| **Infinite repeat** (`tInfiniteRepeat`) | off | When the last section is reached, loop back to the first — and vice versa on the way back. |
| **Reverse gesture** (`tReverseGesture`) | off | Flips the gesture direction mapping. When enabled, upward and leftward gestures navigate forward; downward and rightward navigate backward. |
| **Vertical wheel for horizontal** (`tUseVerticalWheel`) | off | Allows vertical mouse wheel scrolling to navigate horizontal sections. Useful for desktop users who do not have a horizontal scroll wheel. |

> Choose whether sections transition vertically (up/down) or horizontally (left/right).

> Minimum time between section transitions. Prevents rapid triggering on sensitive trackpads.

> Choose which visual effects to apply during section transitions. Select both for smooth opacity and translate animations.

> When reaching the last section, loop back to the first (and vice versa).

> Use standard gesture directions. When enabled, up/left gestures navigate forward, down/right navigate backward.

> Enable vertical mouse wheel scrolling to navigate horizontal sections. Useful for desktop users with traditional mice.

---

## SDK equivalent

The builder Observer / Gesture trigger maps to `.onGesture()` in the SDK. The Builder's **Presentation mode** adds section-layout orchestration on top of the same gesture engine; in hand-written SDK code, use `each: true` with `playNext` / `playPrevious` to step through a section collection.

**Step through a timeline on wheel:**

```typescript
import { Motion } from "@motion.page/sdk";

Motion("wheel-sequence", ".slides", {
  to: { x: "-300%" },
  duration: 1,
}).onGesture({
  types: ["wheel"],
  events: {
    Down: "play",
    Up: "reverse",
  },
  wheelSpeed: 1,
});
```

**Presentation mode — full-page section scrolling:**

```typescript
Motion("presentation", ".section", {
  from: { opacity: 0, y: 60 },
  duration: 0.6,
}).onGesture({
  target: ".presentation",
  types: ["wheel", "touch", "pointer"],
  each: true,
  events: {
    DownComplete: "playNext",
    UpComplete: "playPrevious",
  },
  tolerance: 30,
  stopDelay: 0.5,
});
```

**Swipe navigation — touch and pointer:**

```typescript
Motion("swipe-nav", ".card-stack", {
  to: { x: -200 },
  duration: 0.4,
  ease: "power2.out",
}).onGesture({
  target: ".card-stack",
  types: ["touch", "pointer"],
  tolerance: 50,
  dragMinimum: 50,
  events: {
    LeftComplete: "play",
    RightComplete: "reverse",
  },
});
```

<LivePreview client:visible
  height={280}
  title="Swipe gesture navigation"
  html={`<div class="gesture-scene">
  <div class="gesture-track">
    <div class="gesture-card">Drag or swipe me</div>
  </div>
  <p>Swipe left to dismiss · swipe right to restore</p>
</div>`}
  css={`.gesture-scene { display: grid; place-items: center; gap: 18px; width: 100%; user-select: none; }
.gesture-track { width: min(300px, 85vw); overflow: hidden; padding: 12px; border: 1px solid #29293a; border-radius: 18px; }
.gesture-card { display: grid; place-items: center; height: 120px; color: white; font-weight: 700; background: linear-gradient(135deg, #6633ee, #a855f7); border-radius: 12px; cursor: grab; touch-action: none; }
.gesture-card:active { cursor: grabbing; }
p { color: #8d8fa8; font-size: 12px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("swipe-nav", ".gesture-card", {
  to: { x: "-120%", opacity: 0, rotate: -8 },
  duration: 0.4,
  ease: "power2.out",
}).onGesture({
  target: ".gesture-track",
  types: ["touch", "pointer"],
  tolerance: 35,
  dragMinimum: 35,
  preventDefault: true,
  events: {
    LeftComplete: "play",
    RightComplete: "reverse",
  },
});`}
/>

For the full SDK reference see [Observer / Gesture — SDK reference](/docs/sdk/observer-gesture).

---

## Common patterns

### Full-page presentation

Enable **Presentation mode** with **Direction: Vertical** and set a **Cooldown** of `0.5s` to prevent accidental double-steps on trackpads. Enable **Infinite repeat** to loop the sections endlessly. Use both **Opacity** and **Translate** effects for a polished transition.

### Swipe carousel

Set **Types** to **Touch** and **Pointer**, **Axis** to **X**, and map **onLeft → Play** and **onRight → Reverse** in the Callbacks section. Set a **Tolerance** of `40–60 px` so short taps do not accidentally advance the carousel.

### Wheel-driven horizontal scroll

Set **Types** to **Wheel**, **Axis** to **Y**, and **Animation step** to `0.05`. Map **onDown → Step** and **onUp → Step** (the observer automatically uses the sign of movement to advance or rewind). Enable **Prevent default** so the page does not scroll while the animation is active.

### Gesture-controlled video scrub

Map **onChange → Step** with a very small **Animation step** (e.g. `0.005`) and set both **Wheel** and **Pointer** as types. The timeline advances incrementally on every frame of movement — ideal for scrubbing a video or a frame-by-frame sprite animation.

---

## Related

- [Observer / Gesture — SDK reference](/docs/sdk/observer-gesture) — Full `.onGesture()` API and options
- [Scroll Trigger](/docs/builder/scroll-trigger) — Scroll-position based animation with the SDK's scroll engine
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on element click
- [Mouse Movement](/docs/builder/mouse-movement) — Drive animations from cursor position

---

## Background Color

> Animate background colors between any two values in the builder.

URL: https://motion.page/docs/builder/background-color

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Background Color** animates the `background-color` CSS property of an element — transitioning from one color to another over the course of the animation. Use it to drive hover color changes, scroll-triggered palette shifts, or full-section background transitions.

## Location

**Left Panel → Animation tab → Visual Properties → Background Color**


## Enable Background Color

Click the toggle next to **Background Color** to enable it. The row expands to reveal the color input.

{/* Screenshot: Background Color row expanded, showing the hex text input, the color swatch button, and the eye dropper icon */}
![Background Color control expanded — hex input, color swatch, and eye dropper](/images/builder/background-color-control-expanded.webp)

## Controls

The expanded row contains three controls:

| Control | Description |
|---------|-------------|
| **Text input** | Type any valid CSS color: hex (`#6633EE`), RGB (`rgb(102, 51, 238)`), RGBA (`rgba(102, 51, 238, 0.5)`), or a CSS variable (`var(--brand-color)`). |
| **Color swatch** | Click the colored square to open the visual color picker. The picker supports full RGBA — drag the hue bar at the top, pick saturation and brightness in the canvas below, and adjust the alpha slider at the bottom for transparency. |
| **Eye dropper** | Click the pipette icon to sample any color from your screen. Only available in browsers that support the EyeDropper API (Chrome/Edge). |

RGBA values with transparency are fully supported — The SDK interpolates both the color channels and the alpha channel during the animation.


## From mode — element enters with a color

Switch to the **From** tab, enable Background Color, and pick a starting color. The element begins at that color and transitions to whatever `background-color` is defined in your CSS.


This is useful for reveal animations where an element "washes in" from a highlight color — for example, starting with a bright yellow flash and settling into the element's natural white or transparent background.

## To mode — element transitions to a color

Switch to the **To** tab, enable Background Color, and pick a target color. The element starts at its natural CSS `background-color` and animates to the value you set.


**To** mode is the right choice for:
- Hover color changes (element lights up on hover, reverts on leave)
- Scroll-driven section color shifts
- Click-triggered state changes

<LivePreview client:load
  height={220}
  title="Background color transition"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; }
.box { width: 120px; height: 120px; border-radius: 16px; background: #1a1a2e; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("bg-color", ".box", {
  to: { backgroundColor: "#6633EE" },
  duration: 1,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts at its CSS `background-color` (dark navy) and animates to the **To** color (`#6633EE`) — a smooth one-second transition using a custom ease.

## SDK equivalent

The `backgroundColor` property maps directly to the SDK's `from` and `to` objects.

**Color wash-in (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('color-wash', '.hero', {
  from: { backgroundColor: '#ffdd57' },
  duration: 0.9,
  ease: 'power2.out',
}).onPageLoad();
```

**Hover color change (To mode):**

```typescript
Motion('hover-color', '.card', {
  to: { backgroundColor: '#6633EE' },
  duration: 0.3,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Scroll-driven palette shift — From and To both set:**

```typescript
// Transition from one explicit color to another as the section scrolls in
Motion('section-shift', '.hero', {
  from: { backgroundColor: '#0f0f1a' },
  to:   { backgroundColor: '#6633EE' },
  duration: 1,
  ease: 'none',
}).onScroll({ scrub: true });
```

See [Colors in the SDK](/docs/sdk/colors) for the full color animation reference.

## Common patterns

### Hover color change

Enable **Background Color** on the **To** tab and pick your hover color. Set the trigger to **Hover** with **Reverse on leave** enabled. The element shifts color on hover and snaps back on mouse out.

```typescript
Motion('hover-bg', '.button', {
  to: { backgroundColor: '#4f23cc' },
  duration: 0.25,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Scroll-triggered color shift

Enable **Background Color** on the **To** tab and enable the **Scroll** trigger with **Scrub** on. The background color of a section changes in direct proportion to the scroll position — no timeline, just a live color map.

```typescript
Motion('scroll-color', '.section', {
  to: { backgroundColor: '#6633EE' },
  duration: 1,
  ease: 'none',
}).onScroll({ scrub: true });
```

### Section color transitions

Use **Background Color** on the **From** tab to give each section a unique entry color that resolves to the page's base color. Stack animations for consecutive sections to create a flowing palette as the user scrolls through.

```typescript
Motion('section-reveal', '.section', {
  from: { backgroundColor: '#ffdd57', opacity: 0 },
  duration: 0.7,
  ease: 'power2.out',
}).onScroll();
```

### Flash highlight on page load

Set trigger to **Page Load**, enable **Background Color** on the **From** tab with a bright accent color, and pair it with a short duration. The element flashes from the accent into its natural background — a subtle "look here" signal.

```typescript
Motion('flash-load', '.cta-button', {
  from: { backgroundColor: '#ffdd57' },
  duration: 0.5,
  ease: 'power3.out',
}).onPageLoad();
```

## Tips

- **RGBA transparency is fully animated** — if you set a semi-transparent color like `rgba(102, 51, 238, 0)`, the SDK will smoothly interpolate both the RGB channels and the alpha value.
- **CSS variables work in the input** — type `var(--brand-color)` to reference a design token. The SDK resolves the computed value at runtime.
- **The natural CSS value is the other endpoint** — in From mode the element lands on its CSS background; in To mode it departs from its CSS background. You only need to define one color per mode.
- **Pair with Opacity** for richer entrances — a color wash combined with a fade-in feels more designed than either property alone.
- **Avoid animating `background` shorthand** — always use `background-color` (the `backgroundColor` SDK property) rather than the `background` shorthand, which cannot be interpolated reliably when it contains gradients or images.

## Related

- [Text Color](/docs/builder/text-color) — Animate the `color` (font color) property
- [Border Color](/docs/builder/border-color) — Animate the border color
- [Opacity](/docs/builder/opacity) — Animate transparency; pairs well with Background Color
- [Colors in the SDK](/docs/sdk/colors) — Full SDK reference for color animation
- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each

---

## Scale

> Scale elements with uniform or independent X/Y controls.

URL: https://motion.page/docs/builder/scale

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Scale** increases or decreases the size of an element using a transform. The scaling transformation is defined by a vector — you can scale uniformly (preserving aspect ratio) or independently on each axis (stretching or squishing). Values are unitless: `1` is the element's natural size, `0` is invisible, `2` is double size.

## Location

**Left Panel → Animation tab → Visual Properties → Scale**

{/* Screenshot: Left Panel with the Animation tab open, showing the Scale row in the Visual Properties list with its toggle switch visible */}
![Scale property in the Left Panel Visual Properties list](/images/builder/scale-left-panel.webp)

## Enable Scale

Click the toggle next to **Scale** to enable it. The row expands to reveal the scale controls.

{/* Screenshot: Scale row expanded in uniform mode, showing a single slider and numeric input */}
![Scale control expanded — uniform mode with a single slider](/images/builder/scale-control-expanded.webp)

## Uniform vs per-axis mode

Scale has two display modes. When the Scale row is expanded, a **toggle icon** appears in the row header on the right side. Click it to switch between modes.

{/* Screenshot: Scale row header with the mode-toggle icon button highlighted on the right side */}
![Scale mode toggle — the icon button in the row header that switches between uniform and per-axis](/images/builder/scale-mode-toggle.webp)

### Uniform mode (default)

A single **scale** slider controls X and Y simultaneously. The aspect ratio of the element is preserved.

| Control | Range | Step | Description |
|---------|-------|------|-------------|
| **Scale** | `0` – `50` | `0.01` | Uniform scale applied to both X and Y. Drag range: `0` – `5`. |

### Per-axis mode

Three independent sliders appear — one each for **X**, **Y**, and **Z**. Use this for squish and stretch effects where the axes need different values.

| Control | Range | Step | Description |
|---------|-------|------|-------------|
| **Scale X** | `0` – `50` | `0.01` | Horizontal scale. |
| **Scale Y** | `0` – `50` | `0.01` | Vertical scale. |
| **Scale Z** | `0` – `50` | `0.01` | Depth scale. Requires a 3D transform context. |

{/* Screenshot: Scale row in per-axis mode, showing three separate sliders for X, Y, and Z */}
![Scale per-axis mode — three independent sliders for scaleX, scaleY, and scaleZ](/images/builder/scale-per-axis.webp)

**Value carry-over when switching modes:**
- Switching **uniform → per-axis** copies the `scale` value into `scaleX` and `scaleY`.
- Switching **per-axis → uniform** copies `scaleX` (or `scaleY`) back into `scale`.

## From mode — pop-in entrance

Switch to the **From** tab, enable Scale, and set the value to `0`. The element starts at zero size and grows into its natural dimensions.

{/* Screenshot: Scale in From mode with value set to 0 — classic pop-in entrance setup */}
![From mode — scale set to 0 for a pop-in entrance](/images/builder/scale-from-0.webp)

Setting `scale` to `0.5` instead gives a softer entry — the element is already half-size at the start, which reads as a gentle reveal rather than a hard pop.

## To mode — grow and shrink effects

Switch to the **To** tab, enable Scale, and set the value above or below `1`. The element animates from its natural size to the value you specify.

- `1.1` — a subtle hover-grow: the element enlarges slightly on interaction
- `1.3` — a more pronounced zoom-out start for dramatic reveals
- `0` — a scale-out exit: the element shrinks to a point

{/* Screenshot: Scale in To mode with value set to 1.1 — hover grow setup */}
![To mode — scale set to 1.1 for a hover grow effect](/images/builder/scale-to-1.1.webp)

The natural default for scale is `1`, so you never need to write `to: { scale: 1 }` when using From mode — Motion.page resolves it automatically.

<LivePreview client:load
  height={220}
  title="Scale entrance"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 100px; height: 100px; border-radius: 16px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scale-in", ".box", {
  from: { scale: 0, opacity: 0 },
  duration: 0.55,
  ease: "back.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box uses `from: { scale: 0, opacity: 0 }` — it starts invisible and at zero size, then springs into its natural dimensions using an elastic ease.

<LivePreview client:load
  height={220}
  title="Per-axis squish"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 100px; height: 100px; border-radius: 16px; background: #FF6633; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("squish", ".box", {
  to: { scaleX: 1.4, scaleY: 0.7 },
  duration: 0.35,
  ease: "elastic.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

This uses per-axis mode — `to: { scaleX: 1.4, scaleY: 0.7 }` — to create a squish effect. The element widens while squashing vertically, a technique from classic animation principles.

## SDK equivalent

Scale maps directly to the `scale`, `scaleX`, `scaleY`, and `scaleZ` properties in the SDK. All values are unitless numbers.

**Pop-in entrance (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('pop-in', '.card', {
  from: { scale: 0, opacity: 0 },
  duration: 0.55,
  ease: 'back.out(1.7)',
}).onPageLoad();
```

**Soft reveal (From mode):**

```typescript
Motion('soft-reveal', '.hero', {
  from: { scale: 0.5, opacity: 0 },
  duration: 0.7,
  ease: 'power3.out',
}).onPageLoad();
```

**Hover grow (To mode):**

```typescript
Motion('hover-grow', '.card', {
  to: { scale: 1.05 },
  duration: 0.25,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Pulse loop:**

```typescript
Motion('pulse', '.badge', {
  to: { scale: 1.1 },
  duration: 0.6,
  ease: 'power1.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

**Per-axis elastic jelly (To mode):**

```typescript
Motion('jelly', '.button', {
  to: { scaleX: 1.3, scaleY: 0.8 },
  duration: 0.4,
  ease: 'elastic.out(1, 0.4)',
  repeat: { yoyo: true, times: 1 },
}).onClick({ each: true });
```

## Common patterns

### Scale-in on scroll

Enable **Scale** on the **From** tab, set it to `0.3`. Add **Opacity** at `0` on the same tab. Set the trigger to **Scroll**. Cards scale up from a small size and fade in as they enter the viewport.

```typescript
Motion('card-reveal', '.card', {
  from: { scale: 0.3, opacity: 0 },
  duration: 0.6,
  ease: 'power3.out',
}).onScroll();
```

### Zoom-in entrance

Use a From value greater than `1` — the element starts oversized and shrinks to its natural size. This creates a "zoom in from large" effect common in hero sections.

```typescript
Motion('zoom-in', '.hero-image', {
  from: { scale: 1.3, opacity: 0 },
  duration: 0.8,
  ease: 'power2.out',
}).onPageLoad();
```

### Infinite pulse

Set the trigger to **Page Load**, enable **Scale** on the **To** tab with a value of `1.1`. Enable **Repeat** with **Yoyo** on and **Times** set to `-1`. The element pulses indefinitely.

```typescript
Motion('pulse-loop', '.notification-dot', {
  to: { scale: 1.2 },
  duration: 0.7,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

### Per-axis squish on click

Switch Scale to **per-axis** mode. Set `scaleX` to `1.3` and `scaleY` to `0.8` on the **To** tab. Enable **Repeat** with Yoyo and **Times** set to `1`. The element squishes on click then springs back.

```typescript
Motion('click-squish', '.button', {
  to: { scaleX: 1.3, scaleY: 0.8 },
  duration: 0.3,
  ease: 'elastic.out(1, 0.5)',
  repeat: { yoyo: true, times: 1 },
}).onClick({ each: true });
```

## Tips

- **`scale: 1`** is the natural size — you never need to include it as a `to` value when using From mode.
- **`scale: 0`** produces a hard pop-in; **`scale: 0.5`** gives a softer entry.
- The scale origin defaults to the **element's center**. To scale from a corner or edge, change the [Transform Origin](/docs/builder/transform-origin).
- Use an **elastic or back ease** with scale entrances for a natural spring feel: `ease: 'back.out(1.7)'`.
- Avoid very large scale values (`> 3`) on text elements — raster rendering artifacts can appear on some browsers.
- Per-axis mode is ideal for **squash and stretch** — one of the 12 principles of animation.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Opacity](/docs/builder/opacity) — Combine with Scale for entrance animations
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Transform Origin](/docs/builder/transform-origin) — Change the anchor point for scale (and rotation)
- [Ease](/docs/builder/easing) — Control the motion curve; elastic eases pair well with scale
- [Repeat](/docs/builder/repeat) — Loop or yoyo scale animations for pulse effects

---

## Image Sequence

> Play frame-by-frame image sequences on a canvas element synced to your timeline.

URL: https://motion.page/docs/builder/image-sequence

import LivePreview from "../../components/docs/blocks/LivePreview";

**Image Sequence** renders a series of numbered image frames onto a `<canvas>` element, driven by your timeline's progress. As a trigger (scroll, click, hover) advances the timeline, the canvas draws the corresponding frame — producing smooth, frame-accurate animations from pre-rendered imagery. Commonly used for scroll-driven product spins, cinematic reveals, and 3D object rotations.

> Play a sequence of images on the trigger.

## Location

**Left Panel → Animation tab → Visual Properties → Image Sequence**

Image Sequence is a **Builder-level visual mapping** setting. It is direction-agnostic, meaning the same sequence applies regardless of which **From**, **To**, or **Set** tab is active.

{/* Screenshot: Image Sequence controls expanded showing canvas selector, upload/transcode/gallery buttons, and playback options */}
![Image Sequence controls expanded](/images/builder/image-sequence-controls-expanded.webp)

## Getting Images onto the Canvas

Before configuring playback, you need to supply the image frames. There are two methods:

### Upload

Click the **Upload** button to upload a sequence of pre-prepared image files. Files should be numbered sequentially — e.g. `0001.jpg`, `0002.jpg`, `0003.jpg` — so the sequence player can construct the correct frame order.

> Upload a sequence of images.

### Transcode from Video

Click the **Transcode** button to extract frames directly from a video file using the built-in transcoding tool. The tool converts your video into a numbered image sequence in the browser.

> Use our transcoding tool to create an image sequence directly from a video.

**Requirements:** Transcoding is available **only in Chrome** and only on sites with **SSL (HTTPS)** enabled. On other browsers or non-SSL sites, the Transcode button is disabled.

> The transcoding feature is currently available only on the Chrome browser and on sites with SSL enabled.

### Gallery

After uploading, all your image sequences are accessible via the **Gallery** button. From here you can preview or remove any saved sequence.

> Access all your uploaded image sequences from this point. You have the option to view or remove them as needed.

## Controls

| Control | Type | Default | Description |
|---------|------|---------|-------------|
| **Canvas Selector** | CSS selector | — | The CSS selector for the `<canvas>` element on your page that will render the frames. |
| **Image Fit** | Dropdown | `Cover` | How each frame is drawn relative to the canvas bounds — Cover, Contain, or Fill. |
| **Frame Range** | Range inputs | Full range | Restrict playback to a sub-range of the total frames. Useful when different scroll sections each drive a different chapter of the same sequence. |
| **Skip Frames** | Dropdown | `0` | Skip every Nth frame to reduce the number of images loaded. `0` = disabled; values from `2`–`20` halve or further reduce the total frame count to improve performance. |
| **Reverse** | Toggle | Off | Run the sequence in the opposite direction — the last frame plays first and progress plays backward. |
| **Intersection Observer** | Toggle | Off | Defer image loading until the canvas scrolls into the viewport. Non-priority frames will not be downloaded until the canvas is visible. |
| **IO Offset** | Number input | `0` | Viewport offset (%) used by the Intersection Observer. Positive values start loading before the canvas is fully in view. |
| **When Disabled** | Multi-select | _(none)_ | Conditions under which the sequence is disabled. If any selected condition is met, the fallback mode is applied instead. |
| **Fallback Mode** | Dropdown | `Display first image` | The backup strategy applied when a "When Disabled" condition is met or a breakpoint rule disables the timeline. |
| **Disable Timeline** | Toggle | Off | When any disable condition or breakpoint setting is met, disables the entire timeline (trigger + all nodes) and applies the fallback. |
| **Debug Mode** | Toggle | Off | Logs frame loading errors and diagnostic information to the browser console. Enable this when troubleshooting a sequence that isn't playing correctly. |

## Image Fit Options

Controls how each frame image is drawn relative to the canvas element's dimensions:

| Value | Description |
|-------|-------------|
| **Cover** | Fills the entire canvas, cropping edges when the image and canvas aspect ratios differ. No stretching. Default and recommended for most sequences. |
| **Contain** | Scales the full image to fit within the canvas, leaving transparent bars on the sides or top/bottom. Requires an alpha-capable format (`png`, `webp`, `avif`). |
| **Fill** | Stretches the image to exactly match the canvas width and height, ignoring the original aspect ratio. |

> Cover: Fills the entire size, allowing for overlap but without any stretching of the image.

> **Note on Contain:** Using Contain with `jpg` files produces a black background behind the letterboxed image. Switch to `png`, `webp`, or `avif` for proper transparency.

## Disable Conditions

The **When Disabled** dropdown accepts multiple selections. The sequence is disabled if **any** selected condition is true at page load. All ten conditions available:

| Value | When it triggers |
|-------|-----------------|
| `Slow Connection` | Detected download speed is below ~1.2 Mbps, or the first frame took longer than 600 ms to load |
| `Chrome` | Visitor is using Google Chrome |
| `Safari` | Visitor is using Safari (desktop) |
| `Firefox` | Visitor is using Firefox |
| `Edge` | Visitor is using Microsoft Edge |
| `Internet Explorer` | Visitor is using Internet Explorer |
| `Touch Devices` | Device reports at least one touch point |
| `Mobile` | Mobile user-agent detected |
| `Desktop` | Desktop (non-mobile) user-agent detected |
| `Safari Mobile` | Visitor is using Safari on iOS |

> Turn off the image sequence under certain conditions and initiate the fallback action.

## Fallback Modes

When a disable condition is met, **Fallback Mode** determines what the canvas shows:

| Value | Behaviour |
|-------|-----------|
| `Display first image` | Replaces the canvas with a static `<img>` showing the first frame. Default — ensures the canvas area is never blank. |
| `Display last image` | Replaces the canvas with a static `<img>` showing the last frame. |
| `Remove canvas` | Removes the `<canvas>` element from the DOM entirely. |
| `Empty canvas` | Leaves the canvas in place but does not draw anything — canvas remains blank. |
| `None` | Takes no action. The canvas stays as-is with no fallback content. |

> Opt for a backup strategy that will be implemented when any 'disabled' condition or breakpoint settings are met.

## Performance Tips

Image sequences are asset-heavy. Apply these strategies to keep load times and memory usage under control:

- **Skip Frames** — Setting **Skip Frames** to `2` loads every other frame, halving the total HTTP requests while keeping motion smooth at typical scroll speeds. Use higher values (`3`–`5`) for sequences with very high frame counts.
- **Intersection Observer** — Enable for any sequence that starts below the fold. Non-priority frames will not be fetched until the canvas enters the viewport, keeping initial page load fast.
- **IO Offset** — Set a positive IO Offset (e.g. `20`–`50`) to begin preloading frames slightly before the canvas is fully visible, preventing a loading gap when the user scrolls fast.
- **DPR** — The default DPR of `1.25` sharpens the canvas slightly above native resolution. Lower it to `1.0` on mobile via [Breakpoints](/docs/builder/breakpoints) to reduce the canvas buffer size and memory usage.
- **Format** — Use `jpg` for fully opaque sequences — it has no alpha overhead and produces the smallest file sizes. Only switch to `png` or `webp` when transparency is needed (Image Fit: Contain, or frames with transparent backgrounds).
- **Frame count** — 60–180 frames is sufficient for most product spins and reveals. Higher counts rarely improve perceived smoothness and significantly increase total asset weight.

## Common Patterns

### Scroll-synced product reveal

The most common pattern: pin a section and scrub a 360° product rotation or cinematic reveal as the user scrolls through it.

**In the builder:**
1. Add a `<canvas>` element to your page with a clear selector, e.g. `canvas.product-spin`.
2. Set the **Canvas Selector** to `canvas.product-spin`.
3. Upload your numbered frame sequence or transcode from video.
4. Set **Image Fit** to **Cover**.
5. Enable the **Scroll Trigger** on the timeline, set **Scrub** on, and extend the trigger's **End** offset to give users enough scroll distance to explore all frames comfortably.
6. Enable **Intersection Observer** if the canvas starts below the fold.

```javascript
// Simplified shape of the code generated by the Builder
import { Motion } from "@motion.page/sdk";

const sequence = new window.MOTIONPAGE_FRONT.imageSequence({
  id: "product",
  canvasSelector: "canvas.product-spin",
  largeImagesRoot: "/images/product-360/",
  ext: "jpg",
  totalFrames: 120,
  numPadding: 4,
  dpr: 1.25,
  isIntersectionObserver: true,
});

Motion("product-spin", "canvas.product-spin", { duration: 1 })
  .onUpdate((progress) => sequence.handleUpdate(progress))
  .onScroll({
  target: ".product-section",
  start: "top top",
  end: "+=400%",
  scrub: 1,
  pin: "canvas.product-spin",
});
```

<LivePreview client:visible
  height={360}
  title="Image Sequence output driven by Motion progress"
  html={`<div class="builder-sequence-demo">
  <div class="sequence-stage">
    <canvas class="builder-sequence-canvas"></canvas>
    <span class="sequence-badge">BUILDER OUTPUT · FRAME <b>01</b></span>
  </div>
  <div class="sequence-meta">
    <span>Canvas Selector</span><strong>canvas.product-spin</strong>
    <span>Image Fit</span><strong>Cover</strong>
    <span>Frames</span><strong>60</strong>
  </div>
</div>`}
  css={`.builder-sequence-demo {
  width: min(660px, 100%);
  border: 1px solid rgba(143, 158, 255, 0.22);
  border-radius: 20px;
  overflow: hidden;
  background: #080b20;
}
.sequence-stage {
  position: relative;
  height: 250px;
  background: radial-gradient(circle at 50% 46%, rgba(90, 83, 229, 0.26), transparent 48%), #050713;
}
.builder-sequence-canvas { display: block; width: 100%; height: 100%; }
.sequence-badge {
  position: absolute;
  top: 14px;
  right: 14px;
  padding: 7px 10px;
  border: 1px solid rgba(173, 184, 255, 0.22);
  border-radius: 999px;
  background: rgba(5, 7, 20, 0.76);
  color: #858eaf;
  font-size: 9px;
  letter-spacing: 0.09em;
}
.sequence-badge b { color: #f5f6ff; }
.sequence-meta {
  padding: 15px 18px;
  display: grid;
  grid-template-columns: repeat(3, auto 1fr);
  align-items: center;
  gap: 6px 10px;
  font-size: 10px;
}
.sequence-meta span { color: #70799d; }
.sequence-meta strong { color: #dfe2ff; font-size: 11px; }
@media (max-width: 560px) {
  .sequence-meta { grid-template-columns: auto 1fr; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const canvas = document.querySelector(".builder-sequence-canvas");
const context = canvas.getContext("2d");
const frameLabel = document.querySelector(".sequence-badge b");
const driver = { progress: 0 };

function resize() {
  const dpr = Math.min(devicePixelRatio, 2);
  canvas.width = Math.round(canvas.clientWidth * dpr);
  canvas.height = Math.round(canvas.clientHeight * dpr);
}

function draw(progress) {
  driver.progress = progress;
  const dpr = Math.min(devicePixelRatio, 2);
  const width = canvas.width;
  const height = canvas.height;
  const cx = width / 2;
  const cy = height / 2;
  const angle = progress * Math.PI * 2;
  const frame = Math.round(progress * 59) + 1;

  context.clearRect(0, 0, width, height);
  context.save();
  context.translate(cx, cy);
  context.scale(0.55 + Math.abs(Math.cos(angle)) * 0.45, 1);

  const gradient = context.createLinearGradient(-100 * dpr, 0, 100 * dpr, 0);
  gradient.addColorStop(0, "#bde9ff");
  gradient.addColorStop(0.35, "#5f7cff");
  gradient.addColorStop(0.72, "#29306f");
  gradient.addColorStop(1, "#111531");
  context.fillStyle = gradient;
  context.beginPath();
  context.roundRect(-105 * dpr, -60 * dpr, 210 * dpr, 120 * dpr, 34 * dpr);
  context.fill();

  context.strokeStyle = "rgba(225, 236, 255, 0.7)";
  context.lineWidth = 2 * dpr;
  context.beginPath();
  context.ellipse(0, 0, 55 * dpr, 55 * dpr, angle, 0, Math.PI * 2);
  context.stroke();
  context.restore();

  frameLabel.textContent = String(frame).padStart(2, "0");
}

resize();
draw(0);
addEventListener("resize", () => { resize(); draw(driver.progress); });

Motion("builder-sequence-preview", driver, {
  to: { progress: 1 },
  duration: 2.7,
  ease: "none",
  onUpdate: draw,
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

### Video-to-sequence workflow

Use the built-in **Transcode** tool to go from a video file to a deployable image sequence without leaving the builder:

1. Open **Image Sequence** in the Left Panel.
2. Click **Transcode** (Chrome + HTTPS required).
3. Drop in your video file and select output format and quality.
4. Export — the tool generates numbered frames and adds them to your **Gallery**.
5. Select the sequence from the Gallery and configure playback as normal.

This avoids manual FFmpeg conversion and keeps assets managed directly inside Motion.page.

## Generated SDK Bridge

Image Sequence is a **Builder runtime feature**, not a root-level field in the core SDK's `AnimationConfig`. On export, the Builder instantiates its Image Sequence player with the values from this panel and generates a timeline-level `.onUpdate()` bridge that forwards progress to `sequence.handleUpdate(progress)`.

You do not need to write or maintain that bridge when using the Builder. For a handwritten implementation using the core SDK and your own image loader, see [Image Sequence in the SDK](/docs/sdk/image-sequence).

## Related

- [Scroll Trigger](/docs/builder/scroll-trigger) — The primary trigger for scrubbing image sequences via scroll progress
- [Breakpoints](/docs/builder/breakpoints) — Disable the sequence at specific viewport widths and apply fallback behaviour
- [Image Sequence in the SDK](/docs/sdk/image-sequence) — Handwritten frame loading and `onUpdate` playback

---

## Opacity

> Configure opacity animations in the builder UI.

URL: https://motion.page/docs/builder/opacity

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Opacity** animates the transparency of an element — from fully visible (`1`) to fully invisible (`0`), or anywhere in between. It is the simplest way to build fade-in and fade-out effects in the builder.

## Location

**Left Panel → Animation tab → Visual Properties → Opacity**

{/* Screenshot: Left Panel with the Animation tab open, showing the Opacity row in the Visual Properties list with its toggle switch visible */}
![Opacity property in the Left Panel Visual Properties list](/images/builder/opacity-left-panel.webp)

## Enable opacity

Click the toggle next to **Opacity** to enable it. The row expands to reveal the opacity slider.

{/* Screenshot: Opacity row expanded, showing the slider set to 0 and a numeric input field on the right */}
![Opacity control expanded — slider and numeric input](/images/builder/opacity-control-expanded.webp)

## Controls

| Control | Range | Default | Description |
|---------|-------|---------|-------------|
| **Slider** | `0` – `1` | — | Drag to set the opacity value. Steps in increments of `0.1`. |
| **Numeric input** | `0` – `1` | — | Type an exact value. Accepts decimals (e.g. `0.35`). |

Values outside `0`–`1` are ignored. Double-click the input to reset it.

## From mode — fade in

Switch to the **From** tab, enable Opacity, and set the value to `0`. The element starts invisible and animates to its natural CSS opacity (typically `1`).

{/* Screenshot: From tab active, Opacity enabled and set to 0 — classic fade-in entrance setup */}
![From mode — opacity set to 0 for a fade-in](/images/builder/opacity-from-0.webp)

This is the most common opacity pattern: the element is invisible at the start and fades into view.

## To mode — fade out

Switch to the **To** tab, enable Opacity, and set the value to `0`. The element starts at its natural CSS opacity and fades out to invisible.

{/* Screenshot: To tab active, Opacity enabled and set to 0 — fade-out exit setup */}
![To mode — opacity set to 0 for a fade-out](/images/builder/opacity-to-0.webp)

Use **To** for exit animations, hover dim effects, or any case where the element should start visible and become less so.

<LivePreview client:load
  height={200}
  title="Opacity fade in"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 120px; height: 120px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("fade", ".box", {
  from: { opacity: 0 },
  duration: 0.8,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts at `opacity: 0` (the **From** value) and animates to `opacity: 1` — its natural CSS state.

## SDK equivalent

The `opacity` property maps directly to the SDK's `from` and `to` objects.

**Fade in (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('fade-in', '.hero', {
  from: { opacity: 0 },
  duration: 0.8,
  ease: 'power2.out',
}).onPageLoad();
```

**Fade out (To mode):**

```typescript
Motion('fade-out', '.modal', {
  to: { opacity: 0 },
  duration: 0.5,
  ease: 'power1.in',
}).onClick({ selector: '.close-btn' });
```

**Both From and To — explicit endpoints:**

```typescript
// Animate from 0.2 to 0.8 — neither end is the natural CSS value
Motion('dim-reveal', '.card', {
  from: { opacity: 0.2 },
  to:   { opacity: 0.8 },
  duration: 0.6,
}).onScroll({ scrub: true });
```

For the full SDK reference, see [Opacity in the SDK](/docs/sdk/opacity).

## Common patterns

### Fade in on scroll

Enable **Opacity** on the **From** tab, set it to `0`. Set the trigger to **Scroll** with **Toggle Actions** set to `play pause resume reset`. The element fades in when it enters the viewport.

```typescript
Motion('scroll-fade', '.section', {
  from: { opacity: 0 },
  duration: 0.7,
  ease: 'power2.out',
}).onScroll();
```

### Fade in with a vertical slide

Combine **Opacity** and **Translate** on the same **From** tab. Set `opacity` to `0` and `y` to `40`. The element fades in while rising into place — a common reveal pattern.

```typescript
Motion('slide-fade', '.card', {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll();
```

### Fade out on exit

Set the trigger to **Page Exit**. Enable **Opacity** on the **To** tab and set it to `0`. The page fades out when the user navigates away.

```typescript
Motion('page-exit', 'body', {
  to: { opacity: 0 },
  duration: 0.4,
  ease: 'power1.in',
}).onPageExit();
```

### Hover dim

Enable **Opacity** on the **To** tab, set it to `0.5`. Set the trigger to **Hover** with **Reverse on leave** enabled. The element dims on hover and returns to full opacity on mouse out.

```typescript
Motion('hover-dim', '.thumbnail', {
  to: { opacity: 0.5 },
  duration: 0.25,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Opacity in the SDK](/docs/sdk/opacity) — SDK reference for the `opacity` property
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Ease](/docs/builder/easing) — Control acceleration and deceleration

---

## Animate SVG

> Animate SVG elements with DrawSVG, stroke color, and fill color in the builder.

URL: https://motion.page/docs/builder/svg

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Animate SVG** lets you progressively reveal SVG strokes with DrawSVG, and independently animate the stroke and fill colors of any SVG element — making it the go-to tool for logo draw-ons, icon animations, and illustrated reveals.

## Location

**Left Panel → Animation tab → Visual Properties → Animate SVG**

## Enable Animate SVG

Click the toggle next to **Animate SVG** to enable it. The row expands to reveal three independently toggled sub-controls: **DrawSVG**, **Stroke Color**, and **Fill Color**. Enable only the ones you need — they work independently and can be combined freely.

{/* Screenshot: Animate SVG row expanded, showing the three sub-feature toggles: DrawSVG, Stroke Color, and Fill Color */}
![Animate SVG expanded — three sub-feature rows: DrawSVG, Stroke Color, Fill Color](/images/builder/svg-control-expanded.webp)

## Controls

| Control | Type | Description |
|---------|------|-------------|
| **DrawSVG — Start** | Percentage input | Where the visible portion of the stroke begins (e.g. `0%`). |
| **DrawSVG — End** | Percentage input | Where the visible portion of the stroke ends (e.g. `100%`). |
| **Stroke Color** | Color picker | The color of the line drawn around the SVG element. Animates the `stroke` property. |
| **Fill Color** | Color picker | The color inside the SVG element. Animates the `fill` property. |

## DrawSVG

DrawSVG progressively reveals or hides the strokes of an SVG element. It works by animating `stroke-dasharray` and `stroke-dashoffset` under the hood — the same technique used to hand-draw icons and logos on screen.

Two percentage inputs define the **visible window** of the stroke:

- **Start %** — where the visible portion begins along the stroke path
- **End %** — where the visible portion ends along the stroke path

The full stroke is visible when both values span the entire path. A fully hidden stroke has both values at the same point (e.g. both at `0%` or both at `100%`).

| State | Start | End | Result |
|-------|-------|-----|--------|
| Hidden (default From value) | `0%` | `0%` | Stroke is fully hidden |
| Fully visible | `0%` | `100%` | Entire stroke is drawn |
| Reversed (draw off) | `100%` | `100%` | Stroke is fully hidden from the end |
| Mid-reveal | `0%` | `50%` | First half of the stroke is visible |

DrawSVG applies to any SVG element that has a visible stroke: `<path>`, `<line>`, `<circle>`, `<rect>`, `<polygon>`, and `<polyline>`. Elements with `fill` only and no `stroke` will not animate visually.

## Stroke Color

Enable **Stroke Color** to animate the outline color of the SVG element. Click the color swatch to open the color picker. The chosen color is set as the `stroke` CSS property and can transition from any starting color to any ending color.

Use **Stroke Color** in From mode to animate an element onto the screen with a color shift, or in To mode to react to hover or scroll with a color change.

## Fill Color

Enable **Fill Color** to animate the interior color of the SVG element. The color picker sets the `fill` CSS property. Like Stroke Color, this can be used in From mode to set a starting color or in To mode to animate toward a target color.

## From mode — draw on

Switch to the **From** tab, enable **DrawSVG**, and set **Start** to `0%` and **End** to `0%`. The stroke starts fully hidden and animates to its natural drawn state (`0%`–`100%`). This is the classic draw-on effect: the element appears to be sketched onto the screen in real time.

To animate Stroke Color from a starting color, enable it on the same **From** tab and pick the starting color. The element's stroke will shift from that color to its natural CSS stroke color during the animation.

## To mode — draw off

Switch to the **To** tab, enable **DrawSVG**, and set both **Start** and **End** to `100%`. The stroke starts fully drawn and progressively erases from the end — a draw-off or erase effect. Use this for exit animations, loading indicators that drain, or progress bars that reverse.

<LivePreview client:load
  height={220}
  title="SVG draw-on"
  html={`<div class="scene">
  <svg viewBox="0 0 200 200" width="160" height="160">
    <circle cx="100" cy="100" r="70" class="track" />
    <circle cx="100" cy="100" r="70" class="stroke" />
  </svg>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.track { fill: none; stroke: #222; stroke-width: 8; }
.stroke { fill: none; stroke: #6633EE; stroke-width: 8; stroke-linecap: round; transform-origin: center; transform: rotate(-90deg); }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("draw-circle", ".stroke", {
  from: { drawSVG: "0% 0%" },
  to: { drawSVG: "0% 100%" },
  duration: 1.4,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The circle starts with its stroke fully hidden (`drawSVG: '0% 0%'`) and animates to fully drawn (`drawSVG: '0% 100%'`) — the From mode draw-on pattern.

## SDK equivalent

DrawSVG, Stroke Color, and Fill Color map to the `drawSVG`, `stroke`, and `fill` properties in the SDK.

**Draw on (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('logo-draw', '.logo path', {
  from: { drawSVG: '0% 0%' },
  duration: 1.4,
  ease: 'power2.inOut',
  stagger: { each: 0.12 },
}).onPageLoad();
```

**Draw off (To mode):**

```typescript
Motion('draw-off', '.icon path', {
  to: { drawSVG: '100% 100%' },
  duration: 0.8,
  ease: 'power2.in',
}).onScroll({ scrub: true });
```

**Stroke color shift (To mode):**

```typescript
Motion('icon-hover', '.nav-icon', {
  to: { stroke: '#FF6633' },
  duration: 0.25,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Draw on with simultaneous fill reveal:**

```typescript
Motion('icon-reveal', '.icon', {
  from: {
    drawSVG: '0% 0%',
    fill: 'transparent',
  },
  to: {
    fill: '#6633EE',
  },
  duration: 1.0,
  ease: 'power2.out',
}).onPageLoad();
```

For the full SDK reference, see [SVG in the SDK](/docs/sdk/svg).

## Common patterns

### Logo draw-on on page load

Enable **DrawSVG** on the **From** tab, set **Start** to `0%` and **End** to `0%`. Add a **Stagger** to sequence multiple paths. Set the trigger to **Page Load**. Each path draws on in sequence, creating the signature "sketched logo" entrance.

```typescript
Motion('logo-entrance', '.logo path', {
  from: { drawSVG: '0% 0%', opacity: 0 },
  duration: 1.2,
  ease: 'power2.inOut',
  stagger: { each: 0.15 },
}).onPageLoad();
```

### Icon color change on hover

Enable **Stroke Color** on the **To** tab and pick a highlight color. Set the trigger to **Hover** with **Reverse on leave** enabled. The icon stroke shifts to the highlight color on hover and reverts on mouse out.

```typescript
Motion('icon-hover', '.nav-icon', {
  to: {
    stroke: '#FF6633',
    fill: '#FF220020',
  },
  duration: 0.2,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### SVG line art reveal on scroll

Enable **DrawSVG** on the **From** tab with `0%`–`0%`. Set the trigger to **Scroll** with **Scrub** enabled. The illustration draws itself in sync with the user's scroll position — ideal for scrollytelling and editorial layouts.

```typescript
Motion('line-art-scroll', '.illustration path', {
  from: { drawSVG: '0% 0%' },
  duration: 1,
  ease: 'none',
  stagger: { each: 0.05 },
}).onScroll({ scrub: true });
```

### Progress ring drain

Set up a circular SVG progress ring. Enable **DrawSVG** on the **To** tab with both values at `0% 0%`. Use the **Set** tab to pre-set the starting state (`0%`–`100%`). The ring drains as the animation plays — useful for countdown timers or progress indicators.

```typescript
// Set the initial drawn state
Motion('ring-init', '.progress-ring', {
  set: { drawSVG: '0% 100%' },
}).onPageLoad();

// Then drain it
Motion('ring-drain', '.progress-ring', {
  to: { drawSVG: '0% 0%' },
  duration: 5,
  ease: 'none',
}).onPageLoad();
```

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [SVG in the SDK](/docs/sdk/svg) — SDK reference for `drawSVG`, `stroke`, and `fill`
- [Opacity](/docs/builder/opacity) — Combine with DrawSVG for a combined fade and draw-on entrance
- [Filter](/docs/builder/filter) — Additional visual effects: blur, brightness, and more

---

## Custom Cursor

> Create custom cursor effects with smooth movement, state-based styling, hover targets, and multiple cursor instances.

URL: https://motion.page/docs/builder/custom-cursor

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

The **Custom Cursor** trigger replaces the browser's default cursor with one or more styled HTML elements that follow the pointer. Each cursor instance is independently animated with configurable smoothing, squeeze effects, and CSS-driven state transitions for default, hover, and pressed states.

## Location

**Left Panel → Trigger tab → trigger type dropdown → Mouse Follower**

{/* Screenshot: Custom Cursor trigger panel showing preset picker, instance list, and cursor instance settings */}
![Custom Cursor settings panel](/images/builder/custom-cursor-settings.webp)

---

## Preset selection

The builder ships with **14 presets** to start from. Choose a preset, then customize each instance's properties to match your design.

| Preset | Description |
|--------|-------------|
| `basic` | Semi-transparent circle (smooth: 0.35) + instant solid dot (smooth: 1) |
| `outline` | Ring outline that expands on hover over `a` elements |
| `differenceBlend` | Two layers with `mix-blend-mode: difference` for an inverted color effect |
| `multiOutline` | Four concentric outline rings with staggered smooth values (0.45–0.6) |
| `multiSolid` | Seven solid dots with decreasing smooth values, fading on hover |
| `outlineCross` | Ring + crosshair lines that grow on hover |
| `cross` | Two rectangular bars forming a plus shape |
| `blurred` | Frosted-glass circle using `backdrop-filter: blur()` |
| `invert` | `backdrop-filter: invert(100%)` — inverts content behind the cursor |
| `radialGradient` | Full-viewport `BasicCursor` with a radial gradient centered on the pointer |
| `tooltip` | `TooltipCursor` — shows tooltip text near the cursor |
| `text` | `TextCursor` — reveals a text label on hover |
| `media` | `MediaCursor` — displays an image or video that appears on hover |
| `empty` | Minimal 5 px dot, a blank canvas for custom styling |

Pick a preset and tweak it — the full instance list becomes editable once a preset is applied.

---

## Cursor instance settings

Each cursor is made up of one or more **instances**. Every instance follows the mouse independently and renders as its own DOM element.

### Smooth

> Adjust the smoothness of cursor movement. Lower values create a more fluid, delayed effect, while higher values make the cursor more responsive.

| Control | Range | Description |
|---------|-------|-------------|
| **Smooth** slider | `0` – `1` | `0` = maximum fluid delay; `1` = instant, no lag |

A value of `0.4` gives a natural, slightly delayed feel. Use `1` on a small dot that should sit exactly under the pointer.

### Squeeze

> Enable the squeeze effect to animate the cursor size when moving mouse.

Toggle **Squeeze** to enable an inertia-driven squash and stretch animation as the cursor accelerates. Works well on circular shapes.

### Instance type

The underlying cursor renderer is set per instance. Each type extends the base with extra capability:

| Type | Extra capability |
|------|-----------------|
| `BasicCursor` | Plain HTML element, full CSS control |
| `OutlineCursor` | Same as Basic — commonly used for bordered rings |
| `InvertCursor` | Pre-wired for `backdrop-filter` invert effects |
| `TextCursor` | Adds a **Text properties** section for the text node |
| `MediaCursor` | Adds a **Media properties** section for the img/video element |
| `TooltipCursor` | Renders tooltip markup attached to the cursor |

---

## Cursor states

Each instance has three states. States layer on top of each other using CSS property overrides animated by the SDK.

### Default state

> Adjust the styles of the cursor when it is in default state.

The **Default** state is always active — it defines the base appearance. Toggle it off to disable the instance entirely.

Add CSS property key/value pairs (e.g. `width: 40px`, `border-radius: 50%`, `background-color: black`). Set a **Transition duration** in seconds to control how fast the element animates back to default after leaving another state.

### Hover state

> Adjust the styles of the cursor when it is in hover state.

> Enable the hover state of the cursor.

Enable the **Hover** toggle to activate this state. When the pointer enters any **hover target**, the SDK transitions the cursor element to the hover CSS properties.

| Sub-control | Description |
|-------------|-------------|
| CSS properties | Key/value pairs that override or extend the default state |
| **Hover targets** | CSS selectors for elements that trigger this state |
| **Transition duration** | Speed (seconds) of the transition into hover |

> Adjust the duration of the animation transition when transitioning to selected state.

### Pressed state

> Adjust the styles of the cursor when it is in pressed state.

> Enable the pressed state of the cursor.

Enable **Pressed** to activate a state on `mousedown`. Define CSS property overrides and a transition duration. Useful for a shrink or color flash on click.

---

## Hover targets

> Select the elements that will trigger the hover state of the cursor.

**Hover targets** are CSS selectors that tell the cursor when to switch into its hover state. Add one selector per row.

Common values:

| Selector | What it matches |
|----------|-----------------|
| `a` | All anchor links |
| `button` | All button elements |
| `img` | All images |
| `.interactive` | Elements with a custom class |
| `[data-cursor="hover"]` | Elements with a data attribute |

Leave the targets array empty if you want the hover state to never activate (or use it only with the pressed state).

---

## Text properties

Available on **TextCursor** instances.

> Adjust the CSS properties of the text.

Add CSS property rows to style the inner text node: `font-size`, `color`, `font-weight`, `letter-spacing`, etc. The text content itself is set by the element being hovered (via a `data-cursor-text` attribute on the target element).

---

## Media properties

Available on **MediaCursor** instances.

> Adjust the CSS properties of the image or video element.

Add CSS rows to style the embedded media element inside the cursor: `width`, `height`, `border-radius`, `object-fit`, `opacity`, etc. The media source is provided by the hovered element via a `data-cursor-media` attribute.

---

## Multiple instances

> Add a new instance of the cursor.

A single Custom Cursor trigger can have **multiple instances** — each one is an independent DOM element that follows the pointer with its own `smooth` value, CSS styles, and states. Layers stack to create depth and trailing effects.

Click **+ Add instance** to add another layer.

**Example — `basic` preset (two instances):**

| Instance | Type | Smooth | Description |
|----------|------|--------|-------------|
| 1 | `BasicCursor` | `0.35` | 30 px semi-transparent circle with squeeze, expands on hover |
| 2 | `BasicCursor` | `1` | 5 px solid dot, instant — sits exactly under the pointer |

The larger circle has inertia; the dot has none. The result: the dot snaps to the cursor while the ring trails behind.

**Example — `multiOutline` preset (four instances):**

| Instance | Smooth | Size |
|----------|--------|------|
| 1 | `0.45` | 40 px ring |
| 2 | `0.50` | 30 px ring |
| 3 | `0.55` | 20 px ring |
| 4 | `0.60` | 10 px ring |

The four rings follow at slightly different speeds, creating a ripple trail. Each shrinks to 80 px on hover.

---

## Disable native cursor

> Hide the native cursor.

Toggle **Disable native cursor** to hide the browser's built-in cursor (`cursor: none`). Enable this whenever you want the custom cursor to fully replace the system pointer — otherwise both cursors appear simultaneously.

---

## SDK equivalent

The Builder Custom Cursor maps to `.onCursor()` in the SDK. Each Builder instance becomes one cursor configuration. See [Custom Cursor — SDK reference](/docs/sdk/custom-cursor).

```typescript
import { Motion } from "@motion.page/sdk";

Motion("cursor-outline").onCursor({
  smooth: 0.4,
  squeeze: true,
  hideNative: true,
  default: {
    width: 40,
    height: 40,
    borderRadius: "50%",
    border: "1px solid white",
    backgroundColor: "transparent",
  },
  hover: {
    targets: ["a", "button"],
    width: 80,
    height: 80,
    duration: 0.3,
  },
  click: { scale: 0.75, duration: 0.1 },
});
```

<LivePreview client:visible
  height={280}
  title="Builder outline cursor preset"
  html={`<div class="builder-cursor-stage">
  <div class="preset-copy">
    <span>OUTLINE PRESET</span>
    <strong>Two instances.<br />One responsive trail.</strong>
    <p>Move over the canvas, hover the circle, then click to see the pressed states.</p>
  </div>
  <button class="cursor-card">Hover</button>
</div>`}
  css={`.builder-cursor-stage {
  width: min(620px, 100%);
  min-height: 220px;
  display: grid;
  grid-template-columns: 1fr auto;
  align-items: center;
  gap: 30px;
  padding: 30px;
  overflow: hidden;
  border: 1px solid rgba(255, 255, 255, 0.12);
  border-radius: 22px;
  background: linear-gradient(135deg, #16112c, #28205a 58%, #101426);
}
.preset-copy { max-width: 350px; }
.preset-copy span { color: #b79cff; font-size: 10px; font-weight: 800; letter-spacing: 0.13em; }
.preset-copy strong { display: block; margin-top: 9px; color: white; font-size: 25px; line-height: 1.1; }
.preset-copy p { margin-top: 12px; color: #aaa8c2; font-size: 12px; line-height: 1.5; }
.cursor-card {
  width: 118px;
  height: 118px;
  border: 1px solid rgba(255, 255, 255, 0.22);
  border-radius: 24px;
  background: rgba(255, 255, 255, 0.07);
  color: white;
  font: 700 12px/1 inherit;
}
@media (max-width: 520px) {
  .builder-cursor-stage { grid-template-columns: 1fr 80px; gap: 14px; padding: 22px; }
  .cursor-card { width: 80px; height: 80px; }
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-cursor-ring").onCursor({
  smooth: 0.22,
  squeeze: true,
  default: {
    width: 42,
    height: 42,
    borderRadius: "50%",
    border: "1px solid rgba(255,255,255,0.9)",
    backgroundColor: "transparent",
    zIndex: 999998,
  },
  hover: {
    targets: [".cursor-card"],
    width: 82,
    height: 82,
    border: "2px solid #b99cff",
    duration: 0.28,
  },
  click: { scale: 0.75, duration: 0.1 },
});

Motion("builder-cursor-dot").onCursor({
  smooth: 0.7,
  hideNative: true,
  default: {
    width: 7,
    height: 7,
    borderRadius: "50%",
    backgroundColor: "#ffffff",
    zIndex: 999999,
  },
  hover: {
    targets: [".cursor-card"],
    scale: 0.5,
    backgroundColor: "#b99cff",
    duration: 0.2,
  },
  click: { scale: 1.8, duration: 0.08 },
});`}
/>

---

## Common patterns

### Difference blend cursor

Use the `differenceBlend` preset. Both instances carry `mix-blend-mode: difference` with a white background — anywhere the cursor passes over light content it shows dark, and over dark content it shows white. No hover target configuration needed; the blend does the visual work.

Great for creative portfolios where the cursor should interact visually with every element on the page.

### Text label on hover

Use the `text` preset (`TextCursor`). The cursor is invisible by default (`opacity: 0`). Add a `data-cursor-text="View project"` attribute to the elements you want to label. When the pointer enters a hover target, the cursor expands and fades in with the label text.

Configure the **Text properties** section to set `font-size`, `color`, and `font-family`.

### Media preview on hover

Use the `media` preset (`MediaCursor`). Add `data-cursor-media="/path/to/image.jpg"` (or `.mp4`) to gallery items or cards. The cursor starts hidden (`transform: scale(0)`) and scales in on hover, displaying the media.

Use the **Media properties** section to set `border-radius`, `object-fit: cover`, and size.

### Multi-layer trailing effect

Stack three or more `OutlineCursor` instances with incrementally lower `smooth` values (e.g. `0.45`, `0.55`, `0.65`). Each ring lags slightly more than the one before, producing a comet-tail effect. Apply the same hover target and property overrides to all layers so they expand in unison.

---

## Related

- [Custom Cursor — SDK reference](/docs/sdk/custom-cursor) — `.onCursor()` API and full options
- [Hover Trigger](/docs/builder/hover-trigger) — Trigger animations on pointer enter
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on element click
- [Page Load Trigger](/docs/builder/page-load) — Auto-play animations when the page loads
- [Left Panel](/docs/builder/left-panel) — Full Left Panel reference including the Trigger tab

---

## Responsive Editing

> Tune a single timeline per device with cascading overrides — no duplicate timelines required.

URL: https://motion.page/docs/builder/responsive-editing

import Steps from "../../components/docs/blocks/Steps.astro";

Responsive Editing lets one timeline look different on every device. Instead of building a separate animation for desktop, laptop, tablet, and phone, you edit a single timeline and store only the values that change per device as **overrides**. Everything else cascades down from the wider device automatically.

{/* Screenshot: Top Panel device switcher with an element showing per-breakpoint override markers in the Left Panel */}
![Responsive Editing — device switcher in the Top Panel with override markers on edited values](/images/builder/responsive-editing-overview.webp)

---

## What it is

A timeline has four device tiers — **desktop**, **laptop**, **tablet**, and **phone**. You pick a device, change a value, and that change is saved as an override *for that device only*. Overrides cascade from the widest screen to the narrowest:

**desktop → laptop → tablet → phone**

A tier with no override of its own inherits the value from the closest wider tier. Set a value on desktop and it applies everywhere; override it on tablet and tablet and phone follow the new value while desktop and laptop keep the original. This replaces the old approach of duplicating a timeline once per device and guarding each copy with a media query.

> **Note:** Cascading means you usually only touch the desktop values, then make a few small adjustments on smaller screens. The narrower the device, the fewer overrides you typically need.

---

## How to use it

<Steps>

1. Switch device in the Top Panel

   Use the device switcher in the center of the **Top Panel** to select desktop, laptop, tablet, or phone. The Frame View resizes to that breakpoint's width so you see the page exactly as that device will. The currently selected device determines which tier your edits are saved to.

2. Edit values

   Change any animation property — opacity, translate, duration, easing, anything in the Left Panel. While a non-desktop device is selected, only the values you actually change are stored as overrides for that device. Untouched values stay inherited.

3. Let the overrides cascade

   Your edits flow downward through **desktop → laptop → tablet → phone**. A value set on a wider device is the default for every narrower device until one of them overrides it. You never re-enter values that don't change between devices.

</Steps>

---

## Seeing what's overridden

Each animated element shows a **breakpoint indicator row** that maps to the four device tiers. The indicators make it obvious, at a glance, where a value is inherited and where it has been overridden:

- An **override marker** highlights any property that has its own value on the current device, rather than inheriting from a wider one.
- Inherited values show no marker — they're following the cascade.
- A **one-click reset** on an override removes it and returns the property to its inherited value. The element instantly falls back to whatever the wider device defines.

This lets you audit a responsive timeline quickly: anything marked is intentional per-device tuning; anything unmarked is shared.

{/* Screenshot: A single element's property list showing override markers on two values and the reset control on one of them */}
![Override markers — edited values flagged per device with one-click reset to inherited](/images/builder/responsive-editing-overrides.webp)

---

## Hiding an element per device

Sometimes an animation shouldn't run at all on certain screens — a heavy parallax that doesn't suit phones, or a hover effect that has no place on touch devices. On any device tier you can **hide or disable an element's animation** for that tier.

A disabled element simply doesn't animate on the devices where it's turned off, while continuing to animate normally on the others. Like every other override, this is per-tier and cascades, so disabling on tablet also affects phone unless phone re-enables it.

> **Tip:** Disable hover-driven animations on tablet and phone — touch screens have no hover state, so the effect would never trigger there anyway.

---

## Live preview

Every change is reflected immediately. As you switch devices in the Top Panel, the Frame View swaps to that viewport and replays the timeline with that device's resolved values — no rebuild, no reload. You're always previewing the exact animation a visitor on that device will see.

On the **published site**, the same behavior is live: the correct device variant is selected from the viewport width, and the animation swaps instantly if the viewport crosses a breakpoint boundary (for example, when a tablet is rotated or a desktop window is resized).

---

## Related

- [Breakpoint Sizes](/docs/builder/breakpoints) — Set the pixel thresholds that define each device tier
- [Responsive Animations (SDK)](/docs/sdk/responsive) — The developer-facing `Motion.responsive()` equivalent
- [Top Panel](/docs/builder/top-panel) — The device switcher and preview controls
- [Left Panel](/docs/builder/left-panel) — Where animation values and overrides are edited

---

## Text Splitter

> Split text into chars, words, or lines for per-element animation.

URL: https://motion.page/docs/builder/split-text

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Text Splitter** breaks a text element into individual `<span>` nodes — one per character, word, or line — so each unit can animate independently. Pair it with [Stagger](/docs/builder/stagger) to create cascading text reveals: words sliding in one by one, characters popping in sequence, lines rising from below a clip boundary.

> Split each character, word or line into its div, and animate them one by one using Stagger.

## Location

**Left Panel → Animation tab → Functional Properties → Text Splitter**

Text Splitter is a **functional property** — it is direction-agnostic. The same split applies whether the **From**, **To**, or **Set** tab is active. Enabling it on any tab automatically enables it on all three.


## Enable Text Splitter

Click the toggle next to **Text Splitter** to enable it. The row expands to reveal the type dropdown, class input, Reduce White Space toggle, and Mask toggle. A live preview fires immediately in the builder so you can see the split in action.

{/* Screenshot: Text Splitter row fully expanded, showing the Type dropdown set to "Characters", Class input, Reduce White Space toggle, and Mask toggle */}
![Text Splitter controls expanded — type dropdown, class input, and toggles](/images/builder/split-text-controls-expanded.webp)

## Controls

| Control | Type | Default | Description |
|---------|------|---------|-------------|
| **Type** | Dropdown | `Characters` | The unit each piece of text is split into — Characters, Words, or Lines. |
| **Class** | Text input | _(empty)_ | Optional CSS class applied to every split span. Dot prefixes are stripped automatically. Append `++` to add incrementing numbers: `.char1`, `.char2`, `.char3`. |
| **Reduce White Space** | Toggle | On | Collapses extra whitespace between words for cleaner splitting. Leave on unless your layout depends on multiple spaces. |
| **Mask** | Toggle | Off | Wraps each split element in an `overflow: hidden` container for cinematic clip-reveal effects (e.g. text sliding up from behind an invisible edge). |
| **Inline** | Number input | `0.15em` | Shown when Mask is on. Adds horizontal mask bleed so italic, script, or display glyphs are not clipped on the left/right edges. |
| **Block** | Number input | `0.04em` | Shown when Mask is on. Adds vertical mask bleed so ascenders, descenders, and swashes are not clipped on the top/bottom edges. |

### Split type options

| Value | Description |
|-------|-------------|
| `Characters` | Every character — including spaces — becomes its own animatable span. Use tight stagger values (`0.02`–`0.05`). |
| `Words` | Each word becomes a span. Use looser stagger values (`0.06`–`0.1`). |
| `Lines` | Each line of text (based on the element's actual word-wrap) becomes a span. Typically needs stagger values of `0.1`–`0.2`. |

> **Note on Lines:** Line splitting reflects the element's actual layout at animation time. If the container resizes, the line count changes. Test at your target breakpoint.

## Mask mode

Enable **Mask** to wrap each split unit in an `overflow: hidden` container. Animate with `y: "110%"` on the **From** tab to slide each unit up from behind the invisible clip boundary — a clean newspaper-headline reveal with no extra CSS required.

When Mask is enabled, **Inline** and **Block** controls appear below it. These values add mask bleed in `em` units while the SDK applies matching negative margins, so the clip area expands without changing the text layout. Increase **Inline** for italic/script overhangs; increase **Block** for tall ascenders, descenders, or decorative swashes.

The mask containers use `overflow: hidden` plus the configured bleed. Combine with any **From** translate offset for the reveal direction: `y: "110%"` for up, `x: "-110%"` for from the left.

## Pairing with Stagger

Text Splitter works alongside [Stagger](/docs/builder/stagger), which appears directly below it in the Functional Properties list. Stagger controls the cascade — the delay between each character, word, or line entering. Without stagger, all split units animate simultaneously, which defeats the purpose.

Enable both **Text Splitter** and **Stagger** together. A typical setup:

- **Type:** Words
- **Mask:** On
- **Stagger Each:** `0.08 s`, **From:** `start`
- **From tab:** `y: 110%`, `opacity: 0`

This produces each word sliding up from behind its clip boundary, left to right.

> Text Splitter also **re-enables** Stagger when using the Interactions trigger in Click/Hover Multiple mode — normally stagger is disabled in that mode, but adding Text Splitter lifts that restriction.

<LivePreview client:load
  height={200}
  title="Character-by-character reveal"
  html={`<div class="scene">
  <h1 class="headline">Motion.page</h1>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #0d0d0d; font-family: system-ui; }
.headline { color: #fff; font-size: 2.2rem; font-weight: 700; margin: 0; letter-spacing: -0.02em; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("headline", ".headline", {
  from: { y: "110%" },
  split: "chars",
  mask: true,
  stagger: 0.045,
  duration: 0.55,
  ease: "power3.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

Each character starts at `y: 110%` behind its mask container and slides up into place, left to right. This is **Text Splitter** set to **Characters**, **Mask** on, combined with **Stagger Each: 0.04**.

## SDK equivalent

Text Splitter maps to the `split` and `mask` properties in the SDK config. The builder only supports single-level splits (`chars`, `words`, `lines`) — combined values like `'chars,words'` are available in the SDK directly.

**Characters with mask (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('headline', 'h1', {
  split: 'chars',
  mask: true,
  maskPadding: { inline: 0.15, block: 0.04 },
  from: { y: '110%', opacity: 0 },
  duration: 0.48,
  stagger: { each: 0.04, from: 'start' },
  ease: 'power3.out',
}).onPageLoad();
```

**Words slide in on scroll:**

```typescript
Motion('section-title', '.section-title', {
  split: 'words',
  mask: true,
  from: { y: '110%' },
  duration: 0.6,
  stagger: { each: 0.08, from: 'start' },
  ease: 'power3.out',
}).onScroll({
  each: true,
  toggleActions: 'play none none none',
  start: 'top 85%',
});
```

**Lines fade up:**

```typescript
Motion('paragraph', 'p', {
  split: 'lines',
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: { each: 0.15, from: 'start' },
  ease: 'power2.out',
}).onPageLoad();
```

For the full SDK reference, see [Text Splitter in the SDK](/docs/sdk/split-text).

## Common patterns

### Words slide up from mask

Enable **Text Splitter** → **Words**, turn on **Mask**. On the **From** tab set `y` to `110%`. Add **Stagger** → **Each: 0.08**, **From: start**.

```typescript
Motion('words-mask', 'h2', {
  split: 'words',
  mask: true,
  maskPadding: { inline: 0.25, block: 0.08 },
  from: { y: '110%' },
  duration: 0.6,
  stagger: { each: 0.08, from: 'start' },
  ease: 'power3.out',
}).onPageLoad();
```

### Characters fade in randomly

Set **Type** to **Characters**, leave **Mask** off. On **From**, set `opacity: 0` and `y: 20`. Set **Stagger** → **Each: 0.02**, **From: random** for an organic, shuffled entrance.

```typescript
Motion('chars-random', '.display-title', {
  split: 'chars',
  from: { opacity: 0, y: 20 },
  duration: 0.4,
  stagger: { each: 0.02, from: 'random' },
  ease: 'power2.out',
}).onPageLoad();
```

### Typewriter effect

Set **Type** to **Characters**. On the **From** tab, set only `opacity: 0`. Keep **Duration** very short (`0.05 s`) or set it to `0`. Set **Stagger** → **Each: 0.07**, **From: start**. The characters snap in one by one at a typed cadence.

```typescript
Motion('typewriter', '.terminal', {
  split: 'chars',
  from: { opacity: 0 },
  duration: 0,
  stagger: { each: 0.07, from: 'start' },
}).onPageLoad();
```

### Lines rise on scroll

Set **Type** to **Lines**. On **From**, set `opacity: 0` and `y: 40`. Set **Stagger** → **Each: 0.15**, **From: start**. Use a Scroll trigger so each paragraph line enters as it scrolls into view.

```typescript
Motion('lines-scroll', '.body-text', {
  split: 'lines',
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  stagger: { each: 0.15, from: 'start' },
  ease: 'power2.out',
}).onScroll({
  each: true,
  toggleActions: 'play none none none',
  start: 'top 80%',
});
```

### Custom class with numbered spans

Enter a class name in the **Class** field — for example `word`. Each span receives the class `word`. Append `++` to the name (`word++`) to produce `word1`, `word2`, `word3`, and so on — useful for targeting individual splits in CSS.

```css
/* Target spans with the numbered class pattern */
.word1 { color: #6633EE; }
.word2 { color: #aa88ff; }
```

## Tips

- **Apply Text Splitter to text elements only** — `h1`–`h6`, `p`, `span`, `li`, `a`, and similar inline/block text containers. Applying it to layout wrappers (e.g. `section`, `div` with mixed content) may produce unexpected results.
- **Stagger is required for visible sequencing.** Without Stagger, every split unit animates at exactly the same time.
- **Lines are layout-sensitive.** If the window resizes between page load and animation, line boundaries may differ from when the split was computed. Use the SDK's `onResize` option to recompute on resize when line splitting is critical.
- **Mask + `y: "110%"` is the gold standard** for text reveal. The `110%` ensures the starting position fully clears the clip boundary even with sub-pixel rounding.
- **Increase mask bleed for expressive fonts.** Script, italic, and display fonts often draw outside their text box. Raise **Inline** or **Block** until the glyphs no longer clip.
- **Text Reveals presets** in the [Animation Presets](/docs/builder/animation-presets) panel include 20 ready-made Text Splitter animations — a fast starting point for characters, words, and lines.

## Related

- [Stagger](/docs/builder/stagger) — Control the cascade delay between split units
- [Animation Presets](/docs/builder/animation-presets) — 20 ready-made Text Reveals presets using Text Splitter
- [From, To & Set](/docs/builder/from-to-set) — How functional properties apply across animation mode tabs
- [Translate](/docs/builder/translate) — Set `y` offset values used in Text Splitter reveals
- [Opacity](/docs/builder/opacity) — Often combined with Text Splitter for fade reveals
- [Text Splitter in the SDK](/docs/sdk/split-text) — Full SDK reference including combined split values

---

## Custom Properties

> Animate any CSS property using the Custom Properties panel in the builder.

URL: https://motion.page/docs/builder/custom-properties

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Custom Properties** lets you animate any CSS property that isn't covered by the built-in property panels — from `border-radius` and `letter-spacing` to `box-shadow` and `padding`.

## Location

**Left Panel → Animation tab → Visual Properties → Custom**


## Enable Custom Properties

Click the toggle next to **Custom** to enable it. The row expands to show a two-column input with a **Property** field and a **Value** field.

{/* Screenshot: Custom Properties expanded showing key/value rows with +, code toggle, and × buttons */}
![Custom Properties expanded — key/value rows with property and value inputs](/images/builder/custom-properties-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Property input** | The CSS property name. Accepts camelCase (`borderRadius`) or kebab-case (`border-radius`). |
| **Value input** | The target value for the property. Accepts any valid CSS value string or number. |
| **Add row button** (`+`) | Appends a new empty Property/Value row. Use this to animate multiple custom properties in one animation step. |
| **Code field toggle** | Switches the panel between Key/Value mode and Advanced Code Field mode. The icon is a `</>` code symbol. |
| **Right-click context menu** | Right-click any row in column view to **Duplicate**, **Copy**, **Paste**, or **Delete row**. The last remaining row cannot be deleted. |

## Key/Value mode (default)

Each row has two inputs side by side:

- **Property** — the CSS property you want to animate, e.g. `border-radius`, `letter-spacing`, `padding-top`
- **Value** — the CSS value to animate to (or from), e.g. `50%`, `0.2em`, `24px`

Use camelCase or kebab-case for the property name — both resolve correctly. When you enter a value that contains a `cubic-bezier()` expression or a four-number easing string, the builder normalises the decimal format automatically.

Click the **+** button in the panel header to append additional rows. Each row animates a separate CSS property within the same tween.


## Advanced Code Field mode

Click the **code field icon** (the `</>` button) to switch to **Advanced Code Field** mode. This replaces the row inputs with a freeform code editor that accepts any valid `from`/`to` object key-value pairs.


Use the Advanced Code Field when:

- You need to enter complex multi-value strings like `box-shadow` or `backdrop-filter`
- You want to paste properties copied from existing SDK code
- You need to enter properties with special formatting that the row inputs make awkward

Click the code field icon again to toggle back to Key/Value mode.

## From mode — animate from a custom value

Switch to the **From** tab, enable Custom, and add property/value pairs. The element starts at those values and animates to its natural CSS state.


Example: set `border-radius` to `0` on the **From** tab. If the element's CSS has `border-radius: 50%`, it starts as a sharp square and morphs into a circle.

## To mode — animate to a custom value

Switch to the **To** tab, enable Custom, and set the target property/value. The element starts at its natural CSS state and animates to the specified value.


Example: set `border-radius` to `50%` on the **To** tab. The element morphs from whatever its CSS defines into a circle.

<LivePreview client:load
  height={220}
  title="Border-radius morph — square to circle"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; }
.box { width: 120px; height: 120px; background: #6633EE; border-radius: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("morph", ".box", {
  to: { borderRadius: "50%" },
  duration: 0.8,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts with `border-radius: 0` (the **From** value) and animates to `border-radius: 50%` — a full circle.

## SDK equivalent

Custom Properties map directly to any key-value pair in the `from` and `to` objects of the SDK.

**Border-radius morph (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('circle-in', '.avatar', {
  from: { borderRadius: '0%' },
  to:   { borderRadius: '50%' },
  duration: 0.8,
  ease: 'power2.out',
}).onPageLoad();
```

**Letter-spacing expand (To mode):**

```typescript
Motion('text-expand', '.headline', {
  to: { letterSpacing: '0.15em' },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll({ scrub: true });
```

**Multiple custom properties in one tween:**

```typescript
Motion('card-reveal', '.card', {
  from: {
    borderRadius: '4px',
    boxShadow: '0 0px 0px rgba(0,0,0,0)',
  },
  to: {
    borderRadius: '20px',
    boxShadow: '0 16px 40px rgba(0,0,0,0.18)',
  },
  duration: 0.5,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

For the full SDK reference, see [Custom Properties in the SDK](/docs/sdk/custom-properties).

## Common patterns

### Border-radius morph

Animate a sharp element into a pill or circle shape:

```typescript
Motion('pill-in', '.button', {
  from: { borderRadius: '4px' },
  to:   { borderRadius: '999px' },
  duration: 0.5,
  ease: 'power2.inOut',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Letter-spacing expand on scroll

Widen letter-spacing as the element enters the viewport — a common typographic reveal:

```typescript
Motion('type-reveal', '.tagline', {
  from: { letterSpacing: '-0.05em', opacity: 0 },
  duration: 0.9,
  ease: 'power3.out',
}).onScroll();
```

### Padding push on hover

Animate padding to give a button a "breath" effect on hover:

```typescript
Motion('btn-breathe', '.cta', {
  to: { paddingLeft: '32px', paddingRight: '32px' },
  duration: 0.25,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Box-shadow lift

Elevate a card with a growing shadow on scroll entry:

```typescript
Motion('card-lift', '.card', {
  from: { boxShadow: '0 0px 0px rgba(0,0,0,0)' },
  to:   { boxShadow: '0 16px 40px rgba(0,0,0,0.15)' },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll({ toggleActions: 'play none none reverse' });
```

For shadow interpolation to tween smoothly, keep the **same number of shadow layers** in both `from` and `to`. Mismatched layer counts cause a hard swap at the midpoint.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Custom Properties in the SDK](/docs/sdk/custom-properties) — SDK reference for custom key-value animation pairs
- [Filter](/docs/builder/filter) — Animate blur, brightness, contrast, and other CSS filter functions
- [Opacity](/docs/builder/opacity) — Animate element transparency with a dedicated slider

---

## Getting Started

> Step-by-step guide to creating your first animation in the Motion.page Builder.

URL: https://motion.page/docs/builder/getting-started

import Steps from '../../components/docs/blocks/Steps.astro';
import LivePreview from '../../components/docs/blocks/LivePreview';

This guide walks you through creating your first animation in the Motion.page Builder — from opening the editor to publishing a live animation. No code required.

<Steps>

1. **Open the Builder**

   How you open the builder depends on which version you're using.

   **WordPress Plugin** — In your WordPress admin dashboard, navigate to any page or post and click **Edit with Motion.page**. The builder opens in a full-screen overlay with the page loaded in the Frame View.

   **Desktop App** — Launch the desktop application and sign in. From the **Dashboard**, create a new **Project** (enter a name and website URL) or open an existing one. The project's page loads inside the Frame View, ready to animate. You can also create an **Artifact** for standalone animation code that isn't tied to a specific page.

   {/* IMAGE PLACEHOLDER: Two side-by-side views — left: WordPress admin "Edit with Motion.page" button highlighted on a page row; right: Desktop app Dashboard showing project cards with a "New Project" button */}
   ![Opening the Builder — WordPress button and Desktop Dashboard](/images/builder/getting-started-open-builder.webp)

2. **Select an element**

   Click any element in the **Frame View** — a heading, a button, a card, an image. The **Left Panel** on the left immediately loads the animation settings for that element.

   The **selector** field at the top of the Left Panel shows the CSS selector Motion.page will use to target that element at runtime. If you want to refine it, click the **cursor icon** on the right edge of the field to activate the **Selector Scanner**, then click any element to pick from a list of available selectors for it and its parent.

   {/* IMAGE PLACEHOLDER: Frame View with a heading element highlighted by a blue overlay, and the Left Panel open on the right showing the selector field populated with ".hero h1" and the Animation tab visible */}
   ![Selecting an element — Frame View highlight and Left Panel selector field](/images/builder/getting-started-select-element.webp)

3. **Add an animation property**

   In the **Left Panel**, open the **Animation tab**. You'll see two main tabs: **From** and **To** (and a **Set** tab for instant-set values).

   - **From** — the starting state of the element before the animation plays. Use this for entrance animations.
   - **To** — the ending state the element animates toward. Use this for exit or emphasis animations.

   Click the **From** tab, then click **+ Add Property** (or the `+` icon in the property list). A picker appears — choose a property like **Opacity** or **Translate**. The property row appears with a toggle to enable it and an input to set its value.

   For example, set **Opacity** to `0` in the **From** tab — this means the element starts invisible and fades in when the animation plays.

   {/* IMAGE PLACEHOLDER: Left Panel with the From tab active, showing the property picker open with Opacity highlighted, and an existing Translate Y row already added below */}
   ![Adding an animation property — From tab with property picker open](/images/builder/getting-started-add-property.webp)

4. **Preview the animation**

   Hit the **Play** button in the **Timeline Editor** at the bottom of the screen to preview your animation immediately. The playhead scrubs through the timeline and the element animates in the Frame View.

   For **trigger-based** animations (scroll, hover, click), enable the **Live Play** toggle in the Top Panel. This activates the trigger on the live page inside the Frame View — scroll the page to fire a scroll animation, hover an element to fire a hover animation, and so on.

   {/* IMAGE PLACEHOLDER: Timeline Editor at the bottom showing the Play/Pause button highlighted, with the playhead mid-scrub; inset showing the Live Play toggle in the Top Panel in its active (on) state */}
   ![Previewing the animation — Play button in the Timeline Editor and Live Play toggle](/images/builder/getting-started-preview.webp)

5. **Choose a trigger**

   Every animation needs a trigger — the event that tells it when to play. In the **Left Panel**, switch to the **Trigger tab**.

   | Trigger | When it fires |
   |---------|--------------|
   | **Page Load** | As soon as the page JS initialises — good for hero sections and above-the-fold reveals. |
   | **Scroll** | When the element scrolls into view; can also scrub with the scrollbar or pin in place. |
   | **Hover** | On mouse enter — configure reverse, restart, or hold on mouse leave. |
   | **Click** | On element click — reverse or restart on second click. |
   | **Mouse Movement** | Timeline progress tracks cursor position relative to a container. |
   | **Gesture / Observer** | Responds to pointer, touch, wheel, and scroll direction gestures. |
   | **Page Exit** | Plays when a link is clicked, just before the browser navigates away. |

   Pick **Page Load** to start — it's the simplest and requires no extra configuration. The animation will play automatically every time the page loads.

   {/* IMAGE PLACEHOLDER: Left Panel with the Trigger tab active, showing the trigger type dropdown open with "Page Load" selected and its settings panel expanded below */}
   ![Choosing a trigger — Trigger tab with Page Load selected](/images/builder/getting-started-trigger.webp)

6. **Save and publish**

   When your animation looks right, hit the **Publish** button in the **Top Panel** (top-right corner of the builder).

   **WordPress** — Publish writes the animation configuration to your site. The animation is immediately live for visitors — no separate deploy step needed.

   **Desktop** — Save stores the animation in the project. Use **Export** to copy the generated SDK code, which you can embed in your site's `<head>` or include in your build.

   {/* IMAGE PLACEHOLDER: Top Panel with the Publish button highlighted (WordPress) and, below it, the Desktop export panel showing the generated SDK code snippet ready to copy */}
   ![Saving and publishing — Publish button in the Top Panel](/images/builder/getting-started-publish.webp)

</Steps>

---

## What just happened?

When you hit Publish, Motion.page generated a named animation timeline — something like this under the hood:

```typescript
import { Motion } from '@motion.page/sdk';

Motion('hero-heading', '.hero h1', {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad();
```

The SDK handles scroll detection, trigger lifecycle, and all animation wiring. The builder is a visual interface on top of exactly these function calls.

---

Here's the kind of animation you just built — an element fading up from below on page load:

<LivePreview client:load
  height={200}
  title="Fade-up on page load"
  html={`<div class="hero">
  <h1 class="headline">Motion.page</h1>
  <p class="sub">Your first animation, live.</p>
</div>`}
  css={`.hero {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100%;
  background: #0f0f0f;
  gap: 10px;
}
.headline {
  font-family: system-ui;
  font-size: 28px;
  font-weight: 700;
  color: #dfe1f4;
  margin: 0;
}
.sub {
  font-family: system-ui;
  font-size: 14px;
  color: #888;
  margin: 0;
}`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("hero-reveal", ".headline, .sub", {
  from: { opacity: 0, y: 24 },
  duration: 0.7,
  stagger: 0.15,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

---

## Next Steps

Now that you've created your first animation, explore what else the builder can do:

- [From, To & Set](/docs/builder/from-to-set) — understand the three animation modes and when to use each
- [Element Selection](/docs/builder/element-selection) — target single elements, groups, and dynamic selectors
- [Easing](/docs/builder/easing) — shape how your animation accelerates and decelerates
- [SDK Overview](/docs/sdk/overview) — use the SDK directly to go beyond what the builder's UI exposes

---

## Left Panel

> Animation configuration — tabs, From/To/Set, selectors, folders, and trigger section.

URL: https://motion.page/docs/builder/left-panel

The Left Panel is the primary animation configuration area. It has two main tabs: **Animation** and **Trigger**.

{/* Screenshot: Full Left Panel showing the Animation tab active with selector input, From/To/Set toggle, and visual property list visible */}
![Left Panel overview](/images/builder/left-panel-overview.webp)

---

## Animation Tab

The **Animation** tab is where you define what gets animated and how. It is split into a selector input at the top, the From/To/Set mode toggle, and then the list of animatable properties beneath.

### Selector Input

The **selector input** accepts any valid CSS selector — class, ID, attribute, pseudo-element, or a comma-separated list. Every element that matches the selector on the page will be targeted by the animation.

{/* Screenshot: Selector input field with the scanner icon on the right, showing ".hero-title" typed in the field */}
![Selector input with scanner icon](/images/builder/left-panel-selector.webp)

| Control | Description |
|---------|-------------|
| **Selector field** | Choose one or multiple CSS selectors to animate. |
| **Scanner icon** | Enable the selector scanner — click any element in the Frame View to insert its selector automatically. |

Click the **scanner icon** (tSDetector) to activate the interactive selector detector. With it enabled, hovering over the Frame View highlights elements, and clicking inserts the matching selector into the field.

---

### From / To / Set Mode Toggle

Just below the selector field is the **From / To / Set toggle** — a three-way switch that controls which endpoint of the animation you are configuring.

{/* Screenshot: From/To/Set three-way toggle showing the "From" button active with a dot indicator */}
![From / To / Set toggle](/images/builder/left-panel-from-to-set.webp)

| Mode | Description |
|------|-------------|
| **From** | Add animation properties as 'FROM'. They will be a starting point of your animation, while an ending point are current values of the element or 'To' properties. |
| **To** | Add animation properties as 'TO'. They will be an ending point of your animation, while a starting point are current values of the element or 'From' properties. |
| **Set** | Add properties as 'SET'. Acts as a zero-duration 'TO' tween, which immediately sets properties of the target(s) with no animation. |

A dot indicator appears on the **From** or **To** button when that mode has properties configured. Both modes can hold values simultaneously — switch between them freely to set up each endpoint.

> **Tip:** Right-click on the **From** or **To** button to reveal additional options: Duplicate, Toggle (swap From ↔ To), Clear, Copy, and Paste.

For a full explanation of how these modes interact, see [From, To & Set](/docs/builder/from-to-set).

---

### Visual Properties

**Visual properties** control the appearance and transform of the target element. Each property has a toggle to enable or disable it on the current node.

{/* Screenshot: Visual properties list showing Opacity, Translate, Scale, Rotation, and others as expandable rows */}
![Visual properties list](/images/builder/left-panel-visual-properties.webp)

| Property | Description |
|----------|-------------|
| **Opacity** | Fade in & out using opacity. |
| **Translate** | Move the element on X and/or Y axis. Characterized by a two-dimensional vector defining movement in each direction. |
| **Scale** | Increase or decrease size of the element. Characterized by a two-dimensional vector. If both coordinates are equal, scaling is uniform and aspect ratio is preserved. |
| **Rotation** | Rotate the element on both axis, or Y/X. Positive = clockwise, negative = counter-clockwise. |
| **3D Transform** | Transform the element on the 3D plane using shear mapping. |
| **Animate SVG** | Animate SVG icons & illustrations using DrawSVG and/or changing colors of strokes and fills. |
| **Skew** | Transform the element on the 2D plane using shear mapping that distorts each point by a certain angle in horizontal and vertical directions. |
| **Dimensions** | Animate the width and/or height. |
| **Background Position** | Animate background position for a parallax effect. Note: Set up both positions to animate Y only. |
| **Background Color** | Animate the background color. |
| **Text Color** | Animate the font color. |
| **Border Color** | Animate the border color. |
| **Filter** | Apply CSS filters like blur, grayscale, brightness. |
| **Custom** | Add any animatable CSS property. Right-click to remove in column view. Switch to Advanced Code Field for any valid key/value pair. |
| **Lottie** | Sync Lottie animation with the timeline. Include Lottie Player script and pick the player element's selector. |
| **Image Sequence** | Play a sequence of images on the trigger. |
| **Transform Origin** | Set the origin point of transform animation (translate, scale, rotation). |

Click the toggle next to a property name to enable it. Once enabled, the property expands to show its input fields. Disable a property to remove it from the animation without losing its values.

---

### Functional Properties

**Functional properties** are direction-agnostic — they apply to the entire animation node regardless of whether you are on the From or To tab. They control behaviour like sequencing, repetition, and text splitting rather than visual end-states.

| Property | Description |
|----------|-------------|
| **Text Splitter** | Split each character, word or line into its own div, and animate them one by one using Stagger. Optional class with `++` suffix for incremented numbering. |
| **Text Flapper** | Solari split-flap display effect that cycles through random characters before landing on target text. Choose transition type, character set, cycle count range, and perspective. |
| **Fit** | Morphs one element's geometry to match another's — animates source toward target's position and size. |
| **Stagger** | Animate multiple targets in sequence by adding delay to each element. Use a common selector or multiple selectors. |
| **Repeat** | Repeat in a loop or any number of repetitions. Use `-1` for infinite loop. |
| **MotionPath** | Animate and move any element along an SVG path. |
| **Timeline Control** | Control timeline playback behavior. |
| **Ease** | Set ease style of the animation. Use any default eases like `Power1.easeOut`. |

---

## Trigger Tab

The **Trigger** tab defines what causes the animation to play. Select a trigger type from the dropdown at the top of the tab — the options beneath update dynamically to match the selected type.

{/* Screenshot: Trigger tab showing the trigger type dropdown open with all trigger types listed */}
![Trigger tab with trigger type dropdown](/images/builder/left-panel-trigger-tab.webp)

### Trigger Types

| Trigger | Description |
|---------|-------------|
| **Page Load** | Load the animation as soon as the JS is loaded. |
| **Scroll** | Soften the link between scrollbar and animation. Includes scrub, toggle actions, markers, pin, and offset options. |
| **Hover** | Play timeline on hover. Options for reverse on leave, restart on leave, reverse delay, and trigger selector. |
| **Click** | Play timeline on click. Options for reverse on re-click, restart on re-click, prevent default, and trigger selector. |
| **Mouse Movement** | Animate based on cursor position within viewport or a specific selector. Options for axis mode, distance mode, and smoothing. |
| **Observer / Gesture** | Detect pointer, touch, wheel, or scroll gestures. Includes presentation mode for full-page section scrolling. |
| **Custom Cursor** | Create a custom cursor with smooth movement, squeeze effect, and different states (default, hover, pressed). |
| **Page Exit** | Animate when user navigates away. Options for ignored classes and trigger selectors. |

---

### Page Load

Fires immediately when the Motion.page script initialises on the page. No interaction required. Use this for entrance animations, hero reveals, and anything that should run as soon as the page is ready.

---

### Scroll

Key options:

| Option | Description |
|--------|-------------|
| **Scrub** | Links animation progress directly to scroll position. Set a numeric value to add inertia (e.g. `1` = 1s lag). |
| **Toggle Actions** | Define what happens when the scroll trigger enters, leaves, re-enters, and re-leaves the viewport. |
| **Markers** | Show debug markers for the start and end scroll positions. |
| **Pin** | Pin the trigger element while the animation plays. |
| **Start / End offsets** | Offset the trigger's start and end points relative to the element and viewport. |

For full documentation see [Scroll Trigger](/docs/builder/scroll-trigger).

---

### Hover

Plays the timeline when the pointer enters the trigger element.

| Option | Description |
|--------|-------------|
| **Reverse on leave** | Reverses the timeline when the pointer leaves. |
| **Restart on leave** | Restarts from the beginning on the next hover instead of resuming. |
| **Reverse delay** | Delay in seconds before the reverse begins after the pointer leaves. |
| **Trigger selector** | Override the trigger element with a different CSS selector. |

---

### Click

Plays the timeline when the trigger element is clicked.

| Option | Description |
|--------|-------------|
| **Reverse on re-click** | Reverses the timeline when clicked again. |
| **Restart on re-click** | Restarts from the beginning on each click instead of reversing. |
| **Prevent default** | Calls `event.preventDefault()` — useful on links and form buttons. |
| **Trigger selector** | Override the trigger element with a different CSS selector. |

---

### Mouse Movement

Animates properties in real time based on cursor position relative to the viewport or a container element.

| Option | Description |
|--------|-------------|
| **Axis mode** | Animate on X, Y, or both axes. |
| **Distance mode** | Base animation progress on distance from the centre or from the edges. |
| **Smoothing** | Adds lerp-based lag to follow the cursor smoothly instead of snapping. |

---

### Observer / Gesture

Detects pointer, touch, wheel, and scroll gestures and map them to timeline playback.

Key options include gesture direction, velocity threshold, and **Presentation mode** — a full-page section-scrolling mode that snaps between sections on scroll or swipe.

---

### Custom Cursor

Replaces or augments the default browser cursor with a custom animated element that follows the pointer.

| Option | Description |
|--------|-------------|
| **Squeeze** | Adds a squish deformation effect based on movement speed and direction. |
| **Default state** | Appearance of the cursor in its idle state. |
| **Hover state** | Appearance when hovering over designated elements. |
| **Pressed state** | Appearance when the mouse button is held down. |

---

### Page Exit

Plays the animation when the user navigates away from the current page. Useful for exit transitions.

| Option | Description |
|--------|-------------|
| **Ignored classes** | CSS classes on links that should not trigger the exit animation (e.g. anchors on the same page). |
| **Trigger selectors** | Limit which links trigger the exit animation. |

---

## Breakpoints

At the bottom of the Left Panel, the **Breakpoints** selector controls which viewport sizes this animation is active on. Select the range of breakpoints where the animation is enabled.

{/* Screenshot: Breakpoints section showing the four breakpoint toggles (Mobile, Tablet, Laptop, Desktop) with Mobile and Tablet enabled */}
![Breakpoints selector](/images/builder/left-panel-breakpoints.webp)

Breakpoint widths are configured in **Global Settings → Breakpoints**. Disabling an animation at a breakpoint hides it entirely at that viewport size — the elements remain but no animation timeline is created.

---

## Related

- [From, To & Set](/docs/builder/from-to-set) — Detailed explanation of the three animation modes and context menu options
- [Scroll Trigger](/docs/builder/scroll-trigger) — Full ScrollTrigger configuration reference
- [Workspace Overview](/docs/builder/workspace-overview) — Tour of all four builder regions
- [Opacity](/docs/builder/opacity) — Fade animations using the Opacity property
- [Translate](/docs/builder/translate) — Move elements on X and Y axes
- [Scale](/docs/builder/scale) — Resize elements uniformly or independently
- [Stagger](/docs/builder/stagger) — Sequence multiple targets with per-element delay
- [Ease](/docs/builder/easing) — Control animation acceleration and deceleration
- [Text Splitter](/docs/builder/split-text) — Character, word, and line splitting for staggered text reveals

---

## Selecting Elements

> Choose animation targets — click-to-select, CSS selectors, multiple selectors.

URL: https://motion.page/docs/builder/element-selection

The **selector** tells Motion.page which DOM elements to animate. You can pick targets interactively by clicking in the preview, or type any valid CSS selector by hand.

{/* IMAGE PLACEHOLDER: Overview shot — Left Panel selector input field with the scanner icon highlighted, and a yellow highlight overlay visible on an element in the Frame View */}
![Selector input and Frame View highlight](/images/builder/element-selection-overview.webp)

---

## Click to Select

The fastest way to set a selector is to click directly in the **Frame View**.

1. Click inside the selector input field in the **Left Panel → Animation tab**. This activates the **Selector Scanner** automatically (the cursor icon turns active/highlighted).
2. Move your pointer into the Frame View. A translucent overlay follows your cursor, showing which element would be selected.
3. **Click the element**. A popup appears listing every usable selector for that element and its parent.
4. Click a selector badge to insert it into the field.

{/* IMAGE PLACEHOLDER: Selector Scanner popup — showing the parent row (tag + #id + .class badges) and the current element row, with one badge highlighted on hover */}
![Selector Scanner popup with selector badges](/images/builder/element-selection-scanner-popup.webp)

You can also toggle the scanner manually by clicking the **cursor icon** on the right edge of the selector input (tooltip: "Enable selector scanner"). Click it again to deactivate.

Press **Escape** to deactivate the Selector Scanner and return focus to the builder without inserting a selector.

### Reading the popup

When you click an element, the popup shows two rows:

| Row | What it shows |
|-----|---------------|
| **Parent** | Selectors for the clicked element's direct parent — tag name, ID, classes, data attributes |
| **Current** | Selectors for the clicked element itself — tag name, ID, classes, data attributes |

Each badge represents one selector option. Hover a badge to preview which element it highlights on the page. Click the badge to use it.

For **SVG elements**, the popup also surfaces container-scoped selectors like `#parent-id svg` and `.parent-class svg`, plus individual shape sub-selectors (`path`, `rect`, `circle`, etc.) if the SVG contains them.

---

## Manual Selector Input

Type any valid CSS selector directly into the **Animation Selector** field and press **Enter** to add it.

{/* IMAGE PLACEHOLDER: Selector input field with ".hero-title" typed in and the Enter hint visible */}
![Manual selector input](/images/builder/element-selection-manual-input.webp)

The field accepts:

```css
/* Class */
.hero-title

/* ID */
#section-header

/* Attribute */
[data-animate]

/* Tag */
h1

/* Descendant */
.card-grid .card

/* Child combinator */
.nav > a

/* Comma-separated — targets both elements in one selector */
.heading, .subheading
```

Motion.page validates the selector before adding it. If the value is not a valid CSS selector, the field turns red and shows an error toast — nothing is inserted.

A selector that is valid CSS may still match zero elements on the current page. Motion.page warns you when a selector does not exist in the preview iframe so you can catch typos early.

---

## Multiple Selectors

You can animate **multiple independent targets** from a single animation node by adding more than one selector. Each one becomes a separate **badge** displayed below the input.

{/* IMAGE PLACEHOLDER: Selector list showing three badges — ".headline", ".subline", and ".cta-button" — below the input field */}
![Multiple selector badges](/images/builder/element-selection-multiple-badges.webp)

To add another selector, click the input field, type the selector, and press **Enter**. Repeat for each target.

Every element that matches any badge is animated by the same node. This is equivalent to passing a comma-separated selector in CSS — all matched elements animate together, at the same time, with the same properties.

**To remove a badge:** click it. The selector is removed and the animation updates immediately.

**To edit a badge:** right-click it to open the context menu.

### Badge context menu

| Option | What it does |
|--------|--------------|
| **Edit** | Moves the selector back into the input field for editing |
| **Original state** | Strips combinators and pseudo-classes, leaving the bare class or ID |
| **` > *`** | Appends a child wildcard — targets all direct children of the selector |
| **` + *`** | Appends an adjacent sibling combinator |
| **` img`** | Appends ` img` — targets images inside the selector |
| **Convert → tag / id / class** | Converts the selector prefix between tag name, `#id`, and `.class` |

---

## How the Scanner Generates Selectors

When the Selector Scanner inspects an element, it reads attributes directly from the live DOM and builds selector options in this priority order:

1. **ID** — `#element-id` (if the element has an `id` attribute and the ID starts with a letter)
2. **Classes** — `.class-name` for each class in the element's `classList`
3. **Data attributes** — `[data-name]` for each `data-*` attribute present

Framework-internal attributes are filtered out automatically and never offered as selectors. The following are always excluded:

| Excluded prefix / attribute | Reason |
|-----------------------------|--------|
| `data-flip-id`, `data-marker`, `data-word-index`, `data-char-index` | Motion.page runtime internals |
| `data-split`, `data-scrolltrigger`, `data-cursor`, `data-mp-` | Motion.page internals |
| `data-v-` | Vue scoped-style hashes |
| `data-reactid` | Legacy React internals |
| `data-emotion-`, `data-styled-`, `data-rk-` | CSS-in-JS runtime classes |

If an element has no ID, no classes, and no qualifying data attributes, the scanner falls back to a **tag + `:nth-child`** selector based on the element's position in its parent:

```css
/* Fallback — fragile, avoid relying on these */
.parent-section > p:nth-child(3)
```

---

## Best Practices

### Use semantic class names

Auto-generated selectors (`:nth-child`, framework hashes) are fragile. If the page structure changes — an element moves, a section is reordered — the selector stops matching.

Add a descriptive class to the element in your HTML or page builder, then use that class as the selector:

```html
<!-- Instead of relying on auto-detection -->
<div class="features-grid">
  <div class="feature-card">...</div>
</div>
```

```css
/* Stable — survives layout changes */
.feature-card
```

### Prefer classes over IDs for repeated elements

IDs must be unique per page. For elements that appear multiple times (cards, list items, team members), a shared class is the right choice — the animation applies to every matching instance at once.

```css
/* Animates every .team-member on the page */
.team-member

/* Animates only the one with id="team-member-1" */
#team-member-1
```

To animate each instance separately (staggered), keep the class selector and enable **Stagger** in the Functional properties.

### Scope with parent selectors when needed

If the same class appears in multiple sections and you only want to animate one, scope with a parent:

```css
/* Only cards inside .pricing-section */
.pricing-section .card
```

### Avoid overly broad selectors

Broad selectors like `div`, `p`, or `*` match far more elements than intended and can cause unexpected animation on hidden or structural elements.

---

## Related

- [Left Panel](/docs/builder/left-panel) — Full reference for the Animation tab and selector input location
- [Advanced Targeting](/docs/sdk/advanced-targeting) — Target by URL, post type, or regex pattern using the SDK

---

## Text Color

> Animate font and text colors between any two values in the builder.

URL: https://motion.page/docs/builder/text-color

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Text Color** animates the CSS `color` property of an element — transitioning the font color between any two values. Use it to highlight headings on scroll, shift link colors on hover, or build attention-grabbing color reveals.

## Location

**Left Panel → Animation tab → Visual Properties → Text Color**


## Enable Text Color

Click the toggle next to **Text Color** to enable it. The row expands to reveal the color picker control.

{/* Screenshot: Text Color row expanded, showing the color swatch button and hex input field */}
![Text Color control expanded — color swatch and hex input](/images/builder/text-color-control-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Hex input** | Type any CSS color value — hex (`#6633EE`), RGB, RGBA, HSL, or a named color. |
| **Color swatch** | Click the swatch to open the visual color picker with hue/saturation/alpha controls. |
| **Eye dropper** | Sample any color from the screen using the browser's native eye dropper (supported browsers only). |

The color picker accepts any standard CSS color format. You can freely mix formats between the **From** and **To** values — for example, `from` a named color and `to` a hex value.


## From mode — color reveal

Switch to the **From** tab, enable Text Color, and set a starting color. The element begins at that color and animates to its natural CSS `color` value.


This is useful for **text reveals**: start with a muted or near-invisible color (`#cccccc`, `rgba(0,0,0,0.1)`) and let the text transition into its final styled color as the animation plays.

## To mode — color shift

Switch to the **To** tab, enable Text Color, and set a destination color. The element animates from its natural CSS `color` to the value you specify.


Use **To** for hover highlights, scroll-triggered emphasis, or any interaction where text should shift to a new color and optionally reverse back.

<LivePreview client:load
  height={220}
  title="Text color transition"
  html={`<div class="scene">
  <p class="headline">Motion.page</p>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; background: #0f0f0f; }
.headline { margin: 0; font-size: 2.5rem; font-weight: 700; color: #ffffff; letter-spacing: -0.02em; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("text-color", ".headline", {
  to: { color: "#6633EE" },
  duration: 0.9,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The heading starts white and transitions to a vibrant purple — equivalent to `from: { color: '#ffffff' }` with a `to` value matching the element's natural CSS color, or `to: { color: '#6633EE' }` in a hover/scroll setup.

## SDK equivalent

Text Color maps to the `color` property in the SDK's `from` and `to` objects.

**Color reveal on scroll (From mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('text-reveal', '.heading', {
  from: { color: 'rgba(255,255,255,0.15)' },
  duration: 0.8,
  ease: 'power2.out',
}).onScroll({ scrub: true });
```

**Hover highlight (To mode):**

```typescript
Motion('text-highlight', '.nav-link', {
  to: { color: '#6633EE' },
  duration: 0.2,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Explicit from → to transition:**

```typescript
// Animate between two specific colors — neither matches the element's natural CSS
Motion('color-shift', '.tag', {
  from: { color: '#999999' },
  to:   { color: '#FF6633' },
  duration: 0.5,
  ease: 'power2.inOut',
}).onScroll({ scrub: true });
```

See [Colors in the SDK](/docs/sdk/colors) for the full color animation reference.

## Common patterns

### Highlight text on scroll

Enable **Text Color** on the **To** tab with an accent color (e.g., `#6633EE`). Set the trigger to **Scroll** with **Scrub** enabled. The heading color shifts from its natural CSS color to the accent as the section scrolls into view.

```typescript
Motion('scroll-highlight', '.section-title', {
  to: { color: '#6633EE' },
  duration: 1,
  ease: 'none',
}).onScroll({ scrub: true });
```

### Hover text color

Enable **Text Color** on the **To** tab. Set the trigger to **Hover** with **Reverse on leave** enabled. Each link changes color on mouse enter and reverts on mouse leave.

```typescript
Motion('hover-color', '.menu-item', {
  to: { color: '#FF6633' },
  duration: 0.2,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Alternating heading colors (loop)

Set **Text Color** on the **To** tab to an alternate palette color. Enable **Repeat** with **Yoyo** on and **Times** set to `-1`. The heading color oscillates between two values indefinitely.

```typescript
Motion('color-loop', '.accent-heading', {
  to: { color: '#FF6633' },
  duration: 1.2,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

### Fade-in text using color

Combine **Text Color** and **Opacity** on the **From** tab. Set `color` to a near-transparent value and `opacity` to `0`. The text fades in while its color warms up — a richer entrance than opacity alone.

```typescript
Motion('text-entrance', '.body-copy', {
  from: { color: '#aaaaaa', opacity: 0 },
  duration: 0.7,
  ease: 'power2.out',
}).onScroll();
```

## Tips

- **`color` targets all text** within the element, including inline children (`<span>`, `<em>`, `<strong>`) unless those elements have their own `color` set in CSS. Child elements with an explicit `color` rule will not be affected.
- **Links inherit `color`** by default. If your element contains `<a>` tags without a dedicated color style, they will animate along with the parent — which may or may not be what you want.
- **CSS variables work** — enter `var(--brand-color)` directly in the hex input to animate to a design token.
- The SDK interpolates smoothly between any supported format: hex, RGB, RGBA, HSL, HSLA, or named colors. You can mix formats freely between **From** and **To**.
- For very short durations (< `0.15s`), a **linear** or **power1** ease reads cleanest. Elastic eases on color look odd.

## Related

- [Background Color](/docs/builder/background-color) — Animate the element's background fill
- [Border Color](/docs/builder/border-color) — Animate border color separately from text
- [Text Splitter](/docs/builder/split-text) — Animate individual characters or words, each with their own color transition
- [Colors in the SDK](/docs/sdk/colors) — Full SDK reference for `color`, `backgroundColor`, and `borderColor`
- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each

---

## Timeline Control

> Control other timelines from within a timeline — play, pause, reverse, restart.

URL: https://motion.page/docs/builder/timeline-control

import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";
import LivePreview from "../../components/docs/blocks/LivePreview";

**Timeline Control** lets one timeline orchestrate others — triggering a secondary animation when the current one starts, completes, or updates. Each action maps a lifecycle event on the current timeline to a playback command on a named target timeline.

> Link timelines together: play, pause, reverse, restart, seek, or sync the progress of another named timeline in response to this animation's events.

## Location

**Left Panel → Animation tab → Functional Properties → Timeline Control**

Timeline Control is a **functional property** — it is direction-agnostic. The same actions apply regardless of whether the **From**, **To**, or **Set** tab is active.


## Enable Timeline Control

Click the toggle next to **Timeline Control** to enable it. The section expands to reveal an empty action list and an **+ Add Action** button.

Click **+ Add Action** to add a new action entry. Each entry can be configured independently, and you can add as many entries as needed.

## Controls

Each action entry contains four controls:

| Control | Description |
|---------|-------------|
| **When** | The lifecycle event on the *current* timeline that triggers the action — `onStart`, `onComplete`, or `onUpdate`. |
| **Target** | The name of another timeline to control. The dropdown lists all other timelines on the page by their timeline name. |
| **Action** | What to do to the target timeline — `play`, `pause`, `reverse`, `restart`, `reset`, `complete`, `seek`, `progress`, or `timeScale`. |
| **Value** | Appears for `seek` (time in seconds), `progress` (0–1), and `timeScale` (speed multiplier). Hidden for other actions. |

{/* Screenshot: Timeline Control action entry showing When, Target, and Action dropdowns with + Add Action button */}
![Timeline Control action entry showing When, Target, and Action dropdowns](/images/builder/timeline-control-expanded.webp)

### When (event) options

| Value | Fires when… |
|-------|-------------|
| `onStart` | The current timeline begins playing. |
| `onComplete` | The current timeline finishes. |
| `onUpdate` | Every animation frame while the current timeline is active. Useful for `progress` sync. |

### Action options

| Action | Description | Needs value? |
|--------|-------------|:---:|
| `play` | Play the target timeline from its current position. | No |
| `pause` | Pause the target timeline. | No |
| `reverse` | Play the target timeline backward from its current position. | No |
| `restart` | Reset the target to time 0 and play forward. | No |
| `reset` | Reset the target to time 0 without playing. | No |
| `complete` | Jump the target to its end state immediately. | No |
| `seek` | Jump the target to a specific time in seconds. | Yes — time (s) |
| `progress` | Set the target's progress (0–1). When used with `onUpdate`, syncs progress automatically. | Yes — 0–1 |
| `timeScale` | Set the target's playback speed multiplier. | Yes — speed |

### Progress sync (onUpdate + progress)

When **When** is set to `onUpdate` and **Action** is set to `progress`, the value field disappears and a special **Progress Link** mode activates. The current timeline's progress is automatically mirrored onto the target timeline every frame — useful for driving a secondary animation at the same rate as a scroll-linked one.

## How it works

1. **Name your timelines.** Each timeline has a name field at the top of the Left Panel (tooltip: "Rename the timeline."). Timeline Control references other timelines by this name. The current timeline is automatically excluded from the target list.

2. **Enable Timeline Control** on the timeline you want to use as the controller (the one that triggers actions in others).

3. **Add an action entry.** Choose when the action fires (`onStart`, `onComplete`, `onUpdate`), which target timeline to affect, and what action to perform.

4. **Repeat** for as many cross-timeline relationships as needed. A single timeline can control multiple others, and the same target can receive multiple actions from different events.

When the page loads and animations run, Motion.page injects these relationships into the runtime — no additional code needed.

## Use cases

- **Chained entrance sequences** — Play a secondary hero animation only after the page-load reveal completes. Set the reveal timeline's `onComplete` to `play` the hero timeline.

- **Pause on enter** — When a scroll animation starts (`onStart`), pause a looping background animation to reduce visual noise.

- **Progress mirroring** — Use `onUpdate` + `progress` to drive a progress bar or decorative element at exactly the same rate as a scroll-linked animation.

- **Coordinated exit** — When a modal intro finishes (`onComplete`), `reverse` the overlay fade so both animations end at the same time.

- **Speed control** — Set `timeScale` on a looping animation when a key interaction starts to slow it down for emphasis.

## SDK equivalent

In the SDK, use timeline lifecycle methods such as `.onStart()`, `.onComplete()`, and `.onUpdate()` to control another named timeline. Builder exports compile Timeline Control entries into these callbacks.

```typescript
import { Motion } from "@motion.page/sdk";

// Build the secondary animation first and keep it paused.
const badge = Motion("hero-badge", ".hero-badge", {
  from: { opacity: 0, scale: 0.8 },
  duration: 0.4,
  ease: "back.out",
}).onPageLoad({ paused: true });

// Play it after the primary reveal completes.
Motion("hero-reveal", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
})
  .onComplete(() => badge.play())
  .onPageLoad();
```

<LivePreview client:visible
  height={250}
  title="Chained timeline reveal"
  html={`<div class="chain-scene">
  <section class="hero-card">
    <span class="hero-badge">NEW</span>
    <h3>One timeline hands off to the next.</h3>
    <p>The badge starts only after the card reveal completes.</p>
  </section>
</div>`}
  css={`.chain-scene { display: grid; place-items: center; width: 100%; height: 100%; }
.hero-card { position: relative; width: min(390px, 88vw); padding: 30px; background: linear-gradient(145deg, #171724, #11111a); border: 1px solid #30304a; border-radius: 18px; }
.hero-badge { position: absolute; top: -11px; right: 22px; padding: 6px 10px; color: white; font-size: 10px; font-weight: 900; letter-spacing: .12em; background: #6633ee; border-radius: 999px; }
h3 { margin: 0 0 8px; font-size: 21px; }
p { margin: 0; color: #9395aa; font-size: 13px; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const badge = Motion("hero-badge", ".hero-badge", {
  from: { opacity: 0, scale: 0.6, y: 8 },
  duration: 0.45,
  ease: "back.out(1.7)",
}).onPageLoad({ paused: true });

Motion("hero-reveal", ".hero-card", {
  from: { opacity: 0, y: 35 },
  duration: 0.8,
  ease: "power2.out",
})
  .onComplete(() => badge.play())
  .play();`}
/>

For the full SDK reference, see [Timeline Control in the SDK](/docs/sdk/timeline-control).

## Common patterns

### Chain animations on complete

Play a follow-up animation only after the first one finishes. Set the first timeline's `onComplete` → `play` on the second.

```typescript
import { Motion } from "@motion.page/sdk";

// Subtitle waits until title is done
const subtitle = Motion("subtitle-in", ".subtitle", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  ease: "power2.out",
}).onPageLoad({ paused: true });

// Title slides in first, then starts the subtitle timeline
Motion("title-in", "h1", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: "power2.out",
})
  .onComplete(() => subtitle.play())
  .onPageLoad();
```

### Pause a looping animation on scroll start

When a scroll-triggered animation begins, pause a background loop so it doesn't compete for attention.

```typescript
import { Motion } from "@motion.page/sdk";

// Background pulse — runs indefinitely
Motion("bg-pulse", ".bg-orb", {
  to: { scale: 1.15, opacity: 0.6 },
  duration: 2,
  ease: "power1.inOut",
  repeat: { times: -1, yoyo: true },
}).play();

// Scroll reveal — pauses the loop when it starts
Motion("section-reveal", ".section-content", {
  from: { opacity: 0, y: 50 },
  duration: 0.7,
  ease: "power3.out",
})
  .onStart(() => Motion("bg-pulse").pause())
  .onComplete(() => Motion("bg-pulse").play())
  .onScroll({
  each: true,
  toggleActions: "play none none none",
  start: "top 80%",
});
```

### Mirror scroll progress onto a decorative element

Link two scroll-driven animations so the decorative element tracks the main one exactly, without writing scroll event listeners.

```typescript
import { Motion } from "@motion.page/sdk";

// Build the progress bar without attaching its own trigger.
const progressBar = Motion("progress-bar", ".progress-fill", {
  from: { scaleX: 0 },
  to: { scaleX: 1 },
  duration: 1,
});
progressBar.progress(0);

// Mirror the primary timeline's progress every frame.
Motion("page-scroll", ".hero-text", {
  from: { opacity: 0 },
  to: { opacity: 1 },
  duration: 1,
})
  .onUpdate((progress) => progressBar.progress(progress))
  .onScroll({ scrub: true, start: "top top", end: "bottom bottom" });
```

## Tips

- **Name timelines clearly.** The Target dropdown shows timeline names exactly as entered. Use descriptive, consistent names like `hero-reveal`, `section-2-in`, or `modal-open` rather than the default `Timeline 1`.

- **The current timeline is excluded.** A timeline cannot control itself — the dropdown only shows other timelines on the page.

- **Multiple actions stack.** Add as many action entries as needed. For example, a single `onComplete` can trigger `play` on one timeline and `reverse` on another simultaneously.

- **Paused start required for chained play.** If you want Timeline Control to `play` a target, the target must start paused (use `{ paused: true }` in the trigger options or leave the trigger unset). Otherwise the target will already be playing before the action fires.

- **`onUpdate` fires every frame.** Use `onUpdate` only for `progress` sync — avoid triggering heavy operations on every frame.

- **Ordering matters for `onStart`.** If two timelines load at the same time, the one acting as the controller must initialize before its targets. Page Load trigger order follows the timeline list in the Left Panel.

## Related

- [From, To & Set](/docs/builder/from-to-set) — How functional properties relate to the animation mode tabs
- [Scroll Trigger](/docs/builder/scroll-trigger) — Scroll-driven triggers commonly paired with Timeline Control for chained effects
- [Repeat](/docs/builder/repeat) — Loop animations that can be paused or reversed via Timeline Control
- [Timeline Control in the SDK](/docs/sdk/timeline-control) — Full SDK reference including playback methods and state inspection

---

## Easing

> Select easing curves from the visual easing picker to control animation acceleration and deceleration.

URL: https://motion.page/docs/builder/easing

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Easing** controls how an animation accelerates and decelerates over time. A `power2.out` ease starts fast and slows to a stop; a `back.out` overshoots the target and snaps back — same duration, completely different feel.

## Location

**Left Panel → Animation tab → Functional Properties → Ease**

Ease is a **functional property** — it applies to the entire animation tween regardless of which tab (**From**, **To**, or **Set**) is active. The control is always visible inline in the property row; there is no toggle or expand step.

{/* Screenshot: Left Panel with the Animation tab open, showing the Ease node in the Functional Properties list with the two dropdowns visible side by side */}
![Ease picker — family and direction dropdowns](/images/builder/easing-left-panel.webp)

## Controls

The Ease node contains two dropdowns shown side by side.

| Control | Description |
|---------|-------------|
| **Family** | The easing curve family (e.g. `Power2`, `Back`, `Elastic`). |
| **Direction** | `in` / `out` / `inOut` — hidden when family is `Default` or `None`. |

Selecting **Default** resets the animation to the built-in default (`power1.inOut`) and removes the Ease node entirely. This is the same as not setting an ease in the SDK.

## Easing families

| Family | Character |
|--------|-----------|
| **Default** | Removes the Ease node; uses the SDK default (`power1.inOut`). |
| **Power1** | Gentle, smooth acceleration — the mildest Power ease. |
| **Power2** | Medium acceleration — a reliable general-purpose ease. |
| **Power3** | Strong acceleration — noticeable snap. |
| **Power4** | Very strong acceleration — sharp, punchy movement. |
| **Back** | Overshoots the target, then settles — adds a spring feel. |
| **Elastic** | Oscillates past the end value, like a rubber band. |
| **Bounce** | Bounces at the end, like a ball hitting the floor. |
| **Rough** | Adds jitter for an organic, hand-drawn look. |
| **Slow** | Spends most of its time near the middle of the range. |
| **Circ** | Based on a circular arc — abrupt ease-out finish. |
| **Expo** | Exponential curve — extreme contrast between start and end speed. |
| **Sine** | Gentle sinusoidal curve — the softest ease after `Power1`. |
| **None** | Linear — constant speed with no acceleration. No direction suffix. |

## Direction options

| Direction | Behavior |
|-----------|----------|
| `in` | Starts slow, accelerates toward the end. |
| `out` | Starts fast, decelerates toward the end. Most natural for entrances. |
| `inOut` | Slow at both ends, fastest in the middle. Smooth for loops or scrub. |

The **Direction** dropdown is hidden when **Family** is set to `Default` or `None` — neither has a meaningful direction.

<LivePreview client:load
  height={280}
  title="Easing comparison"
  html={`<div class="scene">
  <div class="row"><span class="label">power1.out</span><div class="track"><div class="dot d1"></div></div></div>
  <div class="row"><span class="label">power3.out</span><div class="track"><div class="dot d2"></div></div></div>
  <div class="row"><span class="label">back.out</span><div class="track"><div class="dot d3"></div></div></div>
  <div class="row"><span class="label">elastic.out</span><div class="track"><div class="dot d4"></div></div></div>
  <div class="row"><span class="label">none (linear)</span><div class="track"><div class="dot d5"></div></div></div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; gap: 10px; padding: 16px 20px; font-family: system-ui; background: #0f0f0f; height: 100%; box-sizing: border-box; }
.row { display: flex; align-items: center; gap: 10px; }
.label { font-size: 11px; color: #888; width: 90px; flex-shrink: 0; font-variant-numeric: tabular-nums; }
.track { flex: 1; height: 20px; background: #1a1a1a; border-radius: 10px; position: relative; overflow: visible; }
.dot { width: 20px; height: 20px; border-radius: 50%; position: absolute; left: 0; top: 0; }
.d1 { background: #6633EE; }
.d2 { background: #9966FF; }
.d3 { background: #33CCFF; }
.d4 { background: #FF6633; }
.d5 { background: #55DD88; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

const eases = ["power1.out", "power3.out", "back.out", "elastic.out", "none"];
const dots = document.querySelectorAll(".dot");

dots.forEach((dot, i) => {
  Motion("ease-" + i, dot, {
    to: { x: 200 },
    duration: 0.95,
    ease: eases[i],
    repeat: { times: -1, delay: 1.5 },
  }).play();
});`}
/>

All five dots travel the same distance in the same duration — only the easing curve differs.

## SDK equivalent

The builder outputs the ease as a lowercase string: family name + `.` + direction.

```typescript
import { Motion } from '@motion.page/sdk';

// power2.out — medium ease out (most common)
Motion('hero', '.hero-text', {
  from: { opacity: 0, y: 40 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad();
```

```typescript
// back.out — slight overshoot on entrance
Motion('card', '.card', {
  from: { opacity: 0, scale: 0.9 },
  duration: 0.5,
  ease: 'back.out',
}).onScroll();
```

```typescript
// none — linear, constant speed (good for loops)
Motion('spinner', '.loader-ring', {
  to: { rotation: 360 },
  duration: 1,
  ease: 'none',
  repeat: -1,
}).onPageLoad();
```

For the full list of valid ease strings and a visual comparison, see [Easing in the SDK](/docs/sdk/easing).

## Common patterns

### Entrance animations — `power2.out`

Start fast and slow to a stop. This matches how physical objects feel when they arrive — momentum decelerates naturally.

```typescript
Motion('fade-up', '.section-title', {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  ease: 'power2.out',
}).onScroll();
```

### Departure animations — `power2.in`

Start slow and accelerate away. Objects that leave the screen feel purposeful, not floaty.

```typescript
Motion('modal-exit', '.modal', {
  to: { opacity: 0, scale: 0.95 },
  duration: 0.3,
  ease: 'power2.in',
}).onClick({ selector: '.close' });
```

### Scroll-scrub — `none` or `power1.inOut`

For animations driven by scroll position, `none` (linear) maps position 1:1. `power1.inOut` softens the feel at the edges of the scrub zone.

```typescript
Motion('parallax', '.bg-image', {
  to: { y: -80 },
  ease: 'none',
}).onScroll({ scrub: 1 });
```

### Springy entrance — `elastic.out`

Overshoots and oscillates back. Use sparingly — best for small elements like badges, icons, or tooltips.

```typescript
Motion('badge', '.notification-dot', {
  from: { scale: 0 },
  duration: 0.8,
  ease: 'elastic.out',
}).onPageLoad();
```

## Related

- [Easing in the SDK](/docs/sdk/easing) — Full reference with visual curve comparison and all valid strings
- [From, To & Set](/docs/builder/from-to-set) — How functional properties relate to animation mode tabs
- [Stagger](/docs/builder/stagger) — Cascade timing across multiple elements
- [Repeat](/docs/builder/repeat) — Loop animations and control yoyo direction

---

## CSS Filters

> Configure CSS filter animations like blur, grayscale, brightness and more in the builder UI.

URL: https://motion.page/docs/builder/filter

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Filters** animates CSS filter functions on an element — blur, brightness, contrast, grayscale, hue rotation, inversion, saturation, sepia, or a fully custom filter string. Use filters to build focus-in reveals, desaturate effects, brightness pulses, and more.

## Location

**Left Panel → Animation tab → Visual Properties → Filter**


## Enable filters

Click the toggle next to **Filter** to enable it. A filter row appears with a **type dropdown** and a **value input**. Each row represents one CSS filter function. You can stack multiple filters by clicking the **+** button next to the filter header.

{/* Screenshot: Filter row expanded, showing the type dropdown set to "Custom" and an empty text input beside it */}
![Filter control expanded — type dropdown and value input](/images/builder/filter-control-expanded.webp)

## Filter types

Select the filter function from the dropdown at the left of each row. The value input to the right updates its unit automatically based on the type.

### Custom

Accepts a raw CSS filter string. Use this when you need a function not listed in the dropdown, or when you want to combine multiple functions in a single value (e.g., `blur(4px) brightness(120%)`).

The value input becomes a free-text field — type any valid CSS filter expression.


### Blur

Applies a Gaussian blur. The value is in **pixels** (`px`). Higher values produce a stronger blur.

| Range | Unit | Notes |
|-------|------|-------|
| `0` – ∞ | `px` | `0` = sharp (no blur); `10` = heavily blurred |

### Brightness

Adjusts the luminance of the element. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – ∞ | `%` | `100%` = natural brightness; `0%` = completely black; `150%` = boosted |

### Contrast

Adjusts the difference between light and dark areas. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – ∞ | `%` | `100%` = natural contrast; `0%` = flat gray; `200%` = high contrast |

### Grayscale

Converts the element to grayscale. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – `100` | `%` | `0%` = full color; `100%` = fully grayscale |

### Hue Rotate

Rotates the hue of all colors by a given angle. The value is in **degrees** (`deg`).

| Range | Unit | Notes |
|-------|------|-------|
| Any number | `deg` | `0` = no change; `180` = complementary colors; `360` = full rotation back to normal |

Negative values rotate in the opposite direction. There is no enforced min or max.

### Invert

Inverts the colors of the element. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – `100` | `%` | `0%` = normal; `100%` = fully inverted (negative) |

### Saturate

Controls color saturation. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – ∞ | `%` | `100%` = natural saturation; `0%` = fully desaturated; `200%` = hyper-saturated |

### Sepia

Applies a warm sepia tone. The value is a **percentage** (`%`).

| Range | Unit | Notes |
|-------|------|-------|
| `0` – `100` | `%` | `0%` = no tint; `100%` = full sepia tone |

## Controls summary

| Control | Description |
|---------|-------------|
| **Type dropdown** | Choose the filter function. Searchable. |
| **Value input** | Numeric value for the selected filter type. Unit is appended automatically. |
| **Custom text input** | Free-text field shown when type is set to **Custom**. Accepts any CSS filter string. |
| **+ button** | Adds another filter row so you can stack multiple filter functions. |

## From mode — blur reveal

Switch to the **From** tab, enable Filter, and set the type to **Blur** with a value of `10`. The element starts blurred and animates to its natural sharp state.


This is the most common filter pattern: the element is blurry at the start and sharpens into view. Pair it with **Opacity** at `0` on the same From tab for a polished entrance.

## To mode — grayscale on hover

Switch to the **To** tab, enable Filter, and set the type to **Grayscale** with a value of `100`. The element animates from its natural color to fully grayscale.


Use **To** for hover effects, dimming states, or exit animations where the element should transition away from its natural appearance.

<LivePreview client:load
  height={220}
  title="Filter blur reveal"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.box { width: 120px; height: 120px; border-radius: 12px; background: #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("blur-reveal", ".box", {
  from: { opacity: 0, filter: "blur(12px)" },
  duration: 0.7,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts at `filter: blur(12px)` with `opacity: 0` (the **From** values) and animates to sharp and fully visible — its natural CSS state.

## SDK equivalent

In the SDK, `filter` accepts a CSS filter string directly. The builder's filter rows are serialized into a single CSS string at output time.

**Blur reveal — From mode:**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('blur-reveal', '.hero', {
  from: { filter: 'blur(10px)', opacity: 0 },
  duration: 0.8,
  ease: 'power2.out',
}).onPageLoad();
```

**Grayscale hover — To mode:**

```typescript
Motion('grayscale-hover', '.card', {
  to: { filter: 'grayscale(100%)' },
  duration: 0.3,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Brightness pulse — loop:**

```typescript
Motion('brightness-pulse', '.cta', {
  to: { filter: 'brightness(140%)' },
  duration: 0.6,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

**Custom filter string — multiple functions:**

```typescript
Motion('warm-reveal', '.image', {
  from: { filter: 'blur(6px) sepia(80%)', opacity: 0 },
  duration: 1,
  ease: 'power3.out',
}).onScroll();
```

For the full SDK reference, see [Filters in the SDK](/docs/sdk/filters).

## Common patterns

### Blur in on scroll

Enable **Filter** on the **From** tab, set type to **Blur**, value `8`. Add **Opacity** at `0` on the same tab. Set the trigger to **Scroll**. Elements focus into view as they enter the viewport.

```typescript
Motion('scroll-blur-in', '.section', {
  from: { filter: 'blur(8px)', opacity: 0 },
  duration: 0.7,
  ease: 'power2.out',
}).onScroll();
```

### Grayscale on hover

Enable **Filter** on the **To** tab, set type to **Grayscale**, value `100`. Set the trigger to **Hover** with **Reverse on leave** enabled. Images desaturate on hover and return to full color on mouse out.

```typescript
Motion('hover-grayscale', '.thumbnail', {
  to: { filter: 'grayscale(100%)' },
  duration: 0.35,
  ease: 'power1.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Brightness pulse

Enable **Filter** on the **To** tab, set type to **Brightness**, value `150`. Set the trigger to **Page Load**. Enable **Repeat** with **Yoyo** on and **Times** set to `-1`. A call-to-action element glows with a repeating brightness cycle.

```typescript
Motion('brightness-pulse', '.badge', {
  to: { filter: 'brightness(150%)' },
  duration: 0.8,
  ease: 'sine.inOut',
  repeat: { yoyo: true, times: -1 },
}).onPageLoad();
```

### Blur out on exit

Set the trigger to **Page Exit**. Enable **Filter** on the **To** tab, set type to **Blur**, value `10`. Pair with **Opacity** at `0`. The page blurs and fades out when the user navigates away.

```typescript
Motion('page-exit', 'body', {
  to: { filter: 'blur(10px)', opacity: 0 },
  duration: 0.5,
  ease: 'power2.in',
}).onPageExit();
```

### Hue rotate on scroll (scrub)

Enable **Filter** on the **To** tab, set type to **Hue Rotate**, value `180`. Set the trigger to **Scroll** with **Scrub** enabled. The element shifts through complementary colors as the user scrolls.

```typescript
Motion('hue-scroll', '.hero-bg', {
  to: { filter: 'hue-rotate(180deg)' },
}).onScroll({ scrub: true });
```

## Related

- [From, To & Set](/docs/builder/from-to-set) — How the three animation modes work and when to use each
- [Filters in the SDK](/docs/sdk/filters) — SDK reference for the `filter` property
- [Opacity](/docs/builder/opacity) — Combine with Filter for polished blur-in entrances
- [Custom Properties](/docs/builder/custom-properties) — Animate arbitrary CSS variables alongside filters

---

## Border Color

> Animate border colors between any two values in the builder.

URL: https://motion.page/docs/builder/border-color

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Border Color** animates the `border-color` CSS property of an element — transitioning between two color values over the duration of the animation. Use it to draw attention to interactive states, validation feedback, or decorative hover effects.

## Location

**Left Panel → Animation tab → Visual Properties → Border Color**


## Enable Border Color

Click the toggle next to **Border Color** to enable it. The row expands to reveal the color picker control.

{/* Screenshot: Border Color row expanded, showing the color picker swatch and hex input field */}
![Border Color control expanded — color picker and hex input](/images/builder/border-color-control-expanded.webp)

## Controls

| Control | Description |
|---------|-------------|
| **Color picker** | Click the swatch to open the color picker. Supports hex, RGB, HSL, and named CSS colors. Also accepts `transparent`. |
| **Hex / color input** | Type any valid CSS color value directly into the field (e.g. `#FF3366`, `rgba(255,0,0,0.5)`, `transparent`). |

## From mode

Switch to the **From** tab, enable Border Color, and choose a starting color. The element's border starts at that color and transitions to whatever `border-color` is defined in your CSS.


Use **From** mode when the element already has a border in CSS and you want the color to arrive at that natural value — for example, animating from red to the default grey border on page load.

## To mode

Switch to the **To** tab, enable Border Color, and choose a destination color. The element's border starts at its natural CSS `border-color` and transitions to the color you specify.


Use **To** mode for hover highlights, focus rings, and validation state changes where the element has a resting border color and you want it to shift to an accent on interaction.

<LivePreview client:load
  height={220}
  title="Border color transition"
  html={`<div class="scene">
  <div class="box"></div>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; font-family: system-ui; }
.box { width: 120px; height: 120px; border-radius: 12px; background: transparent; border: 3px solid #6633EE; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("border-color", ".box", {
  to: { borderColor: "#FF3366" },
  duration: 0.9,
  ease: "power2.inOut",
  repeat: { times: -1, yoyo: true, delay: 0.6 },
}).play();`}
/>

The box starts with a purple border (`#6633EE`) and transitions to a pink-red (`#FF3366`), then back — demonstrating a round-trip border color animation using **From** and **To** together.

## SDK equivalent

The `borderColor` property maps directly to the `from` and `to` objects in the SDK.

**Highlight on hover (To mode):**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('border-highlight', '.card', {
  to: { borderColor: '#6633EE' },
  duration: 0.3,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

**Validation error state (To mode):**

```typescript
Motion('invalid-border', '.input', {
  to: { borderColor: '#FF3366' },
  duration: 0.25,
  ease: 'power1.out',
}).onClick({ selector: '.submit-btn' });
```

**Entrance from a starting color (From mode):**

```typescript
Motion('border-arrive', '.panel', {
  from: { borderColor: 'transparent' },
  duration: 0.6,
  ease: 'power2.out',
}).onPageLoad();
```

See [Colors in the SDK](/docs/sdk/colors) for the full color animation reference.

## Common patterns

### Focus / active state border highlight

Set the trigger to **Focus** or **Click**. Enable **Border Color** on the **To** tab with your brand accent color. Enable **Reverse on leave** so the border returns to its default when focus is lost.

```typescript
Motion('focus-ring', '.form-input', {
  to: { borderColor: '#6633EE' },
  duration: 0.2,
  ease: 'power1.out',
}).onFocus({ each: true, onBlur: 'reverse' });
```

### Card hover border

On hover, shift a card's border from a subtle grey to a vivid color to signal interactivity. Combine with a slight **Scale** or **Translate Y** for extra polish.

```typescript
Motion('card-hover-border', '.card', {
  to: { borderColor: '#00C2FF' },
  duration: 0.25,
  ease: 'power2.out',
}).onHover({ each: true, onLeave: 'reverse' });
```

### Validation feedback color

Animate the border of a form field from its resting color to red on an error state, or to green on success. Trigger on a class toggle or button click.

```typescript
// Error state
Motion('field-error', '.field', {
  to: { borderColor: '#FF3366' },
  duration: 0.2,
  ease: 'power1.out',
}).onClick({ selector: '.validate-btn' });

// Success state
Motion('field-success', '.field', {
  to: { borderColor: '#00D26A' },
  duration: 0.3,
  ease: 'power2.out',
}).onClick({ selector: '.validate-btn' });
```

## Tips

- **The element must already have a visible border.** If `border-width` is `0` or `border-style` is `none`, the color animation will not be visible. Set at least `border: 1px solid` in your CSS before animating the color.
- Animating **from** `transparent` to a color creates a clean "border appear" entrance effect.
- Use `rgba()` or `hsla()` values to animate border color alongside opacity for a fade-in border effect.
- Border color animates all four sides simultaneously. To animate individual sides (e.g. only the bottom), use custom CSS alongside the SDK's `borderBottomColor` property instead.

## Related

- [Background Color](/docs/builder/background-color) — Animate the fill color of an element
- [Text Color](/docs/builder/text-color) — Animate the foreground text color
- [Opacity](/docs/builder/opacity) — Fade an element in or out
- [Colors in the SDK](/docs/sdk/colors) — Full color animation reference for the SDK

---

## Connecting to Your Site

> Enter a URL, connect to any website, and start building animations.

URL: https://motion.page/docs/builder/connecting-sites

import Steps from "../../components/docs/blocks/Steps.astro";

The desktop app works with **any website**. Give it a URL — live site, staging environment, or local dev server — and it opens that site in a built-in browser ready for animation.

{/* Screenshot: Project Dashboard showing site cards with thumbnails */}
![Project Dashboard — Sites tab with project cards](/images/builder/connecting-sites-dashboard.webp)

---

## Creating a site

Every connection starts with a **site** (called a project internally). Create one from the **Project Dashboard**.

<Steps>

1. Open the Project Dashboard

   Click the Motion.page logo in the top-left of the Left Panel, or launch the app — the dashboard is the default home screen.

2. Click **New Site**

   The button is in the top-right of the **Sites** tab. A modal opens with two fields.

3. Enter a project name and URL

   - **Project Name** — a label for your own reference. It appears on the card and in the tab bar.
   - **Website URL** — the full address of the site. Include the protocol (`https://example.com`). For localhost, the protocol is optional (see [Development servers](#development-servers)).

4. Click **Create Project**

   The site opens immediately in a new tab. The builder loads alongside it.

</Steps>

---

## Built-in browser

Once a site is open, it renders inside an **Electron webview** — a full Chromium browser embedded in the app. The site behaves exactly as it would in a regular browser: JavaScript runs, cookies persist, and logged-in sessions are maintained.

The webview fills the **Frame View** in the center of the workspace. You build animations directly on top of the live page.

> **Note:** The webview and the builder share the same Electron session. If you log into a site inside the app, that session persists across app restarts — just like a regular browser profile.

---

## Navigating within a site

The built-in browser functions like any browser tab. Click links, fill forms, and navigate freely — the page updates inside the Frame View.

**Animation context follows the page.** When you navigate to a new URL within the same project, the builder stays active. Timelines scoped to that page appear in the Library panel automatically.

To navigate to a specific page without clicking links on the site, use the **address bar** in the tab strip at the top of the app. Type a path and press `Enter`.

> **Tip:** To build animations on an interior page, open the site and navigate to that page first. Then configure your animation — the page selector in the Left Panel will reflect the current URL.

---

## Development servers

Local development servers work out of the box. The desktop app is not a remote SaaS tool — it runs on your machine and can reach anything your browser can reach.

**Supported formats:**

| Format | Example |
|--------|---------|
| Full URL with protocol | `http://localhost:3000` |
| Localhost without protocol | `localhost:3000` |
| IP address with port | `127.0.0.1:8080` |
| Named local domains | `http://mysite.local` |

When you enter a localhost URL without `http://`, the app prepends it automatically.

> **Tip:** If your dev server uses HTTPS with a self-signed certificate, the webview may show a security warning. Accept the certificate once and the site will load normally on subsequent visits.

---

## Password-protected sites

Sites behind HTTP Basic Auth or a login form work normally. The webview handles authentication the same way a browser does.

**HTTP Basic Auth** — the browser prompts for credentials when the URL is first loaded. Enter them once; the session is maintained.

**Login forms** — navigate to the login page, sign in, and then navigate to the page you want to animate. The session cookie persists for the duration of the app session.

**Staging environments** — connect using the staging URL directly. If the staging site is behind a VPN, ensure the VPN is active before opening the project.

> **Note:** Credentials entered inside the webview are not stored by the builder. They are held in the Electron session for the current app session only.

---

## Refreshing and reconnecting

Use the **Refresh** button in the Top Panel toolbar (the circular arrow icon) to reload the current page inside the Frame View. This is equivalent to pressing `F5` in a browser.

Refresh when:
- Your dev server has restarted and the page is stale.
- You have made code changes and want to see the updated DOM.
- A CSS or JS error is preventing the page from loading correctly.

**Reconnecting after a URL change** — if your site's URL changes (for example, a new staging URL), edit the project to update it. See [Rename and edit a site](#rename-and-edit-a-site) below.

---

## Managing your sites

All your sites are listed in the **Sites** tab of the Project Dashboard. Cards are sorted by last-opened date — most recent first.

### Search

Use the **Search sites** input in the top-right to filter by name or URL. The grid updates as you type.

### Rename and edit a site

Hover over a project card to reveal the action buttons. Click the **cog icon** (Edit Project) to open the edit modal. You can change both the project name and the URL.

Changing the URL reconnects the project to the new address. Existing animations saved to this project are not affected.

### Delete a site

Hover over a project card and click the **delete icon**. A confirmation prompt appears — confirm to permanently remove the project.

> **Caution:** Deleting a site removes it from the dashboard and disconnects it from its saved animations. The animations themselves remain in your library but will no longer have an associated project.

### Thumbnails

The app automatically captures a **thumbnail screenshot** of each site when you open it. Thumbnails update at most once every 24 hours. They appear on the project card and in the tab bar.

If a thumbnail has not been captured yet, the card shows a "No preview available" placeholder until the next time the site is opened.

---

## Multiple sites open at once

The desktop app supports **multiple open tabs**. Each tab runs its own independent builder session with isolated state.

Open a second site by clicking **New Site** from the dashboard, or return to the dashboard (click the logo) and open another project card. Tabs appear in the tab bar at the top of the app. Click any tab to switch between sites.

---

## Next steps

- [Desktop Overview](/docs/builder/desktop-overview) — full overview of the desktop app
- [Workspace Overview](/docs/builder/workspace-overview) — tour of the builder panels
- [Animation Library](/docs/builder/library) — manage, export, and import your saved animations

---

## Scroll Trigger

> Set up scroll-based animations with start/end positions, scrub, toggle actions, pinning, and per-element iteration.

URL: https://motion.page/docs/builder/scroll-trigger

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Scroll Trigger** plays or scrubs a timeline based on scroll position. It is gives you precise control over when an animation starts, when it ends, how it reacts to scrolling back up, and whether it pins an element in place.

## Location

**Left Panel → Trigger tab → trigger type dropdown → Scroll**

When Scroll is selected, the builder enters **Live Play mode** and shows **viewport markers** in the Frame View automatically. These markers show exactly where the start and end scroll positions fall — they are always visible while you configure the trigger.

{/* Screenshot: Left Panel with Trigger tab open, Scroll selected from the dropdown, and viewport markers visible in the Frame View */}
![Scroll Trigger settings panel](/images/builder/scroll-trigger-settings.webp)

---

## Lock to scrollbar

**Lock to scrollbar** (`isScrub`) links animation progress directly to the scroll position. The animation plays forward as the user scrolls down and reverses as they scroll up — it never plays on its own.

> Sync animation progress with the scrollbar.

| Control | Default | Description |
|---------|---------|-------------|
| **Lock to scrollbar** toggle | off | Enables scrub mode — animation progress is driven by scroll position. |
| **Delay** slider | `1s` | Adds inertia so the animation takes time to catch up to the scrollbar. `0` = instant sync. Range: 0–8 s. Double-click to reset to `1`. |

> Soften the link between the scrollbar and the animation, so it takes a certain time for the animation to 'catch up' the scrollbar.

When **Lock to scrollbar** is on, [Toggle Actions](#toggle-actions) and [Timeline repeat](#timeline-repeat) are hidden — they are incompatible with scrub mode.

---

## Toggle Actions

**Toggle Actions** (`toggleActions`) defines how the animation responds at each of its four lifecycle stages: **on enter**, **on leave**, **on enter back**, and **on leave back**. Only available when **Lock to scrollbar** is off.

> Control the playback of your timeline during these 4 stages — On enter, on leave, on enter back, on leave back.

Enable the toggle to reveal a **creatable, searchable dropdown** (`toggleActionsValue`). Choose a preset or type a custom string of four space-separated keywords.

> Choose from the premade list or write down your own using these keywords: play, pause, resume, reset, restart, complete, reverse and none. E.g. `play pause resume reset`

### Presets

| Label | Value |
|-------|-------|
| Play only once on scroll down | `play none none none` |
| Repeat on every scroll down | `restart none none none` |
| Restart on scroll back | `restart none restart none` |
| Reverse on scroll back | `play none reverse none` |
| Reverse on scroll back leave | `play none none reverse` |
| Always reverse on scroll backwards | `play reverse play reverse` |

The four positions map to: `onEnter onLeave onEnterBack onLeaveBack`. Valid keywords: `play`, `pause`, `resume`, `reset`, `restart`, `complete`, `reverse`, `none`.

---

## Pinned element

**Pinned element** (`isPin`) fixes an element in place between two scroll positions while the animation plays.

> Fix an element in place between certain scrolling positions. Use the element start / end selector to define pinned content, and use Scroller range to increase the scrolling duration.

Enable the toggle to reveal two sub-controls:

| Control | Default | Description |
|---------|---------|-------------|
| **Pin Selector** input | *(empty)* | CSS selector for the element to pin. Leave empty to pin the first animated element (`pin: true`). |
| **Add spacing** dropdown | `Auto` | Controls spacing below the pinned element while it is fixed. |

### Add spacing options

> Push other elements down, while a content is pinned by adding a padding or margin.

| Builder option | SDK value | Behaviour |
|---------------|-----------|-----------|
| `Margin` | `pinSpacing: "margin"` | Adds margin to push content below the pin. |
| `Padding` | `pinSpacing: "padding"` | Adds padding instead of margin. |
| `No spacing` | `pinSpacing: false` | No extra space — content may overlap during the pin. |
| `Auto` | *(not set)* | The SDK chooses the default spacing behaviour. |

---

## Trigger each iteration individually

**Trigger each iteration individually** (`multiple`) animates each matched element with its own independent scroll trigger instance.

> By enabling this option, you can animate each iteration of the class individually one-by-one.

Maps to `each: true` in the SDK. When enabled, the position labels in the Start and End blocks change from **"First element's"** to **"Each element's"** — each element's own bounding box is used to compute trigger positions.

---

## Start position

The **Starts When** block defines when the animation begins. It reads as: *"[element position] reaches [viewport position]."*

> The animation starts / ends when selected position of the element reaches certain part of the viewport. By using 'selector' option, you can wrap the element used in from / to properties with a parent element and use it as a trigger.

### Element / Selector

| Option | Behaviour |
|--------|-----------|
| **Element** | Uses the first animated element (or each element if **Trigger each** is on) as the scroll trigger. |
| **Selector** | Shows a CSS selector input. The element at that selector is used as the trigger instead. Switching to Selector also switches the End block to Selector. |

### Element position

Click the **top / center / bottom** icon picker to choose which edge or midpoint of the trigger element is measured.

| Icon | Value | Meaning |
|------|-------|---------|
| Top icon | `top` | Element's top edge |
| Center icon | `center` | Element's vertical midpoint |
| Bottom icon | `bottom` | Element's bottom edge |

### Reaches (viewport position)

The **Reaches** slider sets the vertical position in the viewport where the element position must arrive to fire the trigger.

| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| `start.offset_vw` | `85%` | −100% to 100% / −1000 px to 1000 px | Position from the top of the viewport. `85%` = near the bottom edge. |

Toggle the unit button to switch between **%** and **px**.

Default start: `"top 85%"` — the element's top edge enters at 85% from the viewport top, meaning it just appears from the bottom.

### Offset (element offset)

Click the **+** button (tooltip: *Add a positive or negative offset to the element's trigger*) to reveal the **Offset** slider. This nudges the trigger position by a fixed amount on top of the element's edge.

| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| `start.offset` | `0` | −100% to 100% / −1000 px to 1000 px | Shifts the effective start point up (negative) or down (positive). |

### Enable clamp

> This makes sure the value stays between 0 (the page's top) and the furthest scroll point. This way, the value won't go beyond the page's limits and the page's won't have animations that only play halfway.

Toggle **Enable clamp** (`start.clamp`) to prevent the trigger from firing at a scroll position outside the page boundaries. Useful for elements near the very top or bottom of the page.

---

## End position

The **Ends When** block defines when the animation ends. It has all the same controls as Start, plus one extra option at the top: **Relative to start**.

Default end: `"bottom 15%"` — the element's bottom edge reaches 15% from the viewport top, meaning it is near the top of the viewport.

### Relative to start

Enable **Relative to start** (`end.useRelative`) to express the end position as a distance offset from the start, rather than an absolute viewport position.

When enabled the standard position controls are replaced by a **Distance** slider:

| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| `end.relativeValue` | `100` | 0–1000% / 0–5000 px | How far past the start point the animation should end. |

Toggle the unit button to switch between **%** and **px**. The SDK receives this as `end: "+=100%"` or `end: "+=300px"`.

### End selector

When **Selector** mode is active on the End block, a separate **end trigger selector** input appears (`scrollTrigger.endTrigger`). This lets a different element define the end boundary from the one used for the start.

---

## Custom code

The **Custom code** section is a collapsible field that accepts any valid ScrollTrigger configuration as raw key/value pairs. Use it to access scroll trigger options that are not exposed in the visual UI.

Click **Custom code** to expand the field. When the section is collapsed and contains code, a dot indicator marks it as active.

---

## Advanced Options

The **Advanced Options** section is collapsible and contains lower-level settings.

### Bypass 'prefers-reduced-motion'

> 'prefers-reduced-motion' is a browser accessibility feature that prevents animations to run. You can bypass it by using this option, if necessary.

Disabled by default. Enable only when the animation is purely decorative and safe to show regardless of the user's motion preference.

### Scroller is based on

> The animation starts when Scroller Start meets the animation element.

| Option | SDK | Description |
|--------|-----|-------------|
| **Viewport** | *(not set)* | Default — the browser viewport is the scroll container. |
| **Selector** | `scroller: ".container"` | A custom scrollable element is used as the container. Shows a CSS selector input when selected. |

### Timeline repeat

Only available when **Lock to scrollbar** is off. Enable to loop the animation within the scroll trigger range.

> Apply repeat to the entire timeline.

| Control | Default | Description |
|---------|---------|-------------|
| **Repeat** | `-1` | Number of additional plays. `-1` = infinite. |
| **Delay** | `0` | Seconds between each repeat cycle. |
| **Enable YoYo** | off | The timeline plays forward then backward on alternate cycles. |

> Yoyo causes the timeline to go back and forth on repeat.

When **Lock to scrollbar** is on, this section shows the notice: *"Timeline repeat will not work with lock to scrollbar."*

---

<LivePreview client:load
  height={320}
  title="Scroll-triggered fade in"
  html={`<div class="scene">
  <div class="scroll-hint">↓ Scroll down</div>
  <div class="spacer"></div>
  <div class="card" id="card">
    <div class="card-dot"></div>
    <p class="card-label">Triggered on scroll</p>
  </div>
  <div class="spacer"></div>
</div>`}
  css={`.scene { height: 100%; overflow-y: auto; font-family: system-ui; }
.spacer { height: 120px; }
.scroll-hint { text-align: center; padding: 20px; color: #888; font-size: 13px; }
.card { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 12px; margin: 0 auto; width: 200px; height: 120px; background: #1a1a2e; border-radius: 14px; border: 1px solid rgba(255,255,255,0.08); }
.card-dot { width: 32px; height: 32px; border-radius: 50%; background: #6633EE; }
.card-label { color: #c4b5fd; font-size: 13px; font-weight: 500; margin: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("scroll-fade", "#card", {
  from: { opacity: 0, y: 24 },
  duration: 0.6,
  ease: "power2.out",
}).onScroll({ start: "top 80%", toggleActions: "play none none reverse", scroller: ".scene" });`}
/>

In the builder this is a **From** animation with `opacity: 0` and `y: 24`, with the default start position of `"top 85%"`.

---

## SDK equivalent

The builder Scroll trigger maps to `.scrollTrigger()` in the SDK.

```typescript
import { Motion } from "@motion.page/sdk";

// Default — animate in as element enters viewport
Motion("fade-in", ".card", {
  from: { opacity: 0, y: 24 },
  duration: 0.6,
  ease: "power2.out",
}).scrollTrigger({
  start: "top 85%",
  end: "bottom 15%",
  toggleActions: "play none none none",
});
```

**Scrub — link animation progress to scroll:**

```typescript
Motion("parallax", ".hero-image", {
  to: { y: -80 },
}).scrollTrigger({
  start: "top top",
  end: "bottom top",
  scrub: 1,
});
```

**Pinned section:**

```typescript
Motion("pin-section", ".panel", {
  from: { opacity: 0 },
  duration: 1,
}).scrollTrigger({
  start: "top top",
  end: "+=100%",
  pin: true,
  scrub: true,
});
```

**Per-element triggering:**

```typescript
// Each .item gets its own scroll trigger
Motion("list-reveal", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  ease: "power2.out",
}).scrollTrigger({
  start: "top 85%",
  each: true,
  toggleActions: "play none none none",
});
```

**Custom scroller container:**

```typescript
Motion("inner-scroll", ".content", {
  from: { opacity: 0 },
  duration: 0.4,
}).scrollTrigger({
  start: "top 80%",
  scroller: ".scroll-container",
});
```

For the full SDK reference see [Scroll Trigger](/docs/sdk/scroll-trigger) and [Scroll Trigger Advanced](/docs/sdk/scroll-trigger-advanced).

---

## Common patterns

### Fade in on enter, no reverse

Use the **Play only once on scroll down** toggle actions preset (`play none none none`). The animation fires once when the element enters and stays in its end state even when scrolled back past.

### Parallax background

Enable **Lock to scrollbar** and set a `y` translate on a background image. Set the start to `"top bottom"` and end to `"bottom top"` so the motion covers the full time the section is visible. Use a **Delay** of `0` for instant sync.

### Sticky storytelling section

Enable **Pinned element**, leave the pin selector empty (pins the first animated element), and set a **Relative to start** distance on the end position (e.g. `300%`) to keep the element pinned for three viewport-heights of scrolling.

### Reveal each list item individually

Enable **Trigger each iteration individually**. Every element matching the selector gets its own trigger instance — items reveal one by one as the user scrolls, not all at once.

---

## Related

- [Scroll Trigger — SDK reference](/docs/sdk/scroll-trigger) — `scrollTrigger()` API and options
- [Scroll Trigger Advanced — SDK reference](/docs/sdk/scroll-trigger-advanced) — Pin, snap, and advanced ScrollTrigger features
- [Page Load Trigger](/docs/builder/page-load) — Auto-play animations when the page loads
- [Hover Trigger](/docs/builder/hover-trigger) — Trigger animations on pointer enter
- [Click Trigger](/docs/builder/click-trigger) — Trigger animations on element click
- [Left Panel](/docs/builder/left-panel) — Full Left Panel reference including the Trigger tab

---

## Text Flapper

> Create Solari split-flap display effects that cycle through characters before landing on the target text.

URL: https://motion.page/docs/builder/text-flapper

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Text Flapper** animates text like a mechanical Solari departure board — each character cycles through random intermediate glyphs before landing on the final text. Choose from seven transition styles, configure the character set and cycle count, and optionally enable full styled-board tile rendering.

> Solari split-flap display effect that cycles through random characters before landing on the target text. Choose a transition type, character set, cycle count range, and perspective. Use the 'Board' type for a realistic departure-board look with styled panels.

## Location

**Left Panel → Animation tab → Functional Properties → Text Flapper**

Text Flapper is a **functional property** — it is direction-agnostic. The same flap config applies whether the **From**, **To**, or **Set** tab is active. Enabling it on any tab enables it on all three. The data key in the animation config is `flap`.


## Enable Text Flapper

Click the toggle next to **Text Flapper** to enable it. The row expands to reveal the Type dropdown, Charset picker, Cycles range inputs, Perspective input, and the Styled Board and Preserve Whitespace toggles.

{/* Screenshot: Text Flapper row fully expanded showing Type dropdown, Charset picker, Cycles min/max inputs, Perspective input, Styled Board toggle, and Preserve Whitespace toggle */}
![Text Flapper controls expanded](/images/builder/text-flapper-controls-expanded.webp)

> **Note:** Text Flapper operates on individual characters. It **automatically splits text into characters** internally — you do not need to enable [Text Splitter](/docs/builder/split-text) separately. However, if you do add Text Splitter, it overrides the internal split, letting you reconfigure it (e.g. split into both characters and words).

## Controls

| Control | Type | Default | Description |
|---------|------|---------|-------------|
| **Type** | Dropdown | `flip` | Animation style for each character transition. See [Transition Types](#transition-types) below. |
| **Charset** | Dropdown / text input | `alphanumeric` | Character pool used for the random cycling animation. Pick a preset or enter custom characters. |
| **Cycles Min** | Number input | `2` | Minimum number of random-character cycles before landing on the target letter. |
| **Cycles Max** | Number input | `5` | Maximum number of random-character cycles. Each letter in the text draws independently from the min–max range, adding organic variation. |
| **Perspective** | Number input | `400` | CSS perspective distance in pixels for the 3D **flip** and **board** transitions. Lower values create a more dramatic, compressed 3D effect. Only applies to `flip` and `board` types. |
| **Styled Board** | Toggle | On | Applies a dark gradient background with a split-line gap to each character tile for a realistic departure-board appearance. Only applies to the `board` type. |
| **Preserve Whitespace** | Toggle | Off | Renders whitespace characters as empty board cells instead of skipping them. Produces fixed-width rows like a real departure board. Only applies to the `board` type. |

## Transition Types

Seven styles are available in the **Type** dropdown. All are per-character transitions — the surrounding `from`/`to` animation still applies on top.

| Type | Description |
|------|-------------|
| `flip` | Each character rotates on the X axis like a physical flip card. Uses CSS 3D perspective — adjust **Perspective** for depth. |
| `fade` | The outgoing character fades out, the incoming fades in. Owns the `opacity` property — avoid setting opacity in **From**/**To** when using this type. |
| `slide` | Characters slide vertically in and out, clipped by an `overflow: hidden` parent. Produces a slot-machine feel. |
| `blur` | Characters blur in and out between cycles. Owns the `filter` property — avoid setting filter in **From**/**To** when using this type. |
| `scale` | Characters scale up and down between each cycle — a sharp, punchy pop effect. |
| `board` | Full mechanical split-flap effect. Each character is restructured into layered top/bottom panels that fold at the center split line. The most realistic type — pair with **Styled Board** for the complete tile look. |
| `none` | No built-in visual transition. Characters cycle through the charset without animation. Combine with your own **From**/**To** properties for full custom control. |

<LivePreview client:visible
  height={240}
  title="Split-flap departure board"
  html={`<div class="scene">
  <h2 class="board">DEPARTURES</h2>
</div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; background: #111; }
.board { font-family: 'Courier New', monospace; font-size: 2rem; font-weight: 700; letter-spacing: 0.12em; color: #e8e8ec; margin: 0; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("board", ".board", {
  split: "chars",
  flap: { type: "board", styledBoard: true },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

Each tile flips through random characters before snapping to its target. This mimics the **board** transition type with **Styled Board** enabled — dark gradient tiles, split-line divider, and staggered timing per character.

## Charset Options

The **Charset** control sets the pool of characters used for random intermediate glyphs. Select a preset from the dropdown or type any custom string — every character in the string is drawn from at random.

| Preset | Characters used |
|--------|----------------|
| `alphanumeric` | `ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789` |
| `alpha` | `ABCDEFGHIJKLMNOPQRSTUVWXYZ` |
| `numeric` | `0123456789` |
| `hex` | `0123456789ABCDEF` |
| `binary` | `01` |
| `katakana` | Full katakana syllabary (`ア`–`ン`) |
| `symbols` | `!@#$%^&*+-=<>?/\|~` |
| `blocks` | `░▒▓█▄▀■□▪▫` |
| Custom | Any string — type directly into the charset input |

Choose **numeric** for a score counter, **katakana** for a cyberpunk/matrix look, or **blocks** for a loading-indicator feel.

## Common Patterns

### Airport departure board

The canonical use case: **Type → board**, **Styled Board on**, **Preserve Whitespace on** (when row text includes spaces). Add [Stagger](/docs/builder/stagger) each `0.05` for the classic cascade effect. Text Flapper handles character splitting automatically — no need to add Text Splitter separately.

```typescript
import { Motion } from "@motion.page/sdk";

// split: 'chars' is auto-applied when flap is set — no need to add it manually
Motion("departures", ".board-header", {
  flap: { type: "board", styledBoard: true, preserveWhitespaceCells: true },
  stagger: 0.05,
  duration: 0.9,
}).onPageLoad();
```

<LivePreview client:visible
  height={220}
  title="Builder airport board pattern"
  html={`<div class="scene"><h2 class="board-header">MADRID IB3170</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.board-header { margin: 0; font: 800 clamp(1rem, 4vw, 1.55rem)/1 ui-monospace, monospace; letter-spacing: 0.08em; color: #edf0ff; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-departures-preview", ".board-header", {
  flap: { type: "board", styledBoard: true, preserveWhitespaceCells: true },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Subtle text decode reveal

For a lighter touch — no heavy tile styling, just a quick scramble before the real text settles in. Use **Type → fade**, set **Cycles** to `2–4`, and keep **Duration** short.

```typescript
Motion("decode", ".hero-headline", {
  flap: { type: "fade", charset: "alphanumeric", cycles: [2, 4] },
  stagger: { each: 0.03, from: "random" },
  duration: 0.6,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Builder subtle decode pattern"
  html={`<div class="scene"><h2 class="hero-headline">CREATE MOTION</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.hero-headline { margin: 0; font: 800 clamp(1.15rem, 5vw, 2rem)/1 ui-monospace, monospace; letter-spacing: 0.12em; color: #93d8ff; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-decode-preview", ".hero-headline", {
  flap: { type: "fade", charset: "alphanumeric", cycles: [2, 4] },
  stagger: { each: 0.03, from: "random" },
  duration: 0.6,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Slot machine / score counter

Use **Type → slide**, **Charset → numeric**, and a higher cycle count so the digits visibly roll before landing.

```typescript
Motion("score", ".score-value", {
  flap: { type: "slide", charset: "numeric", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
}).onPageLoad();
```

<LivePreview client:visible
  height={200}
  title="Builder score counter pattern"
  html={`<div class="scene"><strong class="score-value">8750</strong></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.score-value { font: 850 3rem/1 ui-monospace, monospace; letter-spacing: 0.1em; color: #ffd974; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-score-preview", ".score-value", {
  flap: { type: "slide", charset: "numeric", cycles: 10 },
  stagger: 0.08,
  duration: 1.2,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

### Cyber / matrix scramble

**Type → fade**, **Charset → katakana**, **Stagger → random** for an organic decode order. Works well as a scroll-triggered reveal.

```typescript
Motion("matrix", ".terminal-output", {
  flap: { type: "fade", charset: "katakana", cycles: [4, 8] },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
}).onScroll({ toggleActions: "play none none none", start: "top 80%" });
```

<LivePreview client:visible
  height={200}
  title="Builder cyber scramble pattern"
  html={`<div class="terminal"><span class="prompt">&gt;</span><span class="terminal-output">SYSTEM ONLINE</span></div>`}
  css={`.terminal { display: flex; align-items: center; gap: 0.7rem; padding: 1rem 1.2rem; border: 1px solid #184b3a; border-radius: 0.45rem; background: #06120f; }
.prompt { color: #3affad; }
.terminal-output { font: 700 clamp(0.85rem, 3vw, 1.25rem)/1 ui-monospace, monospace; letter-spacing: 0.1em; color: #62f1ba; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-matrix-preview", ".terminal-output", {
  flap: { type: "fade", charset: "katakana", cycles: [4, 8], stableWidth: "container" },
  stagger: { each: 0.03, from: "random" },
  duration: 1,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

## SDK Equivalent

Text Flapper maps to the `flap` property in the SDK config. Full documentation, including the `stableWidth` option and `board` type internals, is available on the SDK reference page.

**Builder controls → SDK mapping:**

| Builder control | SDK property |
|----------------|-------------|
| Type | `flap.type` |
| Charset | `flap.charset` |
| Cycles Min / Max | `flap.cycles` (number or `[min, max]` tuple) |
| Perspective | `flap.perspective` |
| Styled Board | `flap.styledBoard` |
| Stable width | `flap.stableWidth` (`false` · `true`/`'cells'` · `'container'`) |
| Preserve Whitespace | `flap.preserveWhitespaceCells` |

**Stable width modes**

The **Stable width** dropdown offers three strategies for preventing layout shift while the characters cycle:

- **Off** — no pinning; text width flexes naturally. Fine for same-width charsets.
- **Per cell** — each character cell is pinned to the widest glyph (target + charset). Classic split-flap monospace look.
- **Per container** — only the animated element's outer width is reserved; letters flow at natural spacing inside. Best for inline hover flappers on nav links where per-cell pinning would visibly space out Latin letters.

```typescript
import { Motion } from "@motion.page/sdk";

Motion("board", ".departure-title", {
  flap: {
    type: "board",
    charset: "alphanumeric",
    cycles: [3, 7],
    perspective: 400,
    styledBoard: true,
    preserveWhitespaceCells: true,
  },
  stagger: 0.05,
  duration: 0.9,
}).onPageLoad();
```

<LivePreview client:visible
  height={220}
  title="Builder controls SDK equivalent"
  html={`<div class="scene"><h2 class="departure-title">MAD JFK 12:45</h2></div>`}
  css={`.scene { display: flex; align-items: center; justify-content: center; height: 100%; }
.departure-title { margin: 0; font: 800 clamp(0.9rem, 4vw, 1.45rem)/1 ui-monospace, monospace; letter-spacing: 0.07em; color: #edf0ff; white-space: nowrap; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("builder-sdk-equivalent-preview", ".departure-title", {
  flap: {
    type: "board",
    charset: "alphanumeric",
    cycles: [3, 7],
    perspective: 400,
    styledBoard: true,
    preserveWhitespaceCells: true,
  },
  stagger: 0.05,
  duration: 0.9,
})
  .withRepeat({ times: -1, delay: 0.8 })
  .play();`}
/>

For the full SDK reference, see [Text Flapper in the SDK](/docs/sdk/text-flapper).

## Related

- [Text Splitter](/docs/builder/split-text) — Optional: Text Flapper auto-splits into characters internally. Add Text Splitter only to reconfigure the split (e.g. include words or lines)
- [Stagger](/docs/builder/stagger) — Control the cascade timing between each flapping character
- [From, To & Set](/docs/builder/from-to-set) — How functional properties apply across animation mode tabs

---

## Page Load Trigger

> Configure auto-play on DOM ready or full page load.

URL: https://motion.page/docs/builder/page-load

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

**Page Load** is the default trigger for every new timeline. The animation plays automatically when the page loads — no user interaction required.

## Location

**Left Panel → Trigger tab → Page Load**

Open the Trigger tab in the Left Panel and select **Page Load** from the trigger dropdown. It is selected by default on new timelines.

{/* Screenshot: Left Panel with the Trigger tab open, showing the Page Load option selected in the trigger dropdown/ComboBox */}
![Page Load trigger settings](/images/builder/page-load-trigger.webp)

## Timing toggle

Once Page Load is selected, a two-option toggle appears below the trigger selector:

| Option | Browser event | Description |
|--------|---------------|-------------|
| **Before Load** (default) | `DOMContentLoaded` | Fires as soon as the JS is loaded — before images and stylesheets finish downloading. Use for above-the-fold entrances. |
| **After Load** | `window.load` | Fires after the entire page — images, fonts, and all resources — has loaded. Use when animations depend on fully rendered assets. |

**Before Load** is the right choice for most entrance animations. Switch to **After Load** only when elements (images, web fonts, videos) need to be fully rendered before the animation begins.

## Advanced options

Expand **Advanced options** in the Left Panel for two additional controls specific to Page Load:

### Load the timeline paused

Builds the timeline on page load but does not auto-play it. Use this to trigger the animation from custom code — for example, after a user action or an asynchronous event.

When enabled, the builder displays the exact call to start the animation:

```js
Motion('your-timeline-name').play();
```

### Play the timeline in a loop

Repeats the timeline after it finishes. Configure repeat count, delay between repeats, and YoYo mode (alternating direction) in the expanded repeat settings.

<LivePreview client:load
  height={240}
  title="Page load entrance"
  html={`<div class="scene">
  <div class="card">
    <div class="dot"></div>
    <div class="lines">
      <div class="line line-a"></div>
      <div class="line line-b"></div>
    </div>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; font-family: system-ui; background: #0d0d0d; }
.card { display: flex; align-items: center; gap: 16px; background: #1a1a1a; border: 1px solid #2a2a2a; border-radius: 14px; padding: 20px 24px; width: 260px; }
.dot { width: 42px; height: 42px; border-radius: 10px; background: #6633EE; flex-shrink: 0; }
.lines { display: flex; flex-direction: column; gap: 8px; flex: 1; }
.line { height: 10px; border-radius: 5px; background: #2e2e2e; }
.line-a { width: 100%; }
.line-b { width: 65%; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("card-entrance", ".card", {
  from: { opacity: 0, y: 24 },
  duration: 0.6,
  ease: "power2.out",
  repeat: { times: -1, yoyo: true, delay: 1.5 },
}).play();`}
/>

The card enters from below and fades in on page load. The icon and text lines stagger in after the container settles.

## SDK equivalent

The builder's **Page Load** trigger maps directly to `.onPageLoad()` in the SDK.

**Before Load (default) — DOM ready:**

```typescript
import { Motion } from '@motion.page/sdk';

Motion('hero', '.hero', {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad();
```

**After Load — full page loaded:**

```typescript
Motion('hero', '.hero', {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad({ timing: 'after' });
```

**Paused — manual trigger:**

```typescript
// Timeline is built on page load but doesn't play until you call .play()
Motion('hero', '.hero', {
  from: { opacity: 0, y: 30 },
  duration: 0.7,
  ease: 'power2.out',
}).onPageLoad({ paused: true });

// Start it manually — e.g. after a custom event
Motion('hero').play();
```

### `onPageLoad` options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timing` | `'during' \| 'after'` | `'during'` | `'during'` fires on `DOMContentLoaded` (**Before Load**); `'after'` fires on `window.load` (**After Load**). |
| `paused` | `boolean` | `false` | When `true`, registers the timeline but does not auto-play. Call `Motion('name').play()` to start it. |

For the full SDK reference, see [Page Load in the SDK](/docs/sdk/page-load).

## Common patterns

### Staggered card entrance

Use **Page Load** with a stagger to reveal a list of cards one after another as the page loads.

```typescript
Motion('cards', '.card', {
  from: { opacity: 0, y: 40 },
  duration: 0.6,
  ease: 'power2.out',
  stagger: 0.1,
}).onPageLoad();
```

### Hero reveal after images load

Images inside `.hero` must be fully rendered before the animation reads their dimensions. Use **After Load**.

```typescript
Motion('hero-reveal', '.hero', {
  from: { opacity: 0, scale: 0.96 },
  duration: 0.8,
  ease: 'power3.out',
}).onPageLoad({ timing: 'after' });
```

### Deferred banner — play on demand

Set **Load the timeline paused** in Advanced options, then trigger the banner after an async operation resolves.

```typescript
Motion('promo-banner', '.banner', {
  from: { opacity: 0, y: -20 },
  duration: 0.5,
  ease: 'power2.out',
}).onPageLoad({ paused: true });

// Play once your condition is met
fetchUserData().then(() => {
  Motion('promo-banner').play();
});
```

## Related

- [Page Load in the SDK](/docs/sdk/page-load) — Full SDK reference for `.onPageLoad()` and its options
- [Page Exit Trigger](/docs/builder/page-exit) — Intercept link clicks and play an exit animation before navigating
- [From, To & Set](/docs/builder/from-to-set) — How animation modes work and when to use each
- [Opacity](/docs/builder/opacity) — Fade in elements using the opacity property
- [Translate](/docs/builder/translate) — Slide elements in using X and Y offsets

---

## Top Panel

> Toolbar controls — undo/redo, device preview, zoom, playback, theme, and CDN toggle.

URL: https://motion.page/docs/builder/top-panel

The Top Panel sits at the top of the [Workspace](/docs/builder/workspace-overview) and provides quick access to undo/redo, device preview, and global settings. Additional playback and zoom controls appear in the [Timeline Editor](/docs/builder/timeline-editor) bar.

{/* Screenshot: Full top panel bar showing all three columns — resize, refresh, undo/redo on left, device breakpoints in center, settings cog on right */}
![Top Panel — full toolbar with undo/redo, device preview, and settings](/images/builder/top-panel-overview.webp)

## Left Controls

The left column of the Top Panel contains controls for managing your workspace view and editing history.

1. **Fullscreen** — Expands the preview iframe to fill the screen. Tooltip: "Full screen"
2. **Refresh** — Reloads the preview iframe. Tooltip: "Refresh"
3. **Undo** — Reverts the last action. Grayed out when no history is available. Tooltip: "Undo last action"
4. **Redo** — Re-applies an undone action. Grayed out when no future states exist. Tooltip: "Redo last action"

| Control | Shortcut | Description |
|---------|----------|-------------|
| **Fullscreen** | — | Expand preview to full screen |
| **Refresh** | — | Reload the preview iframe |
| **Undo** | `Cmd/Ctrl + Z` | Revert the last action |
| **Redo** | `Cmd/Ctrl + Shift + Z` | Re-apply an undone action |

> **Tip:** `Cmd/Ctrl + Y` is an alternative shortcut for **Redo** — useful if `Cmd/Ctrl + Shift + Z` conflicts with another binding.

A history dropdown is available for browsing past actions. The dropdown also exposes a **Clear all undo/redo history** option (tooltip: "Clear all undo/redo history").

Actions that occur within 500ms are batched into a single history entry: node move, node resize, and animation property updates.

## Device Preview

The center column contains four breakpoint buttons that set the preview iframe width to simulate different screen sizes. The active device is highlighted.

| Button | Tooltip | Behavior |
|--------|---------|----------|
| **Mobile** | "Mobile" | Preview at phone breakpoint width |
| **Tablet** | "Tablet" | Preview at tablet breakpoint width |
| **Laptop** | "Laptop" | Preview at laptop breakpoint width |
| **Desktop** | "Desktop" | Preview at full width |

The actual pixel values for each breakpoint are defined in your Global Settings. Switching device does not affect your animations — it only resizes the preview iframe.

{/* Screenshot: Device preview buttons with tablet active, showing narrowed iframe */}
![Device preview — tablet breakpoint active](/images/builder/top-panel-device-preview.webp)

## Global Settings

The **Settings cog** on the right side opens the Global Settings panel. Several toggles here affect the builder experience directly.

### Theme Toggle

Switches the builder between dark and light theme. Tooltip: "Switch between the dark or light theme of the builder". The selected theme is stored persistently across sessions.

### CDN Toggle

Enables or disables loading animation files from the CDN instead of locally. Tooltip: "Enable / disable loading files from CDN, instead of locally." Disable this when working offline or testing against local builds.

### Tooltips Toggle

Enables or disables tooltip display throughout the builder. Tooltip: "Enable / disable display of tooltips". Turn this off once you are familiar with the interface to reduce visual noise.

## Timeline Playback Controls

These controls live in the bar directly above the [Timeline Editor](/docs/builder/timeline-editor). They let you drive animation playback without leaving the builder.

1. **Add Node** (+) — Adds a new animation node to the timeline. Tooltip: "Add an animation node"
2. **Loop** — Toggles looping playback during preview. Tooltip: "Preview in a loop"
3. **Jump to Start** — Moves the playhead to the beginning of the timeline. Tooltip: "Jump to start"
4. **Play / Pause** — Toggles playback and displays the current time and total duration with a progress bar. Tooltip: "Play / Pause"
5. **Jump to End** — Moves the playhead to the end of the timeline. Tooltip: "Jump to end"
6. **Live** — When enabled, animations execute live on the page to preview trigger behavior (scroll, click, hover). Hidden for the Page Events trigger. Tooltip: "If enabled, animations are executed live on the page for preview of a trigger (scroll, click, hover)."

| Control | Description |
|---------|-------------|
| **Add Node** | Add a new animation node |
| **Loop** | Toggle looping playback |
| **Jump to Start** | Move playhead to the beginning |
| **Play / Pause** | Toggle playback; shows current time / total duration |
| **Jump to End** | Move playhead to the end |
| **Live** | Execute animations live on the page for trigger preview |

{/* Screenshot: Timeline playback bar showing play button, loop toggle, and time display */}
![Timeline playback controls](/images/builder/top-panel-playback-controls.webp)

## Zoom & Timeline Controls

The right side of the timeline bar contains controls for navigating and scaling the timeline view.

1. **Click to Place** — Toggle checkbox that enables placing nodes on the timeline by clicking. Tooltip: "Toggle click-to-place nodes on timeline"
2. **Timeline Scrollbar** — Slider for scrolling through the timeline horizontally. Tooltip: "Scrollbar of your timeline."
3. **Max Columns** — Sets the maximum timeline length, cycling from 10s to 70s in 10s steps. Tooltip: "Maximum length of the timeline editor. Click and drag to change."
4. **Zoom Out** — Decreases the zoom level (minimum 0.2×). Tooltip: "Zoom out of the timeline"
5. **Zoom In** — Increases the zoom level (maximum 3.4×). Tooltip: "Zoom in on the timeline"

| Control | Description |
|---------|-------------|
| **Click to Place** | Toggle click-to-place mode for adding nodes |
| **Timeline Scrollbar** | Scroll horizontally through the timeline |
| **Max Columns** | Set maximum timeline length (10s–70s in 10s steps) |
| **Zoom Out** | Decrease timeline zoom (min 0.2×) |
| **Zoom In** | Increase timeline zoom (max 3.4×) |

> **Tip:** Both **Zoom In** and **Zoom Out** support click-and-hold for continuous zoom — you do not need to click repeatedly.

## Keyboard Shortcuts Summary

| Shortcut | Action |
|----------|--------|
| `Cmd/Ctrl + Z` | Undo |
| `Cmd/Ctrl + Shift + Z` | Redo |
| `Cmd/Ctrl + Y` | Redo (alternative) |
| `Cmd/Ctrl + S` | Save timeline |

## Fullscreen Mode

When **Fullscreen** is active, a floating control overlay appears directly over the preview. It mirrors the core timeline playback controls so you can drive animations without returning to the builder:

- Loop toggle
- Jump to Start
- Play/Pause with timer
- Jump to End

Exit fullscreen to return to the full builder interface.

## Related Pages

- [Workspace Overview](/docs/builder/workspace-overview)
- [Timeline Editor](/docs/builder/timeline-editor)
- [Left Panel](/docs/builder/left-panel)

---

## Click Trigger

> Configure click animations with toggle support.

URL: https://motion.page/docs/builder/click-trigger

import LivePreview from "../../components/docs/blocks/LivePreview";
import CodeBlock from "../../components/docs/blocks/CodeBlock.astro";

The **Click trigger** plays a timeline when a specified element is clicked. By default, the animated element itself is the click target. Configure toggle behavior — reverse or restart — to control what the second click does.

## Location

**Left Panel → Trigger tab → Interactions → Click**

Select **Click** from the trigger dropdown to reveal the click configuration panel.

{/* Screenshot: Left Panel with Trigger tab open, Interactions section expanded, Click selected from the trigger dropdown */}
![Click trigger settings panel](/images/builder/click-trigger-settings.webp)

---

## 1st click

The **1st click** section controls which element triggers the animation.

| Control | Description |
|---------|-------------|
| **Trigger selector** | CSS selector for the click target. Leave empty to use the animation selector. Accepts `.class` or `#id`. |
| **Play each iteration individually** | When enabled, each matched element gets its own independent timeline instance — clicking one does not affect the others. |

**Trigger selector** follows the rule set by the mode:

- **Single mode** (each off) — pick any specific selector: `.trigger_class`, `#ID`. Leave empty to default to the animation selector.
- **Each mode** (each on) — the selector acts as a wrapper class. Elements inside each wrapper are targeted individually. Leave empty to use the animation selector as the wrapper.

> Leave empty to use the animation selector as a click trigger or pick a specific selector that triggers the timeline.

> By enabling **Play each iteration individually**, you can animate each iteration of the class individually one-by-one.

---

## 2nd click

The **2nd click** section controls what happens when the element is clicked a second time.

| Control | Description |
|---------|-------------|
| **2nd click selector** | Optional separate element that triggers the second click action. Defaults to the 1st click selector when left empty. Only available when **each** is off. |
| **Reverse animation** | Plays the timeline backward on the second click. Alternates play/reverse on every subsequent click. |
| **Restart animation** | Replays the timeline from the beginning on the second click. No reverse. |

**Reverse** and **Restart** are mutually exclusive — enabling one disables the other. When both are off, repeated clicks play the animation forward from the current position each time.

---

## Prevent default

The **Prevent default actions of the element** toggle disables the element's native browser behavior on click — for example, preventing a link from navigating or a submit button from submitting a form.

> Disable actions of the element on click, e.g. a link.

Enable this when the click target is an `<a>` tag or `<button type="submit">` and the animation should take precedence over the default action.

---

## Toggle behavior

| Mode | What the 2nd click does |
|------|------------------------|
| **Reverse** on | Plays the timeline backward. Alternates play ↔ reverse on every click. |
| **Restart** on | Replays from the beginning. Each click always starts fresh. |
| Both off | Plays forward from the current position each time. |

Use **Reverse** for accordions, drawers, and toggles. Use **Restart** for flash effects, notifications, and one-shot reactions.

---

<LivePreview client:load
  height={220}
  title="Click to expand / collapse"
  html={`<div class="scene">
  <button class="btn">Open panel</button>
  <div class="panel">
    <p class="panel-text">Revealed on click. Click again to close.</p>
  </div>
</div>`}
  css={`.scene { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 16px; height: 100%; font-family: system-ui; }
.btn { padding: 10px 28px; background: #6633EE; color: #fff; border: none; border-radius: 8px; font-size: 14px; font-weight: 600; cursor: pointer; }
.btn:hover { background: #7744ff; }
.panel { overflow: hidden; height: 0; background: #1a1a2e; border-radius: 10px; width: 240px; display: flex; align-items: center; justify-content: center; }
.panel-text { padding: 0 20px; color: #e0d4ff; font-size: 14px; text-align: center; line-height: 1.5; }`}
  js={`import { Motion } from "https://cloud.motion.page/sdk/latest.js";

Motion("expand", ".panel", {
  to: { height: "88px" },
  duration: 0.38,
  ease: "expo.out",
}).onClick({ target: ".btn", toggle: "reverse" });`}
/>

First click plays the animation forward. Second click reverses it — equivalent to enabling **Reverse animation** in the builder.

---

## SDK equivalent

The builder Click trigger maps directly to `.onClick()` in the SDK.

```typescript
import { Motion } from "@motion.page/sdk";

// Basic toggle — plays forward, then reverses on second click
Motion("panel", ".panel", {
  from: { height: 0, opacity: 0 },
  to: { height: "88px", opacity: 1 },
  duration: 0.38,
  ease: "expo.out",
}).onClick({ target: ".btn", toggle: "reverse" });
```

**Restart on every click:**

```typescript
Motion("flash", ".notification", {
  to: { backgroundColor: "#ff4444", scale: 1.04 },
  duration: 0.25,
  ease: "power2.out",
}).onClick({ toggle: "restart" });
```

**Each — independent per-element instances:**

```typescript
// Each card toggles independently
Motion("cards", ".card", {
  to: { y: -8, boxShadow: "0 12px 32px rgba(0,0,0,0.2)" },
  duration: 0.3,
  ease: "power2.out",
}).onClick({ each: true, toggle: "reverse" });
```

**Prevent default on a link:**

```typescript
Motion("lightbox", ".lightbox", {
  from: { opacity: 0, scale: 0.92 },
  duration: 0.35,
  ease: "power2.out",
}).onClick({
  target: "a[data-lightbox]",
  toggle: "reverse",
  preventDefault: true,
});
```

For the full SDK reference see [Click Trigger in the SDK](/docs/sdk/click).

---

## Common patterns

### Accordion / drawer

Set a selector for the expandable element. Enable **Reverse animation**. On the first click, the panel opens; on the second, it collapses.

### Per-card hover-like expand

Enable **Play each iteration individually** so each card in a grid expands and collapses independently without affecting sibling cards.

### Rotate icon on toggle

Add **Rotate** on the **To** tab with a value of `180`. Enable **Reverse animation**. The icon spins to 180° and back on each click — useful for chevrons next to dropdowns.

---

## Related

- [Click Trigger in the SDK](/docs/sdk/click) — Full SDK reference for `.onClick()`
- [Hover Trigger](/docs/builder/hover-trigger) — Trigger animations on mouse enter and leave
- [Page Load Trigger](/docs/builder/page-load) — Auto-play on DOM ready
- [From, To & Set](/docs/builder/from-to-set) — Configure what the animation does

---