CSS Houdini APIs
CSS Houdini is a set of low-level browser APIs that let developers directly control the CSS rendering engine. It allows custom layouts, styles, animations, and properties without heavy JavaScript.
- Paint API: Draw custom graphics for backgrounds, borders, and masks.
- Layout API: Create new layout algorithms beyond Flexbox/Grid.
- Properties & Values API: Define typed CSS variables with validation.
- Animation Worklet: High-performance animations in the rendering pipeline.
CSS Houdini Paint API: Custom Rendering
The Paint API allows you to draw custom graphics directly in CSS using a JavaScript paint worklet, reducing reliance on JavaScript for styling.
<div class="box">Custom Gradient Border</div>
<script>
CSS.paintWorklet.addModule('gradient-border.js');
</script>
.box {
width: 200px;
height: 100px;
border: 10px solid;
border-image: paint(gradient-border) 10;
}
Paint Worklet (gradient-border.js)
registerPaint('gradient-border', class {
paint(ctx, size) {
const gradient = ctx.createLinearGradient(0, 0, size.width, size.height);
gradient.addColorStop(0, 'blue');
gradient.addColorStop(1, 'purple');
ctx.fillStyle = gradient;
ctx.fillRect(0, 0, size.width, size.height);
}
});
Layout Worklet
Define custom layout algorithms like masonry, circular, or grid variations.
Example:
<div class="container">
<div class="item">1</div>
<div class="item">2</div>
<div class="item">3</div>
<div class="item">4</div>
</div>
.container {
display: layout(masonry); /* Requires a custom layout worklet */
gap: 10px;
}
.item {
background-color: lightblue;
padding: 20px;
border-radius: 8px;
text-align: center;
}
Animation Worklet
Enables high-performance animations tied to scroll, timeline, or custom triggers.
Example:
registerAnimator('scroll', class {
animate(context, timeline) {
// Scroll-driven animation logic
const progress = timeline.currentTime / timeline.duration;
context.element.style.transform = `translateX(${progress * 100}px)`;
}
});
Properties & Values Worklet
Allows custom CSS properties with type validation and dynamic behavior.
Example:
CSS.registerProperty({
name: '--custom-radius',
syntax: '<length>',
inherits: false,
initialValue: '10px'
});
Animated Example
Animate a custom property for a spinner element:
<div class="spinner"></div>
/* Register a custom property for rotation */
@property --spin-angle {
syntax: '<angle>';
inherits: false;
initialValue: 0deg;
}
/* Spinner element using the custom property */
.spinner {
--spin-angle: 0deg;
width: 100px;
height: 100px;
border: 8px solid lightgray;
border-top-color: steelblue;
border-radius: 50%;
animation: spin 2s linear infinite;
transform: rotate(var(--spin-angle));
}
/* Animate the custom property */
@keyframes spin {
to { --spin-angle: 360deg; }
}