CSS Animation Worklet API

1. Introduction

This document introduces a new primitive that provides extensibility in web animations and enables high performance interactive procedural animations on the web. For details on the rationale and motivation see both [explainer] and [principles].

The Animation Worklet API provides a method to create scripted animations that control a set of animation effects. The API is designed to make it possible for user agents to run such animations in their own dedicated thread to provide a degree of performance isolation from main thread.

1.1. Relationship to the Web Animations API

Animations running inside an Animation Worklet execution context expose the Animation interface from the Web Animations specification on the main javascript execution context. This means they can be controlled and inspected from main thread using the same Web Animation APIs.

2. Animation Worklet

The animationWorklet's worklet global scope type is AnimationWorkletGlobalScope.

AnimationWorkletGlobalScope represents the global execution context of animationWorklet.

[Exposed=Window]
partial namespace CSS {
    [SameObject] readonly attribute Worklet animationWorklet;
};

3. Animator

An Animator represents an animation instance that is running on the animation thread. Animators are identified by a unique name and determine how the animation progresses its keyframe effects given current input time. Animator instances live in AnimationWorkletGlobalScope and each one is associated with a WorkletAnimation instance. An animator can only be instantiated by construction of a WorkletAnimation.

Two animators types are supported: StatelessAnimator and StatefulAnimator each providing a different state management strategy.

3.1. StatelessAnimator Interface

This interface represents a stateless animator. This type of animator does not depend on any local state either stored on the instance or global scope. Effectively, the animate function of an StatelessAnimator can be treated as a pure function with the expectation that given the same input, it produces the same output.

[Exposed=AnimationWorklet, Global=AnimationWorklet, Constructor (optional any options)]
interface StatelessAnimator {
};

class FooAnimator extends StatelessAnimator {
    constructor(options) {
        // Called when a new animator is instantiated.
    }
    animate(currentTime, effect) {
        // Animation frame logic goes here.
    }
}

Note: The statelessness allows an animation worklet to perform optimization such as producing multiple animation frames in parallel and performing very cheap teardown and setup. Using StatelessAnimator is highly recommended to enable such optimizations.

3.2. StatefulAnimator Interface

This interface represents a stateful animator. This animator can have local state and animation worklet guarantees that it maintains this state as long as the stateful animator fulfills the contract required by this interface as described following.

Animation worklet maintains a set of WorkletGlobalScopes which may exist across different threads or processes. Animation worklet may temporarily terminate a global scope (e.g., to preserve resources) or move a running animator instance across different global scopes (e.g., if its effect is mutable only in a certain thread). Animation worklet guarantees that a stateful animator instance’s state is maintained even if the instance is respawned in a different global scope.

The basic mechanism for maintaining the state is that the animation worklet snapshots the local state that is exposed via the state function and then reifies it so that it can be passed into the constructor when the animator instance is respawned at a later time in a potentially different global scope. The migrate an animator instance algorithm specifies this process in details.

A user-defined stateful animator is expected to fulfill the required contract which is that its state function returns an object representing its state that can be serialized using structured serialized algorithm and that it can also recreate its state given that same object passed to its constructor.

[Exposed=AnimationWorklet, Global=AnimationWorklet,
Constructor (optional any options, optional any state)]
interface StatefulAnimator {
  any state();
};

class BarAnimator extends StatefulAnimator {
    constructor(options, state) {
      // Called when a new animator is instantiated (either first time or after being respawned).
      this.currentVelocity  = state ? state.velocity : 0;
    }
    animate(currentTime, effect) {
        // Animation frame logic goes here and can rely on this.currentVelocity.
        this.currentVelocity += 0.1;
    }
    state() {
      // The returned object should be serializable using structured clonable algorithm.
      return {
        velocity: this.currentVelocity;
      }
    }
}

3.3. Animator Definition

An animator definition is a struct which describes the author defined custom animation as needed by AnimationWorkletGlobalScope. It consists of:

• An animator name <ident>#.

• A class constructor which is a AnimatorInstanceConstructor callback function type.

• An animate function which is a Function callback function type.

• A stateful flag

3.4. Registering an Animator Definition

[ Exposed=AnimationWorklet, Global=AnimationWorklet ]
interface AnimationWorkletGlobalScope : WorkletGlobalScope {
    void registerAnimator(DOMString name, AnimatorInstanceConstructor animatorCtor);
};

callback AnimatorInstanceConstructor = any (any options, optional any state);

4. Animator Instance

An animator instance is a struct which describes a fully realized custom animation instance in an AnimationWorkletGlobalScope. It has a reference to an animator definition and owns the instance specific state such as animation effect and timeline. It consists of:

• An animator name.

• An animation requested flag.

• An animator effect which is an animation effect.

• An animator current time which is the corresponding worklet animation’s current time.

• An animator timeline which is a timeline.

• An animator serialized options which is a serializable object.

