paint() | CSS-Tricks

Experimental: Check browser support before using this in production.
The paint() function allows us to use PaintWorklets as background images in CSS. PaintWorklets are images created in JavaScript that are applied to an element in CSS with the paint() function.
The paint() function is defined in the CSS Painting API Level 1 specification. It is part of a larger set of features related to CSS Houdini.
The paint() function syntax is straightforward: it accepts a single required value, which is the name of the PaintWorklet that is defined in JavaScript:
And it can be used wherever an <image> value is expected:
The paint() function actually takes up to two arguments, the other of which is optional:
What do we mean by “parameters” for the second optional value? We don’t know for sure until the specification becomes a formal candidate recommendation, but the idea is that we can, apply additional styling to the image at the same time we call it, for example, adding a stroke to the background image:
What we do know is that parameters will support CSS Custom Properties, which we’ll cover a bit later.
The paint() function allows us to import an <image> created with the CSS Painting API. The API is one of the several low-level APIs that allow developers to interact with the CSS Object Model. Together, they are classified as CSS Houdini APIs that allow us to write JavaScript code that the browser parses as CSS.
What is Houdini? It gives us the chance to create custom styles that are not natively available in CSS. The Paint API works by registering a PaintWorklet, which is a script that handles painting and runs on a separate thread. This separation prevents the painting logic from blocking the main thread, thus improving performance.
To use the paint() function we first…
We have to write the class at the start of the file because, unlike JavaScript functions, classes cannot be hoisted and need to be defined before they are used.
Imagine we have some CSS Custom Properties that we want to use in our PaintWorklet:
These properties are defined once within the class’s static getter method, inputProperties. The method informs the browser that the custom properties are accessible with the paint() method — and we can declare those properties as the second optional paint() parameter.
Let’s build off of the first demo we looked at together and make a multi-colored polka dot background pattern made out of varying dot sizes. This paint uses the Math.random() method to generate different hex codes on refresh, giving the website a new look every time.
The flow is the same four-step process as before!
On every rerun, you get a different background pattern!
The CSS Paint API isn’t new by any means — in fact, CSS-Tricks has covered it a lot over the years — and developers have made amazing background images with it. For example, I came across George Francis’s article, “Creating Generative Patterns with the CSS Paint API”, from 2021 where he shares three awesome patterns.
I love George’s “Voronoi Arcs” background example:
There are several cool things going around here:
Can’t we use HTML <canvas> for drawing images? Good question! Both paint() and <canvas> have access to the 2D context, but they differ in several key ways, as illustrated in the table below:
The paint() function is defined in the CSS Painting API Level 1 specification, which is currently in Editor’s Draft. That means the information can change between now and when it formally becomes a Candidate Recommendation for browsers to implement.
The <ident> argument works in the listed browsers, but the <declaration-value>, which indicates additional parameters, is not supported in any browser at all.
To be on the safe side, add a fallback image just in case your user uses an unsupported browser.
Join our community of front-end nerds!
Andy Clarke shows you how to create designs that people recognize and remember in his brand-new e-book, Standout Designs for the Web. Pre-order it today!
Join our community of front-end nerds! You'll get into the Discord server and member-only perks and free swag.
Sign up to get front-end roundups, browser updates, and exclusive content sent to your inbox bi-weekly.
Get your t-shirts, prints, stickers, and yes, even mousepads at the brand-spankin' new CSS-Tricks store, now open.
CSS-Tricks is powered by a small team of real-life humans.
Handwritten. Twice a month. No spam. See past issues →