189 lines
10 KiB
Markdown
189 lines
10 KiB
Markdown
---
|
||
name: gsap-core
|
||
description: Use GSAP core API correctly — gsap.to(), gsap.from(), gsap.fromTo(), easing, duration, stagger, and defaults. Use when animating DOM elements, SVG, or objects with GSAP, or when the user asks about GSAP tweens, easing, or basic animation. GSAP is used by Webflow Interactions (Webflow acquired GSAP); Webflow outputs or runs GSAP under the hood — GSAP skills apply when debugging or customizing Webflow animations.
|
||
license: MIT
|
||
---
|
||
|
||
# GSAP Core
|
||
|
||
## When to Use This Skill
|
||
|
||
Apply when writing or reviewing GSAP animations that use the core engine: single tweens, eases, staggers, or when explaining how GSAP tweens work.
|
||
|
||
**Context:** GSAP was acquired by Webflow and powers **Webflow Interactions**. Code generated or run by Webflow’s interaction system is GSAP-based; when users ask about Webflow animations or interactions not behaving as expected, GSAP docs and patterns (e.g. tweens, ScrollTrigger) are relevant for debugging or customizing.
|
||
|
||
## 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 (good for entrances).
|
||
- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end; no reading of current values.
|
||
- **gsap.set(targets, vars)** — apply immediately (duration 0).
|
||
|
||
Always use **property names in camelCase** in the vars object (e.g. `backgroundColor`, `marginTop`, `rotationX`, `scaleY`).
|
||
|
||
## Common vars
|
||
|
||
- **duration** — seconds (default 0.5).
|
||
- **delay** — seconds before start.
|
||
- **ease** — string or function. Prefer built-in: `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`.
|
||
- **stagger** — number (seconds between) like `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
|
||
- **overwrite** — `false` (default), `true` (immediately kill all active tweens of the same targets), or `"auto"` (when the tween renders for the first time, only kill individual overlapping properties in other **active** tweens of the same targets).
|
||
- **repeat** — number or `-1` for infinite.
|
||
- **yoyo** — boolean; with repeat, alternates direction.
|
||
- **onComplete**, **onStart**, **onUpdate** — callbacks; scoped to the Animation instance itself (Tween or Timeline).
|
||
- **immediateRender** — When `true` (default for **from()** and **fromTo()**), the tween’s start state is applied as soon as the tween is created (avoids flash of unstyled content and works well with staggered timelines). When **multiple from() or fromTo() tweens** target the same property of the same element, set **immediateRender: false** on the later one(s) so the first tween’s end state is not overwritten before it runs; otherwise the second animation may not be visible.
|
||
|
||
## Transforms and CSS properties
|
||
|
||
GSAP’s CSSPlugin (included in core) animates DOM elements. Use **camelCase** for CSS properties (e.g. `fontSize`, `backgroundColor`). Prefer GSAP’s **transform aliases** over the raw `transform` string: they apply in a consistent order (translation → scale → rotationX/Y → skew → rotation), are more performant, and work reliably across browsers.
|
||
|
||
**Transform aliases (prefer over translateX(), rotate(), etc.):**
|
||
|
||
| GSAP property | Equivalent CSS / note |
|
||
|---------------|------------------------|
|
||
| `x`, `y`, `z` | translateX/Y/Z (default unit: px) |
|
||
| `xPercent`, `yPercent` | translateX/Y in %; use for percentage-based movement; work on SVG |
|
||
| `scale`, `scaleX`, `scaleY` | scale; `scale` sets both X and Y |
|
||
| `rotation` | rotate (default: deg; or `"1.25rad"`) |
|
||
| `rotationX`, `rotationY` | 3D rotate (rotationZ = rotation) |
|
||
| `skewX`, `skewY` | skew (deg or rad string) |
|
||
| `transformOrigin` | transform-origin (e.g. `"left top"`, `"50% 50%"`) |
|
||
|
||
Relative values work: `x: "+=20"`, `rotation: "-=30"`. Default units: x/y in px, rotation in deg.
|
||
|
||
- **autoAlpha** — Prefer over `opacity` for fade in/out. When the value is `0`, GSAP also sets `visibility: hidden` (better rendering and no pointer events); when non-zero, `visibility` is set to `inherit`. Avoids leaving invisible elements blocking clicks.
|
||
- **CSS variables** — GSAP can animate custom properties (e.g. `"--hue": 180`, `"--size": 100`). Supported in browsers that support CSS variables.
|
||
- **svgOrigin** _(SVG only)_ — Like `transformOrigin` but in the SVG’s **global** coordinate space (e.g. `svgOrigin: "250 100"`). Use when several SVG elements should rotate or scale around a common point. Only one of `svgOrigin` or `transformOrigin` can be used. No percentage values; units optional.
|
||
- **Directional rotation** — Append a suffix to rotation values (string): **`_short`** (shortest path), **`_cw`** (clockwise), **`_ccw`** (counter-clockwise). Applies to `rotation`, `rotationX`, `rotationY`. Example: `rotation: "-170_short"` (20° clockwise instead of 340° counter-clockwise); `rotationX: "+=30_cw"`.
|
||
- **clearProps** — Comma-separated list of property names (or `"all"` / `true`) to **remove** from the element’s inline style when the tween completes. Use when a class or other CSS should take over after the animation. Clearing any transform-related property (e.g. `x`, `scale`, `rotation`) clears the **entire** transform.
|
||
|
||
```javascript
|
||
gsap.to(".box", { x: 100, rotation: "360_cw", duration: 1 });
|
||
gsap.to(".fade", { autoAlpha: 0, duration: 0.5, clearProps: "visibility" });
|
||
gsap.to(svgEl, { rotation: 90, svgOrigin: "100 100" });
|
||
```
|
||
|
||
## Targets
|
||
|
||
- **Single or Multiple**: CSS selector string, element reference, array or NodeList. GSAP handles arrays; use stagger for offset.
|
||
|
||
## Stagger
|
||
|
||
Offset the animation of each item by 0.1 second like this:
|
||
```javascript
|
||
gsap.to(".item", {
|
||
y: -20,
|
||
stagger: 0.1
|
||
});
|
||
```
|
||
Or use the object syntax for advanced options like how each successive stagger amount is applied to the targets array (`from: "random" | "start" | "center" | "end" | "edges" | (index)`)
|
||
|
||
### Learn More
|
||
|
||
https://gsap.com/resources/getting-started/Staggers
|
||
|
||
## Easing
|
||
|
||
Use string eases unless a custom curve is needed:
|
||
|
||
```javascript
|
||
ease: "power1.out" // default feel
|
||
ease: "power3.inOut"
|
||
ease: "back.out(1.7)" // overshoot
|
||
ease: "elastic.out(1, 0.3)"
|
||
ease: "none" // linear
|
||
```
|
||
|
||
Built-in eases: base (same as `.out`), `.in`, `.out`, `.inOut` where "power" refers to the strength of the curve (1 is more gradual, 4 is steepest):
|
||
|
||
```
|
||
base (out) .in .out .inOut
|
||
"none"
|
||
"power1" "power1.in" "power1.out" "power1.inOut"
|
||
"power2" "power2.in" "power2.out" "power2.inOut"
|
||
"power3" "power3.in" "power3.out" "power3.inOut"
|
||
"power4" "power4.in" "power4.out" "power4.inOut"
|
||
"back" "back.in" "back.out" "back.inOut"
|
||
"bounce" "bounce.in" "bounce.out" "bounce.inOut"
|
||
"circ" "circ.in" "circ.out" "circ.inOut"
|
||
"elastic" "elastic.in" "elastic.out" "elastic.inOut"
|
||
"expo" "expo.in" "expo.out" "expo.inOut"
|
||
"sine" "sine.in" "sine.out" "sine.inOut"
|
||
```
|
||
|
||
### Custom: use CustomEase (plugin)
|
||
|
||
Simple cubic-bezier values (as used in CSS `cubic-bezier()`):
|
||
|
||
```javascript
|
||
const myEase = CustomEase.create("my-ease", ".17,.67,.83,.67");
|
||
|
||
gsap.to(".item", {x: 100, ease: myEase, duration: 1});
|
||
```
|
||
|
||
Complex curve with any number of control points, described as normalized SVG path data:
|
||
|
||
```javascript
|
||
const myEase = CustomEase.create("hop", "M0,0 C0,0 0.056,0.442 0.175,0.442 0.294,0.442 0.332,0 0.332,0 0.332,0 0.414,1 0.671,1 0.991,1 1,0 1,0");
|
||
|
||
gsap.to(".item", {x: 100, ease: myEase, duration: 1});
|
||
```
|
||
|
||
## Returning and Controlling Tweens
|
||
|
||
All tween methods return a **Tween** instance. Store the return value when controlling playback is needed:
|
||
|
||
```javascript
|
||
const tween = gsap.to(".box", { x: 100, duration: 1, repeat: 1, yoyo: true });
|
||
tween.pause();
|
||
tween.play();
|
||
tween.reverse();
|
||
tween.kill();
|
||
tween.progress(0.5);
|
||
tween.time(0.2);
|
||
tween.totalTime(1.5);
|
||
```
|
||
|
||
## Function-based values
|
||
Use a function for a `vars` value and it will get called **once for each target** the first time the tween renders, and whatever is returned by that function will be used as the animation value.
|
||
|
||
```javascript
|
||
gsap.to(".item", {
|
||
x: (i, target, targetsArray) => i * 50, // first item animates to 0, the second to 50, the third to 100, etc.
|
||
stagger: 0.1
|
||
});
|
||
```
|
||
|
||
## Relative values
|
||
|
||
Use a `+=`, `-=`, `*=`, or `/=` prefix to indicate a **relative** value. For example, the following will animate x to 20 pixels less than whatever it is when the tween renders for the first time.
|
||
|
||
```javascript
|
||
gsap.to(".class", {x: "-=20" });
|
||
```
|
||
`x: "+=20"` would add 20 to the current value. `"*=2"` would multiply by 2, and `"/=2"` would divide by 2.
|
||
|
||
|
||
## Defaults
|
||
|
||
Set project-wide Tween defaults with **gsap.defaults()**:
|
||
|
||
```javascript
|
||
gsap.defaults({ duration: 0.6, ease: "power2.out" });
|
||
```
|
||
|
||
## Best practices
|
||
|
||
- ✅ Use **property names in camelCase** in vars (e.g. `backgroundColor`, `rotationX`).
|
||
- ✅ Prefer **transform aliases** (`x`, `y`, `scale`, `rotation`, `xPercent`, `yPercent`, etc.) over animating the raw `transform` string; use **autoAlpha** instead of `opacity` for fade in/out when elements should be hidden and non-interactive at 0.
|
||
- ✅ Use documented built-in eases; use CustomEase when a custom curve is needed.
|
||
- ✅ Store the tween/timeline return value when controlling playback (pause, play, reverse, kill).
|
||
|
||
## Do Not
|
||
|
||
- ❌ Animate layout-heavy properties (e.g. `width`, `height`, `top`, `left`) when transform aliases (`x`, `y`, `scale`, `rotation`) can achieve the same effect; prefer transforms for better performance.
|
||
- ❌ Use both **svgOrigin** and **transformOrigin** on the same SVG element; only one applies.
|
||
- ❌ Rely on the default **immediateRender: true** when stacking multiple **from()** or **fromTo()** tweens on the same property of the same target; set **immediateRender: false** on the later tweens so they animate correctly.
|
||
- ❌ Use invalid or non-existent ease names; stick to documented eases.
|
||
- ❌ Forget that **gsap.from()** uses the element’s current state as the end state; the initial values in the tween will be applied immediately unless `immediateRender: false` is in the `vars`.
|