GSAP

https://github.com/greensock/gsap
Admin
GSAP is a framework-agnostic JavaScript animation library for building high-performance animations...
Tokens:240,482
Snippets:1,022
Trust Score:6.8
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### wrap usage examples

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/utils.md

JavaScript examples showing direct invocation with a numeric range and curried form with an array, including the expected outputs.

```javascript
gsap.utils.wrap(0, 100, 150);        // 50
const loop = gsap.utils.wrap(["a", "b", "c"]);
loop(4);                             // "b"
```

--------------------------------

### MotionPathHelper.create and kill usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/motion-plugins.md

JavaScript example showing how to import MotionPathHelper and create a helper for an element with a given path, ease, and duration. The kill() method removes the editor UI from the DOM.

```javascript
import MotionPathHelper from "gsap/MotionPathHelper";
const helper = MotionPathHelper.create(".plane", { path: "#path", ease: "none", duration: 6 });
helper.kill(); // removes editor UI from the DOM
```

--------------------------------

### MotionPathPlugin usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/motion-plugins.md

JavaScript example showing how to import and register MotionPathPlugin, tween an element along a path with alignment and auto-rotation, and use utility methods like `stringToRawPath`, `cacheRawPathMeasurements`, `getPositionOnPath`, and `pointsToSegment`.

```javascript
import MotionPathPlugin from "gsap/MotionPathPlugin";
gsap.registerPlugin(MotionPathPlugin);

gsap.to("#plane", {
  motionPath: { path: "#flightPath", align: "#plane", autoRotate: true, alignOrigin: [0.5, 0.5] },
  duration: 5, ease: "none"
});

// utilities
const raw = MotionPathPlugin.stringToRawPath("M0,0 C100,20 300,50 400,0");
MotionPathPlugin.cacheRawPathMeasurements(raw);
const pos = MotionPathPlugin.getPositionOnPath(raw, 0.5, true); // {x, y, angle}
const seg = MotionPathPlugin.pointsToSegment([0,0, 100,50, 200,0], 0.5);
```

--------------------------------

### distribute usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/utils.md

JavaScript example showing how to create a distribution function and use it as a function-based value in a tween.

```javascript
const dx = gsap.utils.distribute({ base: 0, amount: 100, from: "center", grid: [2, 3], axis: "x", ease: "power1.inOut" });
gsap.to(cards, { x: dx }); // per-target values
```

--------------------------------

### Install GSAP via npm

Source: https://github.com/greensock/gsap/blob/master/README.md

Installs GSAP via npm. See the guide to using GSAP via NPM at gsap.com for more details.

```javascript
npm install gsap
```

--------------------------------

### ScrollToPlugin usage examples (JavaScript)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-to-plugin.md

JavaScript examples showing how to import, register, and use ScrollToPlugin for various scroll-to tweens, including static methods and error handling.

```javascript
import ScrollToPlugin from "gsap/ScrollToPlugin";
gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { scrollTo: { y: "#section-4", offsetY: 80, autoKill: true, onAutoKill: () => console.log("user took over") }, duration: 1.5, ease: "power2.inOut" });
gsap.to(scroller, { scrollTo: "max", duration: 2 });                  // to the bottom
gsap.to(scroller, { scrollTo: 250, duration: 1 });                    // px
gsap.to(scroller, { scrollTo: { x: 100, y: "+=200" }, duration: 1 }); // relative

// statics
const maxY = ScrollToPlugin.max(window);
const off = ScrollToPlugin.offset("#el", ".container");

// error handling
ScrollToPlugin.config({ autoKill: true, autoKillThreshold: 5 });
try {
  ScrollToPlugin.offset("#missing", window); // warns and returns {x:0, y:0}
} catch (e) { /* no throw; warning only */ }
```

--------------------------------

### Animation method chaining example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/animation.md

Example of chaining Animation methods: pause, eventCallback, timeScale, then, and kill. Shows usage of the then() promise and eventCallback with parameters and scope.

```js
const tween = gsap.to(".box", { x: 100, duration: 1, repeat: 1, yoyo: true });
tween.pause(0.5)
     .eventCallback("onComplete", done, [param], scope)
     .timeScale(2);
tween.then(result => console.log("resolved", result.id));
tween.kill();
```

--------------------------------

### InertiaPlugin Usage Example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/physics-plugins.md

Usage example for InertiaPlugin. Registers the plugin, then shows the simplest inertia tween (current velocity continues) and a full-control configuration with velocity, end candidates, linkedProps, resistance, and duration constraints. Also demonstrates error handling for getVelocity when the property is not tracked yet.

```js
import InertiaPlugin from "gsap/InertiaPlugin";
gsap.registerPlugin(InertiaPlugin);

// simplest: current velocity continues
gsap.to(el, { x: 500, inertia: true, duration: 3 });

// full control
gsap.to(el, {
  inertia: {
    x: { velocity: 800, end: [200, 400, 600], min: 0, max: 1000 },
    y: { velocity: "auto", end: 300 },
    linkedProps: "x,y",
    resistance: 150,
    duration: { min: 0.2, max: 6, overshoot: 0.3 }
  }
});

// error handling / fallback to manual tween
try {
  InertiaPlugin.getVelocity(el, "x");
} catch (err) {
  console.warn("not tracked yet — call InertiaPlugin.track(el, 'x')", err);
}
```

