@property directive

untyped CSS var → typed @property: the upgrade

A plain custom property like --angle: 0deg is, to the browser, an untyped string. It can hold "0deg" or "banana" — the engine has no idea it is an angle, so it cannot interpolate it. Animate it and the value just snaps between keyframes. @property registers the property with the engine: a syntax type, an initial-value, and an inherits flag. Now the browser knows how to glide from 0deg to 360deg in smooth steps. Tailwind v4 emits @property for its theme tokens for exactly this reason.

1 · animated spinner — @property --angle + @keyframes

The circle below rotates by reading var(--angle) in its transform. The @keyframes spin-typed animation animates --angle itself from 0deg to 360deg. This only works because @property --angle told the browser that --angle is an <angle>, so it can interpolate. The live readout samples the computed value every frame — watch the degrees climb smoothly.

Why not just animate transform directly? You can — but @property lets you animate the angle value itself and reuse it elsewhere (a second spinner, a gradient stop, a clip-path) all driven by one variable. It composes; raw transform animations do not.

2 · with vs without @property — same keyframes, different physics

Two identical spinners, identical @keyframes (0deg → 360deg, 1.4s linear infinite). The ONLY difference: the left registers --angle with @property; the right uses an unregistered --raw-angle. Watch them — and watch the live value samplers. The left glides through dozens of distinct angles; the right snaps between just two values (so 0deg↔360deg look identical and the spinner appears frozen).

3 · animated gradient on hover — @property + transition

Hover (or tap) each card. The top card registers --grad-pos as <percentage> and transition: --grad-pos .6s ease — the gradient stop glides. The bottom card uses an unregistered --grad-pos-raw with the same transition rule — but the transition is ignored, so the stop snaps instantly. Same CSS, only the @property block differs.

4 · syntax types — what you can register

The syntax descriptor is the heart of @property. It accepts a single type, a multi-value list (+ or #), or the universal *.

Gotcha: <integer>, <url>, and * animate discretely even when registered — there is no smooth path between two URLs or two integers. Use <number> if you want smooth numeric steps.

5 · inheritance + the JS twin (CSS.registerProperty)

Plain custom properties always inherit — a child sees the parent's value whether you want it to or not. @property makes this explicit with inherits: false (default for most tokens — avoids accidental cascade leakage) or inherits: true (for theme-level vars like --color-brand that should propagate).

6 · how Tailwind v4 uses @property internally

Tailwind v4's generated CSS emits @property for its theme tokens so they are typed, have safe initial values, and don't leak via inheritance. This is why bg-blue-500 resolves cleanly and why var(--color-blue-500) has a sensible fallback when unset. (Illustrative — not live-compiled by this page.)

Net effect: every Tailwind color/spacing/radius token is a registered custom property, so they resolve predictably and compose safely with your own var() usage. See oklch_colors for the values themselves.

intent → pattern