🇺🇸English
GSAP Plugins
When to Use This Skill
Apply when using or reviewing code that uses GSAP plugins: registering plugins, scroll-to, flip/FLIP animations, draggable elements, SVG (DrawSVG, MorphSVG, MotionPath), text (SplitText, ScrambleText), physics, easing plugins (CustomEase, EasePack, CustomWiggle, CustomBounce), or GSDevTools. ScrollTrigger has its own skill (gsap-scrolltrigger).
Related skills: For core tweens use gsap-core ; for ScrollTrigger use gsap-scrolltrigger ; for React use gsap-react.
Registering Plugins
Register each plugin once so GSAP (and bundlers) know to include it. Use gsap.registerPlugin() with every plugin used in the project:
import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";
gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
- ✅ Register before using the plugin in any tween or API call.
- ✅ In React, register at top level or once in the app (e.g. before first useGSAP); do not register inside a component that re-renders. useGSAP is a plugin that needs to be registered before use.
Scroll
ScrollToPlugin
Animates scroll position (window or a scrollable element). Use for “scroll to element” or “scroll to position” without ScrollTrigger.
gsap.registerPlugin(ScrollToPlugin);
gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
ScrollToPlugin — key config (scrollTo object):
| Option | Description |
|---|
x, y | Target scroll position (number), or "max" for maximum |
element | Selector or element to scroll to (for scroll-into-view) |
offsetX, offsetY | Offset in pixels from the target position |
ScrollSmoother
Smooth scroll wrapper (smooths native scroll). Requires ScrollTrigger and a specific DOM structure (content wrapper + smooth wrapper). Use when smooth, momentum-style scroll is needed. See GSAP docs for setup; register after ScrollTrigger. DOM structure would look like:
<body>
<div id="smooth-wrapper">
<div id="smooth-content">
<!--- ALL YOUR CONTENT HERE --->
</div>
</div>
<!-- position: fixed elements can go outside --->
</body>
DOM / UI
Flip
Capture state with Flip.getState(), then apply changes (e.g. layout or class changes), then use Flip.from() to animate from the previous state to the new state (FLIP: First, Last, Invert, Play). Use when animating between two layout states (lists, grids, expanded/collapsed).
gsap.registerPlugin(Flip);
const state = Flip.getState(".item");
// change DOM (reorder, add/remove, change classes)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
Flip — key config (Flip.from vars):
| Option | Description |
|---|
absolute | Use position: absolute during the flip (default: false) |
nested | When true, only the first level of children is measured (better for nested transforms) |
scale | When true, scale elements to fit (avoids stretch); default true |
simple | When true, only position/scale are animated (faster, less accurate) |
More information
https://gsap.com/docs/v3/Plugins/Flip
Draggable
Makes elements draggable, spinnable, or throwable with mouse/touch. Use for sliders, cards, reorderable lists, or any drag interaction.
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });
Draggable — key config options:
| Option | Description |
|---|
type | "x", "y", "x,y", "rotation", "scroll" |
bounds | Element, selector, or { minX, maxX, minY, maxY } to constrain drag |
inertia |
Inertia (InertiaPlugin)
Works with Draggable for momentum after release, or track the inertia/velocity of any property of any object so that it can then seamlessly glide to a stop using a simple tween. Register with Draggable when using inertia: true:
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });
Or track velocity of a property:
InertiaPlugin.track(".box", "x");
Then use "auto" to continue the current velocity and glide to a stop:
gsap.to(obj, { inertia: { x: "auto" } });
Observer
Normalizes pointer and scroll input across devices. Use for swipe, scroll direction, or custom gesture logic without tying directly to scroll position like ScrollTrigger.
gsap.registerPlugin(Observer);
Observer.create({
target: "#area",
onUp: () => {},
onDown: () => {},
onLeft: () => {},
onRight: () => {},
tolerance: 10
});
Observer — key config options:
| Option | Description |
|---|
target | Element or selector to observe |
onUp, onDown, onLeft, onRight | Callbacks when swipe/scroll passes tolerance in that direction |
tolerance | Pixels before direction is detected; default 10 |
type | "touch", , or (default: ) |
Text
SplitText
Splits an element’s text into characters, words, and/or lines (each in its own element) for staggered or per-unit animation. Use when animating text character-by-character, word-by-word, or line-by-line. Returns an instance with chars , words , lines (and masks when mask is set). Restore original markup with revert() or let gsap.context() revert. Integrates with gsap.context() , matchMedia() , and useGSAP(). API: SplitText.create(target, vars) (target = selector, element, or array).
gsap.registerPlugin(SplitText);
const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// later: split.revert() or let gsap.context() cleanup revert
With onSplit() (v3.13.0+), animations run on each split and on re-split when autoSplit is used; returning a tween/timeline from onSplit() lets SplitText clean up and sync progress on re-split:
SplitText.create(".split", {
type: "lines",
autoSplit: true,
onSplit(self) {
return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
}
});
SplitText — key config (SplitText.create vars):
| Option | Description |
|---|
| type | Comma-separated: "chars", "words", "lines". Default "chars,words,lines". Only split what is needed (e.g. "words, chars" if not using lines) for performance. Avoid chars-only without words/lines or use smartWrap: true to prevent odd line breaks. |
| charsClass , wordsClass , linesClass | CSS class on each split element. Append "++" to add an incremented class (e.g. linesClass: "line++" → , , …). |
Tips: Split only what is animated (e.g. skip chars if only animating words). For custom fonts, split after they load (e.g. document.fonts.ready.then(...)) or use autoSplit: true with onSplit(). To avoid kerning shift when splitting chars, use CSS font-kerning: none; text-rendering: optimizeSpeed;. Avoid text-wrap: balance; it can interfere with splitting. SplitText does not support SVG <text>.
Learn more: SplitText
ScrambleText
Animates text with a scramble/glitch effect. Use when revealing or transitioning text with a scramble.
gsap.registerPlugin(ScrambleTextPlugin);
gsap.to(".text", {
duration: 1,
scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});
SVG
DrawSVG (DrawSVGPlugin)
Reveals or hides the stroke of SVG elements by animating stroke-dashoffset / stroke-dasharray. Works on <path>, <line>, <polyline>, <polygon>, <rect>, <ellipse>. Use when “drawing” or “erasing” strokes.
drawSVG value: Describes the visible segment of the stroke along the path (start and end positions), not “animate from A to B over time.” Format: "start end" in percent or length. Examples: "0% 100%" = full stroke; "20% 80%" = stroke only between 20% and 80% (gaps at both ends). The tween animates from the element’s current segment to the target segment — e.g. gsap.to("#path", { drawSVG: "0% 100%" }) goes from whatever it is now to full stroke. Single value (e.g. 0, "100%") means start is 0: "100%" is equivalent to "0% 100%".
Required: The element must have a visible stroke — set stroke and stroke-width in CSS or as SVG attributes; otherwise nothing is drawn.
gsap.registerPlugin(DrawSVGPlugin);
// draw from nothing to full stroke
gsap.from("#path", { duration: 1, drawSVG: 0 });
// or explicit segment: from 0–0 to 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// stroke only in the middle (gaps at ends)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
Caveats: Only affects stroke (not fill). Prefer single-segment <path> elements; multi-segment paths can render oddly in some browsers. Contents of <use> cannot be visually changed. DrawSVGPlugin.getLength(element) and DrawSVGPlugin.getPosition(element) return stroke length and current position.
Learn more: DrawSVG
MorphSVG (MorphSVGPlugin)
Morphs one SVG shape into another by animating the d attribute (path data). Start and end shapes do not need the same number of points — MorphSVG converts to cubic beziers and adds points as needed. Use for icon-to-icon morphs, shape transitions, or path-based animations. Works on <path>, <polyline>, and <polygon>; <circle>, <rect>, <ellipse>, and <line> are converted internally or via MorphSVGPlugin.convertToPath(selector | element) (replaces the element in the DOM with a <path>).
morphSVG value: Can be a selector (e.g. "#lightning"), an element , raw path data (e.g. "M47.1,0.8 73.3,0.8..."), or for polygon/polyline a points string (e.g. "240,220 240,70 70,70 70,220"). For full config use the object form with shape as the only required property.
gsap.registerPlugin(MorphSVGPlugin);
// convert primitives to path first if needed:
MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");
gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
// object form:
gsap.to("#diamond", {
duration: 1,
morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
});
MorphSVG — key config (morphSVG object):
| Option | Description |
|---|
| shape | (Required.) Target shape: selector, element, or raw path string. |
| type | "linear" (default) or "rotational". Rotational uses angle/length interpolation and can avoid kinks mid-morph; try it when linear looks wrong. |
| map | How segments are matched: "size" (default), "position", or "complexity". Use when start/end segments don’t line up; if none work, split into multiple paths and morph each. |
| shapeIndex | Offsets which point in the start path maps to the first point in the end path (avoids shape “crossing over” or inverting). Number for single-segment paths; for multi-segment (e.g. ). Negative reverses that segment. Use once to log the auto-calculated value, then paste the number/array into the tween. (separate utility) provides an interactive UI to find a good value. Only applies to closed paths. |
Utilities: MorphSVGPlugin.convertToPath(selector | element) converts circle/rect/ellipse/line/polygon/polyline to <path> in the DOM. MorphSVGPlugin.rawPathToString(rawPath) and stringToRawPath(d) convert between path strings and raw arrays. The plugin stores the original d on the target (e.g. for tweening back: morphSVG: "#originalId" or the same element).
Tips: For twisted or inverted morphs, set shapeIndex (use "log" or findShapeIndex()). For multi-segment paths, shapeIndex is an array (one value per segment). Precompile only when the first frame is slow; it does not fix jank during the tween (simplify the SVG or reduce size if needed).
Learn more: MorphSVG
MotionPath (MotionPathPlugin)
Animates an element along an SVG path. Use when moving an object along a path (e.g. a curve or custom route).
gsap.registerPlugin(MotionPathPlugin);
gsap.to(".dot", {
duration: 2,
motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] }
});
MotionPath — key config (motionPath object):
| Option | Description |
|---|
path | SVG path element, selector, or path data string |
align | Path element or selector to align the target to |
alignOrigin | [x, y] origin (0–1); default [0.5, 0.5] |
autoRotate | Rotate element to follow path tangent |
curviness |
MotionPathHelper
Visual editor for MotionPath (alignment, offset). Use during development to tune path alignment.
gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);
const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
// adjust in UI, then use helper.path or helper.getProgress() in your animation
Easing
CustomEase
Custom easing curves (cubic-bezier or SVG path). Use when a built-in ease is not enough. Basic usage is covered in gsap-core; register when using:
gsap.registerPlugin(CustomEase);
const ease = CustomEase.create("name", ".17,.67,.83,.67");
gsap.to(".el", { x: 100, ease: ease, duration: 1 });
EasePack
Adds more named eases (e.g. SlowMo, RoughEase, ExpoScaleEase). Register and use the ease names in tweens.
CustomWiggle
Wiggle/shake easing. Use when a value should “wiggle” (multiple oscillations).
CustomBounce
Bounce-style easing with configurable strength.
Physics
Physics2D (Physics2DPlugin)
2D physics (velocity, angle, gravity). Use when animating with simple physics (e.g. projectiles, bouncing).
gsap.registerPlugin(Physics2DPlugin);
gsap.to(".ball", {
duration: 2,
physics2D: {
velocity: 250,
angle: 80,
gravity: 500
}
});
PhysicsProps (PhysicsPropsPlugin)
Applies physics to property values. Use for physics-driven property animation.
gsap.registerPlugin(PhysicsPropsPlugin);
gsap.to(".obj", {
duration: 2,
physicsProps: {
x: { velocity: 100, end: 300 },
y: { velocity: -50, acceleration: 200 }
}
});
Development
GSDevTools
UI for scrubbing timelines, toggling animations, and debugging. Use during development only; do not ship. Register and create an instance with a timeline reference.
gsap.registerPlugin(GSDevTools);
GSDevTools.create({ animation: tl });
Other
Pixi (PixiPlugin)
Integrates GSAP with PixiJS for animating Pixi display objects. Register when animating Pixi objects with GSAP.
gsap.registerPlugin(PixiPlugin);
const sprite = new PIXI.Sprite(texture);
gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });
Best practices
- ✅ Register every plugin used with gsap.registerPlugin() before first use.
- ✅ Use Flip.getState() → DOM change → Flip.from() for layout transitions; use Draggable + InertiaPlugin for drag with momentum.
- ✅ Revert plugin instances (e.g.
SplitTextInstance.revert()) when components unmount or elements are removed.
Do Not
- ❌ Use a plugin in a tween or API without registering it first (gsap.registerPlugin()).
- ❌ Ship GSDevTools or development-only plugins to production.
Learn More
https://gsap.com/docs/v3/Plugins/
Weekly Installs
917
Repository
greensock/gsap-skills
GitHub Stars
1.5K
First Seen
4 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex909
opencode908
cursor908
kimi-cli907
gemini-cli907
github-copilot907