--------------------------------

### Observer.create example with error handling

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/observer.md

Demonstrates creating an Observer with various callbacks and options, then shows registry-driven cleanup and lookup by id.

```javascript
Observer.create({
  target: "#stage",
  type: "wheel,touch,pointer",
  onUp: self => console.log("up", self.deltaY),
  onDown: self => console.log("down", self.deltaY, "velocity", self.velocityY),
  onLeft: () => prev(),
  onRight: () => next(),
  onChange: self => gsap.to("#indicator", { x: self.pointerX }),
  lockAxis: true,
  onLockAxis: self => console.log("locked", self.axis),
  onStop: () => console.log("stopped"),
  ignore: ".ui-controls",
  wheelSpeed: 1.2,
  tolerance: 2
});

// error handling: registry-driven cleanup
Observer.getAll().forEach(o => o.kill());
const o = Observer.create({ id: "my-observer", onWheel: handleWheel });
Observer.getById("my-observer")?.disable();
```

--------------------------------

### CSSRulePlugin usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/css-plugin.md

JavaScript example showing how to import, register, and use CSSRulePlugin to animate a CSS rule. Includes error handling for selectors with no matching rule, which returns undefined.

```javascript
import { CSSRulePlugin } from "gsap/all";
gsap.registerPlugin(CSSRulePlugin);

const rule = CSSRulePlugin.getRule(".btn::before");
gsap.to(rule, { cssRule: { color: "#0af", scale: 1.2 }, duration: 0.5 });

// error handling: selector with no matching rule returns undefined
const missing = CSSRulePlugin.getRule(".does-not-exist");
if (!missing) console.warn("rule not found");
```

--------------------------------

### snap() usage examples

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/utils.md

JavaScript examples for gsap.utils.snap(). Shows snapping to an increment, to an array of values, to a value within a radius, creating a reusable snap function, and snapping 2D points.

```javascript
gsap.utils.snap(10, 23.5);                          // 20
gsap.utils.snap([100, 50, 500], 65);                // 50
gsap.utils.snap({ values: [0, 100, 300], radius: 20 }, 85); // 100
const snapIncrement = gsap.utils.snap(5);
snapIncrement(0.5);                                 // 0
// 2D points:
gsap.utils.snap({ values: [{x:0,y:0},{x:10,y:10}], radius: 5 }, {x:8, y:8}); // {x:10,y:10}
```

--------------------------------

### CustomEase

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/easing.md

Documentation for the CustomEase class, including constructor, methods, properties, and usage example.

```APIDOC
## class CustomEase

### Description
CustomEase is a GSAP plugin that lets you create custom easing functions using SVG path data or an array of [time, value] points. It registers the ease with GSAP so it can be used in tweens.

### Constructor
`new CustomEase(id: string, data?: string | number[], config?: CustomEaseConfig)`

### Parameters
- **id** (string) - Required - The unique identifier for the ease.
- **data** (string | number[]) - Optional - SVG path data (e.g., `"M0,0 C0.25,0.1 0.75,1 1,1"`) or an array of `[time, value]` points.
- **config** (CustomEaseConfig) - Optional - Configuration object with properties: `precision`, `height`, `originY`, `width`, `x`, `y`, `invert`, `path`.

### Methods

#### `setData(data?: string | number[], config?: CustomEaseConfig): this`
Re-parses the ease data in place.

#### `getSVGData(config?: CustomEaseConfig): string`
Returns the SVG path data for the ease.

#### `static create(id: string, data?: string | number[], config?: CustomEaseConfig): EaseFunction`
Creates a new CustomEase and returns an easing function.

#### `static register(core: object): void`
Registers the plugin with GSAP.

#### `static get(id: string): EaseFunction`
Retrieves an existing CustomEase by its id.

#### `static getSVGData(ease: CustomEase | EaseFunction | string, config?: CustomEaseConfig): string`
Returns SVG data for a given ease.

### Properties
- **id** (string) - The ease identifier.
- **ease** (EaseFunction) - The easing function.
- **data** (string | number[]) - The raw data.
- **segment** (number[]) - Internal segment data.

### Errors
Throws `"Invalid CustomEase"` (string) when the data cannot be parsed.

### Example
```js
import CustomEase from "gsap/CustomEase";
gsap.registerPlugin(CustomEase);

CustomEase.create("myEase", "M0,0 C0.1,0.9 0.9,1 1,1");
gsap.to(el, { x: 100, ease: "myEase" });

try {
  new CustomEase("bad", "not-a-path");
} catch (e) {
  console.warn(e); // "Invalid CustomEase"
}
```
```

--------------------------------

### VelocityTracker usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/physics-plugins.md

Example of importing and registering VelocityTracker, tracking the x and y properties, animating, and reading the velocity. The getVelocity method returns the last computed velocity in pixels per second.

