Simple API

Shorthand signature:

spirit.loadAnimation(data: object): Promise<Timeline|object>

Although the Extended API gives you more control, this shorthand notation will cover most animation playback scenarios.

You can call spirit.loadAnimation() to start an animation. It takes an object as an unique param with:

path: The url to animation json
animationData: Raw animation data (copied from app)
container: The dom element on which to render the animations, default: document.body
autoPlay: true/false it will start playing as soon as it's ready, default: true
loop: true/false/number, default: false
yoyo: true/false play animation back and forth, default: false
delay: number the repeat delay, default: 0
timeScale: number overwrite time scale of animations

It returns the animation Timeline instance you can control with play, pause, reverse, etc.


  container: element, // the dom element that will contain the animation
  loop: true,
  yoyo: true,
  delay: 2


Play animation data (copied from app):

  animationData: { ... }

Play animation from url:

  path: './animation.json'

Add playback features (like loop, yoyo, etc):

  loop: true,
  yoyo: true,
  delay: 1,
  path: 'animation.json'

GSAP's TimelineMax required for these features.

Return values

Load a single group


spirit.loadAnimation(data: object): Promise<Timeline>


spirit.loadAnimation({ autoPlay: false, path: 'single-group.json' }).then(timeline => {

The return type for a single group is the GSAP Timeline itself.

Load multiple groups


spirit.loadAnimation(data: object): Promise<Timeline[]>

example (with 2 groups: chair and table):

spirit.loadAnimation({ autoPlay: false, path: 'multiple-groups.json' }).then(
  ({ chair, table }) => {

The return type of multiple groups is an object indexed by group name. The chair and table are spirit Group objects.

Adding interactivity

Here's a little snippet to show you how you can easily add interactivity to your animations:

// assume group.json has 1 group in it. 
// (returns the timeline instance)
spirit.loadAnimation({ autoPlay: false, path: './group.json' })
  .then(timeline => {
    window.onmousemove = ({ clientX }) => {
      timeline.progress(clientX / window.innerWidth)

// assume groups.json has 2 groups. 
// (returns an indexed object)
spirit.loadAnimation({ autoPlay: false, path: './groups.json' })
  .then(({ chair, table }) => {
    document.querySelector('.button-1').onclick = () =>
    document.querySelector('.button-2').onclick = () => table.reverse().play(0)

Here's an example animation created by Timo Kuilder - Zwarte Koffie

Move mouse, works on touch devices as well

What happens in the background

To keep things as simple as possible, this shorthand notation executes some tasks chronologically in the background:

  • Load GSAP from CDN (once)
  • Cache the urls
  • Load/create the animation data
  • Construct the timelines based on strategy (default GSAP)
  • Playback the animation based on features
  • Returns the created timeline instances

results matching ""

    No results matching ""