Animation API

The CSS Animation Worklet API, or more succinctly, the Animation API, gives us the ability to drive KeyframeEffect Animations based on user input, like scrolling, in a standard, non-blocking way!

• Listen for user input, like scroll events!
• Animate elements based on that user input
• Do it all of the main thread!
• Animation API: Make Parallax Perform

Animation API Worklet

The Animation API works a little different than both the Paint API and the Layout API in that it isn't a "set it and forget it" worklet, but rather it gets loaded and then used by creating a new WorkletAnimation which consists of the name of the registered worklet to use, the KeyframeEffect to apply, at least one timeline to base the animation on (like the new ScrollTimeline), and options to pass in to the worklet's constructor.

Worklet Overview

// https://wicg.github.io/animation-worklet/ August 13, 2018 Draft Community Group Report

registerAnimator('sample-animator', class {
  constructor(options) {
    // Called when a new animator is instantiated
    // Used to set stuff up for each use of an animator
  }
  animate(currentTime, effect) {
    // currentTime - The current time from the defined timeline
    // effect - Group of effects that this animation is working on

    // Animation frame logic goes here.
    // Usually something to the effect of setting the time of an effect
    effect.localTime = currentTime;
  }
});

Register and Use Worklet from Main JavaScript

await CSS.animationWorklet.addModule('path/to/animation-worklet.js');

// Element we want to animate
const elem = document.querySelector('#my-elem');
// The element we want to watch the scrolling on
const scrollSource = document.scrollingElement;
// Number of steps our animation will be broken up in to
const timeRange = 1000;
 // A new ScrollTimeline to use! Listen to scroll on the `scrollSource`, divide everything in to `timeRage` pieces, optionally start at `startScrollOffset` and end at `endScrollOffset`
const scrollTimeline = new ScrollTimeline({
  scrollSource,
  timeRange,
});

const effectKeyframes = new KeyframeEffect(
  elem,
  // The Keyframe animation effects we want to apply
  [
    {transform: 'scale(1)'},
    {transform: 'scale(.25)'},
    {transform: 'scale(1)'}
  ],
  {
    // The duration of the effect. If set to `timeRange` it will be a 1:1 movement with the scroll of the element, 0-`timeRange` will be faster, >`timeRage` will be slower, and 0 will be off
    duration: timeRange,
  },
);

// Create a new WorkletAnimation
new WorkletAnimation(
  // Name of the Animation Worklet to use
  'sample-animator',
  // Effect(s) to use. Can be an array of KeyframeEffects
  effectKeyframes,
  // Timeline to use for the Worklet
  scrollTimeline,
  // Options to pass in to Animation Worklet constructor
  {},
).play(); // Make It So

Today, the Animation API will only animate fast properties (like opacity and transform) and only items that can be composited (so no direct SVGs)

Play with the Animation API

Now it's your turn! Below are two examples of the Animation API in action, each showcasing something a little different, for you to see and play with! The Parallax example shows just that! A simple parallax-in-action, almost identical to what powers the landscape in the header. The Twitter example is a lovingly re-skinned version of Surma's fantastic Twitter Header from the Google Chrome Labs Houdini Samples

Each one of these examples are fully editable, and you'll see the changes live as you type! You can change the Worklet code, the userland JavaScript, the CSS, and the HTML. Worklets get added automagically, and the userland JavaScript runs after its loaded.

You're preloaded with the Parallax example. Use the other buttons to switch examples. The Custom button will give you a blank Animation API worklet scaffolding to start from for you to experiment from scratch! Copy the URL once you've started making a Custom example to get back to your work later!