Spirit has been discontinued. Spirit is no longer available as a service and these docs are kept for reference only. Read more.

Timeline Construction

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

When using:

you'll receive a Spirit.Groups object containing the parsed animation timeline groups.

Spirit.Groups API

/**
 * Container element
 *
 * @type {HTMLElement|SVGElement}
 */
rootEl

/**
 * Add group data
 *
 * @param group {Spirit.Group}
 */
add(group: Spirit.Group);

/**
 * Remove group data
 *
 * @param group {Spirit.Group}
 */
remove(group: Spirit.Group);

/**
 * Construct all groups at once.
 *
 * @param resolve {boolean}
 * @returns {Array<gsap.Timeline>}
 */
construct(resolve = false);

/**
 * Get group by name
 *
 * @param name {string}
 * @returns {Spirit.Group}
 */
get(name: string): Spirit.Group;

// LIST

/**
 * The actual groups list
 *
 * @type {Array<Spirit.Group>}
 */
list: Array<Spirit.Group>;

/**
 * Get group at index
 *
 * @param index {number}
 * @returns {Spirit.Group}
 */
at(index: number): Spirit.Group;

/**
 * Clear all groups
 */
clear(): void;

/**
 * Iterate over groups
 *
 * @param cb {Function}
 */
each(cb: (group: Spirit.Group) => void): void;

You can access a single Spirit.Group using the following methods on the groups object:

groups.at(index), get a group at list index, groups.at(0)
groups.get(name), get a group by name, groups.get('logo')
groups.each(cb), iterate over all groups, groups.each(group => { ... })

Spirit.Group API

/**
 * The group timeline
 *
 * @type {gsap.timeline|null}
 */
timeline

/**
 * Internal list of timelines
 * for each element
 *
 * @type {List}
 */
timelines

/**
 * Playback speed
 *
 * Setting this value updates
 * the timeScale of the GSAP timeline
 *
 * @type {number}
 */
timeScale

/**
 * The total duration in seconds
 * Setting this value updates the duration
 * and timeScale of the GSAP timeline
 *
 * @type {number}
 */
duration

/**
 * Name of the group
 *
 * @type {string}
 */
name

/**
 * Get unresolved timelines
 *
 * @returns {Array<Spirit.Timeline>}
 */
unresolved

/**
 * Get resolved timelines
 *
 * @returns {Array<Spirit.Timeline>}
 */
resolved

/**
 * Kill GSAP timeline
 *
 * @type {() => void}
 */
reset()

/**
 * Resolve transformObjects for timelines
 * Updates accordingly:
 *   this.resolved
 *   this.unresolved
 *
 * @returns {Spirit.Group}
 */
resolve()

/**
* Convert to a readable and interchangeable
* javascript object
*
* @type    {Function}
* @returns {object}
*/
toObject()

/**
* Construct the GSAP timeline
*
* @type {Function}
*/
construct()

Example:

spirit.setup(gsap);

const groups = spirit.create({ ... }, container);
const timelines = spirit.each(group => group.construct());

Under the hood

When constructing a group group.construct(), this happens:

Clear previous timeline & tweens for elements
Clear GSAP cache for elements
Construct new timelines for elements
Returns the updated master timeline

Once a group is constructed you can use the GSAP Timeline API to control the animation.

Why constructing?

A single element can be used in multiple animation groups. You need to tell the web player which animation needs to be played. Generate a new GSAP timeline that can be played and controlled on demand.

Example:

index.html

<body>
  <div id="container">
    <h1 data-spirit-id="title">Title</h1>
  </div>

  <button id="btn-1">play animation 1</button>
  <button id="btn-2">play animation 2</button>

  ...
</body>

app.js

"animation.json" contains 2 animation groups both animating <h1 data-spirit-id="title">Title</h1>

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

const btn1 = document.getElementById('btn-1');
const btn2 = document.getElementById('btn-2');

spirit.setup(gsap);

spirit.loadAnimation({
  container: document.getElementById('container'),
  path: './animation.json'
}).then( ({ animation1, animation2 }) => {
  btn1.onclick = () => {
    animation1.construct().play();
  };
  btn2.onclick = () => {
    animation2.construct().play();
  };
});

Construct Event

On group construction the construct event is dispatched. Listen for construct events:

const group = spirit.groups.get('my-animation');

group.on('construct', timeline => {
  console.log('group is constructed => ', timeline);
});

group.construct();

Access

Initially, the group.timeline instance is null. Once the group is constructed, the GSAP timeline instance will be accessible via group.timeline.

Example:

console.log(group.timeline); // null

group.construct();

console.log(group.timeline); // gsap.timeline