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. Houdini is a group of APIs that give developers direct access to the CSS Object Model (CSSOM), enabling developers to write code the browser can parse as CSS, thereby creating new CSS features without waiting for them to be implemented natively in browsers.
Advantages of Houdini
Houdini enables faster parse times than using JavaScript .style for style changes. Browsers parse the CSSOM — including layout, paint, and composite processes — before applying any style updates found in scripts. In addition, layout, paint, and composite processes are repeated for JavaScript style updates. Houdini code doesn't wait for that first rendering cycle to be complete. Rather, it is included in that first cycle — creating renderable, understandable styles. Houdini provides an object-based API for working with CSS values in JavaScript.
Houdini's CSS Typed OM is a CSS Object Model with types and methods, exposing values as JavaScript objects making for more intuitive CSS manipulation than previous string based HTMLElement.style manipulations. Every element and style sheet rule has a style map which is accessible via its StylePropertyMap.
A feature of CSS Houdini is the Worklet. With worklets, you can create modular CSS, requiring a single line of JavaScript to import configureable components: no pre-processors, post-processors or JavaScript frameworks needed.
<script>
CSS.paintWorklet.addModule('csscomponent.js');
</script>
This added module contains registerPaint() functions, which register completely configurable worklets.
The CSS paint() function parameters include the name of the worklet, along with optional parameters. The worklet also has access to the element's custom properties: they don't need to be passed as function arguments.
li {
background-image: paint(myComponent, stroke, 10px);
--highlights: blue;
--lowlights: green;
}
Note: With great power comes great responsibility! With Houdini you could invent your own masonry, grid, or regions implementation, but doing so is not necessarily the best idea. The CSS Working group does a lot of work to ensure every feature is performant, handles all edge cases, and considers security, privacy, and accessibility. As you extend CSS with Houdini, make sure to keep these considerations in mind, and start small before moving on to more ambitious projects.
The Houdini APIs
Below you can find links to the main reference pages covering the APIs that fall under the Houdini umbrella, along with links to guides to help you if you need guidance in learning how to use them.
Start by reading Houdini, an introduction — this provides a brief history of Houdini and an overview of its many features.
- CSS Parser API
- An API exposing the CSS parser more directly, for parsing arbitrary CSS-like languages into a mildly typed representation.
No guide or reference has currently been written for this API. - CSS Properties and Values API
- Defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.
CSS Properties and Values API reference
CSS Properties and Values API guide - CSS Typed OM
- Converting CSSOM value strings into meaningfully typed JavaScript representations and back can incur a significant performance overhead. The CSS Typed OM exposes CSS values as typed JavaScript objects to allow their performant manipulation.
CSS Typed OM reference
CSS Typed OM guide - CSS Layout API
-
Designed to improve the extensibility of CSS, this API enables developers to write their own layout algorithms, like masonry or line snapping. It is not yet natively available.
No guide or reference has currently been written for this API. - CSS Painting API
-
Developed to improve the extensibility of CSS — allows developers to write JavaScript functions that can draw directly into an element's background, border, or content via the
paint()CSS function.
CSS Painting API reference
CSS Painting API guide - Worklets
-
An API for running scripts in various stages of the rendering pipeline independent of the main JavaScript execution environment. Worklets are conceptually similar to Web Workers, and are called by and extend the rendering engine.
Worklets reference
Other topics
Related topics which may be of interest, since they can be used in tandem with Houdini APIs in interesting ways.
- Composite Scrolling and Animation