CSS Paint Worklet is part of the CSS Houdini family of APIs. It allows developers to programmatically generate images using JavaScript that can be used anywhere CSS expects an image — like background-image, border-image, or mask-image. The worklet runs on a separate thread and renders into a PaintRenderingContext2D, similar to Canvas 2D. Use paint(workletName) in your CSS to invoke it.

Chrome 65+ Edge 79+ Opera 52+ Firefox ❌ Safari ❌

As of 2025, Chromium-based browsers fully support the Paint API. Firefox and Safari have not yet implemented it. You can feature-detect using if ('paintWorklet' in CSS).

There are two ways: 1) CSS Custom Properties — define inputProperties: ['--my-color'] in registerPaint(), then set --my-color: red in CSS. Access via properties.get('--my-color') in the paint() method. 2) Arguments — define inputArguments: ['<number>'] and pass values directly: paint(worklet, 5). Properties auto-trigger repaint when changed; arguments require explicit updates.

The PaintRenderingContext2D is a subset of the full Canvas 2D API. Limitations include: no text rendering (fillText), no drawImage, no pixel manipulation (getImageData/putImageData), no pattern creation, no shadow properties, and no globalCompositeOperation. The worklet also cannot access the DOM, use setTimeout, or make network requests. It's designed for pure, stateless image generation.

Paint Worklets are highly performant for dynamic, resolution-independent graphics. Since they run off the main thread and render at the device's native resolution, they're ideal for responsive patterns, gradients, and procedural textures. They automatically repaint when CSS custom properties change, making them more efficient than JavaScript-driven Canvas overlays. For static images, traditional formats may still be more appropriate, but for dynamic, parametric graphics, Paint Worklets excel.

Yes! You can layer multiple paint worklets using CSS layering techniques. For example, use one worklet for background-image, another for border-image, and yet another for mask-image. You can also use ::before and ::after pseudo-elements, each with their own paint() calls. Each worklet runs independently, allowing complex compositions purely in CSS.