gsap.registerEffect()
gsap.registerEffect is a GSAP core method that packages an animation into a named, reusable recipe you call as `gsap.effects.name(targets, config)`. You write the tween or timeline logic once, register it with default values, and every call site gets the same motion without copy-pasting the animation code.
Updated July 1, 2026
How gsap.registerEffect works
You register an effect once with a config object. name becomes the method on gsap.effects. effect is a function that receives (targets, config) and MUST return a GSAP animation (a tween or a timeline). defaults supplies the config values that fill in when a call site omits them. GSAP merges the call-site config over the defaults before handing it to your effect function.
Now the recipe is callable from anywhere. Pass only what you want to override; the rest comes from defaults.
extendTimeline: true also mounts the effect as a method on every timeline instance, so it slots into a sequence and honors the position parameter. For that to work your effect has to read config.duration, since the timeline needs to know how long the returned animation runs.
It returns a fresh animation each call
gsap.effects.name(...) call runs the effect function again and returns a new tween or timeline. That means the recipe reads the targets' current state at call time, so the same effect works on elements that mounted after registration.Use it for
- A motion you repeat across a codebase (card reveals, modal open/close, button press) that should stay identical everywhere
- Keeping one motion vocabulary across a team, so a design tweak to the reveal changes in one registration instead of 30 call sites
- Turning a house animation style into a named verb (
gsap.effects.reveal,gsap.effects.pop) that reads clearly at the call site - Sequencing a reusable step inside larger timelines via
extendTimeline: trueand the position parameter - Shipping a small animation preset as part of a shared library or design system
Why bother
registerEffect is how you keep that consistency mechanical instead of relying on everyone remembering the same magic numbers.Use something else when
- A motion only exists in one place, use a plain
gsap.to/gsap.from, registering an effect is overhead you won't reuse - You only need shared duration and ease defaults, not a whole recipe, use
gsap.defaults({ duration: 0.6, ease: "expo.out" }) - The animation is a fixed multi-step choreography, build a
gsap.timeline()and control it withplay/reverse, an effect returns a new instance each call so it's awkward to hold and scrub - You want a reusable custom easing curve, not a full animation, use
CustomEase.create()and reference the named ease - You're in React and the concern is cleanup on unmount, that's
useGSAP, effects anduseGSAPare complementary, not a substitute
Used in these Annnimate components
Each Annnimate component ships as a self-contained module, so most don't call registerEffect internally. The pattern is what you reach for when you pull that motion into your own project and want to reuse it, so it maps cleanly onto these two:
- The Text Reveal stagger is a natural effect to register once as
gsap.effects.textReveal, then fire on any headline withextendTimeline: trueinside a page-enter timeline - The Magnetic Button spring-back is the same tween every time the cursor leaves, exactly the kind of one-recipe-many-buttons motion
registerEffectis built for
Register once, at module load
gsap.registerEffect a single time when your animation code first loads, not inside a component render or an event handler. Re-registering the same name on every render just overwrites the entry and wastes work.See it running in production
Common questions
- Is gsap.registerEffect a paid or Club GSAP feature?
- No. It's part of the free GSAP core, no plugin needed. GSAP has been 100% free including all former Club plugins and commercial use since version 3.13 (Webflow made it free, fully live April 30 2025). Any tutorial that calls a GSAP feature Club-only is pre-3.13 and out of date.
- What's the difference between registerEffect and gsap.defaults?
gsap.defaults()sets fallback duration and ease for every tween in the project.registerEffectpackages a whole animation, the properties, the stagger, the structure, behind one named call. Use defaults for shared timing, use an effect when the reusable thing is the animation itself, not just its timing.- Does my effect have to return the animation?
- Yes. The
effectfunction must return a GSAP tween or timeline. GSAP uses that returned instance, and if you setextendTimeline: true, it reads the returned animation's duration so it can place the effect correctly on a parent timeline. Return nothing and the effect can't be sequenced. - How do I call an effect on a timeline with a position parameter?
- Set
extendTimeline: truewhen you register, then call the effect as a method on the timeline:tl.fadeUp(".el", { duration: 1 }, "-=0.3"). The third argument is the standard position parameter. Youreffectfunction has to honorconfig.durationfor the timeline to know the length. - Can I override just one config value at a call site?
- Yes. Pass only the keys you want to change and GSAP merges them over the registered
defaults.gsap.effects.fadeUp(".hero", { duration: 1 })keeps every other default and only swaps the duration.
