Spirit App: Easy Realtime Animation For the Web

Full timeline control, import & export JSON, inspect animations, intuitive interface, live editing, easy to understand  API, aimed at speed, and realtime feedback: all the things you could ever want in a graphical user interface when creating and managing web animations. In this article we’ll take a look at the newest tool available for web animators called Spirit by Patrick Brouwer. We’ll learn how it can change the way you create animations on the web. Let’s animate!

Spirit App: Easy Realtime Animation For the Web

Getting Up and Running

Spirit is a three part recipe, requiring:

  1. A desktop app (the timeline).
  2. A runtime (JavaScript file).
  3. A browser extension that allows you to connect to any web page by communicating between the app and the runtime.

The desktop app is a GUI (graphical user interface) for creating and managing your animations, while the browser extension creates the connection between its corresponding desktop app and your web page.

Spirit App: Easy Realtime Animation For the Web

The app is currently available for Mac, but will be available for Windows and Linux in the very near future. Spirit’s browser extension is strictly Chrome at this time, but compatible extensions for other major browsers (Firefox, Opera and Safari) are under development.

When each component required is in place you can begin your animation development. Open the app, navigate to the desired web page URL using your browser, enable the extension and start animating!

Tips for Developing Locally

If you’d like to animate a web page from your local file system, make sure to toggle the checkbox Allow access to file URLs in your chrome extension settings.

Spirit App: Easy Realtime Animation For the Web

It’s recommended you add a data-spirit-id to each element you’d like to animate when developing locally.

<!--first group-->
<div data-spirit-id="foo">…</div>

<!--second group-->
<ul data-spirit-id="bar">…</ul>

This makes it easier to use the GUI for editing an element’s timeline and also makes it easier for the runtime to select your targets without using element-based CSS selectors (e.g. body > div > div > ul).

The Runtime Player

Spirit uses what’s called the “runtime (player)’. If the web page you’re visiting has no Spirit runtime, the browser extension will auto inject a temporary runtime for you. Runtime is just a JavaScript file (~10kb), so anytime you hear the term “runtime” say to yourself “JavaScript file”.

<script src="spirit.js"></script>

Runtime enables you to play the animations directly on your web page and leverages the power of GSAP for all its animation playback. That means you can use GSAP-specific properties as well as plugins like drawSVG or morphSVG, along with other animating strategies still under development (WAAPI).

The runtime is available through Open Source should you desire to donate your time to help maintain or enhance it. If you prefer to install the runtime player as an NPM package you can type the install command npm install spiritjs --save from your terminal, or you can give Yarn a try using their install command yarn add spiritjs.

The Timeline Inspector

Spirit App: Easy Realtime Animation For the Web

Are you a web animator looking for a timeline that’s easy to control, navigate and use?Spirit has your back, with an elegant and intuitive interface providing plenty of options to fine-tune your creations. The timeline can be scrubbed and keyframes added with ease. Sorting elements, however, is a feature awaiting to be implemented. If you’re developing in real-time, elements can be added or removed as needed. When your work is finished, click the back button, export the JSON file containing your progress, and load using the Spirit runtime API when desired.

Spirit App: Easy Realtime Animation For the Web

Each keyframe can be fine-tuned with regards to timing and easing. Adding and removing them is also straightforward. Elements are listed vertically in the timeline inspector and each one has its own timeline.

The values for animating each property can be anything that the runtime accepts. It’s even possible to use JavaScript code as a passed value, producing elements that are dynamic and flexible using mouse events, scrolling and position detection to name just a few. Make sure to wrap your JavaScript logic for property values with curly braces like so { window.innerWidth - this.clientWidth }.

Spirit App: Easy Realtime Animation For the Web

Each element can have many different properties available to animate including specific SVG properties relating to stroke, fill, color, position and size. You can even select clip-paths, filters, box-shadow and z-index to animate. Custom properties can be added as well, if the default ones provided don’t fit your needs. Make sure custom properties passed in are aligned with CSS property names documented by W3C specifications.

Understanding “Groups”

An animation group is a collection of objects (HTML elements) you’d like to animate. Think of groups as being “components” where each one has the ability to be exported as JSON.

Spirit App: Easy Realtime Animation For the Web

You can create as many groups as you’d like and posses control over each one of them. Create new groups easily and add new elements by selecting each one directly from your webpage, or via the Elements panel in Chrome Devtools. When the captured element doesn’t have a data-spirit-id attribute the only reference it has is an XPath (relative to the selected root) so it’s best to create attribute references when production development calls.

var tl = new TimelineMax()

spirit.setup().then(() => {

    spirit.load('./my-animations.json').then(groups => {
		// construct all groups
		groups.construct();

		// control the firing sequence of each group using GSAP
		tl.add(groups.get('group-name'), 0).add(groups.get('group-anothergroupname'), '-=0.25').add(groups.get('group-yetanothergroupname'), '+=0.125')

	})

});

A group is really just a collection of GSAP timelines so if you’re already a user of GreenSock this will be a welcome addition to your workflow and tooling. Groups can’t be controlled at once using the desktop app (a future feature request), but the issue can be alleviated using Spirit’s advanced API as its runtime leverages the GSAP API for timeline instances reflected in the code above. You can also check out this demo created by Spirit’s maker, showcasing the use of a master timeline sequence with UI controls and multiple groups:

Spirit’s API

As I discussed in my prior explanation pertaining to groups, Spirit has an API for developers who require deeper control. There are two APIs provided; a simple API and an advanced API.

spirit.loadAnimation({
  container: element, // dom element that contains animation
  loop: true,
  yoyo: true,
  delay: 2
})

While the advanced API allows for extensive control, the simple API can cover tasks such as controlling playback through an array of options. You can even return values, load groups and add interactivity.

spirit.setup()

The advanced API is for all your extra needs outside the simple API. Before you can use the advanced API you’ll need to tell the runtime where it can find the GSAP Tween and Timeline instances. After the call to Spirit’s setup method is in place, the flood gates will open providing you the ability to do things such as timeline construction and referencing, interactivity, keyframe and property referencing and much more.

Parting Thoughts

Keeping things in sync is important, especially for Spirit to run effectively. The Spirit desktop application auto updates itself in the background, so you’ll always have the latest version installed and the newest features at your fingertips. By auto updating the Spirit app, it’s easier to iterate and implement new features along the way. Chrome extensions are also updated in the background. Every few hours, the browser checks whether any installed extensions or apps have an update URL. For each one, it makes a request to that URL looking for an updated manifest XML file.

Spirit App: Easy Realtime Animation For the Web

Go to chrome://extensions and tick the Developer mode checkbox at the top right, then press the Update extensions now button. By ensuring this setup is in place Spirit can operate without leading to unexpected behavior as new features and updated data are added.

If you’d like to keep tabs on new features and progress with Spirit you can sign up for their newsletter here as well as following progress on Twitter. Spirit is definitely the tool that will change the way you create animations for the web.

Useful Links