Skip to main content

GSDevTools

Club GSAP plugin

Quick Start

Trial URL

GSDevTools is a Club GSAP perk, join today or grab this trial URL to take it for a spin for free.  Works on localhost, Codepen, CodeSandbox and Stackblitz.

gsap.registerPlugin(GSDevTools)

Minimal usage

GSDevTools.create();

Description​

GSDevTools gives you a visual UI for interacting with and debugging GSAP animations, complete with advanced playback controls, keyboard shortcuts, global synchronization and more. Jump to specific scenes, set in/out points, play in slow motion to reveal intricate details, and even switch to a "minimal" mode on small screens. GSDevTools makes building and reviewing GSAP animations simply delightful.

Get Started​

  1. Load the JavaScript file

    //be sure to use a path that works in your dev environment
    <script src="js/gsap/GSDevTools.min.js"></script>

  2. Create a GSDevTools instance

    GSDevTools.create();

That's it!

Though we suggest linking it to a particular animation instance because then GSDevTools doesn't need to worry all the global syncing of things. You can do that by setting the animation value of the dev tools instance:

var tl = gsap.timeline();
tl.to(...); // add your animations, etc.

// link it to this specific timeline:
GSDevTools.create({animation: tl});

The demo below shows GSDevTools running with its default settings. It automatically gives you control over every animation on the global timeline.

loading...

Select an animation by id​

Any GSAP animation (tween or timeline) can be assigned an id (a string) which causes it to show up in the animation menu. That makes it easy to jump to any scene. Notice how the timeline and each tween below have an id assigned:

//give the timeline and child tweens their own id.
var tl = gsap.timeline({ id: "timeline" });

tl.to(".orange", { duration: 1, x: 700, id: "orange" }).to(".green", {
  duration: 2,
  x: 700,
  ease: "bounce",
  id: "green",
}); //give this tween an id

gsap.to(".grey", { duration: 1, x: 700, rotation: 360, delay: 3, id: "grey" });

//instantiate GSDevTools with default settings
GSDevTools.create();

Now each id shows up in the animations menu (lower left).

loading...

Persistence between refreshes​

For added convenience, when you manually set the in/out points, animation, timeScale, or looping state in the UI, they persist between refreshes! This means you can drag the in/out points to isolate a particular section and then tweak the code, hit refresh, and see the changes immediately within that cropped area. Any values set in the GSDevTools.create({...}) method will override manual selections. Set persist: false to disable persistence. If you encounter persistence contamination (e.g. setting timeScale in one affects another), simply assign a unique id to the GSDevTools instance (the recorded values are segregated by id, session, and domain).

Configuration options​

GSDevTools can be configured extensively. Optionally define any of these properties in the config object:

    Property

    Description

  • animation

    [String | Animation] - If you define an animation, like animation: myTimeline, animation: myTween or animation: "id", that animation will be initially selected. By default, the global timeline is selected.

  • container

    [String | Element] - Specify the container element for GSDevTools, like: "#devTools" or document.getElementById ("devTools").

  • css

    [Object | String] - The CSS you want on the outer div, like {width: "50%", bottom: "30px"} or a string of CSS like "width: 50%; bottom: 30px".

  • globalSync

    Boolean - Animations can be kept in context and synchronized with the root timeline (scrubbing one scrubs them all). To enable this, set globalSync: true to hook it to the global timeline.

  • hideGlobalTimeline

    Boolean - If true, the Global Timeline will be removed from the animation menu.

  • id

    String - A unique string to identify the GSDevTools instance.

  • inTime

    [Number | String] - Position of the in marker (time, in seconds, or label or animation id).

  • keyboard

    Boolean - If true (the default), keyboard shortcuts will work. Note: Only one GSDevTools instance can listen for keyboard shortcuts.

  • loop

    Boolean - Initial loop state.

  • minimal

    Boolean - If true, the UI will only show minimal controls (scrubber, play/pause, and timeScale). Note: When the screen is less than 600px it automatically switches to minimal mode anyway.

  • outTime

    [Time | Label] - Position of the out marker (time, in seconds, or label, or animation id).

  • paused

    Boolean - Initial paused state.

  • persist

    Boolean - By default, GSDevTools remembers the in and out points, selected animation, timeScale, and looping state between refreshes in the same domain session, but you can disable that behavior by setting persist: false.

  • timeScale

    Number - Initial timeScale.

  • visibility

    String - "auto" causes the controls to automatically hide when you roll off of them for about 1 second, and return when you move your mouse over the area again.
