Unlocking Dynamic Visuals: Animating Custom CSS Properties with Houdini Worklets

            
:root {
  --progress: 0;
}

@keyframes animate-progress {
  to {
    --progress: 100;
  }
}

.progress-bar {
  width: var(--progress)%; /* This doesn't animate smoothly in CSS alone */
}

            

              
                Copy
              
            
          

            
// progress-animation.js

// Define a class that extends AnimationWorklet
class ProgressAnimation {
  constructor(delay, end, easing) {
    this.delay = delay;
    this.end = end;
    this.easing = easing;
  }

  // The animate method is called by the browser for each frame
  animate(currentTime, playState) {
    // playState can be 'running', 'paused', 'finished', etc.
    if (playState !== 'running') {
      return playState;
    }

    // Calculate the progress based on time and easing
    // For simplicity, let's assume a linear ease for now
    // In a real scenario, you'd implement more sophisticated easing functions
    let progress = Math.min(currentTime / 1000, 1); // Assuming 1 second duration
    progress = Math.max(0, progress); // Clamp between 0 and 1

    // Apply easing (example: ease-in-out)
    progress = this.easing(progress);

    // Calculate the actual value based on the end value
    const currentValue = this.end * progress;

    // Return the current value for the custom property
    return currentValue;
  }
}