```js
import { VelocityTracker } from "gsap/InertiaPlugin";
gsap.registerPlugin(VelocityTracker);

VelocityTracker.track(el, "x,y", "num");
gsap.to(el, { x: 300, duration: 2 });
console.log(VelocityTracker.getVelocity(el, "x")); // px/s
VelocityTracker.untrack(el, "x");
```

--------------------------------

### Basic and advanced CSSPlugin animation examples

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/css-plugin.md

Shows how to animate CSS properties with gsap.to. The first example uses x, yPercent, rotation, scale, transformOrigin, autoAlpha, and ease. The second demonstrates advanced options like width: 'auto', random colors, random x, borderRadius, modifiers, clearProps, and force3D.

```javascript
import gsap from "gsap";

gsap.to(".box", {
  x: 100, yPercent: 50, rotation: 45, scale: 1.5, transformOrigin: "center bottom",
  autoAlpha: 0.5, duration: 1, ease: "power1.inOut"
});

// advanced options
gsap.to(".box", {
  width: "auto",
  backgroundColor: "random([red, blue, green])",
  x: "random(0, 300, 10)",
  borderRadius: 20,
  modifiers: { x: gsap.utils.unitize(gsap.utils.wrap(0, 500), "px") },
  clearProps: "x", // remove inline x when done
  force3D: true
});
```

--------------------------------

### EasePack: TypeScript interfaces and usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/easing.md

TypeScript interfaces for EasePack, SlowMo, RoughEase, and ExpoScaleEase, followed by a JavaScript usage example. Importing EasePack registers the "slow", "expoScale", and "rough" ease-string names and adds weighted-ease .config() to all unconfigured eases. The example shows using the string forms and the RoughEase config method.

```ts
interface EasePack { SlowMo: gsap.SlowMo; ExpoScaleEase: gsap.ExpoScaleEase; RoughEase: gsap.RoughEase; }

interface SlowMoConfig extends EaseFunction {
  (linearRatio: number, power?: number, yoyoMode?: boolean): EaseFunction;
}
interface SlowMo extends EaseFunction { config: SlowMoConfig; ease: SlowMoEase; }

interface RoughEaseVars {
  clamp?: boolean; points?: number; randomize?: boolean;
  strength?: number; taper?: "in" | "out" | "both" | "none";
  template?: string | EaseFunction;
}
interface RoughEase extends EaseFunction { config: RoughEaseConfig; ease: RoughEaseEase; }

interface ExpoScaleEase {
  config(startingScale: number, endingScale: number, ease?: string | EaseFunction): EaseFunction;
}
```

```js
import { EasePack } from "gsap/EasePack";
gsap.registerPlugin(EasePack);
gsap.to(el, { x: 200, ease: "slow(0.7, 0.7)" });
gsap.to(el, { scale: 5, ease: "expoScale(1, 5, 'power2.inOut')" });
gsap.to(el, { x: 100, ease: RoughEase.ease.config({ points: 30, strength: 1, taper: "both" }) });
```

--------------------------------

### gsap.fromTo JavaScript example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Animates .card elements from x:-100 and opacity:0 to x:0 and opacity:1 over 0.8 seconds.

```javascript
gsap.fromTo(".card", { x: -100, opacity: 0 }, { x: 0, opacity: 1, duration: 0.8 });
```

--------------------------------

### CustomBounce

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/easing.md

Documentation for the CustomBounce class, including constructor, methods, properties, and usage example.

```APIDOC
## class CustomBounce

### Description
CustomBounce is a GSAP plugin that creates custom bounce easing functions with configurable strength and squash effects. It requires CustomEase to be registered.

### Constructor
`new CustomBounce(id: string, vars?: CustomBounceVars)`

### Parameters
- **id** (string) - Required - The unique identifier for the bounce ease.
- **vars** (CustomBounceVars) - Optional - Configuration object with properties:
  - `strength` (number) - Optional - Default `0.7`. Controls the bounce strength.
  - `endAtStart` (boolean) - Optional - If true, the bounce ends at the start.
  - `squash` (number) - Optional - Strength of the squash animation.
  - `squashID` (string) - Optional - ID for the squash ease.

### Methods

#### `static create(id: string, vars?: CustomBounceVars): EaseFunction`
Creates a new CustomBounce and returns an easing function.

#### `static register(core: object): void`
Registers the plugin with GSAP.

### Properties
- **ease** (EaseFunction) - The easing function.

### Example
```js
import CustomBounce from "gsap/CustomBounce";
gsap.registerPlugin(CustomBounce);
CustomBounce.create("myBounce", { strength: 0.8, squash: 0.4, squashID: "myBounceSquash" });
gsap.fromTo(".ball", { y: 0 }, { y: 300, ease: "myBounce", transformOrigin: "center bottom" });
gsap.fromTo(".ball", { scaleY: 1 }, { scaleY: 0.3, ease: "myBounceSquash" });
```
```

--------------------------------

### gsap.exportRoot() usage

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Example of calling gsap.exportRoot() with options to enable smooth child timing and include delayed calls.

```js
const tl = gsap.exportRoot({ smoothChildTiming: true }, true);
```

--------------------------------

### Flip.batch

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/flip.md

