gsap

GSAP

Core Tween Methods

• gsap.to(targets, vars) — animate from current state to vars. Most common.
• gsap.from(targets, vars) — animate from vars to current state (entrances).
• gsap.fromTo(targets, fromVars, toVars) — explicit start and end.
• gsap.set(targets, vars) — apply immediately (duration 0).

Always use camelCase property names (e.g. backgroundColor, rotationX).

Common vars

• duration — seconds (default 0.5).
• delay — seconds before start.
• ease — "power1.out" (default), "power3.inOut", "back.out(1.7)", "elastic.out(1, 0.3)", "none".
• stagger — number 0.1 or object: { amount: 0.3, from: "center" }, { each: 0.1, from: "random" }.
• overwrite — false (default), true, or "auto".
• repeat — number or -1 for infinite. yoyo — alternates direction with repeat.
• onComplete, onStart, onUpdate — callbacks.
• immediateRender — default true for from()/fromTo(). Set false on later tweens targeting the same property+element to avoid overwrite.

Transforms and CSS

Prefer GSAP's transform aliases over raw transform string:

• autoAlpha — prefer over opacity. At 0: also sets visibility: hidden.
• CSS variables — "--hue": 180.
• svgOrigin (SVG only) — global SVG coordinate space origin. Don't combine with transformOrigin.
• Directional rotation — "360_cw", "-170_short", "90_ccw".
• clearProps — "all" or comma-separated; removes inline styles on complete.
• Relative values — "+=20", "-=10", "*=2".

Function-Based Values

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

Easing

Built-in eases: power1–power4, back, bounce, circ, elastic, expo, sine. Each has .in, .out, .inOut.

Defaults

gsap.defaults({ duration: 0.6, ease: "power2.out" });

Controlling Tweens

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia() (Responsive + Accessibility)

Runs setup only when a media query matches; auto-reverts when it stops matching.

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

Timelines

Creating a Timeline

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Position Parameter

Third argument controls placement:

• Absolute: 1 — at 1s
• Relative: "+=0.5" — after end; "-=0.2" — before end
• Label: "intro", "intro+=0.3"
• Alignment: "<" — same start as previous; ">" — after previous ends; "<0.2" — 0.2s after previous starts

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // same start as .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts

Labels

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

Timeline Options

• paused: true — create paused; call .play() to start.
• repeat, yoyo — apply to whole timeline.
• defaults — vars merged into every child tween.

Nesting Timelines

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

Playback Control

tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().

Performance

Prefer Transform and Opacity

Animating x, y, scale, rotation, opacity stays on the compositor. Avoid width, height, top, left when transforms achieve the same effect.

will-change

will-change: transform;

Only on elements that actually animate.

gsap.quickTo() for Frequent Updates

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

Stagger > Many Tweens

Use stagger instead of separate tweens with manual delays.

Cleanup

Pause or kill off-screen animations.

Enterprise Async Loader Overlays

For critical waits such as report generation, use a page-level overlay, not a dock-only spinner. The overlay should isolate the whole viewport (position: fixed, explicit z-index, backdrop/isolation) so lower page sections and icons cannot leak through while the system owns the user's attention.

Build a master timeline with labels for entrance, signal loop, stage-copy updates, ready handoff and exit. Continuous motion should be distributed across the composition (background scan, cards, progress, focal mark, copy/type effect), not concentrated in one tiny moving element. Keep copy calm, real and lightly human; avoid exposing raw internal terms unless the user benefits from them.

When the copy says "Efeonce", show the Efeonce mark/logo rather than a plain text pill. Avoid decorative bars or floating shapes unless they communicate analysis progress, evidence assembly, or handoff state.

Respect prefers-reduced-motion with a static staged state and no infinite loops. Animate transform and opacity, kill timelines on navigation/unmount, and keep the final ready transition smooth: ready state -> premium "report ready/opening" overlay -> route/report entrance.

References (loaded on demand)

• references/effects.md — Drop-in effects: typewriter text, audio visualizer. Read when needing ready-made effect patterns for HyperFrames.

Best Practices

• Use camelCase property names; prefer transform aliases and autoAlpha.
• Prefer timelines over chaining with delay; use the position parameter.
• Add labels with addLabel() for readable sequencing.
• Pass defaults into timeline constructor.
• Store tween/timeline return value when controlling playback.

Do Not

• Animate layout properties (width/height/top/left) when transforms suffice.
• Use both svgOrigin and transformOrigin on the same SVG element.
• Chain animations with delay when a timeline can sequence them.
• Create tweens before the DOM exists.
• Skip cleanup — always kill tweens when no longer needed.