Paint API

The CSS Painting API Level 1, also known as the Houdini Paint API, gives us a new option for places where we would use images in CSS: backgrounds, masks, and the like. With the new paint() function, and a Paint API worklet, we can:

• Use a 2D Canvas-like drawing context to draw
• Scale our drawn image based on the size of the element (and redraw too)
• Style our drawing using Custom Properties

Taken together, we have a powerful new tool in our toolbelt to express ourselves

Paint API Worklet

Register Worklet from Main JavaScript

await CSS.paintWorklet.addModule('path/to/paint-worklet.js');

Worklet Overview

// From https://drafts.css-houdini.org/css-paint-api/ Apirl 18, 2018 Editor's Draft

registerPaint('sample-paint', class {
  // Custom properties from element's style to look for
  static get inputProperties() { return ['--foo']; }
  // Input arguments that can be passed to the `paint` function
  static get inputArguments() { return ['<color>']; }
  // Whether Alpha is allowed?
  static get contextOptions() { return {alpha: true}; }

  paint(ctx, size, props, args) {
    // ctx - drawing context
    // size - size of the box being painted
    // props - inputProperties
    // args - array of passed-in arguments

    // Paint code goes here.
  }
});

A Paint API worklet can read in input properties on the element it's attached to (either custom properties or standard properties), it can be passed arguments with CSS Value types for each argument, and options for the context can be set (like if Alpha is allowed)

Paint API Polyfill

Start using the Paint API today! Google Chrome Labs maintains a polyfill for the Paint API which makes it available in all browsers that support Canvas! Note: Not currently in use on this site.

Play with the Paint API

Now it's your turn! Below are four examples of the Paint API in action, each showcasing something a little different, for you to see and play with! The Circle example is fairly basic, showing how to use input properties and the size of the element to draw a basic circle. The Tabs example shows off input arguments and demonstrates how we may be able to leverage the Paint API in design systems to make otherwise difficult to implement and maintain flourishes easy by creating a tabbed component with nicely rounded transitions. The Generative Art example is based on the work of Tim Holman and built after seeing his JSConf AU talk; it uses generative art techniques to build a random background pattern. Finally, the Animation example is a recreation of the Chrome Lab's Ripple Houdini sample showing how you can manipulate a worklet with userland JavaScript by changing the values of an input property in order to produce an animation effect.

Each one of these examples are fully editable, and you'll see the changes live as you type! You can change the Worklet code, the userland JavaScript, the CSS, and the HTML. Worklets get added automagically, and the userland JavaScript runs after its loaded.

You're preloaded with the Circle example. Use the other buttons to switch examples. The Custom button will give you a blank Paint API worklet scaffolding to start from for you to experiment from scratch! Copy the URL once you've started making a Custom example to get back to your work later!