CSS Houdini Paint Worklets for Cheap Visuals

A decorative animated background — a spinning conic ring, a shimmering gradient, a hand-drawn border — is stealing 5–7ms of your main thread every frame because the drawing logic runs as JavaScript that rewrites a style string and forces a Recalculate Style + Paint on each tick, and the paint phase reruns instead of the compositor reusing cached pixels.

This guide is part of Off-Main-Thread Rendering, inside the broader Compositing and GPU Acceleration work. The premise is simple: the visual does not need main-thread JavaScript at all. The CSS Paint API — the “paint worklet” corner of CSS Houdini — lets you register a drawing function that the browser invokes in an isolated worklet scope, off the thread that runs your application code, and re-invokes only when a size or a declared custom property actually changes.

The symptom: a paint phase that reruns every frame

The classic offender is animation driven by mutating inline styles inside a requestAnimationFrame loop. It feels harmless — you are “just” assigning a string — but every assignment invalidates style for the element and schedules a repaint. Here is a minimal reproduction of a spinning progress ring:

const ring = document.querySelector('.ring');
let angle = 0;

function tick() {
  angle = (angle + 4) % 360;
  // rebuilds a multi-stop gradient string AND dirties style + paint every frame — all on the main thread
  ring.style.background =
    `conic-gradient(from ${angle}deg, #4456a8 0deg, #7a5c95 140deg, transparent 320deg)`;
  requestAnimationFrame(tick);
}
tick();

Three costs stack up on the main thread for each of the 60 frames per second: the callback builds a fresh gradient string, the assignment triggers Recalculate Style on the element, and because the painted result differs, the element is added to the paint invalidation set and repainted. None of that work is shared with your application logic — it competes with it. When a data fetch resolves or a React commit lands in the same frame, the ring’s overhead is exactly what pushes the frame past 16.6ms.

The tell in a profile is that the Main lane is never idle: a thin, unbroken ribbon of scripting-plus-paint runs the entire time the animation is on screen, whether or not the user is doing anything. That is the workload we want to evacuate from the main thread entirely.

Where a paint worklet actually runs

The CSS Paint API introduces a second global environment: the PaintWorkletGlobalScope. It has no window, no document, and no access to the DOM — it exists only to hold registered painters and run them. You load a module into it with CSS.paintWorklet.addModule(url), and inside that module you call registerPaint(name, class). The browser keeps a registry that maps the paint name (ring) to your class definition.

When the browser needs to paint an element whose computed style contains background-image: paint(ring), it does not call back into your main-thread code. It looks up ring in the registry, constructs an instance in the worklet scope, and calls paint(ctx, geometry, properties). The ctx is a restricted 2D drawing context whose commands are recorded into a display list (a PaintRecord), not rasterized inline. The compositor then rasterizes that display list into tiles on its raster worker threads — the same off-main-thread raster path described in Why transform and opacity are GPU-accelerated.

Two design constraints fall out of this architecture. First, paint() must be stateless and idempotent — the browser may run it on more than one thread, in any order, and may cache or discard the result freely, so instance fields cannot be relied on to persist across calls. Second, invalidation is explicit. A painter declares static get inputProperties() listing the custom properties it reads; the browser re-invokes paint() only when the element’s size changes or when one of those declared properties changes value. Everything else is served from cached tiles. That opt-in invalidation surface is the entire reason the effect becomes cheap — the browser knows precisely when it is allowed to skip the paint.

Reading the DevTools trace

Record the animation in the Performance panel with Paint and Composite categories enabled, then compare the Main lane before and after. The inline-style version fills the Main thread with a repeating scripting-and-paint block; the worklet version leaves the Main lane almost empty and moves the drawing into the compositor’s paint-worklet task.

BEFORE — inline-style rAF loop
Main Thread ──────────────────────────────────────────────
  Frame 1  [Task 6.4ms of 16.6ms budget]
    ├─ Animation Frame Fired                    0.2ms
    │    └─ tick(): build conic-gradient string 2.1ms
    ├─ Recalculate Style   (.ring)              1.9ms
    ├─ Pre-Paint / invalidate                   0.4ms
    └─ Paint   .ring background                 1.8ms   <-- repaints every frame
  Frame 2 ... identical, 60x/sec  => ~384ms/sec of main-thread time

AFTER — paint worklet + animated custom property
Main Thread ──────────────────────────────────────────────
  Frame 1  [Task 0.3ms]
    └─ (registered custom-property tick; no user JS)     <-- main thread idle
Compositor / Paint Worklet ───────────────────────────────
  Frame 1
    └─ Paint Worklet  ring.paint()              0.5ms    <-- off the main thread
       └─ raster on worker threads              GPU
  Main thread free: ~15.8ms of the 16.6ms budget

