# 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.

```javascript
// 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:

```javascript
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).

```javascript
// 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]]