Modifiers
ModifiersPlugin is an internal plugin, It is automatically included in GSAP's core and doesn't have to be loaded using gsap.registerPlugin().
You can think of internal plugins as just a part of GSAP.
Description
You can define a "modifier" function for almost any property. This modifier intercepts the value that GSAP would normally apply on each update ("tick"), feeds it to your function as the first parameter and lets you run custom logic, returning a new value that GSAP should then apply. This is perfect for tasks like snapping, clamping, wrapping, or other dynamic effects.
value, target
The modifier functions are passed two parameters:
value
(number | string) - The about-to-be-applied value from the regular tween. This is often a number, but could be a string based on whatever the property requires. For example if you're animating thex
property, it would be a number, but if you're animating theleft
property it could be something like"212px"
, or for theboxShadow
property it could be"10px 5px 10px rgb(255,0,0)"
.target (object) - The target itself.
For example, change the x
of one object based on the y
of another object or change rotation
based on the direction
it is moving. Below are some examples that will help you get familiarized with the syntax.
Snap rotation
The tween below animates 360 degrees but the modifier function forces the value to jump to the closest 45-degree increment. Take note how the modifier function gets passed the value of the property that is being modified, in this case a rotation
number.
loading...
If snapping is all that you're wanting to do, we recommend using the SnapPlugin that is built into GSAP's core.
Clamp with Modulus
The tween below animates x
to 500 but the modifier function forces the value to wrap so that it's always between 0 and 100.
loading...
Here's the same sort of technique but using GSAP's wrap utility function:
loading...
Carousel Wrap
Have you ever built a carousel and wrestled with making it loop seamlessly? Perhaps you duplicated each asset or wrote some code that moved each item back to the beginning when it reached the end. With ModifiersPlugin you can get a seamless repeating carousel with a single .to()
with a stagger
! The example below tweens each box to a relative x
position of "+=500"
. Click the "show overflow" button to see each box get reset to x: 0
when it goes beyond 500.
loading...
Advanced demos
We've only scratched the surface of what ModifiersPlugin can do. Our moderator Blake Bowen has been putting this plugin to the test and has an impressive collection of demos that will surely inspire you.
Caveats:
To modify CSS transform's
scale
, usescaleX
andscaleY
(since it's a shortcut for those). And userotation
, notrotationZ
.RoundPropsPlugin and SnapPlugin tap into the same mechanism internally as ModifiersPlugin (to maximize efficiency, minimize memory, and keep kb down). Think of a
roundProps
tween as just a shortcut that creates a modifier that appliesMath.round()
, thus you cannot do bothroundProps
and a modifier on the same property. It's easy to get that functionality, though, by just doingMath.round()
inside the modifier function.
FAQs
How do I include this plugin in my project?
Simply load GSAP's core - ModifiersPlugin is included automatically!
Do I need to register ModifiersPlugin?
Nope. ModifiersPlugin and other core plugins are built into the core and don't have to be registered.