Gets or creates a named `FlipBatch` for coordinating multiple independent flips.

```APIDOC
## Flip.batch

### Description
Gets or creates a named `FlipBatch` for coordinating multiple independent flips.

### Method
Static method

### Signature
`batch(id?: string): FlipBatch`

### Parameters
- **id** (string) - Optional - The batch identifier. Defaults to `"default"`.

### Returns
- **FlipBatch** - The batch instance.
```

--------------------------------

### gsap.timeline JavaScript example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Creates a timeline with default duration 0.5 and repeat 1, then chains .to tweens with a -0.2 offset.

```javascript
const tl = gsap.timeline({ defaults: { duration: 0.5 }, repeat: 1 });
tl.to(".a", { x: 100 }).to(".b", { x: 100 }, "-=0.2");
```

--------------------------------

### gsap.quickTo JavaScript example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Creates a reusable function that tweens the x property of #ball. The returned function can be called with a value, and func.tween exposes the underlying tween.

```javascript
const xTo = gsap.quickTo("#ball", "x", { duration: 0.6, ease: "power3" });
button.addEventListener("click", e => xTo(e.clientX));
```

--------------------------------

### GSDevTools.create() usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gs-dev-tools.md

Shows how to import and register GSDevTools, create a timeline, and instantiate the dev tools with options like animation, container, keyboard, loop, inTime/outTime, persist, and css. Also demonstrates cleanup via GSDevTools.getById().kill().

```javascript
import GSDevTools from "gsap/GSDevTools";
gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline({ id: "intro" });
tl.to(".a", { x: 100 }).to(".b", { x: 100, duration: 0.5 }).addLabel("end");

const tools = GSDevTools.create({
  animation: tl,
  container: "#devtools",
  keyboard: true,
  loop: true,
  inTime: 0, outTime: "end",
  persist: false,
  css: { position: "fixed", bottom: 0 }
});

// error handling / cleanup
GSDevTools.getById("intro")?.kill();
```

--------------------------------

### gsap.from() Usage Example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Example of using gsap.from() to animate an element from specified values with stagger.

```javascript
gsap.from("#logo", { y: -40, autoAlpha: 0, stagger: 0.1 });
```

--------------------------------

### gsap.to() Usage Example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Example of using gsap.to() to animate an element with x, duration, ease, and onComplete callback.

```javascript
gsap.to(".box", { x: 100, duration: 1, ease: "power2.out", onComplete: () => console.log("done") });
```

--------------------------------

### gsap.quickSetter(targets, property, unit?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Documentation for the gsap.quickSetter method.

```APIDOC
## `gsap.quickSetter(targets, property, unit?)`

### Description
Returns a fast, reusable setter function that sets a property on the target(s). When multiple targets are provided, it returns a bulk setter that sets the property on all targets at once.

### Method
Function call

### Signature
`gsap.quickSetter(targets, property, unit?)`

### Parameters
- **targets** (TweenTarget) - Required - The target element(s) or object(s) to set the property on.
- **property** (string) - Required - The CSS property or transform property to set.
- **unit** (string) - Optional - The unit to append to the value (e.g., "px").

### Returns
- **Function** - A setter function that accepts a value and applies it to the target(s).

### Example
```js
const setOpacity = gsap.quickSetter("#el", "opacity");
setOpacity(0.5);
```
```

--------------------------------

### gsap.install

Source: https://github.com/greensock/gsap/blob/master/_autodocs/configuration.md

Copies GSAP globals onto a specified scope.

```APIDOC
## gsap.install

### Description
Copies GSAP globals onto another object or scope. This is useful for integrating GSAP into different environments or namespaces.

### Method
`gsap.install(scope)`

### Parameters
- **scope** (object) - Required - The object or scope onto which GSAP globals will be copied.

### Source
`src/gsap-core.js:3050`
```

--------------------------------

### wrapYoyo usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/utils.md

JavaScript example of wrapYoyo in curried form, showing ping-pong behavior with the expected output.

```javascript
const pingpong = gsap.utils.wrapYoyo(0, 100);
pingpong(120); // 80
```

--------------------------------

### PhysicsPropsPlugin type declarations and usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/physics-plugins.md

Type declarations and usage example for the physicsProps tween var. The type definitions show the expected shape of the values and vars. The usage example animates two properties with different velocities and accelerations/friction over a duration of 4 seconds.

```ts
declare namespace PhysicsPropsPlugin {
  interface Values { acceleration?: gsap.TweenValue; friction?: gsap.TweenValue; velocity?: gsap.TweenValue; }
  interface Vars { [key: string]: Values; }
}
interface TweenVars { physicsProps?: PhysicsPropsPlugin.Vars; }
```

```js
gsap.to(obj, {
  physicsProps: {
    value:  { velocity: 100, acceleration: 40 },
    wobble: { velocity: 200, friction: 0.1 }
  },
  duration: 4
});
```

--------------------------------

### Tween.invalidate(soft?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/animation.md

Instance method that clears PropTweens, forcing the tween to re-parse its start values. The soft parameter preserves from() start records.

