Rendering PipelineBaseline · Newly

CSS Houdini @property

Mental Model

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.

Interactive Simulator

Untyped --angle vs @property <angle>

Compare discrete snapping against continuous gradient angle interpolation.

Lines of Code
Before
6
After
8
Reflows / Browser Cost
Before
0 (discrete 50% flip)
After
0 (Paint per frame)
BeforeUntyped Custom Property
.ring {
  --angle: 0deg;
  background: conic-gradient(#3b82f6 var(--angle), #111 0);
  transition: --angle 400ms;
}
.ring:hover { --angle: 360deg; } /* Snaps! */
Lines: 6Reflows: 0 (discrete 50% flip)Dependencies: Token string only

Engine cannot interpolate raw tokens, so --angle jumps at 50%.

After (Native)Typed @property <angle>
@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; }
Lines: 8Reflows: 0 (Paint per frame)Dependencies: Native CSSOM type

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.

  1. Type Validation: Invalid assignments (like --angle: red) are rejected at parse time and fall back to initial-value.
  2. Interpolation: Knowing the type (<color>, <length>, <angle>, <number>) lets transitions and @keyframes compute intermediate values.
  3. Inheritance Opt-Out: Setting inherits: false stops style recalculations from propagating down large subtrees.
CSS
@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 requestAnimationFrame loops just to animate a gradient stop.
  • 2020–2024: CSS Properties and Values API (@property) reached Baseline Newly Available across all major engines.

Production Pitfalls

Production Pitfall
  • Missing descriptors: Omitting initial-value or inherits invalidates the entire @property rule silently.
  • Main-thread Paint cost: Animating a typed @property inside background still triggers Paint & Rasterization every frame, unlike transform or opacity.
When Not to Use
  • 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

Rendering PipelineCSS Houdini @property

Mechanical Comparisons