# GSAP

Control effect time and intensity with a timeline you own.

A GSAP tween animates properties over time. Use native tweens to animate any domfx effect, and a timeline to sequence them. The effect instance exposes numeric `time` and `intensity` setters. No domfx plugin registration or `@domfx/gsap` import is needed.

Follow the [installation guide](/docs/installation/#add-the-optional-gsap-binding) and add GSAP to your app. This example uses Fire; replace its import to use another effect.

### Try the sequence

One timeline moves the text and drives five effects, letter by letter.

domfx

Hover to inspectZoom to inspect Focus the preview: + and − zoom, arrows pan, 0 resets. Drag to pan on touchscreens.

<!-- Pan first: its arrows unfold leftward, so the zoom buttons never move under the pointer. -->

Playback needs JavaScript and WebGPU. The sequence and original text remain readable.

<!-- Open without JavaScript too: the tracks and starting values stay readable. -->

* time (s)

  0.00

* rootColor

  **

* intensity

  0.000.000.000.000.00

Timeline position (s)0.00

Seeking pauses playback.

The sequence

```ts
timeline.fromTo(host, { opacity: 0 }, {
  opacity: 1,
  duration: .4,
  ease: "none",
  immediateRender: false
}, 0);
timeline.fromTo(letters, { y: 70 }, {
  y: 0,
  duration: .8,
  ease: "back.out(2.2)",
  stagger: .06,
  immediateRender: false
}, 0);
timeline.addLabel("ignite", 1);
timeline.to(fires, {
  intensity: 1,
  duration: .7,
  ease: "power3.in",
  stagger: .14
}, "ignite");
timeline.addLabel("surge", 2.4);
timeline.to(fires, {
  rootColor: "#ffffff",
  tipColor: "#ffd27a",
  duration: .7,
  ease: "power1.in"
}, "surge");
timeline.to(fires, {
  rootColor: "#99ddff",
  tipColor: "#0066ff",
  duration: .8,
  ease: "power1.out"
}, "surge+=0.7");
timeline.to(letters, {
  y: -18,
  duration: .3,
  ease: "sine.inOut",
  yoyo: true,
  repeat: 1,
  stagger: .07
}, "surge+=0.3");
timeline.addLabel("burnOut", 4.2);
timeline.to(fires, {
  intensity: .08,
  duration: 1,
  ease: "power2.out",
  stagger: {
    each: .15,
    from: "end"
  }
}, "burnOut");
timeline.to(fires, {
  time: 6,
  duration: 6,
  ease: "none"
}, 0);
```

This is the sequence the player executes, including its stagger and labels. The complete example below starts smaller, with one target and one effect.

The player gives each letter its own effect with `attachFire(letter, { host, clock: 'manual', intensity: 0, flameReach: 0.7 })`, then passes the letters and effects to one timeline, so `stagger` applies to both. Move, scale and fade the host or the letters’ position freely: the effect follows without a new capture. Rotation and skew turn the effect off with `unsupported-placement`, and target-only opacity changes are unsupported, so fade the host.

The rest of this guide starts smaller, with one target and one effect.

## Provide your elements

[Section titled “Provide your elements”](#provide-your-elements)

Use the `index.html` from [installation](/docs/installation/#provide-the-target-and-host), including the click counter. Replace all of `main.ts` with the module below. In a component, run it after the elements mount.

## Build your sequence

[Section titled “Build your sequence”](#build-your-sequence)

Create the effect with `clock: ‘manual’` so GSAP controls its time. The container fades in over half a second; the effect then moves from time 0 to 4 and intensity 0.8 to 0.4 over four seconds. Fade the container so the original target and effect share opacity. Target-only opacity changes are unsupported.

```ts
import { gsap } from 'gsap';
import { attachFire } from '@domfx/browser';

const host = document.querySelector('#host');
const target = document.querySelector('#target');
const clicks = document.querySelector('#clicks');
if (!(host instanceof HTMLElement) || !target || !clicks) {
  throw new Error('Missing host, target or click counter');
}

let count = 0;
const onClick = () => { clicks.textContent = String(++count); };
target.addEventListener('click', onClick);

let disposed = false;
let fire: ReturnType<typeof attachFire> | undefined;
const timeline = gsap.timeline({ paused: true });
let unsubscribe: (() => void) | undefined;

function cleanup() {
  disposed = true;
  window.removeEventListener('pagehide', cleanup);
  target?.removeEventListener('click', onClick);
  unsubscribe?.();
  timeline.revert();
  fire?.dispose();
}

// Before calling setup, also register cleanup to run on component unmount.
window.addEventListener('pagehide', cleanup, { once: true });

const setup = async () => {
  await document.fonts.ready;
  if (disposed) { return; }

  fire = attachFire(target, {
    host, clock: 'manual', motion: 'respect',
    time: 0, intensity: 0.8, seed: 314,
  });
  unsubscribe = fire.onDispose(() => timeline.revert());
  // The target and effect share the container opacity.
  timeline.from(host, {
    opacity: 0,
    duration: .5,
    immediateRender: false
  });
  timeline.addLabel("ignite", .5);
  timeline.to(fire, {
    time: 4,
    intensity: .4,
    duration: 4,
    ease: "none"
  }, "ignite");

  await fire.ready;
  if (disposed) { return; }
  if (fire.lifecycle !== 'active') {
    console.info(fire.reason);
    return;
  }

  timeline.play();
};

void setup();
```

Run `pnpm dev` and open the printed URL. The button fades in, then its flames change over four seconds; clicking it increases the counter. For production, run `pnpm build`, then `pnpm preview`.

## Seek and play

[Section titled “Seek and play”](#seek-and-play)

After setup, use `timeline.play()`, `pause()`, `seek()` and `reverse()`. At `timeline.seek(2.5)`, effect time is 2 and intensity is 0.6. Seeking backward to 1.5 gives time 1 and intensity 0.7. Callback-suppressed seeks still update the setters; an `onUpdate` copy is unnecessary.

Chain `.to()` calls to animate from preceding destinations. Use `.from()` or `.fromTo()` for explicit starting values, remembering their default immediate rendering. Later `.fromTo()` segments commonly need `immediateRender: false`. Easing controls the rate of change. Easing, `repeat`, `yoyo`, `overwrite` and `timeScale()` follow normal GSAP conventions.

`gsap.killTweensOf(fire, ‘intensity’)` stops only that property; it does not dispose the effect or stop a time tween. Keep one driver per property and keep values within the [control ranges](/docs/api/shared/#control-playback).

## Animate color

[Section titled “Animate color”](#animate-color)

Every effect except Burned paper supports a writable `color`. Initialize it with an explicit supported opaque color string, then use explicit opaque endpoints with `fromTo()`; the original palette is `undefined`, not an interpolation endpoint. This changes the decoration, preserving the target and effect opacity.

```ts
fire.color = '#ff6600';
const colorTween = gsap.fromTo(
  fire,
  { color: '#ff6600' },
  { color: '#6699ff', duration: 2, ease: 'power1.inOut' },
);
```

For subsequent changes, use `gsap.to(fire, { color: '#ff6600', duration: 2 })`. During cleanup, call `colorTween.kill()` before disposing the effect. To restore the original palette, stop color tweens and assign `fire.color = undefined`.

Fire’s `rootColor` and `tipColor` animate the same way, with no plugin: assign an explicit color first, then use `fromTo()`. Neither can be set while `color` is set.

```ts
fire.rootColor = '#fff5a3';
fire.tipColor = '#ff1701';
const flameTween = gsap.fromTo(
  fire,
  { rootColor: '#fff5a3', tipColor: '#ff1701' },
  { rootColor: '#99ddff', tipColor: '#0066ff', duration: 2 },
);
```

## Own the lifetime

[Section titled “Own the lifetime”](#own-the-lifetime)

Register `cleanup()` in your framework’s unmount hook before calling `setup()`. It removes listeners, reverts and kills this example’s timeline, and disposes the effect. This works while fonts or `ready` are pending. The disposal listener also restores opacity if the target is removed. On remount, create fresh variables, an effect and a timeline.

When borrowing a timeline, retain and kill only your child tweens; its owner cleans up the timeline and siblings. Finishing, killing or overwriting a tween does not release its target’s resources.

### GSAP context cleanup

[Section titled “GSAP context cleanup”](#gsap-context-cleanup)

Create tweens inside `gsap.context()` and return explicit resource cleanup. Register synchronously; a context does not automatically collect work created later by arbitrary promise continuations.

When adapting this example to a context, return `cleanup` from its setup function and call `context.revert()` on unmount.

## Optional lifecycle helpers

[Section titled “Optional lifecycle helpers”](#optional-lifecycle-helpers)

`@domfx/gsap` provides `bindEffect` and `bindEffectAsync` for snapshot bindings with explicit cleanup responsibility. The asynchronous helper safely disposes results arriving after cancellation.

These helpers capture starting controls when created and animate private proxy targets. They differ from native chained `.to()` calls, target-based kill and overwrite. Use the [binding reference](/docs/api/gsap/#snapshot-bindings) when you need that contract; prefer native tweens for ordinary sequencing.

## Unavailable output and retry

[Section titled “Unavailable output and retry”](#unavailable-output-and-retry)

The main example starts playback only when the effect is active. Missing GPU support or reduced motion preserves the original target. Correct the condition, then await `fire.retry()`, inspect its state and play the existing timeline. Retry retains controls; it does not require another tween.

Every [effect reference](/docs/api/effects/) opens with a live preview of the shared controls. See [GSAP API](/docs/api/gsap/) and [troubleshooting](/docs/troubleshooting/) for reference details.
