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 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.
Playback needs JavaScript and WebGPU. The sequence and original text remain readable.
- time (s)
- rootColor
- intensity
Seeking pauses playback.
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”Use the index.html from installation, 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”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.
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”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.
Animate color
Section titled “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.
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.
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”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”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”@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 when you need that contract; prefer native tweens for ordinary sequencing.
Unavailable output and retry
Section titled “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 opens with a live preview of the shared controls. See GSAP API and troubleshooting for reference details.