CSS Houdini: Paint API and Properties API

The plain-language idea

Normally, a new CSS capability follows the same path: someone proposes it, browsers implement it independently, and developers wait — often years — for it to become safe to rely on. CSS Houdini is a set of lower-level browser APIs that sidesteps that wait for specific problems by exposing pieces of the browser's own CSS rendering engine directly to JavaScript. Instead of simulating a visual effect in JS and hoping it looks close enough to native CSS, you register your own behavior and the browser treats it as a genuine, first-class part of the rendering pipeline — the same pipeline that paints borders, animates opacity, and lays out grid.

Houdini is a large, still-evolving collection of separate APIs, and most of it remains niche or experimental. This lesson covers the two pieces that are the most established and the most likely to show up in real work:

• The Properties API — lets you declare a custom property's type, so the browser can animate it.
• The Paint API — lets you write a small JavaScript "painter" that draws directly into an element's background or border.

See it in a real thing: a custom property that can animate, and a background the browser paints for you

A plain custom property has no declared type — as far as the browser is concerned, --progress: 0 and --progress: 100 are just two arbitrary strings, and there's no way to interpolate between two arbitrary strings. That's why animating an untyped custom property doesn't work. The Properties API fixes this by letting you register a type:

@property --progress {
  syntax: "<number>";
  inherits: false;
  initial-value: 0;
}

.bar {
  width: calc(var(--progress) * 1%);
  transition: --progress 0.4s ease;
}

Once --progress is declared as a <number>, the browser knows how to smoothly interpolate between 0 and 100 the same way it interpolates width or opacity — the transition on .bar genuinely animates the property, not just snaps between values. (CSS.registerProperty() does the same thing from JavaScript, for cases where the type needs to be registered dynamically rather than declared statically in a stylesheet.)

The Paint API solves a different problem: drawing a custom visual pattern without exporting an SVG or image file. You register a "paint worklet" — a small piece of JavaScript that runs in its own isolated context and draws directly into a paint() value:

// paint-worklet.js
class CheckerPainter {
  paint(ctx, size) {
    const tile = 20;
    for (let y = 0; y < size.height; y += tile) {
      for (let x = 0; x < size.width; x += tile) {
        if ((x / tile + y / tile) % 2 === 0) {
          ctx.fillStyle = "rgba(0,0,0,0.06)";
          ctx.fillRect(x, y, tile, tile);
        }
      }
    }
  }
}
registerPaint("checkerboard", CheckerPainter);

.panel {
  background: paint(checkerboard);
}

ctx is a restricted 2D canvas-like context, and paint() re-runs it automatically whenever the element resizes — no manual redraw logic, no image asset to generate and ship. It's a programmatic, parameterized pattern generator that lives entirely in CSS and a small worklet file.

What people usually miss

Watch out

• The Properties API's whole value proposition is animatability, not organization. Plain custom properties (covered earlier in this track) already cascade and inherit fine without Houdini — @property only matters when you specifically need a custom property to interpolate smoothly during a transition or animation, which untyped custom properties fundamentally cannot do.
• @property and CSS.registerProperty() are the same registration, two syntaxes. The at-rule form is declarative and lives in a stylesheet; the JS form is imperative and useful when the type needs to be computed or registered conditionally. Neither one is "the real API" with the other as a shortcut — they're equivalent entry points.
• The Paint API only draws into the background/border layer — it's not a general replacement for canvas or SVG illustration. It's well-suited to repeatable, parameterized patterns (textures, custom borders, generative decoration) driven by CSS custom properties, not for arbitrary complex graphics.
• Most of Houdini beyond these two APIs is genuinely still experimental or has limited adoption — the Layout API and the Animation Worklet, in particular, solve real problems on paper but aren't something to reach for as a default tool yet. Treat this lesson as orientation to what Houdini is, not a signal that the whole API surface is safe to build on.
• A paint worklet needs to be registered before it's used, via CSS.paintWorklet.addModule("paint-worklet.js") in your page's JavaScript — forgetting this step is the most common reason a paint() background silently does nothing.

Why this matters in interviews

"Why can't you animate a CSS custom property with a plain transition?" is a real question that tests whether a candidate understands why untyped values can't interpolate — and knowing @property exists as the fix, rather than reaching for a JavaScript-driven animation as the only way out, signals genuine depth past the beginner explanation of custom properties.