CSS Houdini @property
Standard CSS custom properties are untyped token streams, the engine cannot interpolate them. @property registers a variable's syntax, inherits flag, and initial-value, enabling smooth transitions on gradients, angles, and numbers while curbing unnecessary inheritance work.
Untyped --angle vs @property <angle>
Compare discrete snapping against continuous gradient angle interpolation.
.ring {
--angle: 0deg;
background: conic-gradient(#3b82f6 var(--angle), #111 0);
transition: --angle 400ms;
}
.ring:hover { --angle: 360deg; } /* Snaps! */Engine cannot interpolate raw tokens, so --angle jumps at 50%.
@property --angle {
syntax: '<angle>'; inherits: false; initial-value: 0deg;
}
.ring {
background: conic-gradient(#3b82f6 var(--angle), #111 0);
transition: --angle 400ms;
}
.ring:hover { --angle: 360deg; }Engine parses --angle as an angle and interpolates smoothly.
Under the Hood
Without @property, --angle: 45deg is just a sticky note with characters scribbled on it; @property turns it into a typed dial the Browser Rendering Pipeline can turn smoothly.
- Type Validation: Invalid assignments (like
--angle: red) are rejected at parse time and fall back toinitial-value. - Interpolation: Knowing the type (
<color>,<length>,<angle>,<number>) lets transitions and@keyframescompute intermediate values. - Inheritance Opt-Out: Setting
inherits: falsestops style recalculations from propagating down large subtrees.
@property --glow-alpha {
syntax: '<number>';
inherits: false;
initial-value: 0.2;
}
.card {
box-shadow: 0 0 24px rgb(59 130 246 / var(--glow-alpha));
transition: --glow-alpha 250ms ease;
}
.card:hover { --glow-alpha: 0.8; }Problem Genealogy
- 2016–2020: CSS Variables shipped as untyped substitutions, forcing JS
requestAnimationFrameloops just to animate a gradient stop. - 2020–2024: CSS Properties and Values API (
@property) reached Baseline Newly Available across all major engines.
Production Pitfalls
- Missing descriptors: Omitting
initial-valueorinheritsinvalidates the entire@propertyrule silently. - Main-thread Paint cost: Animating a typed
@propertyinsidebackgroundstill triggers Paint & Rasterization every frame, unliketransformoropacity.
- When not to use
@property: Do not register static design tokens that never animate and need normal inheritance; plain custom properties are lighter.
Connections & Logical Next Steps
Type registration changes how the Style phase parses and interpolates custom properties.
Interpolated @property values drive smooth gradient and color repaints across frames.
Untyped custom properties defer validation to var() substitution, whereas @property type-checks at parse time.