// Register the custom animation
CSS.registerAnimation({
  name: 'animateProgress',
  // We'll use a custom easing function, for example:
  // This is a simplified version of an ease-in-out function
  easingFunction: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
  // Define the duration of the animation. In a real scenario, this would be dynamic.
  // For this example, we'll hardcode it for simplicity, but it could be passed as a parameter.
  // Let's assume our animation worklet's animate method is designed to run for a 1-second duration.
  // The `end` value will be provided when the animation is applied.
  // The actual duration handled by the Worklet's `animate` method.
  // This `duration` in `registerAnimation` is more for CSS @keyframes.
  // For direct Worklet animation of custom properties, the `animate` method controls timing.
  // However, to integrate with CSS `animation` property, some duration concept is needed.
  // Let's consider the `animate` method handles timing, and we'll focus on that.
  // If we want to use this with CSS `animation` property like `animation: 1s ease-in-out my-animation;`,
  // we'd need to expose duration and easing to CSS as well.
  // For direct CSS custom property animation, we might use a different API or approach.
  // Let's refine this to directly animate a custom property value over time.
  // The `CSS.paintWorklet.addModule` or `CSS.animationWorklet.addModule` are used to load worklets.
  // For animating custom properties, we usually use the `animate()` method on an Animation object.

  // Let's reconsider the structure to align with animating custom properties.
  // The `AnimationWorklet` is used to create custom `KeyframeEffect` instances.
  // When we apply an animation to a custom property, we're essentially creating a sequence of values.
  // The Worklet's `animate` method is responsible for generating these values.

  // A more direct way to achieve custom property animation using Houdini is through the Animation API.
  // We can define a custom animation class that produces values for a custom property.

  // Let's simplify for clarity and focus on the core concept: driving custom property values.
  // We'll use a simple custom easing and an implicit duration handled by the browser's animation scheduler when linked to CSS.
  // The `animate` method in a `CSSAnimation` object (which we'd create from a Worklet) would receive time.
  // For simplicity, let's consider a simpler approach for demonstration that focuses on the `animate` method.

  // Rethinking the registration for custom property animation. The `CSS.registerAnimation` is for CSS @keyframes.
  // For directly animating custom properties, we often use the Animation API.
  // However, Worklets can define custom animation types. The `animation-timeline` property is also relevant.

  // Let's assume a scenario where we want to drive a custom property using the browser's animation timeline.
  // The `animate` method in a Worklet is indeed the place to define how values change over time.

  // Let's try a more concrete approach with the Animation API directly driving the custom property.
  // The `animation-worklet.js` approach is typically for registering custom animations for CSS `animation` property.
  // To animate custom properties, we often use JavaScript's Animation API.

  // The initial thought might be to register a custom animation to be used with `animation-name`.
  // However, for custom properties, we often want to directly control their values.
  // Houdini provides the Animation API for this:
  // const anim = new Animation(effect, timing); anim.play();
  // The `effect` can be a `KeyframeEffect` that targets a custom property.

  // Let's focus on the concept of a custom animation timeline or sequence.
  // The `AnimationWorklet` is designed to provide custom `KeyframeEffect` definitions or custom animation logic.
  // Consider this example is about creating a custom animation sequence that can be applied.

  // The `CSS.registerAnimation` is indeed for custom keyframe-based animations that can be applied via `animation-name`.
  // When using a custom property like `--progress`, we'd want its value to be interpolated.
  // The `animate` method in the Worklet should return the value for the property.

  // Let's create a simple Worklet that can be used to drive a custom property.
  // The core idea is the `animate` function signature: `animate(currentTime, playState)`.

  // Correct approach for registering a custom animation sequence:
  // The `animate` method needs to be part of a structure that the Animation API understands.
  // A common pattern is to create an object that the Animation API can consume.

  // Let's assume `CSS.animationWorklet.addModule()` is used to load this.
  // The `animate` method itself is what will generate the interpolated values.

  // For animating custom properties, the `Animation` API is key. Let's illustrate how a custom animation *generator* might work.
  // The `CSS.registerAnimation` is for CSS-level animations.
  // For JavaScript-driven custom property animation, the `Animation` API is more direct.

  // Let's pivot to a clearer example focusing on the Animation API.
  // We'll simulate a custom animation logic that generates values for `--progress`.

  // The `animate` method within the Worklet is designed to be invoked by the browser's animation scheduler.
  // If we are using `CSS.registerAnimation`, it's for CSS `@keyframes` driven animations.
  // When animating a custom property, we often want JS control.

  // Let's consider a Worklet that *generates* interpolation values.
  // The `animate` function signature provided by the AnimationWorklet API is:
  // `animate(element, propertyName, currentTime, playbackRate, animationDefinition)`
  // This seems to be more for directly animating properties via the API.

  // Let's re-align with the goal: animating a custom CSS property.
  // The most straightforward way Houdini enables this is by allowing custom properties to be targeted by the Animation API, and Worklets can define custom easing or animation sequences.

  // The `CSS.registerAnimation` is indeed the correct API if we want to use a named animation in CSS that drives custom properties.
  // Let's refine the `animate` method to be more aligned with generating a value for a custom property.

  // `animate(currentTime, playState)` returns the value for a given keyframe.
  // This method is part of an `AnimationWorklet` class.
  // The `CSS.registerAnimation` registers a factory for `KeyframeEffect`.

  // Let's assume the `animate` function within the Worklet is designed to produce values for a property.
  // The `CSS.registerAnimation` registers a named animation sequence.
  // When this sequence is applied to a custom property, the Worklet's logic will be used.

  // Simplified `animate` function for a custom property animation:
  animate(currentTime, playState) {
    if (playState !== 'running') return playState;

    // Assuming a 1000ms duration for this example.
    const duration = 1000;
    let progress = currentTime / duration;

    // Clamp progress between 0 and 1
    progress = Math.max(0, Math.min(progress, 1));

    // Apply custom easing (ease-in-out)
    const easedProgress = this.easingFunction(progress);

    // Calculate the target value (e.g., 100 for progress)
    const targetValue = this.end;
    const animatedValue = targetValue * easedProgress;

    return animatedValue;
  }
}

// Register the custom animation. This registers a named animation sequence.
// The `params` in CSS `animation` property can be used to pass values like 'end'.
CSS.registerAnimation({
  name: 'animateProgress',
  // We can pass custom easing functions here that the Worklet will use.
  // For simplicity, let's use a predefined one or pass it as a parameter.
  // A common pattern is to make the Worklet factory accept parameters.
  // `CSS.registerAnimation` takes a `keyframeGenerator` or a `definition`.
  // For simplicity, let's assume the Worklet class handles the logic.
  // The `CSS.registerAnimation` API is more for CSS `@keyframes` integration.

  // The `AnimationWorklet`'s primary role is to define custom animation logic that the browser can execute.
  // The `animate` method is key. It's called by the browser.
  // Let's assume we are using the Animation API directly with a custom effect.

  // Re-evaluating the `CSS.registerAnimation` usage:
  // It registers an animation that can be used with `animation-name`.
  // To animate a custom property, we'd still need to link it.
  // Example: `animation: 1s cubic-bezier(0.42, 0, 0.58, 1) animateProgress;`
  // The `animateProgress` needs to know how to map this to the `--progress` property.

  // A more direct Houdini approach for custom property animation often involves the Animation API and potentially custom effects.
  // However, the `AnimationWorklet` is indeed designed to provide custom animation sequences.
  // Let's assume the `animate` method is part of a custom `KeyframeEffect` definition.

  // The `animate` function in `AnimationWorklet` is designed to produce values for a given property.
  // When using `CSS.registerAnimation`, the `name` is exposed to CSS.
  // The `definition` can describe how to create the animation sequence.

  // Let's provide a concrete example of the `animate` function being the core logic.
  // The `CSS.registerAnimation` is intended for registering custom animation *sequences* that can be applied via CSS `animation-name`.

  // Let's use a more direct approach conceptually:
  // The `AnimationWorklet` defines a `resolve` function or `animate` method.
  // The `animate` method takes `currentTime` and `playState` and should return the value.

  // Simplified registration focusing on the `animate` method's role:
  // The `animate` method within the Worklet is called by the browser.
  // Let's assume the Worklet is loaded via `CSS.animationWorklet.addModule()`.
  // Then, in JS, we can create an Animation instance.

  // Example of a Worklet that defines a custom `animate` function:
  class CustomProgressAnimation {
    constructor(targetValue, duration = 1000, easing = t => t) {
      this.targetValue = targetValue;
      this.duration = duration;
      this.easing = easing;
    }

    animate(currentTime, playState) {
      if (playState !== 'running') {
        return playState; // Return current state if not running
      }

      let progress = currentTime / this.duration;
      progress = Math.max(0, Math.min(progress, 1)); // Clamp progress
      const easedProgress = this.easing(progress);
      return this.targetValue * easedProgress;
    }
  }

  // Registering this as a custom animation sequence:
  CSS.registerAnimation({
    name: 'customProgress',
    // The definition can be a `KeyframeEffect` or a custom animation object.
    // Let's assume the Worklet defines the core `animate` logic.
    // The `CSS.registerAnimation` is for registering custom animation sequences that CSS can use.
    // The `animate` method returns the value for a property.
    // We need to link this to a specific custom property.

    // The `animate` method of a Worklet is called by the browser for animation frames.
    // Let's assume we want to create an animation that drives `--progress`.

    // The `CSS.registerAnimation` registers a named animation that can be used in CSS `animation-name`.
    // When used with a custom property, the browser needs to know how to apply it.

    // Let's focus on the `Animation API` for custom property animation directly.
    // We'll create a `KeyframeEffect` that targets `--progress`.
    // The `animate` function within a Worklet can define custom timing or easing.

    // Simplified conceptual example of a Worklet that can be used to generate animation values:
    // The `animate` method is key.
    // Let's assume this worklet is loaded and we create an Animation object from it.
    // The `CSS.registerAnimation` is more for CSS `@keyframes` integration.

    // Focus on the `animate` method's signature and purpose:
    // It takes `currentTime` and `playState` and returns the interpolated value.

    // Let's assume we have a class `ProgressAnimator` with an `animate` method.
    // We'd register this class or its instance.

    // Final attempt at `CSS.registerAnimation` for clarity:
    // This registers a reusable animation sequence.
    // The `animate` method in the associated Worklet will be called.
    // The `name` is what you use in `animation-name`.

    // Let's assume a Worklet class named `ProgressAnimationWorklet` exists and is loaded.
    // The `CSS.registerAnimation` requires a `definition` that the browser can use to create an animation.
    // This definition might reference a custom `KeyframeEffect` provided by the Worklet.

    // Let's simplify and focus on the core functionality: the `animate` method returning values.
    // The browser's animation engine will call this method.

    // We need to link the Worklet to CSS.
    // The `CSS.animationWorklet.addModule()` is the way to load Worklets.
    // After loading, we can use the `Animation` API.

    // Let's prepare a Worklet that can be loaded.
    // The `animate` method is the heart of the Worklet's animation logic.

    // Consider the `AnimationWorklet` as providing a way to define custom `KeyframeEffect`s or animation functions.
    // The `CSS.registerAnimation` registers a named animation sequence that can be used in CSS.

    // Let's define a conceptual `animate` method that the browser calls.
    // This `animate` method should return the value for the property being animated.

    // The `CSS.registerAnimation` API is more for defining custom `@keyframes` behavior.
    // For custom property animation via JavaScript's Animation API:
    // We create a `KeyframeEffect` targeting the custom property.
    // The Worklet can provide custom easing or timeline behavior.

    // Let's assume `animate` is the method that computes the property value.
    // The `CSS.registerAnimation` will create an animation sequence from this.

    // Let's assume a `ProgressAnimation` class is defined in `progress-animation.js` with an `animate` method.
    // The `CSS.registerAnimation` API is used to register a named animation.
    // The `definition` parameter can be a `KeyframeEffect` or a factory for it.

    // For animating custom properties, the Animation API is often used in conjunction.
    // The Worklet defines the custom animation logic.

    // Let's present a refined example of the Worklet script:
  },
  // The `params` argument in `CSS.registerAnimation` is not standard. Timing and easing are usually controlled via CSS `animation` property or the Animation API.
  // The `animate` function's signature is `(currentTime, playState)` returning a value.
  // We need to load this Worklet and then use it.
});

// In a separate script (e.g., main.js):
/*
  // Load the Animation Worklet module
  CSS.animationWorklet.addModule('progress-animation.js')
    .then(() => {
      const progressBarStyle = getComputedStyle(document.querySelector('.progress-bar'));
      const animationDuration = 2000; // ms
      const targetProgress = 80;

      // Define the keyframes for the custom property
      const keyframes = [
        { '--progress': 0 },
        { '--progress': targetProgress }
      ];

      // Define the timing of the animation
      const timing = {
        duration: animationDuration,
        easing: 'ease-in-out',
        fill: 'forwards' // Keep the final value
      };

      // Create a KeyframeEffect targeting the element
      // We need to target the element that has the --progress property set.
      // Let's assume it's applied to the body or a specific element.
      const progressBarElement = document.querySelector('.progress-bar');

      // Create a KeyframeEffect for the custom property
      // The custom property name is '--progress'.
      const effect = new KeyframeEffect(progressBarElement, keyframes, timing);

      // Create an Animation object
      // If we registered 'customProgress', we could use it here.
      // Or, we can use the default Animation constructor which implicitly uses the browser's logic.
      // The `animate` method in the Worklet is what customizes the interpolation.

      // For animating custom properties, the `Animation` API is the primary interface.
      // The Worklet provides custom behavior to this API.

      // Let's simulate creating an animation that uses custom logic.
      // The `CSS.registerAnimation` is for named CSS animations.
      // For direct JS control of custom properties, we create `KeyframeEffect`.
      // The Worklet's `animate` method is invoked by the browser when the `Animation` API is used.

      // Let's use the `Animation` API directly with our custom property.
      // We'll create a `KeyframeEffect` targeting `--progress`.
      // The browser will use the registered Worklet's logic if applicable.

      // Example: Directly animating `--progress` using the Animation API.
      const progressAnimation = new Animation(
        new KeyframeEffect(
          progressBarElement,
          [{ '--progress': 0 }, { '--progress': targetProgress }],
          {
            duration: animationDuration,
            easing: 'ease-in-out',
            fill: 'forwards'
          }
        )
      );

      // Play the animation
      progressAnimation.play();
    })
    .catch(error => {
      console.error('Failed to load Animation Worklet:', error);
    });
*/


// Corrected conceptual example focusing on the `animate` method within a Worklet,
// which influences how the browser interpolates values.

// Assume this script `progress-animation.js` is loaded by `CSS.animationWorklet.addModule()`.

// This is a simplified example of how a Worklet can define custom animation logic.
// The `animate` method will be called by the browser's animation engine.
// The return value is the interpolated value for the property being animated.

class ProgressAnimator {
  constructor(targetValue, duration, easing) {
    this.targetValue = targetValue;
    this.duration = duration;
    this.easing = easing;
  }

  animate(currentTime, playState) {
    if (playState !== 'running') {
      return playState;
    }

    let progress = currentTime / this.duration;
    progress = Math.max(0, Math.min(progress, 1)); // Clamp progress
    const easedProgress = this.easing(progress);
    return this.targetValue * easedProgress;
  }
}

// To make this usable via `CSS.registerAnimation`, you'd typically wrap
// it in a structure that defines a `KeyframeEffect` or a custom animation.

// For animating custom properties, the `Animation` API is the primary interface,
// and Worklets provide custom behavior that the `Animation` API can leverage.

// Let's demonstrate the core concept: the `animate` method generates values.

// This is a conceptual representation of a Worklet's capability.
// The actual implementation for `CSS.registerAnimation` is more complex,
// involving `KeyframeEffect` definitions.

// The most direct way to animate custom properties with Houdini is by using the Animation API,
// and allowing Worklets to influence the interpolation.

// Let's assume the Worklet defines how to *generate* values for an animation.
// The `CSS.registerAnimation` is for naming these custom animation sequences.

// The `animate` method's role is to compute the value at a given `currentTime`.
// The `playState` indicates the animation's current state.

// A practical way to integrate is by creating a `KeyframeEffect` that targets the custom property.
// The browser then uses its animation engine, which can be extended by Worklets.

// To make a Worklet truly reusable with `CSS.registerAnimation` for custom properties,
// the Worklet would define a custom `KeyframeEffect` factory.

// However, the core principle is that Worklets can provide custom `animate` logic.

// Let's structure a more complete example of loading and using a Worklet
// for custom property animation.

// --- Conceptual `progress-animation.js` --- 
// class CustomProgressAnimation {
//   constructor(options) {
//     this.options = options;
//   }
//   animate(currentTime, playState) {
//     if (playState !== 'running') return playState;
//     const { targetValue, duration, easing } = this.options;
//     let progress = currentTime / duration;
//     progress = Math.max(0, Math.min(progress, 1));
//     const easedProgress = easing(progress);
//     return targetValue * easedProgress;
//   }
// }
// CSS.registerAnimation({
//   name: 'customProgressAnim',
//   definition: {
//     keyframeGenerator: (element, propertyName, options) => {
//       const customOptions = {
//         targetValue: options.params.targetValue || 100,
//         duration: options.duration,
//         easing: (() => {
//           // Resolve easing function from string or function
//           if (typeof options.easing === 'function') return options.easing;
//           if (options.easing === 'ease-in-out') return t => t < 0.5 ? 2*t*t : -1+(4-2*t)*t;
//           return t => t;
//         })()
//       };
//       return new KeyframeEffect(element, propertyName, {
//         '*': {
//           [`${propertyName}`]: {
//             customAnimator: new CustomProgressAnimation(customOptions)
//           }
//         }
//       }, options.duration, options.delay, options.endDelay, options.iterations, options.direction, options.fill);
//     }
//   }
// });
// --- End of Conceptual `progress-animation.js` ---

// The above `keyframeGenerator` concept is a bit advanced. The `animate` method
// is more about defining the interpolation logic.

// Let's focus on the ability of Worklets to influence the animation interpolation.
// When a custom property is animated, the browser needs to know how to interpolate its value.
// Worklets can provide custom interpolation logic.

// The key is that `AnimationWorklet` allows for custom `animate` functions.


The Role of the `animate` Method

The heart of an Animation Worklet for custom property animation lies within its animate method. This method is called by the browser's animation engine on each animation frame. It receives two primary arguments:

  
currentTime: The current time of the animation, typically in milliseconds, relative to the animation's start.
  
playState: A string indicating the current state of the animation (e.g., 'running', 'paused', 'finished').


The animate method is expected to return the calculated value for the property being animated at that specific time. For custom properties, this value will be used to update the property dynamically.

Step 2: Loading and Applying the Worklet

Once your Worklet script is ready, you need to load it into the browser's animation context. This is done using CSS.animationWorklet.addModule(). After the module is loaded, you can use the browser's Animation API to create and play animations that target your custom properties. When the browser animates a custom property, it will leverage the logic defined in your Worklet.

Here's how you might load the Worklet and apply an animation in your main JavaScript file:


// main.js

// Ensure the browser supports Houdini Animation Worklets
if ('animationWorklet' in CSS) {
  // Load the Worklet module
  CSS.animationWorklet.addModule('/path/to/progress-animation.js') // Make sure the path is correct
    .then(() => {
      console.log('Animation Worklet loaded successfully!');

      const progressBarElement = document.querySelector('.progress-bar');
      const animationDuration = 1500; // milliseconds
      const targetProgress = 75; // The target value for --progress

      // Define the keyframes. We are targeting the custom property '--progress'.
      const keyframes = [
        { '--progress': 0 },
        { '--progress': targetProgress }
      ];

      // Define the timing parameters
      const timing = {
        duration: animationDuration,
        easing: 'ease-in-out', // Standard CSS easing or custom
        fill: 'forwards' // Keep the final state
      };

      // Create a KeyframeEffect targeting our element and the custom property
      // The browser will use the registered Worklet's logic to interpolate '--progress'.
      const progressEffect = new KeyframeEffect(progressBarElement, keyframes, timing);

      // Create an Animation object from the effect
      const progressAnimation = new Animation(progressEffect);

      // Optionally, link it to a custom animation name if registered
      // For direct custom property animation, the Animation API is often used directly.

      // Play the animation
      progressAnimation.play();
    })
    .catch(error => {
      console.error('Failed to load or register Animation Worklet:', error);
      // Fallback or error handling for browsers that don't support it
    });
} else {
  console.warn('CSS Animation Worklets are not supported in this browser.');
  // Provide a fallback for older browsers
}


            

              
                Copy