```APIDOC
## Tween.invalidate(soft?)

### Description
Clears the tween's PropTweens, forcing it to re-parse its start values on the next render. This is useful when the target's properties change dynamically.

### Method
Instance method (override)

### Signature
`invalidate(soft?: boolean): this`

### Parameters
- **soft** (boolean) - Optional - If true, keeps the `from()` start records, allowing the tween to continue from its original start values.

### Returns
- **this** - The Tween instance for chaining.

### Example
```js
const tw = gsap.to(el, { x: 100 });
tw.invalidate();
```
```

--------------------------------

### Timeline creation and manipulation example (JavaScript)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/animation.md

Demonstrates building a timeline with defaults, adding tweens, labels, a pause, a callback, and a fromTo tween using position syntax. Shows how to complete all children via getChildren and remove a label. Position strings like "mid", "+0.5", ">", and "<" are used.

```javascript
const tl = gsap.timeline({ defaults: { ease: "power2.out" } });
tl.to(".a", { x: 100 })
  .addLabel("mid")
  .to(".b", { x: 100 }, "mid")
  .addPause("+0.5")
  .call(log, ["reached"], ">")
  .fromTo(".c", { opacity: 0 }, { opacity: 1 }, "<");
tl.getChildren(true, true, true).forEach(c => c.progress(1)); // complete everything
tl.removeLabel("mid");
```

--------------------------------

### CustomWiggle: TypeScript interface and usage example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/easing.md

TypeScript interface and class definition for CustomWiggle, followed by a JavaScript usage example. Requires CustomEase to be registered. The example creates a custom ease named "wiggly" with random type, 8 wiggles, and power1.inOut amplitude, then applies it to a tween.

```ts
interface CustomWiggleVars {
  type?: "uniform" | "random" | "anticipate" | "easeOut" | "easeInOut";
  wiggles?: number;                       // default 10
  amplitudeEase?: string | EaseFunction;  // default "none"
  timingEase?: string | EaseFunction;     // default "none"
}
class CustomWiggle {
  ease: EaseFunction;
  constructor(id: string, vars?: CustomWiggleVars);
  static create(id: string, vars?: CustomWiggleVars): EaseFunction;
  static register(core: object): void;
}
```

```js
import CustomWiggle from "gsap/CustomWiggle";
gsap.registerPlugin(CustomWiggle);
CustomWiggle.create("wiggly", { type: "random", wiggles: 8, amplitudeEase: "power1.inOut" });
gsap.to(el, { x: 50, ease: "wiggly", duration: 2 });
```

--------------------------------

### EaselPlugin JavaScript Usage Example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/renderer-plugins.md

Shows how to import and register EaselPlugin, then tween a CreateJS Container with various properties including color filters and frame labels. Includes a guard for the missing createjs global.

```javascript
import EaselPlugin from "gsap/EaselPlugin";
gsap.registerPlugin(EaselPlugin);

const child = new createjs.Container();
gsap.to(child, {
  easel: { x: 200, rotation: 45, regX: 50, alpha: 0.5, saturation: 0, contrast: 1.2, frame: "labelName" },
  duration: 1, ease: "back.out"
});

// error handling: guard missing createjs global
if (typeof createjs === "undefined") {
  console.warn("CreateJS must be loaded before using EaselPlugin");
}
```

--------------------------------

### Flip.batch usage with add()

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/flip.md

Creates a Flip batch for the "app" element and adds a configuration object that captures state, loads state, mutates the DOM, animates with Flip.from, and handles entering elements. The batch runs when appBtn is clicked.

```javascript
const batch = Flip.batch("app");
batch.add({
  getState: self => Flip.getState("#list .item"),
  loadState: done => done(),          // e.g. wait for an image, then done()
  setState: () => app.classList.toggle("reverse"),   // DOM mutation
  animate: self => Flip.from(self.state, { ease: "power1.inOut", stagger: 0.05 }),
  onEnter: els => gsap.fromTo(els, { scale: 0 }, { scale: 1 }),
  once: false
});
appBtn.addEventListener("click", () => batch.run());
```

--------------------------------

### Create and control Draggable instances

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/draggable.md

Shows how to create a rotation draggable with bounds, inertia, and snapping, then create an x/y draggable, apply bounds, test overlap, force-end a drag, listen for dragend, and kill the instance.

```javascript
Draggable.create("#knob", {
  type: "rotation",
  bounds: { minRotation: 0, maxRotation: 270 },
  inertia: true, snap: { rotation: [0, 90, 180, 270] },
  onDrag: function () { gauge.textContent = Math.round(this.rotation) + "°"; }
});

const d = Draggable.create(".card", { type: "x,y", bounds: "#container" })[0];
d.applyBounds({ minX: 0, maxX: 500, minY: 0, maxY: 300 });
if (d.hitTest("#dropzone", 20)) { d.endDrag(d.pointerEvent); }

// error handling via events
d.addEventListener("dragend", () => console.log("released"));
d.kill();
```

--------------------------------

### FlipBatch Methods

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/flip.md

Documentation for the FlipBatch class methods, including add, clear, getState, getStateById, run, remove, and kill.

