How it works
A background that is a function
This is a flagged, experimental effect. The CSS Painting API lets a small script paint an element's background, border or mask on demand, at whatever size and resolution the element has. It is not Baseline: only Chromium ships it, so everything here has a plain CSS gradient twin.
1. paint() is an image
Anywhere CSS takes an image (background-image, border-image, mask-image) it also takes paint(name). The browser then calls the paint() method of the class registered under that name with a 2D context of the element's
size, the size itself and the element's computed styles. It calls it again whenever the size or
one of the listed input properties changes, and paints at the device pixel ratio, so the result
is sharp on every screen without any image files.
// worklet.js, runs in a PaintWorkletGlobalScope (no DOM, no network, no text)
registerPaint('vfx-pattern', class {
static get inputProperties() {
return ['--vfx-paint-size', '--vfx-paint-phase', '--vfx-paint-color-1' /* … */];
}
paint(ctx, geom, props) {
const size = parseFloat(props.get('--vfx-paint-size')); // a typed CSSUnitValue, in px
const phase = parseFloat(props.get('--vfx-paint-phase'));
// ctx is a PaintRenderingContext2D: paths, arcs, fills, strokes, transforms
for (const cell of jitteredGrid(geom.width, geom.height, size)) {
ctx.beginPath();
ctx.arc(cell.x, cell.y, size / 2, 0, 2 * Math.PI);
ctx.fillStyle = String(props.get(cell.color));
ctx.fill();
}
}
}); The worklet runs in its own global scope: no DOM, no fetch, no text drawing, no
images. That is why the painter here is a single self-contained function. The same function
is unit-tested in Node and copied into the worklet with Function.prototype.toString(), so the tests and the browser run identical code.
2. Registered custom properties are the parameters
A worklet reads its inputs through inputProperties. Registering those
properties (with CSS.registerProperty or @property) gives them a
type: the worklet then gets computed, typed values, so a <length> written
as 1rem arrives as px and a <color> as a resolved color. The
component registers them from JavaScript rather than with @property because an @property rule inside a shadow root is ignored, and the custom element renders in
one.
// Once per document. The worklet module can be any URL; here it is a Blob,
// so it needs no static file and works under any base path.
for (const p of [
{ name: '--vfx-paint-size', syntax: '<length>', initialValue: '16px' },
{ name: '--vfx-paint-phase', syntax: '<number>', initialValue: '0' },
{ name: '--vfx-paint-color-1', syntax: '<color>', initialValue: 'black' },
// … one entry per input property
]) CSS.registerProperty({ ...p, inherits: true });
const url = URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
await CSS.paintWorklet.addModule(url); The module is a Blob URL built from a string at runtime. A file in static/ would not ship with the npm package and would have to know the site's base path; a Blob URL needs
neither. The one catch is a Content-Security-Policy: worklets count as scripts, so script-src must allow blob:, or the module fails to load and the
component stays on the gradient twin.
3. A jittered grid that grows instead of reshuffling
Shapes sit one per grid cell, offset from the cell center by up to Jitter × half a cell. Each cell seeds its own small random generator (mulberry32) from a hash of the seed, its column and its row. So a given cell always gets the same shape, color and angle: when the element gets wider, new cells appear on the right and the existing ones stay put. One cell of margin on every side lets shapes that start outside the box reach into it.
- dots
- circles, radius scaled by up to ±40% of Jitter
- squiggles
- a two-period sine polyline, rotated at random, stroked with round caps
- blobs
- a closed radial curve, the base radius plus three low harmonics (2, 3 and 5 lobes) with random phases
4. Animation: keyframes on a registered number
Because --vfx-paint-phase is a registered <number>, plain
CSS keyframes interpolate it, and every new value invalidates the paint image. The
squiggles' waves slide along, dots breathe and blobs wobble. The animation is CSS, so it
stops for prefers-reduced-motion: reduce and pauses inside a data-motion="paused" region like every other animation in the library.
.pattern { animation: phase 6s linear infinite; }
@keyframes phase {
to { --vfx-paint-phase: 1; }
}
@media (prefers-reduced-motion: reduce) {
.pattern { animation: none; }
} 5. The gradient twin
Outside Chromium, and for the moment until the module has loaded, the same layer gets ordinary gradients built from the same parameters. A gradient can't place shapes at random, so the twin overlays one repeating tile per color, with tile sizes in non-integer ratios (1.53 : 1.79 : 2.11 cells) and seeded offsets, so the repeats rarely line up. The squiggle twin is a wave per color made from half rings: a lower half ring at the top edge of each tile, an upper one at the bottom edge, cropped by the tile so the halves join on the tile boundary. The twin stays still when Animate is on.
.pattern {
background-image:
radial-gradient(circle at 7.2px 0px, #0000 5.7px, #ff5c8a 6.2px 8.2px, #0000 8.7px),
radial-gradient(circle at 21.6px 115.2px, #0000 5.7px, #ff5c8a 6.2px 8.2px, #0000 8.7px),
radial-gradient(circle at 7.2px 0px, #0000 5.7px, #ffc94d 6.2px 8.2px, #0000 8.7px),
radial-gradient(circle at 21.6px 115.2px, #0000 5.7px, #ffc94d 6.2px 8.2px, #0000 8.7px),
radial-gradient(circle at 7.2px 0px, #0000 5.7px, #4dd6c4 6.2px 8.2px, #0000 8.7px),
radial-gradient(circle at 21.6px 115.2px, #0000 5.7px, #4dd6c4 6.2px 8.2px, #0000 8.7px);
background-size: 64.05px 115.2px, 64.05px 115.2px, 70.04px 115.2px, 70.04px 115.2px, 77.41px 115.2px, 77.41px 115.2px;
background-position: 45.95px 0px, 45.95px 0px, 11.6px 38.4px, 11.6px 38.4px, 60.05px 76.8px, 60.05px 76.8px;
} For hand-written CSS, the same order works without JavaScript feature detection: declare the
gradient twin, then paint() inside @supports. In Chromium, paint() of a name that isn't registered yet is a transparent image, which is why
the component waits for the module before switching.
.pattern {
--vfx-paint-pattern: squiggles;
--vfx-paint-seed: 7;
--vfx-paint-density: 1;
--vfx-paint-size: 16px;
--vfx-paint-stroke: 3px;
--vfx-paint-jitter: 0.8;
--vfx-paint-color-1: #ff5c8a;
--vfx-paint-color-2: #ffc94d;
--vfx-paint-color-3: #4dd6c4;
background-color: #1b1640;
/* the gradient twin first (background-image/-size/-position as above) */
}
@supports (background: paint(x)) {
.pattern {
background-image: paint(vfx-pattern);
background-size: auto;
}
} Browser support and performance
- Not Baseline. The CSS Painting API (
paint(),CSS.paintWorklet) is Chromium-only, since Chrome 65; Firefox and Safari have no implementation (web-features, webstatus.dev/features/paint). Detection is easy for once:'paintWorklet' in CSSis true exactly where it works. Registered custom properties are Baseline newly available since July 2024. - Checked in Chromium (worklet) and with the gradient renderer, which is what other browsers get. Real Firefox and Safari are untested.
- A static pattern is painted once per size change and then cached like any image. An animated one runs the painter every frame on the main thread's paint step: about a thousand shapes on a full-screen box is fine on a laptop, but keep animated worklets small, or animate something cheaper.
- The pattern layer is decorative and
aria-hidden; the text on top is real text on a nearly opaque card. Busy patterns behind text hurt readability, which is why the border mode exists.