CSS Paint API: Worklets
Create custom CSS background images and borders programmatically using Paint Worklets.
CSS Paint API: Worklets is a free CSS Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What is the CSS Paint API?
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.
Paint Worklet Architecture
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.
Writing a Paint Worklet
A worklet class implements the paint() method:
// checkerboard.js
class CheckerboardPainter {
paint(ctx, size, properties) {
const tileSize = 20;
for (let x = 0; x < size.width; x += tileSize) {
for (let y = 0; y < size.height; y += tileSize) {
ctx.fillStyle = (Math.floor(x/tileSize) + Math.floor(y/tileSize)) % 2 === 0
? "#fff" : "#ddd";
ctx.fillRect(x, y, tileSize, tileSize);
}
}
}
}
registerPaint("checkerboard", CheckerboardPainter);Registering the Worklet
Load the worklet from your main JavaScript:
CSS.paintWorklet.addModule('./checkerboard.js');Using the Painter in CSS
Reference the registered painter name in any property that accepts an image:
.grid {
background: paint(checkerboard);
}Receiving CSS Custom Properties
Painters can read CSS custom properties by declaring them as input properties:
class ColorPainter {
static get inputProperties() { return ["--primary", "--secondary"]; }
paint(ctx, size, properties) {
ctx.fillStyle = properties.get("--primary");
ctx.fillRect(0, 0, size.width/2, size.height);
ctx.fillStyle = properties.get("--secondary");
ctx.fillRect(size.width/2, 0, size.width/2, size.height);
}
}The canvas-like API
The ctx parameter is a PaintRenderingContext2D — a restricted version of the Canvas 2D context. You use familiar methods: fillRect, arc, bezierCurveTo, etc.
Use Cases
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 Worklet Performance
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.
Browser Support
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.
@supports for Graceful Degradation
Always provide a fallback and use @supports to apply the paint worklet only when supported:
.element {
background: linear-gradient(...);
/* fallback */
}
@supports (background: paint(worklet)) {
.element {
background: paint(my-painter);
}
}Quick Check
What method does a CSS Paint Worklet class implement to perform drawing?
Recap
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.
Frequently asked questions
Is the “CSS Paint API: Worklets” lesson free?
Yes — the full text of “CSS Paint API: Worklets” is free to read here on the web, and the CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the CSS Academy course, upgrade to CoddyKit PRO.
What will I learn in “CSS Paint API: Worklets”?
Create custom CSS background images and borders programmatically using Paint Worklets. You practise CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start CSS Academy?
No prior experience is required. CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “CSS Paint API: Worklets” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this CSS Academy lesson?
Yes. Every CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.