```APIDOC
## FlipBatch.add

### Description
Registers an action on the batch. The action can be a configuration object or a function.

### Method
add

### Signature
`(config: BatchActionConfig | Function): FlipBatchAction`

### Parameters
- **config** (BatchActionConfig | Function) - Required - The action configuration or function to register.

### Returns
- **FlipBatchAction** - The registered action.

## FlipBatch.clear

### Description
Removes all actions from the batch, or only the merged state if `stateOnly` is true.

### Method
clear

### Signature
`(stateOnly?: boolean): FlipBatch`

### Parameters
- **stateOnly** (boolean) - Optional - If true, only the merged state is removed.

### Returns
- **FlipBatch** - The batch instance for chaining.

## FlipBatch.getState

### Description
Runs all actions' `getState` methods and returns the batch.

### Method
getState

### Signature
`(merge?: boolean): FlipBatch`

### Parameters
- **merge** (boolean) - Optional - Whether to merge the states.

### Returns
- **FlipBatch** - The batch instance for chaining.

## FlipBatch.getStateById

### Description
Finds a sub-state by `data-flip-id`.

### Method
getStateById

### Signature
`(id: string): Flip.FlipState | null`

### Parameters
- **id** (string) - Required - The `data-flip-id` to search for.

### Returns
- **Flip.FlipState | null** - The found sub-state, or null if not found.

## FlipBatch.run

### Description
Executes the full sequence `getState() → loadState() → setState() → animate()` for all actions.

### Method
run

### Signature
`(skipGetState?: boolean, merge?: boolean): FlipBatch`

### Parameters
- **skipGetState** (boolean) - Optional - If true, skips the `getState` step.
- **merge** (boolean) - Optional - Whether to merge states.

### Returns
- **FlipBatch** - The batch instance for chaining.

## FlipBatch.remove

### Description
Removes a single action from the batch.

### Method
remove

### Signature
`(action: FlipBatchAction): FlipBatch`

### Parameters
- **action** (FlipBatchAction) - Required - The action to remove.

### Returns
- **FlipBatch** - The batch instance for chaining.

## FlipBatch.kill

### Description
Unregisters the batch and returns an action (typed as such).

### Method
kill

### Signature
`(): FlipBatchAction`

### Returns
- **FlipBatchAction** - An action (typed as such).
```

--------------------------------

### random() usage examples

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/utils.md

JavaScript examples for gsap.utils.random(). Shows generating a random number in a range, a multiple of 5, a function that returns a new random value each call, and a random element from an array.

```javascript
gsap.utils.random(-100, 100);            // number
gsap.utils.random(0, 500, 5);            // multiple of 5
const rand = gsap.utils.random(0, 500, 10, true);
rand();                                  // each call new value
gsap.utils.random(["red", "blue", "green"]);
```

--------------------------------

### Flip plugin usage: getState, from, fit, isFlipping

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/flip.md

Shows the core Flip workflow: register the plugin, capture state with getState, reorder the DOM, then animate with Flip.from. Also demonstrates Flip.fit to match one element to another and a guard using Flip.isFlipping to avoid overlapping flips.

```javascript
gsap.registerPlugin(Flip);

const state = Flip.getState(".cards", { props: "backgroundColor" });
// ... reorder/shuffle the DOM ...
Flip.from(state, { duration: 0.8, ease: "power1.inOut", stagger: 0.05, fade: true,
  onEnter: els => gsap.fromTo(els, { opacity: 0 }, { opacity: 1 }),
  onLeave: els => gsap.to(els, { opacity: 0 }) });

// fit one element exactly over another
Flip.fit("#from", "#to", { scale: true, absolute: true, duration: 1, ease: "power2" });

// error handling: isFlipping guard
if (!Flip.isFlipping("#card")) {
  Flip.from(state2, { duration: 0.5 });
}
```

--------------------------------

### new Observer(vars) / Observer.create(vars)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/observer.md

Creates a new Observer instance with the given configuration. The constructor is aliased to Observer.create.

```APIDOC
## new Observer(vars) / Observer.create(vars)

### Description
Creates a new Observer instance that normalizes scroll-like input (wheel, touch, pointer, scroll) into uniform delta and velocity values. The constructor is aliased to `Observer.create`.

### Method
Constructor

### Parameters
- `vars` (Observer.ObserverVars) - Required - Configuration object for the observer.

### Returns
- `Observer` - The newly created Observer instance.

### Example
```js
const observer = Observer.create({
  target: window,
  type: "wheel,touch,scroll",
  onChange: (self) => {
    console.log(self.deltaX, self.deltaY);
  }
});
```
```

--------------------------------

### SplitText Usage Example

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/text-plugins.md

Shows how to register the plugin, split an element into characters and words with masking, animate the characters, re-split into lines, revert, and kill the instance. Note that kill() is needed to stop autoSplit observers before unmounting.

```javascript
gsap.registerPlugin(SplitText);

const split = new SplitText("#headline", {
  type: "chars,words",
  charsClass: "char", wordsClass: "word",
  mask: "words",
  aria: "hidden"
});
gsap.from(split.chars, { yPercent: 120, opacity: 0, stagger: 0.02, duration: 0.6, ease: "back.out(1.7)" });

// re-split differently later
split.split({ type: "lines", linesClass: "line" });
split.revert(); // back to the original HTML

// error handling: kill autoSplit before unmount
split.kill();
```

