Animation Worklet API (Houdini)
The Animation Worklet API is part of the CSS Houdini project. It allows developers to write imperative animations that run on the compositor thread, ensuring they are smooth (jank-free) even if the main thread is busy.
Note: This API is experimental and currently has limited browser support (primarily Chromium-based behind flags).
1. The Problem: Main Thread Jank
Traditional JavaScript animations (using requestAnimationFrame) run on the main thread. If the main thread is blocked by heavy JavaScript execution (e.g., parsing data, complex logic), the animation will stutter or freeze.
CSS Animations and Transitions run on the compositor thread, which is separate and smooth, but they are declarative and limited in logic.
2. The Solution: Animation Worklet
The Animation Worklet API combines the best of both worlds:
- Performance: Runs on a separate thread (like CSS animations).
- Control: Allows imperative logic (like JavaScript animations).
- Stateful: Can maintain state and react to scroll or time.
3. Defining an Animator
You create a separate JavaScript file (e.g., animator.js) and define a class with an animate() method.
// animator.js
registerAnimator('scroll-animator', class {
animate(currentTime, effect) {
// currentTime: The current time of the animation (or scroll offset)
// effect: The animation effect (allows setting local time)
// Example: Map scroll time directly to animation progress
effect.localTime = currentTime;
}
});4. Registering the Worklet
In your main JavaScript file:
if ('animationWorklet' in CSS) {
CSS.animationWorklet.addModule('animator.js');
}5. Using the Animator
You create a WorkletAnimation instance, passing the name of the registered animator, the effects to animate, and the timeline (e.g., a scroll timeline).
// Create a KeyframeEffect
const element = document.querySelector('.box');
const effect = new KeyframeEffect(
element,
[
{ transform: 'translateX(0)' },
{ transform: 'translateX(100px)' }
],
{ duration: 1000 }
);
// Create a ScrollTimeline (if supported) or use document.timeline
const timeline = new ScrollTimeline({
scrollSource: document.scrollingElement,
orientation: 'block'
});
// Create and play the WorkletAnimation
const animation = new WorkletAnimation(
'scroll-animator',
effect,
timeline,
{} // options
);
animation.play();6. Use Cases
- Scroll-linked Animations: Parallax effects, sticky headers that shrink, progress bars.
- Complex Timing: Animations that depend on complex logic not expressible in CSS keyframes.
- Stateful Animations: Animations that remember previous states (e.g., spring physics).
programming/javascript/vanilla/javascript programming/javascript/vanilla/web-animations-api programming/javascript/vanilla/css-houdini