Welcome to Part 37 of the CSS Mastery & Responsive Layouts Course. In this part, we will explore CSS Houdini & Paint API.

For years, developers had to wait for browser vendors to implement new CSS properties and layout behaviors. CSS Houdini changes this by exposing the browser’s CSS engine internals to developers. Through a set of low-level APIs, Houdini allows you to hook directly into the browser’s styling, layout, and painting steps, making it possible to create highly performant custom styles and effects that run at 60 FPS natively.

---

Chapter 188: What is CSS Houdini?

CSS Houdini is a collection of APIs that give developers direct access to the CSS Object Model (CSSOM).

➤ The Houdini API Spectrum

Houdini includes several specifications:

• CSS Paint API: Write custom 2D canvas drawing logic for backgrounds, borders, and masks.
• Properties and Values API: Register custom properties with syntax definitions, inheritance rules, and initial values (enabling smooth transitions on custom properties).
• Typed OM: Interact with CSS values as JavaScript objects instead of strings (improving performance).
• Layout API & Worklets: Write custom layout behaviors (similar to grid or flexbox).

---

Chapter 189: The CSS Paint API (paint())

The Paint API lets you use canvas-like commands to draw directly into an element’s background or border image via a JavaScript Paint Worklet.

➥ Defining a Paint Worklet (JavaScript)

Create a separate file paint-worklet.js and register a paint class:

class BubblePaint {
  static get inputProperties() { return ['--bubble-color']; }
  
  paint(ctx, geom, properties) {
    const color = properties.get('--bubble-color').toString() || 'blue';
    const width = geom.width;
    const height = geom.height;
    
    ctx.fillStyle = color;
    ctx.beginPath();
    ctx.arc(width / 2, height / 2, Math.min(width, height) / 3, 0, 2 * Math.PI);
    ctx.fill();
  }
}
registerPaint('bubble-paint', BubblePaint);

➤ Calling the Paint Worklet in CSS

First, load the worklet in JavaScript, then invoke it inside CSS:

.card-bubbles {
  --bubble-color: #3b82f6;
  background-image: paint(bubble-paint); /* Call registered paint worklet */
}

---

Chapter 190: The Custom Properties API (CSS.registerProperty)

Normally, browsers treat custom properties as plain strings. Because of this, you cannot transition variables (e.g., transitioning --gradient-start from red to blue fails because the browser doesn’t know it represents a color).

➥ Registering Properties in JavaScript

By registering custom properties, you declare their type syntax:

CSS.registerProperty({
  name: '--gradient-start',
  syntax: '<color>',
  inherits: false,
  initialValue: '#ef4444',
});

➤ Registering Properties in CSS (@property)

You can also register properties directly in your CSS files using the @property rule:

@property --my-accent {
  syntax: '<color>';
  inherits: false;
  initial-value: #3b82f6;
}

.button {
  background-color: var(--my-accent);
  transition: --my-accent 0.5s ease; /* Browser can now animate this variable! */
}
.button:hover {
  --my-accent: #10b981;
}

---

Chapter 191: Houdini Practice & Self-Check

➥ Practice Exercises

1. Exercise 1: Animate a Custom Gradient Variable: Register two custom properties (--grad-1 and --grad-2) as <color> values using the @property rule. Create a box with a linear gradient background using these properties, and animate them on hover.

➤ Self-Check Questions

1. What is CSS Houdini?
   • Answer: A collection of low-level APIs that expose parts of the CSS engine directly to developers.
2. Which Houdini API allows drawing custom graphics directly in CSS?
   • Answer: The CSS Paint API.
3. What function loads a paint worklet script into JavaScript?
   • Answer: CSS.paintWorklet.addModule('path/to/worklet.js').
4. How is a registered paint worklet invoked inside CSS?
   • Answer: Using paint(worklet-name).
5. Why can’t default CSS variables be transitioned smoothly?
   • Answer: Because the browser treats them as plain strings and doesn’t know what data type (color, length, angle) they represent.
6. What CSS rule registers custom property definitions directly in stylesheets?
   • Answer: @property.
7. What parameter defines the type of value in @property?
   • Answer: syntax.
8. What are common values for the syntax property?
   • Answer: <color>, <length>, <percentage>, <angle>, <number>, <integer>.
9. What is Typed OM?
   • Answer: A low-level performance API that treats CSS values as structured JavaScript objects rather than strings.
10. Do Houdini worklets block the main browser thread?
    • Answer: No, worklets run on a separate background thread, preserving main thread scrolling and layout performance.