What is CSS Painting API?

Mon Jan 17 2022

2 min read

The HTML provides the structure, whereas CSS provides the design layer to your web application. There are multiple ways to write CSS: inline-CSS, internal styles, and external stylesheets. You can also manipulate CSS via JavaScript.

JavaScript provides interactivity to your web application. It takes care of all the logical stuff that a site needs. JavaScript also contains a web API called CSS painting API that lets you draw in an element’s border, background or content. Let’s take a look at this API in this piece.

CSS Painting API

CSS Painting API, also known as the CSS Custom Paint or Houdini’s paint worklet, allows you to paint an image whenever a CSS property expects an image. It lets you paint backgrounds, content and highlight the box based on its size and computed styles.

The properties like background-image use url() to load an image. With CSS paint API, you can define a paint worklet and then reference it like paint(myPainter) instead of the url(). Here is an example:

footer {
background-image: paint(myPaintedImage);

Defining a Paint Worklet

You need to create a JavaScript file to define all the worklets. Inside this file, you can specify a paint worklet like this:

class MyPainter {
paint(ctx, geometry, properties) {
// ...
registerPaint('myPainter', MyPainter);

Inside the paint function in the above snippet, you write down all the instructions for rendering a painted image. Once you are done, you need to load this JavaScript file on your main website. For the sake of this piece, let’s call the file firstPaintWorklet.js. Now inside the script tag in your HTML file, you need to paste the following snippet:


CSS Painting API is only supported on chrome at the moment and does not work on Firefox and Safari.