The signature you are looking for is the disappearance of the Recalculate Style / Paint pair from the Main lane and the appearance of a Paint Worklet entry on the compositor. If you still see Recalculate Style on the main thread after switching, an inputProperties value is being written from main-thread JavaScript on every frame — drive it through a registered-property animation instead (shown below) so the change is scheduled off-thread. To turn this observation into a standing check, Observing long tasks with PerformanceObserver will flag the pre-worklet version as a stream of long tasks that vanishes after the fix.

The fix: draw it once in a worklet

The rewrite has three parts: a worklet module that draws the ring, a one-time addModule registration, and a CSS @property declaration so the angle is a typed custom property the browser can animate off-thread. The paint() function reads --ring-angle through the typed OM properties map, and because that property is the only thing in inputProperties, the browser re-invokes the painter only when the angle changes — which the CSS animation schedules on the compositor rather than in your JavaScript.

Before — main-thread rAF loop (repeated for reference):

const ring = document.querySelector('.ring');
let angle = 0;

function tick() {
  angle = (angle + 4) % 360;
  // dirties style + paint on the main thread every frame
  ring.style.background =
    `conic-gradient(from ${angle}deg, #4456a8 0deg, #7a5c95 140deg, transparent 320deg)`;
  requestAnimationFrame(tick);
}
tick();

After — a paint worklet driven by an animated registered property:

// ring-painter.js  (loaded into the PaintWorkletGlobalScope)
registerPaint('ring', class {
  // paint() re-runs ONLY when size or one of these properties changes
  static get inputProperties() { return ['--ring-angle']; }

  paint(ctx, geom, props) {
    const angle = parseFloat(props.get('--ring-angle')) || 0;
    const cx = geom.width / 2;
    const cy = geom.height / 2;
    const r = Math.min(cx, cy) - 6;

    ctx.lineWidth = 12;
    ctx.lineCap = 'round';
    ctx.strokeStyle = '#4456a8';
    ctx.beginPath();
    ctx.arc(cx, cy, r, -Math.PI / 2, -Math.PI / 2 + (angle * Math.PI) / 180);
    ctx.stroke();
  }
});

// main bundle — register the module exactly once, then never touch it again
if ('paintWorklet' in CSS) {
  await CSS.paintWorklet.addModule('/ring-painter.js');
}

/* declaring the property makes it typed and animatable off the main thread */
@property --ring-angle {
  syntax: '<number>';
  inherits: false;
  initial-value: 0;
}

.ring {
  width: 96px;
  height: 96px;
  background-image: paint(ring); /* drawn in the PaintWorkletGlobalScope, off the main thread */
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to { --ring-angle: 360; }
}

There is no requestAnimationFrame, no string building, and no inline-style write left on the main thread. The angle advances through the CSS animation of a registered custom property, the browser re-invokes paint() in the worklet scope, and the compositor rasterizes the result. If the browser lacks the Paint API, the if ('paintWorklet' in CSS) guard skips registration and you fall back to a static background — supply one in the base rule so the element is never blank. This is the same “isolate the work, invalidate narrowly” discipline behind Minimizing paint areas with layer boundaries; here the boundary is a whole thread rather than a layer.

The same pattern generalizes well beyond a ring. Any decoration you would otherwise build from stacked gradients, a blurred box-shadow that repaints a large region, or a JavaScript-driven <canvas> overlay is a candidate: checkerboards, ripple fills, dashed focus rings, noise textures, tooltip pointers. Each becomes one paint() call whose cost the browser can cache and whose execution never lands on the thread your interactions run on — which is exactly what keeps input responsive, as covered across Compositing and GPU Acceleration.

Verification checklist

• Performance trace during the animation shows no Recalculate Style or Paint entries for the decorated element on the Main lane.
• A Paint Worklet (or ring.paint) entry appears on the compositor lane, not the Main lane.
• CSS.paintWorklet.addModule() is called exactly once at startup, guarded by 'paintWorklet' in CSS.
• The painter lists every custom property it reads in static get inputProperties(); nothing it depends on is omitted.
• Animating the effect changes only a registered @property value — no inline-style writes remain in a requestAnimationFrame loop.
• A static background fallback renders acceptably when the Paint API is unavailable.
• Observing long tasks with PerformanceObserver reports no long tasks attributable to the animation.
• Main-thread idle time per frame recovers to within a few percent of the un-decorated baseline.

Frequently Asked Questions

Related Guides

• Off-Main-Thread Rendering — the parent topic covering every technique for keeping rendering work off the thread that runs your code.
• Why transform and opacity are GPU-accelerated — the compositor path that rasterizes your worklet’s display list.
• Minimizing paint areas with layer boundaries — scope invalidation so repaints stay small.
• Observing long tasks with PerformanceObserver — confirm the main-thread long tasks disappear after the switch.