GSAP API
Animate effect properties with GSAP or use optional bindings with fixed starting values.
Native property tweens
Section titled “Native property tweens”A tween animates property values over time. Use gsap.to(effect, { time, intensity, duration, ease }) or add the same target to a timeline. Use clock: ‘manual’ when creating the effect. No domfx plugin registration or @domfx/gsap import is needed for these numeric properties.
GSAP writes the effect’s public setters, including during callback-suppressed seeks. Chained .to() calls start from the preceding values. .from(), .fromTo(), ease (the rate of change), repeat/yoyo, property overwrite and gsap.killTweensOf(effect) use standard GSAP behavior.
Keep values within the effect control ranges. The instance validates writes at runtime; GSAP’s types do not enforce these ranges. intensity clamps per write, so overshooting eases may clip its animation.
Kill your tweens and dispose your effect during teardown. Killing or completing a tween does not dispose its target. Register cleanup immediately, including when setup is still pending. See the complete GSAP guide for the lifecycle pattern.
Optional snapshot bindings
Section titled “Optional snapshot bindings”Choose a binding when you need fixed starting values or its cleanup helpers. For ordinary sequences, use the native tweens above.
Import bindEffect from @domfx/gsap. It accepts any undisposed EffectHandle with manual control. Supply the effect instance, a caller-owned GSAP timeline and these options:
| Property | Type | Default |
|---|---|---|
timeAbsolute destination time in seconds. Must be finite and representable as float32. | number | Required |
intensityFinite destination strength. Clamped to 0–1 before interpolation. | number | Required |
durationFinite, nonnegative interpolation duration in seconds. Zero is accepted. | number | Required |
positionGSAP insertion position. Omitting it appends to the timeline. | gsap.Position | undefined |
disposeEffectGive effect cleanup responsibility to the binding, including context revert. | boolean | false |
bindEffect(effect, timeline, options) returns an EffectBinding. It fixes the starting controls when called and interpolates linearly. Later writes do not change those starting values. binding.dispose() removes its tween, keeps the last control values and disposes the effect only with disposeEffect: true. The caller still owns the timeline.
bindEffectAsync(promise, timeline, options) accepts a promise of any effect handle and requires disposeEffect: true. It returns an AsyncEffectBinding with dispose() and ready: Promise<void>, releasing late results after cancellation. Use context.revert() for GSAP context cleanup.
See the GSAP guide for a complete sequence and teardown.
These adapters animate private objects rather than the effect instance: gsap.killTweensOf(effect) and overwrite between bindings do not affect those tweens. Multiple bindings created together snapshot the same starting controls; use native .to() calls for normal chained sequencing.
Killing the caller's timeline alone does not remove a binding's disposal subscription. Dispose the binding too. An asynchronous binding's ready waits for binding setup or late-result cleanup, not the effect's own initial setup.
You can bind before effect.ready settles. Invalid options, automatic control and disposed instances throw synchronously; failed validation leaves effect cleanup with you. Disposing an effect detaches its bindings. Use context.revert(), not context.kill(), to run custom context cleanup.