CSS Painting API (Houdini)
The CSS Painting API is part of the CSS Houdini project. It allows developers to write JavaScript functions that can draw directly into an element's background, border, or content image. Essentially, it lets you create custom CSS images programmatically.
1. The Concept
Traditionally, if you wanted a complex background pattern that CSS gradients couldn't handle, you had to use an image (PNG/SVG) or a <canvas> element. The CSS Painting API allows you to define a "painter" in JavaScript that the browser calls whenever it needs to paint an element.
This runs in a Worklet, which is a lightweight version of a Web Worker.
2. Defining a Paint Worklet
You create a separate JavaScript file (e.g., checkerboard.js) and define a class with a paint() method.
// checkerboard.js
class CheckerboardPainter {
// Define input properties (CSS variables) we want to access
static get inputProperties() {
return ['--checker-size', '--checker-color'];
}
paint(ctx, geometry, properties) {
// ctx: Similar to Canvas 2D context (subset)
// geometry: { width, height } of the area
// properties: Map of input properties
const size = parseInt(properties.get('--checker-size').toString()) || 20;
const color = properties.get('--checker-color').toString() || 'black';
ctx.fillStyle = color;
for (let y = 0; y < geometry.height / size; y++) {
for (let x = 0; x < geometry.width / size; x++) {
if ((x + y) % 2 === 0) {
ctx.fillRect(x * size, y * size, size, size);
}
}
}
}
}
// Register the painter
registerPaint('checkerboard', CheckerboardPainter);3. Registering the Worklet
In your main JavaScript file, you load the worklet module.
// main.js
if ('paintWorklet' in CSS) {
CSS.paintWorklet.addModule('checkerboard.js');
}4. Using it in CSS
Once registered, you can use the paint() function in CSS wherever an image is expected (like background-image or border-image).
.my-element {
width: 300px;
height: 300px;
/* Set custom properties */
--checker-size: 30;
--checker-color: red;
/* Use the painter */
background-image: paint(checkerboard);
}5. Advantages
- Performance: Runs off the main thread (in the worklet).
- Scalability: Like SVG, it's drawn programmatically, so it looks crisp at any resolution.
- Responsiveness: It automatically redraws when the element resizes or when input properties (CSS variables) change.
- Small Size: Code is usually much smaller than an equivalent image file.
programming/javascript/vanilla/javascript programming/javascript/vanilla/canvas-api programming/javascript/vanilla/web-workers