info

Keyboard Controls​

  • SPACEBAR: play/pause
  • UP/DOWN ARROWS: increase/decrease timeScale
  • LEFT ARROW: rewind
  • RIGHT ARROW: jump to end
  • L: toggle loop
  • I: set the in point to current position of playhead
  • O: set the out point to current position of playhead
  • H: hide/show toggle

Tips and tricks​

  • It is almost always best to define an animation directly like GSDevTools.create({ animation: yourAnimation... }); so that it doesn't need to worry about mergine all the global animations in.

  • Clicking the GreenSock logo (bottom right) gets you right to the GreenSock docs!

  • Double-click on the in/out marker(s) to reset them both immediately.

  • If the playback UI is obscuring part of your animation, just tap the "H" key to hide it (and again to bring it back) - you can still use all the keyboard shortcuts even when it's invisible.

Advanced demos​

We purposefully chose very basic animations for the demos above, but here are a few that illustrate how easy GSDevTools makes it to control and debug even super-complex animation sequences.

loading...

loading...

caution

GSDevTools doesn't work with ScrollTrigger-driven animations because that would be logically impossible to have the scrollbar and the GSDevTools scrubber both control the same animation.

Methods​

GSDevTools.create( config:Object ) : GSDevTools

FAQ's​

Why is my Global Timeline 1000 seconds long?

That means you've probably got an infinitely repeating animation somewhere. GSDevTools caps its duration at 1000 seconds. Scrubbing to Infinity is awkward.

How do I kill/destroy/remove the dev tools instance?

If you have a reference to the dev tools (it's probably easiest to give the dev tools instance an id, i.e. 

GSDevTools.create({id:"main"})

then you can kill the instance by using

GSDevTools.getById("main").kill()

Why isn't GSDevTools in the CDN or GitHub repo?

Because it's a membership benefit of Club GSAP. It's a way for us to give back to those who support our ongoing development efforts. That's why we've been able to continue innovating for over a decade. See our "Why License?" article for details about our philosophy.

Does GSDevTools work with other animation libraries?

Nope, it depends on some unique capabilities baked into the GSAP architecture.

How do I include GSDevTools in my project?

See the installation page for all the options (CDN, NPM, download, etc.) where there's even an interactive helper that provides the necessary code. Easy peasy. Don't forget to register GSDevTools like this in your project:

gsap.registerPlugin(GSDevTools)

Is this included in the GSAP core?

No, you must load/import it separately

Is this only for Club GSAP members?

Yes. It's our way of saying "Thank you" to those who support our efforts. If you're not a member, what are you waiting for? Satisfaction is guaranteed or your money back. Take your animation skills to the next level. If you're already a member, you can download GSAP along with this and the other bonus plugins from your account dashboard. See the installation page for details about how to get it into your project via a <script> tag or NPM, Yarn, etc.

Can I try GSDevTools out for free?

You betcha! There's a trial (but fully-functional) version of GSDevTools that you can use on Codepen as much as you want for free. Get the URLs here. It's a fantastic way to experiment. Note: the trial version of the plugins will only work on the CodePen domain.

It works fine during development, but suddenly stops working in the production build! What do I do?

Your build tool is probably dropping the plugin when tree shaking and you forgot to register GSDevTools (which protects it from tree shaking). Just register the plugin like this:

gsap.registerPlugin(GSDevTools)

Is it bad to register a plugin multiple times?

No, it's perfectly fine. It doesn't help anything, nor does it hurt.

Contents