--------------------------------

### ScrollTrigger.sort

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-trigger.md

Re-sorts triggers by refreshPriority or start.

```APIDOC
## ScrollTrigger.sort

### Description
Re-sorts triggers by refreshPriority or start.

### Method
sort

### Signature
`(func?: Function): ScrollTrigger[]`

### Parameters
- **func** (Function) - Optional - Custom sort function.

### Returns
- **ScrollTrigger[]** - The sorted triggers.
```

--------------------------------

### ScrollTrigger.getScrollFunc

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-trigger.md

Gets a scroller's position function.

```APIDOC
## ScrollTrigger.getScrollFunc

### Description
Gets a scroller's position function.

### Method
getScrollFunc

### Signature
`(element: gsap.DOMTarget | Window, horizontal?: boolean): ScrollTrigger.ScrollFunc`

### Parameters
- **element** (gsap.DOMTarget | Window) - Required - The scroller element.
- **horizontal** (boolean) - Optional - If true, returns horizontal scroll function.

### Returns
- **ScrollTrigger.ScrollFunc** - The scroll position function.
```

--------------------------------

### gsap.matchMedia(scope?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Creates a MatchMedia instance for conditional animations based on media queries.

```APIDOC
## `gsap.matchMedia(scope?): MatchMedia`

### Description
Creates a MatchMedia instance that conditionally runs animations based on media query conditions. The returned object provides methods to add conditions, revert all animations, and kill the instance.

### Method
`gsap.matchMedia(scope?)`

### Parameters
- **scope** (Element | string | object) - Optional - Scope for the matchMedia instance.

### Returns
- **MatchMedia** - An object with methods: `add`, `revert`, `kill`, and `contexts`.

### Example
```js
const mm = gsap.matchMedia();
mm.add("(min-width: 800px)", (context) => {
  gsap.to(".box", { x: 200 });
});
mm.revert(); // clean up
```

### MatchMedia Interface
```ts
interface MatchMedia {
    contexts: Context[];
    add(conditions: string | object, func: ContextFunc, scope?: Element | string | object): MatchMedia;
    revert(config?: object): void;
    kill(revert?: boolean): void;
}
```
```

--------------------------------

### ScrollTrigger.defaults

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-trigger.md

Sets or gets global defaults for ScrollTrigger.

```APIDOC
## ScrollTrigger.defaults

### Description
Sets or gets global defaults for ScrollTrigger.

### Method
defaults

### Signature
`(vars: StaticVars): StaticVars`

### Parameters
- **vars** (StaticVars) - Required - The default variables to set.

### Returns
- **StaticVars** - The current defaults.
```

--------------------------------

### gsap.matchMedia() usage

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Creates a MatchMedia instance, adds a condition for screens at least 800px wide, and reverts to clean up. The revert() call removes the added animations.

```js
const mm = gsap.matchMedia();
mm.add("(min-width: 800px)", (context) => {
  gsap.to(".box", { x: 200 });
});
mm.revert(); // clean up
```

--------------------------------

### gsap.ticker usage examples

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Example usage of the GSAP ticker: add a callback with once=false and prioritize=true, set lag smoothing with threshold 500 and adjusted lag 33, set fps to 60, and remove a callback. Defaults are _lagThreshold=500, _adjustedLag=33, and _gap=1000/240.

```javascript
gsap.ticker.add((time, deltaTime, frame) => { draw(time); }, false, true);
gsap.ticker.lagSmoothing(500, 33);
gsap.ticker.fps(60);
gsap.ticker.remove(myFn);
```

--------------------------------

### shiftChildren

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/animation.md

Shifts the start times of all children by the given amount.

```APIDOC
## `shiftChildren`

### Description
Shifts the start times of all children by the given amount.

### Method
`shiftChildren`

### Signature
`shiftChildren(amount: number, adjustLabels?: boolean, ignoreBeforeTime?: number): this`

### Parameters
- **amount** (number) - Required - The amount to shift the start times by.
- **adjustLabels** (boolean) - Optional - If true, also shifts labels.
- **ignoreBeforeTime** (number) - Optional - Only shift children that start at or after this time.

### Returns
`this` - The timeline instance for chaining.

### Example
```js
const tl = gsap.timeline();
tl.shiftChildren(1, true);
```
```

--------------------------------

### Using ScrollSmoother instance methods and instance replacement

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Demonstrates common instance methods: applying parallax effects, scrolling to a target, adjusting smoothing, pausing, reading and setting scroll position, getting velocity, and killing the instance. The second block shows that creating a new instance automatically kills the previous one.

```javascript
const smoother = ScrollSmoother.create({ wrapper: "#wrap", content: "#content", smooth: 1.5, effects: true });
smoother.effects(".parallax-el", { speed: (i, el) => 0.5 + i * 0.1 });
smoother.scrollTo("#section-3", true, "center center");
smoother.smooth(2);
smoother.paused(true);
const y = smoother.scrollTop();
smoother.scrollTop(0);
smoother.getVelocity();
smoother.kill(); // then ScrollSmoother.create() again if desired
```

