Unlock CSS Houdini: Create Custom Paint, Layout, and Worklet Effects

Background

When a browser renders a page it parses HTML and CSS, builds a rendering tree, then performs layout and painting. Before Houdini, developers could not intervene in layout or painting, making it hard to polyfill missing CSS features. Pre‑processors like Sass emerged to compensate for CSS’s lack of programmability.

What is CSS Houdini?

CSS Houdini exposes a set of browser APIs that let developers hook into the CSS engine, enabling custom properties, painting, layout, and worklets.

CSS Properties and Values API

Allows defining custom CSS variables that start with -- and are accessed via var(). Example:

div {
  --font-color: #9e4a9b;
  color: var(--font-color);
}

Variables are scoped to the element and its descendants.

Painting API

Developers can create a Paint class and register it with registerPaint. The class receives a CanvasRenderingContext2D to draw custom background‑image content.

registerPaint('rect', class {
  static get inputProperties() { return ['--rect-color']; }
  paint(ctx, geom, properties) {
    const color = properties.get('--rect-color')[0];
    ctx.fillStyle = color;
    ctx.fillRect(0, 0, geom.width, geom.height);
  }
});

Usage in CSS:

.wrapper {
  background-image: paint(rect);
  --rect-color: #3a4ba2;
}

Layout API

Allows defining custom layout behavior via registerLayout. The layout method receives children, edges, constraints, etc., and must return an object describing the final positions.

registerLayout('block-like', class {
  layout(children, edges, constraints, properties, breakToken) {
    // custom layout logic
    return { /* layout result */ };
  }
});

Worklets

Paint and Layout APIs run inside a Worklet, a lightweight thread similar to a Web Worker, isolated from the main window.

if ('paintWorklet' in CSS) {
  CSS.paintWorklet.addModule('paintworklet.js');
}
if ('layoutWorklet' in CSS) {
  CSS.layoutWorklet.addModule('layoutworklet.js');
}

Basic three‑step Painting API example

Define a Paint class, load it via a worklet, and apply it in CSS to draw a rectangle whose color is controlled by a CSS variable.

Advanced: Dynamic wave effect

Shows how to animate a wave using the Painting API and requestAnimationFrame, then improve realism by replacing the sine function with simplex-noise for continuous, irregular motion.

Code snippets illustrate importing simplex-noise, generating noise‑based waveforms, and drawing them.

References: CSS Painting API Level 1, CSS Layout API Level 1, CSS Houdini introduction.