Brought to you by web.dev

Houdini.how

Using Houdini

Firstly, when using paint worklets, we highly recommend you also use the CSS Paint Polyfill to ensure that all modern browsers can run these styles as well. Read on for instructions on implementing both worklets and the polyfill in your user interfaces.

Note: Houdini worklets must either be run via a server locally, or on HTTPS in production. In order to work with a Houdini worklet, you will need to either install it locally or use a content delivery network (CDN) like unpkg to serve the files.

There are four steps required to use a Houdini paint worklet:

  1. Install the worklet to your file system (either via an npm module or linked through a CDN).
  2. Add the worklet to your local CSS interface using CSS.paintWorklet.addModule().
  3. Use the worklet in your CSS file.
  4. Polyfill your site using the CSS Paint Polyfill

The following goes through some of the various ways to achieve the above steps. You can also find demos and guidance on how to use the worklets in your CSS file on the worklet page.

1. Install and 2. Add

Option 1: Install and register from npm
(recommended for production)

Install your worklet from npm:

npm install <package-name>

Importing this package does not automatically inject the paint worklet. To install the worklet (step 2), you'll need to generate a URL that resolves to the package's worklet.js, and register that. You do so with:

CSS.paintWorklet.addModule(..file-path/worklet.js)

Option 2: Register directly from unpkg

When registering from unpkg, you can link directly to the worklet file without needing to locally install the worklet. Unpkg will resolve to the main script, or you can specify it yourself (i.e. worklet.js). Unpkg will not cause CORS issues, as it is served over HTTPS.

CSS.paintWorklet.addModule("https://
                unpkg.com/<package-name>");

Note that this does not register the custom properties for syntax and fallback values. Instead, they each have fallback values embedded into the worklet.

To optionally register the custom properties, include the properties.js file as well.

<script src="https://unpkg.com/<package-name>/properties.js"></script>

Installation in Bundlers

Here is an example of how to use Houdini in modern bundlers:

Parcel and WMR

import workletURL from "url:<package-name>/worklet.js"

          CSS.paintWorklet.addModule(workletURL);

Vite

import workletURL from "<package-name>/worklet.js?url"

            CSS.paintWorklet.addModule(workletURL);

Webpack 4 and 5

import workletURL from "url-loader!<package-name>/worklet.js"

CSS.paintWorklet.addModule(workletURL);

Rollup

Install rollup-plugin-off-main-thread plugin. Then:

import workletURL from "omt:<package-name>/worklet.js"; 

CSS.paintWorklet.addModule(workletURL);

3. Use in CSS

Now you're ready to call the worklet by its name in your CSS file.

div {
  background: paint(<paintName>);
}

Most of the worklets showcased on this site have optional styling parameters which can be custimzed via CSS custom properties. These are denoted with a --. See the worklets page for more information on customizations and how to use the worklets in CSS.

div {
  --customValue: <value>
  background: paint(<paintName>);
}

4. Polyfill your site

As previously mentioned, when using the Paint worklet, you should also include the CSS Paint Polyfill.

<script src="css-paint-polyfill.js"></script>
          
// or with unpkg:
<script src="https://unpkg.com/css-paint-polyfill"></script>

With a bundler or ES modules:

import 'css-paint-polyfill';

Houdini.how

Brought to you by web.dev