2 min read

CSS Houdini

CSS Houdini is a set of low-level APIs that exposes parts of the CSS engine, giving developers the power to extend CSS by hooking into the styling and layout process of a browser's rendering engine.

1. The Problem: The Black Box

Traditionally, the browser's CSS engine was a "black box". You wrote CSS, and the browser rendered it. If you wanted a feature that CSS didn't support (like a masonry layout or a specific background pattern), you had to use JavaScript to manipulate the DOM or Canvas.

This approach had downsides:

  • Performance: JavaScript runs on the main thread. Complex visual effects could cause jank.
  • Timing: JavaScript often runs after the initial render, causing layout shifts (FOUC).
  • Polyfilling: You couldn't truly polyfill CSS properties; you could only fake them.

2. The Solution: Houdini

Houdini opens up the browser's rendering pipeline. It allows you to write code (often in Worklets) that the browser executes during specific stages of the rendering process (Style, Layout, Paint, Composite).

Because these worklets run in a separate thread (similar to Web Workers) and hook directly into the engine, they are highly performant.

3. Key APIs

Houdini consists of several separate APIs:

1. CSS Typed OM

Converts CSS values from strings ("10px") to typed JavaScript objects (CSS.px(10)). This is the foundation for other Houdini APIs.

2. CSS Painting API

Allows you to programmatically draw images into CSS properties like background-image or border-image.

3. CSS Layout API

Allows you to define custom layout algorithms (like display: layout(masonry)).

4. CSS Properties and Values API

Allows you to define types, default values, and inheritance behavior for custom CSS properties (variables). This enables transitions and animations on custom properties.

5. Animation Worklet API

Allows you to write imperative animations that run on the compositor thread, ensuring they are smooth even if the main thread is busy.

4. Browser Support

Houdini is a collection of drafts. Support varies by API and browser:

  • Typed OM & Paint API: Good support in Chromium-based browsers (Chrome, Edge, Opera). Safari and Firefox have partial or in-progress support.
  • Layout API & Animation Worklet: Still experimental in most browsers.

Always check Is Houdini Ready Yet? for current status.

programming/javascript/vanilla/javascript programming/javascript/vanilla/web-workers