paint()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

The paint() CSS function defines an <image> value generated with a PaintWorklet.

Syntax

css
paint(workletName, ...parameters)

where:

workletName

The name of the registered worklet.

parameters Optional

Optional additional parameters to pass to the paintWorklet

Formal syntax

<paint()> = 
paint( <ident> , <declaration-value>? )

Examples

Basic CSS paint() usage

Given the following HTML:

html
<ul>
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
  <li>item 4</li>
  <li>item 5</li>
  <li>item 6</li>
  <li>item 7</li>
  <li>item 8</li>
  <li>item 9</li>
  <li>item 10</li>
  <li>item N</li>
</ul>

In JavaScript, we register the paint worklet:

js
CSS.paintWorklet.addModule(
  "https://mdn.github.io/houdini-examples/cssPaint/intro/worklets/boxbg.js",
);

In the CSS, we define the background-image as a paint() type with the worklet name, boxbg, along with any variables (ex. --boxColor and --widthSubtractor) the worklet will use:

css
body {
  font: 1.2em / 1.2 sans-serif;
}
li {
  background-image: paint(boxbg);
  --boxColor: hsl(55 90% 60%);
}

li:nth-of-type(3n) {
  --boxColor: hsl(155 90% 60%);
  --widthSubtractor: 20;
}

li:nth-of-type(3n + 1) {
  --boxColor: hsl(255 90% 60%);
  --widthSubtractor: 40;
}

CSS paint() with parameters

You can pass optional arguments in the CSS paint() function. In this example, we passed two arguments that control whether the background-image on a group of list items is filled or has a stroke outline, and the width of that outline:

css
body {
  font: 1.2em / 1.2 sans-serif;
}

li {
  --boxColor: hsl(55 90% 60% / 100%);
  background-image: paint(hollowHighlights, stroke, 2px);
}

li:nth-of-type(3n) {
  --boxColor: hsl(155 90% 60% / 100%);
  background-image: paint(hollowHighlights, filled, 3px);
}

li:nth-of-type(3n + 1) {
  --boxColor: hsl(255 90% 60% / 100%);
  background-image: paint(hollowHighlights, stroke, 1px);
}

We've included a custom property in the selector block defining a boxColor. Custom properties are accessible to the PaintWorklet.

Specifications

Specification
CSS Painting API Level 1
# paint-notation

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
paint()
Supports additional parameters to pass to the paintWorklet

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

See also