Knowledge base
GSAP in Webflow
Verified, concept-indexed material on GSAP animation in Webflow, derived from 23 lessons and their cloneables; start with _agent-guide.md, then descend one level and open exactly one leaf page.
The knowledge base is published in English only.
Read _agent-guide.md first. It explains how to find a page without
loading the bundle, how to pitch an answer at the reader’s level, and the rules about
identifiers you must not break.
Then descend one level and open one leaf. Each section index lists only titles and one-line summaries, so navigating costs very little.
| Section | The question sounds like | Pages |
|---|---|---|
concepts/ | ”What is X?” · “What’s the difference between…“ | 6 |
recipes/ | ”How do I…” · “Build me a…“ | 20 |
pitfalls/ | ”Why is this broken?” · “Why does X flash/jump/fail?“ | 9 |
reference/ | ”What’s the exact attribute name?“ | 1 |
If you read only two pages
- The interactions model — trigger, target, action, timeline — trigger, target, action, timeline. Everything else assumes it.
- Verified identifiers — the exact names. Copy from there, never reconstruct.
Scope
GSAP animation in Webflow, derived from all 23 lessons across Mastering GSAP Interactions in Webflow and GSAP Animations & Integrations in Webflow — every one of them is cited by at least one page here, and every identifier is traced to the lesson’s cloneable.
Not covered: Webflow generally, accessibility as its own subject, third-party class systems, and anything outside GSAP.
Coverage inside that scope is complete, but it is not infinite: if a question has no page here, say so rather than extrapolating a confident answer from an adjacent page. A fabricated Webflow workflow is harder to debug than an admitted gap.
Concepts 6
- Scroll-driven animation — scrub versus trigger actions
Every scroll animation is one of two kinds: a scrub, where the playhead is tied continuously to scroll position, or trigger actions, where crossing a threshold fires an animation that then plays on its own clock; choosing wrong is the most common cause of a scroll effect that feels off, and the scaffold for a scrub is always a tall section with a sticky full-viewport window inside it.
- Split Text — turning one text element into many targets
Split Text breaks a single text element into words, lines or characters so each piece becomes its own animation target, which is what gives stagger something to spread across; the mask option wraps every piece in its own clipping container so it stays hidden until it moves into view.
- Stagger — spreading one animation across many targets
Stagger spreads a single animation across multiple targets, so it does nothing at all with one target; offset time sets a fixed gap between each target's start while total time is one budget divided across the intervals, and the stagger's own ease shapes the distribution of delays — a different job from the action's ease.
- Target filters — resolving a target relative to the trigger
An action's target is not one setting but three composed into a sentence — what to target, a filter, and the element the filter is measured against — so "the sidebar that is the previous sibling of the trigger" is Previous sibling of + Trigger element, not a single menu option; this is what lets one interaction serve every card in a CMS collection.
- The interactions model — trigger, target, action, timeline
A Webflow GSAP interaction is a trigger that fires one or more actions, each applied to a set of targets and laid out on a horizontal timeline; the action's type (to / from / from to) absorbs the initial state, so there is no separate initial-state step the way Classic Interactions had.
- Timeline control — control, speed, jump to, delay, repeat
One GSAP timeline can be driven by many events, and the event settings decide what each one does to it: control moves or holds the playhead, speed changes the rate without moving it, jump to repositions it, and repeat loops either the whole interaction or a single action — which are not the same thing.
Recipes 20
- Add a staggered reveal to any list with one attribute
Drop fc-gsap-staggered="list" on the div wrapping your items — or straight onto a Collection List — and the included script builds a staggered slide-and-fade with sensible defaults; every other option is a bare attribute you add only when you want tighter control over timing, motion or order.
- Build a cursor spotlight and an SVG prism hover
The spotlight is darkness with a hole in it — an oversized radial-gradient overlay moved by a mouse-move interaction — and the prism is an SVG filter that splits the image into R, G and B channels with zero offsets at rest, so a small GSAP timeline animating those offsets pulls the colours apart on hover and focus.
- Build a glass button that refracts the page behind it
A real SVG displacement-map filter wired to the button through backdrop-filter bends whatever scrolls underneath, and a tiny GSAP timeline hardens it from frosted glass to crisp ice on hover — but SVG filter references in backdrop-filter are Chromium-only, so Safari and Firefox visitors see the plain frosted base and none of the refraction.
- Build a light/dark theme toggle
Put every themed colour in a variable collection with a second manual variable mode, then the whole theme switch is a GSAP set action toggling one class on the html element; a theme-transition class added for 0.8s smooths the change without colliding with your other animations, and two small scripts make the choice survive a reload.
- Build a scroll-driven 3D cube gallery from CMS data
This is a build, not a snippet — the value is four ideas rather than a click path: scroll distance becomes animation time via a tall section and a sticky window, each cube face's transform lives in the CMS as numeric fields, the interaction is scrubbed rather than triggered, and real 3D needs perspective on the parent plus preserve-3d on the cube.
- Build a seamless infinite marquee
Duplicate the content into two identical trail groups side by side and animate them by -100% of their own width on an infinite linear loop, so the second group lands exactly where the first began and the reset is invisible; -100% rather than a measured width is what makes it work for any item count.
- Build a stack of draggable, throwable cards
GSAP's Draggable plugin powers a photo-stack you can grab, tilt and toss off-screen, driven entirely from Webflow settings by fc-draggable-card attributes; the two structural details that make it feel right are overflow hidden on the section and a pointer-events pairing that lets clicks reach the reset button once the deck is empty.
- Build an accessible dialog or slide-in panel
A dialog is one GSAP timeline played forward to open and reversed to close, plus four non-negotiable ARIA attributes, real button elements, an outside-click overlay stacked behind the panel, and a scroll lock — and it is not finished until focus is managed.
- Build animated hover buttons — and know when not to use GSAP
Five button effects share three reusable moves: an overflow-hidden wrapper masking a moving child, animating width from 0 to auto, and pushing an incoming overlay to -101%; the real lesson is the tool boundary — CSS for the element's own properties, GSAP the moment you must reach into a child.
- Cut letters out of a solid block with a normalised clip-path
This is a build, not a snippet — the transferable technique is cutting a shape out of a solid field with a CSS clip-path built as the negative around the letters in Figma, then normalising the exported path's absolute pixel coordinates into the 0–1 range that objectBoundingBox expects.
- Disintegrate an image into fragments on scroll
One attribute turns an image into a cloud of canvas fragments that scatter and fade as you scroll — the script snapshots the image with html2canvas, rebuilds it as fragments and animates them with ScrollTrigger; it needs a non-static position on the component and overflow hidden around it, and it is expensive enough that it belongs on a hero, not a grid.
- Draw a border on hover with a conic gradient
There is no border — a slightly larger wrapper behind the element leaves a visible ring, filled by a conic gradient whose fill percentage is registered with @property so it can actually transition; GSAP's only job is toggling one class on the hovered instance's wrapper.
- Grow CMS images from the centre and scatter them into a grid
An embed inside the collection item lets CSS read each item's own CMS order, compute how far it sits from the grid centre, and multiply that shift by a move-factor variable — so animating one variable from 1 to 0 releases every card from the centre into its real cell, with the scatter's start time derived arithmetically from the grow stagger.
- Lock page scroll while an overlay is open
Scroll locking in Webflow is a state change, not an animation, so it belongs in a GSAP set action at the start of the open timeline — either flipping body overflow to hidden via a custom selector, or toggling an overflow-hidden class when the close animation needs to finish first.
- Pin an element and shrink it into the corner on scroll
A picture-in-picture effect is a discrete state change, not a scrub — trigger actions with leave → play and enter back → reverse, a combo class carrying all three sticky properties, and one number variable multiplied into three calc-based transforms so a single animate-variable action drives the move and the scale together.
- Play an image sequence on a canvas as the page scrolls
The Apple-style scroll animation is ~150 stills swapped on a canvas — no video, no WebGL, no Lottie; the build splits into an asset pipeline (extract, compress, upload, then fetch the CDN URLs via the Webflow Data API because Webflow renames every file) and a runtime of two attributes on a tall section with a sticky container.
- Reveal a heading word by word or letter by letter on page load
Enable Split Text on the action so one heading becomes many targets, set the type to from with opacity 0 and move Y 100%, turn the mask on to match the split unit so each piece is clipped, and choose offset time for a fixed rhythm or total time to fit a slot on the timeline.
- Stagger a grid row by row as it scrolls into view
GSAP's own stagger cannot do this, so invert the responsibility — a set action adds an in-view class to each card as it enters the viewport, CSS transitions do the animation, and a per-card transition-delay computed from sibling-index() and a column-count variable produces a stagger that resets on every row and re-derives itself at every breakpoint.
- Switch between discrete states with jump to and pause
Treat the timeline as a set of states rather than something you play through — a zero-duration action per state at a fixed time, each trigger jumping the playhead to its own time with control play, and one catch-all event with control pause freezing it there; a CSS transition, not the timeline, does the smooth part.
- Trap keyboard focus inside an open panel
A GSAP interaction can animate a dialog but cannot manage focus, so a keyboard user Tabs straight out of it into the page behind; this script moves focus in on open, cycles Tab inside the panel, closes on Escape, and returns focus to the control that opened it.
Pitfalls 9
- A full-height overlay is cut off or jumps on mobile
vh is measured against the initial viewport and does not track the mobile browser's UI expanding and collapsing, so a 100vh fixed overlay is taller than the visible area and its bottom is unreachable; use 100dvh, which always matches the real visible height.
- A sticky element ends up in the wrong place after moving or scaling it
A translateY on an element that is also position sticky throws the final layout too low, because the transform moves the painted element without changing the space it reserves; compensate with a bottom margin equal to the scaled height and cancel the gap with a negative top margin on the element below.
- A style cleanup deletes the classes your interactions toggle
A class that exists only to be added by a GSAP set action is applied to no element, so Webflow flags it as unused and any style cleanup deletes it — publishing itself does not strip it, which means this breaks work that was already correct, later, when someone tidies the project; keep an element wearing the class so it is genuinely used and never appears in a cleanup list.
- A thin line or sliver appears at the edge of a moving element
Fractional device pixels mean an element parked at exactly -100% can leave a hairline of itself visible, and two perfectly aligned elements moving together can show an anti-aliasing seam between them; overshoot to -101% in the first case and pull a -1px margin in the second.
- Elements flash before a page-load animation starts
The flash is a one-frame timing gap where the browser paints elements in their final CSS state before GSAP applies the animation's initial values; fix it by hiding the wrapper from the page head, scoped to .w-mod-js so content stays visible when JavaScript is off. Webflow now prevents this automatically for Interactions with GSAP, so the manual fix is only needed for custom-code GSAP.
- It works in the Designer but not live — or the reverse
Custom code, non-standard CSS properties, first-paint flicker, scroll lock and keyboard focus all behave differently in the Designer and in plain preview than on the published site, and the Designer additionally shows you your animations' initial states, so half-hidden content while building is expected rather than broken.
- overflow hidden on the body — right for scroll lock, wrong for clipping
Overflow hidden on the body does exactly one thing — it disables scrolling for the whole page — so using it to crop something that spills sideways breaks the site to fix one section, while using it as an overlay's scroll lock is correct because there disabling scroll is the goal; clip at the container instead, and make sure every close path releases the lock.
- Reordering in the navigator doesn't change what's on top
An absolutely positioned element paints above a static sibling no matter where it sits in the DOM, so reordering does nothing; give the shared parent position: relative so both children keep z-index: auto, and then DOM order decides — the element that comes later renders on top.
- Webflow's native Button is wrong for animated controls
Webflow's native Button element renders as an anchor and cannot nest children, which makes it wrong twice over — semantically wrong for anything that performs an action rather than navigating, and structurally useless for the layered hover effects that need an icon or overlay inside.
Reference 1
- Verified identifiers
Every exact attribute name, class name, variable name, SVG id and selector used across the GSAP-in-Webflow corpus, each traced to the cloneable it was copied from; copy these verbatim and never reconstruct one from memory, because a wrong identifier fails silently.