Houdini worklets: from CSS magic to a community library
CSS Houdini is a collection of low-level browser APIs designed to give developers finer control over the styles they write. With Houdini, you can define advanced custom properties that carry syntax, default values, and inheritance rules via the Properties and Values API. It also brings paint, layout, and animation worklets, letting authors hook into the browser's rendering pipeline directly.
What worklets do
Houdini worklets are scripts that run off the main thread and are invoked when the browser needs them. They work like service workers for CSS: you register a module once, then reference it by name in your stylesheet. Registering a worklet is a one-liner — CSS.paintWorklet.addModule(workletURL) — and usage is equally simple, for example background: paint(confetti).
The CSS Painting API
The CSS Painting API is one of the most mature Houdini specs and a W3C Candidate Recommendation. It enables developers to write canvas-like custom painting functions for use as backgrounds, borders, masks, and more. Instead of waiting for a browser to add a feature like angled borders natively, you can write your own paint worklet or use one that's already published, then apply it to borders and clipping.
Browser support for the Painting API is solid: enabled in all Chromium-based browsers, partially supported in Safari, and under consideration for Firefox. For projects needing full cross-browser coverage, the CSS Paint Polyfill fills in the gaps so your styles work in every modern browser.
Houdini.how: a library of worklets
To showcase what paint worklets can do and give developers a starting point, the team built houdini.how. It's a library and reference for Houdini worklets, complete with browser support data, an API overview, usage guides, extra resources, and live samples. Every sample runs on the CSS Paint API, so they all work across modern browsers. The site also accepts community contributions via its GitHub repository.
Getting worklets into your project
Houdini worklets require a local server or HTTPS to run. You can either install them locally or serve them from a content delivery network like unpkg, then register the worklet in your code. Regardless of the method, include the CSS Paint Polyfill to guarantee cross-browser compatibility.
Prototyping with a CDN
Registering from unpkg lets you link straight to a worklet's worklet.js file. Unpkg resolves it as the main script and serves over HTTPS, avoiding CORS issues. Note that this approach doesn't register custom properties, but each worklet has fallback values built in. If you want syntax and fallbacks registered, load the optional properties.js file. The polyfill can be included the same way, via unpkg.
Managing worklets with npm
For production use, install the worklet from npm. Importing the package doesn't auto-register the worklet; you need to generate a URL to the package's worklet.js and call CSS.paintWorklet.addModule(). The npm package name and link are listed on each worklet card in the Houdini.how catalog. The polyfill can be included as a script or imported directly in a bundler setup.
With either a CDN link or an npm-managed module, a paint worklet gives your CSS a considerably wider toolbox than the built-in background and border styles offer — and without a long wait for browser vendors to catch up. Houdini.how collects the best of these efforts in one place, ready to drop into your next project.
