@zilahir/gsap-tools
v1.0.14
Published
A simple tool to debug GSAP animations
Downloads
5
Maintainers
Readme
GsapTools
A simple tool to debug GSAP animations
Managing and debugging Tween and Timeline in GSAP is a hassle, even with the official dev tools. So we created GsapTools, a tool for React1, that makes it all so much easier. Scroll down to know more and go take a look at the website.
—
1. GsapTools only works with React for the moment, but we plan to make it works on other popular front-end library in the future.
Installation
yarn add gsap-tools
Features
- Play/pause
- Loop
- Rewind
- In/out markers
- Timescale
- Draggable UI
- Updated animations
- Timeline details
How to use it
First, add GsapTools component globally to your application. You only need to do this once.
import GsapTools from 'gsap-tools';
<GsapTools />
Next, register your GSAP animation to be controlled with GsapTools.
Define an id on the Timeline constructor or on the Tween vars object, call the add function to register the timeline, and create a reference to the add function to remove it when the component is unmounted.
import { add } from 'gsap-tools';
componentDidMount() {
this.t = new TimelineLite({ id: 'myTimeline' });
this.disposer = add(this.t);
}
componentWillUnmount() {
this.disposer();
}
That’s the simpler version. Here is an alternative setup.
import { add } from 'gsap-tools';
/*
* With Timeline
*/
componentDidMount() {
// You can define an id on the Timeline's constructor
this.timeline = new TimelineLite({ id: 'myTimeline' });
// Or you can also define an id on the add function itself
this.disposer = add(this.timeline, 'myTimeline');
// Or it will generate an id if you don't specify any
this.disposer = add(this.timeline);
}
componentWillUnmount() {
// Remove the Timeline by using the disposer reference
this.disposer();
}
/*
* With Tween
*/
componentDidMount() {
// You can define an id within the vars object
this.tween = TweenLite.to(this.el, 1, { x: 50, id: 'myTween' });
// Or you can define an id on the add function itself
this.disposer = add(this.tween, 'myTween');
// Or it will generate an id if you don't specify any
this.disposer = add(this.tween);
}
componentWillUnmount() {
// Remove the Tween by using the disposer reference
this.disposer();
}
Examples
- The GsapTools’ website use the tool itself, you can see it in action here: AppLayout.js and Hero.js.
- There is also more examples with Tween and Timeline also here.
Shortcuts
- space Play/pause
- L Toggle loop
- H Toggle UI
- E Expand Timeline
- R Reset in/out markers
- ← Rewind
- ↑ Speed up
- ↓ Slow down
References
<GsapTools />
component
isVisible (default = false) Show GsapTools by default. Or not. It’s a free country.
isFixed (default = true) With the draggable feature, GsapTools defaults to
position: fixed
on top of everything. But you can passfalse
to this prop to position the tool however you like.onClick (default = undefined) The tool comes with a built-in button to toggle the component. But if you decide to have your own button to handle this, just pass an
onClick
prop to the component and it will override the built-in function. This is useful if you have a whole dev tools package and already have a way to enable specific tools.
add()
function
Timeline/Tween (required) The first argument to pass is the animation object. It can be either Tween or Timeline instances.
id (optional) Instead of passing the id to the timeline method constructor you can pass it on the
add()
function itself.
But, why?
We ❤️ GSAP. We ❤️ it so much that we use GSAP for animations on almost all of our projects.
But one thing were struggling with for a long time was debugging big timelines. Most of the time we reload, reload, reload, reload, reload, reload, reload, reload. You get where this is going.
Recently GSAP introduced their dev tools. We tried them but found they didn’t really fit our needs: Setting the tools up with webpack, a real mess; when unmounting a component, removing its timeline after being registered is not possible; and finally, animations are only registered if they are played 2 seconds after the page is loaded, which is a problem if we have an animation playing based on user interaction, or when a waypoint is triggered.
That’s why we decided to make our own tool to address these issues.
You to the rescue
If you noticed any issues, have any ideas, or want to open pull requests, just do it. And if you want to know more about who we are and what we do, here’s a link for that.
Development
In source folder:
npm run watch
npm link
In project:
npm link gsap-tools