A stateful animator instance is an animator instance whose corresponding animator definition’s stateful flag is true.

4.1. Creating an Animator Instance

Each animator instance lives in an AnimationWorkletGlobalScope.

Each AnimationWorkletGlobalScope has an animator instance set. The set is populated when the user agent constructs a new animator instance in the AnimationWorkletGlobalScope scope. Each animator instance corresponds to a worklet animation in the document scope.

4.2. Running Animators

When the user agent wants to produce a new animation frame, if for any animator instance the associated animation requested flag is frame-requested then the the user agent must run animators for the current frame.

Note: The user agent is not required to run animations on every visual frame. It is legal to defer generating an animation frame until a later frame. This allow the user agent to provide a different service level according to their policy.

should be explicit as to what happens if the animateFunction throws an exception. At least we should have wording that the localTime values of the keyframes are ignored to avoid incorrect partial updates.

4.3. Removing an Animator Instance

4.4. Migrating an Animator Instance

The migration process allows stateful animator instance to be migrated to a different WorkletGlobalScope without losing their local state.

If an animator state getter throws the user agent will remove the animator but does not recreate it. This effectively removes the animator instance.

4.5. Requesting Animation Frames

Each animator instance has an associated animation requested flag. It must be either frame-requested or frame-current. It is initially set to frame-current. Different circumstances can cause the animation requested flag to be set to frame-requested. These include the following:

• Changes in the current time of the animator’s timeline

• Changes in the current time of the animator’s corresponding Worklet Animation

§4.2 Running Animators resets the animation requested flag on animators to frame-current.

5. Web Animations Integration

5.1. Worklet Animation

Being an animation, worklet animation has an animation effect and a timeline. However unlike other animations the worklet animation’s current time does not directly determine the animation effect’s local time (via its inherited time). Instead the associated animator instance controls the animation effect’s local time directly. Note that this means that the timeline’s current time does not fully determine the animation’s output.

Worklet animation has the following properties in addition to the Animation interface:

• an animation animator name which identifies its animator definition.

• a serialized options which is serializable object that is used when constructing a new animator instance.

5.2. Creating a Worklet Animation

[Exposed=Window,
 Constructor (DOMString animatorName,
              optional (AnimationEffect or sequence<AnimationEffect>)? effects = null,
              optional AnimationTimeline? timeline,
              optional any options)]
interface WorkletAnimation : Animation {
        readonly attribute DOMString animatorName;
};

5.3. Worklet Animation timing model

This section describes how worklet animation’s timing model differs from other animations.

In addition to the existing conditions on when the animation is considered ready, a worklet animation is only considered ready when the following condition is also true:

• the user agent has completed any setup required to create the worklet animation’s corresponding animator instance.

As described in §5.1 Worklet Animation, the worklet animation’s current time does not determine its animation effect’s local time. Instead the associated animator instance controls the animation effect’s local time directly. This means that the animation effect’s local time is controlled from a WorkletGlobalScope which may be in a parallel execution context.

Here are a few implications of the above semantics:

• Setting the current time or start time of a worklet animation does not necessarily change its output, but may change the animation play state.

• Similarly, invoking finish() or updating a worklet animation’s playback rate will only change the animation play state and may not change the output.

• Querying the animation effect’s local time using getComputedTiming() may return stale information, in the case where the animator instance is running in a parallel execution context.

If a Worklet Animation animation is executing in a parallel worklet execution context, the last known state of its animation effects should be periodically synced back to the main javascript execution context. The synchronization of effect values from the parallel worklet execution context to the main javascript execution context must occur before running the animation frame callbacks as part of the document lifecycle. Note that due to the asynchronous nature of this animation model a script running in the main javascript execution context may see a stale value when reading a target property that is being animated by a Worklet Animation, compared to the value currently being used to produce the visual frame that is visible to the user. This is similar to the effect of asynchronous scrolling when reading scroll offsets in the main javascript execution context.

Come with appropriate mechanism’s for animator instance to get notified when its animation currentTime is changing e.g., via reverse(), finish() or playbackRate change. So that it can react appropriately. <https://github.com/w3c/css-houdini-drafts/issues/811>

5.4. Interaction with Animator Instances

A worklet animation corresponds to at most one animator instance at any time, and may have no current corresponding animator instance. The correspondance of an animator instance for a worklet animation depends on the animation play state.

When a given workletAnimation’s play state changes to pending, running, or paused, run the procedure to associate animator instance of worklet animation given workletAnimation.

When a given workletAnimation’s play state changes to idle or finished, run the procedure to disassociate animator instance of worklet animation given workletAnimation.

When the procedure to set the target effect of an animation for a given workletAnimation is called, then set animator instance of worklet animation given workletAnimation.

When the procedure to set the timeline of an animation for a given workletAnimation is called, then set animator instance of worklet animation given workletAnimation.

5.5. ScrollTimeline

