📐Web player API

  1. Setup
  2. Shorthand
  3. Create
  4. Load
  5. GSAP Plugins
  6. Construct
  7. Access
  8. Events


Spirit web player uses GSAP for constructing the timelines. Use setup() to tell the web player where it can find GSAP.

You need to do this once during the start of your application.

spirit.setup(gsapInstance: gsap): Promise<void>;

Fetch GSAP from CDN

If called without arguments, it tries to fetch GSAP from CDN:

setup().then(() => {
  // gsap is fetched and loaded from CDN

By default GSAP is fetched from unpkg, however you can customize the CDN url. More on customizing the CDN url

Use (bundled) GSAP instance

If GSAP is already loaded or bundled in your app i.e. Webpack, Rollup, Parcel, etc, you can pass down the GSAP instance directly and prevent fetching it from CDN:

import gsap from 'gsap'
import spirit from 'spiritjs'

spirit.setup(gsap).then(() => {
  // spirit is now ready and uses the
  // provided gsap instance to create the timelines

No need to wait till the Promise has resolved, passing down the GSAP instance sets the value and resolves immediately. This is also valid:

// set

// use

Load and play APIs

There are multiple ways of using the web player.



The shorthand syntax is the most simple one to use, thefore it's also the recommended way. It automatically fetches GSAP from CDN (if you haven't already configured it) and create/load the animation for you. Once loaded, the animation starts playing immediately (you can config this to your needs).

spirit.loadAnimation({ path: './my-animation.json' });

More on using the Shorthand API



Parse the RAW animation data and turn it into runnable Spirit data that can be used to generate GSAP timelines. This is a slightly more advanced usage.

spirit.create(animationData, container);

More on using the Create API



Load the animation data via url (using XHR) and parses the data internally via create().

spirit.load(path, container);

More on using the Load API

Which one to pick?

Your go-to method should be the shorthand spirit.loadAnimation(). This covers most scenarios and the playback options are easy to configure. Use create() or load() if you need more control (setting up GSAP, constructing timelines, etc).

GSAP Plugins

GSAP Plugins

You can use any GSAP plugin for your animations. Don't forget to register them on your web page before using it in Spirit Studio.

gsap.registerPlugin(MorphSVGPlugin, DrawSVGPlugin);

More on using GSAP Plugins with Spirit



The web player turns animation data into parsed timeline data ready to be constructed for animation.


// load multiple groups
spirit.loadAnimation({ path: './animation.json' }).then(({ logo, card }) => {
  // we have 2 Spirit.Group objects.
  // at this point the elements are not animated yet,

  // let's construct the GSAP timelines
  const logoTimeline = logo.construct();
  const cardTimeline = card.construct();


More on Timeline Construction



By default, the spirit instance is globally available on the window scope. Once an animation is created, it can be accessed via spirit.groups API.

You can always remove it with delete window.spirit

More on accessing animations



The Spirit web player dispatches events that you can listen to. Do note that you probably won't need these, but it's good to know that there are events you can listen to and tap-in for custom logic.

More on listening to events

  • Spirit
  • Support
  • Terms