```javascript
// error handling: creating a second instance kills the first
const a = ScrollSmoother.create({ wrapper: "#w1", content: "#c1" });
const b = ScrollSmoother.create({ wrapper: "#w2", content: "#c2" }); // a.kill() called internally
```

--------------------------------

### smoother.getVelocity()

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Instance method to get the current scroll velocity.

```APIDOC
## smoother.getVelocity()

### Description
Returns the vertical scroll velocity in pixels per second.

### Method
getVelocity

### Parameters
None.

### Response
Returns a number representing the scroll velocity in px/s.
```

--------------------------------

### smoother.smooth(value?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Instance method to get or set the smoothing duration.

```APIDOC
## smoother.smooth(value?)

### Description
Gets or sets the smoothing duration in seconds.

### Method
smooth

### Parameters
- **value** (number) - Optional - The smoothing duration in seconds.

### Response
- If called with a value, returns void.
- If called without arguments, returns the current smoothing duration as a number.
```

--------------------------------

### smoother.scrollTop(position?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Instance method to get or set the scroll position.

```APIDOC
## smoother.scrollTop(position?)

### Description
Gets or sets the scroll position immediately.

### Method
scrollTop

### Parameters
- **position** (number) - Optional - The scroll position to set.

### Response
- If called with a position, returns `this` for chaining.
- If called without arguments, returns the current scroll position as a number.
```

--------------------------------

### smoother.wrapper(element?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Instance method to get or set the wrapper element.

```APIDOC
## smoother.wrapper(element?)

### Description
Gets or sets the wrapper element (viewport) for the ScrollSmoother.

### Method
wrapper

### Parameters
- **element** (gsap.DOMTarget) - Optional - The wrapper element to set.

### Response
- If called with an element, returns `this` for chaining.
- If called without arguments, returns the current wrapper HTMLElement.
```

--------------------------------

### gsap.registerPlugin: Register plugins

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/gsap.md

Shows how to import and register plugins. Must be called before creating tweens that use those plugins.

```javascript
import ScrollTrigger from "gsap/ScrollTrigger";
import Flip from "gsap/Flip";
gsap.registerPlugin(ScrollTrigger, Flip);
```

--------------------------------

### FlipBatchAction

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/flip.md

Documentation for the FlipBatchAction class, including its methods and properties.

```APIDOC
## FlipBatchAction

### Description
Represents an action within a Flip batch, providing methods to query captured states and remove the action from the batch.

### Methods

#### getStateById
- **Signature**: `(id: string): Flip.FlipState | null`
- **Description**: Finds a state captured in this action by its ID.
- **Parameters**:
  - `id` (string) - Required - The ID of the state to find.
- **Returns**: `Flip.FlipState | null` - The matching state, or `null` if not found.

#### kill
- **Signature**: `(): FlipBatchAction`
- **Description**: Removes the action from the batch.
- **Returns**: `FlipBatchAction` - The action instance for chaining.

### Properties
- `batch` (FlipBatch) - Read-only - The batch this action belongs to.
- `state` - Read-only - The state associated with the action.
- `states` (Flip.FlipState[]) - Read-only - Array of states captured in this action.
- `timeline` (gsap.core.Timeline) - Read-only - The timeline for the action.
- `targets` - Read-only - The targets of the action.
- `vars` (BatchActionConfig) - Read-only - Configuration variables for the action.

### Example
```js
const batch = Flip.batch("app");
batch.add({
  getState: self => Flip.getState("#list .item"),
  loadState: done => done(),          // e.g. wait for an image, then done()
  setState: () => app.classList.toggle("reverse"),   // DOM mutation
  animate: self => Flip.from(self.state, { ease: "power1.inOut", stagger: 0.05 }),
  onEnter: els => gsap.fromTo(els, { scale: 0 }, { scale: 1 }),
  once: false
});
appBtn.addEventListener("click", () => batch.run());
```
```

--------------------------------

### smoother.content(element?)

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/scroll-smoother.md

Instance method to get or set the content element.

```APIDOC
## smoother.content(element?)

### Description
Gets or sets the content element for the ScrollSmoother.

### Method
content

### Parameters
- **element** (gsap.DOMTarget) - Optional - The content element to set.

### Response
- If called with an element, returns `this` for chaining.
- If called without arguments, returns the current content HTMLElement.
```

--------------------------------

### Observer.scrollY

Source: https://github.com/greensock/gsap/blob/master/_autodocs/api-reference/observer.md

Gets or sets the vertical scroll position (scrollTop) of the target.

```APIDOC
## Observer.scrollY

### Description
Gets or sets the vertical scroll position (scrollTop) of the target.

### Method
scrollY

### Signature
`scrollY(): number` / `scrollY(position: number): void`

### Parameters
- **position** (number) - Optional - The new vertical scroll position.

### Returns
- **number** - When called with no arguments, returns the current vertical scroll position.
- **void** - When called with a position argument, sets the scroll position.
```
Tokens:
Raw