CSS Paint API: Worklets

The CSS Paint API is a CSS Houdini feature that lets you write JavaScript worklet functions to programmatically generate backgrounds, borders, and masks — effectively extending what CSS background-image can render.

A Paint Worklet is a JavaScript file that runs in a separate worklet scope (not the main thread). It registers a custom CSS painter that can be used as a CSS value.

A worklet class implements the paint() method:

Load the worklet from your main JavaScript:

Reference the registered painter name in any property that accepts an image:

Painters can read CSS custom properties by declaring them as input properties:

The ctx parameter is a PaintRenderingContext2D — a restricted version of the Canvas 2D context. You use familiar methods: fillRect, arc, bezierCurveTo, etc.

CSS Paint API enables:

• Complex geometric backgrounds without SVG
• Variable-data backgrounds (progress bars, activity graphs)
• Ripple effects on buttons driven by custom properties
• Complex border effects (dashed, hatched)
• Wavy dividers and organic shapes

Paint worklets run off the main thread (in a separate worklet context) and repaint only when their CSS custom properties change. This is more efficient than Canvas-based drawing that runs on the main thread.

CSS Paint API is supported in Chrome 65+, Edge 79+. Firefox and Safari do not support it as of 2024. Use as a progressive enhancement.

Always provide a fallback and use @supports to apply the paint worklet only when supported:

The CSS Paint API allows JavaScript worklets to programmatically generate CSS images. Write a class with a paint() method, register it with registerPaint(), load it with CSS.paintWorklet.addModule(), and use it as background: paint(name). Painters can read CSS custom properties to create data-driven visuals. Provide fallbacks with @supports.