ScrollTimeline is a new concept being proposed for addition to web animation API. It defines an animation timeline whose time value depends on the scroll position of a scroll container. Worklet animations can have a scroll timeline and thus drive their scripted effects based on a scroll offset.

Note: Access to input: We are interested on exposing additional user input beside scrolling (e.g., touch/pointer input) to these animations so that authors can create jank-free input driven animations which are not really possible today. We are still trying to figure out the right abstractions and mechanisms to do this.

5.6. WorkletGroupEffect

WorkletGroupEffect is a type of group effect that allows its child effect’s local times to be mutated individually.

When a WorkletGroupEffect is set as the animation effect of a WorkletAnimation, the corresponding animator instance can directly control the child effects' local times. This allows a single worklet animation to coordinate multiple effects - see §8.2 Example 2: Parallax backgrounds. for an example of such a use-case.

[Exposed=AnimationWorklet]
interface WorkletGroupEffect {
  sequence<AnimationEffect> getChildren();
};

[Exposed=AnimationWorklet]
partial interface AnimationEffect {
    // Intended for use inside Animation Worklet scope to drive the effect.
    attribute double localTime;
};

The above interface exposes a conservative subset of GroupEffect proposed as part of web-animation-2. We should instead move this into a delta spec against the web-animation. <https://github.com/w3c/csswg-drafts/issues/2071>

5.7. Effect Stack and Composite Order

As with other animations, worklet animations participate in the effect stack. A worklet animation does not have a specific animation class which means it has the same composite order as other Javascript created web animations.

6. Security Considerations

There are no known security issues introduced by these features.

7. Privacy Considerations

There are no known privacy issues introduced by these features.

8. Examples

8.1. Example 1: Twitter header.

// In document scope.
<div id='scrollingContainer'>
  <div id='header' style='height: 150px'></div>
  <div id='avatar'><img></div>
</div>

<script>
await CSS.animationWorklet.addModule('twitter-header-animator.js');
const animation = new WorkletAnimation(
    'twitter-header',
    [new KeyframeEffect($avatar,  /* scales down as we scroll up */
                    [{transform: 'scale(1)'}, {transform: 'scale(0.5)'}],
                    {duration: 1000, iterations: 1}),
    new KeyframeEffect($header, /* loses transparency as we scroll up */
                    [{opacity: 0}, {opacity: 0.8}],
                    {duration: 1000, iterations: 1})],
    new ScrollTimeline({
      scrollSource: $scrollingContainer,
      orientation: 'block',
      timeRange: 1000,
      startScrollOffset: 0,
      endScrollOffset: $header.clientHeight}));
animation.play();

// Since this animation is using a group effect, the same animation instance
// is accessible via different handles: $avatarEl.getAnimations()[0], $headerEl.getAnimations()[0]

</script>

// Inside AnimationWorkletGlobalScope.
registerAnimator('twitter-header', class HeaderAnimator extends StatelessAnimator {
  constructor(options) {
    this.timing_ = new CubicBezier('ease-out');
  }

  animate(currentTime, effect) {
    const scroll = currentTime;  // scroll is in [0, 1000] range

    // Drive the output group effect by setting its children local times individually.
    effect.children[0].localTime = scroll;
    effect.children[1].localTime = this.timing_(clamp(scroll, 0, 500));
  }
});

function clamp(value, min, max) {
  return Math.min(Math.max(value, min), max);
}

8.2. Example 2: Parallax backgrounds.

<style>
.parallax {
    position: fixed;
    top: 0;
    left: 0;
    opacity: 0.5;
}
</style>
<div id='scrollingContainer'>
  <div id="slow" class="parallax"></div>
  <div id="fast" class="parallax"></div>
</div>

<script>
await CSS.animationWorklet.addModule('parallax-animator.js');
const scrollTimeline = new ScrollTimeline({
  scrollSource: $scrollingContainer,
  orientation: 'block',
  timeRange: 1000
});
const scrollRange = $scrollingContainer.scrollHeight - $scrollingContainer.clientHeight;

const slowParallax = new WorkletAnimation(
    'parallax',
    new KeyframeEffect($parallax_slow, [{'transform': 'translateY(0)'}, {'transform': 'translateY(' + -scrollRange + 'px)'}], {duration: 1000}),
    scrollTimeline,
    {rate : 0.4}
);
slowParallax.play();

const fastParallax = new WorkletAnimation(
    'parallax',
    new KeyframeEffect($parallax_fast, [{'transform': 'translateY(0)'}, {'transform': 'translateY(' + -scrollRange + 'px)'}], {duration: 1000}),
    scrollTimeline,
    {rate : 0.8}
);
fastParallax.play();
</script>

// Inside AnimationWorkletGlobalScope.
registerAnimator('parallax', class ParallaxAnimator extends StatelessAnimator {
  constructor(options) {
    this.rate_ = options.rate;
  }

  animate(currentTime, effect) {
    effect.localTime = currentTime * this.rate_;
  }
});