[FEE-11201] @property — Typed Custom Properties
INFO
Register a CSS custom property with a type and you unlock animation, safe fallbacks, and inheritance control. The browser then knows what the value means instead of treating it as an opaque string.
Baseline Newly Available
Supported in Chrome 85+, Firefox 128+, Safari 16.4+. Use progressive enhancement for older browsers.
Context
CSS custom properties (--color: red) are raw text. The browser stores whatever string you assign and substitutes it at computed-value time. This design was intentional: custom properties were conceived as a generic variable system, not a typed property system. Flexibility was the goal.
That flexibility has costs:
- No animation. A transition or
@keyframesrule that targets an untyped custom property does nothing. The browser cannot interpolate between two opaque strings. It does not know whether--hueis an angle, a color, or the word "purple", so it cannot compute a value at 37% of the transition. - No guaranteed initial value. If a rule references
var(--spacing)and--spacingwas never set in the current scope, the value is the empty string. Any property that receives that substitution becomes invalid at computed-value time, silently. The layout breaks with no error in the console. - Inheritance is always on. Every custom property inherits by default. A
--card-paddingset on a parent flows into every child element, including deeply nested children inside other components. Component-level variables bleed unless you manually reset them.
These costs show up as soon as you try to animate anything through a custom property. Build a button whose background hue should shift on hover, and transition: --hue 0.4s does nothing: the browser has two opaque strings, "220deg" and "280deg", and no way to interpolate between them. Example 1 below walks through the full fix.
@property is the CSS at-rule from CSS Houdini Properties & Values API Level 1 that solves all three problems. Declare a type, an initial value, and an inheritance policy, and the browser treats the property as a first-class typed value from that point on.
Visual
| Behavior | Unregistered custom property | Registered via @property |
|---|---|---|
| Stored value | Raw token string, untyped | Typed value matching syntax |
transition / @keyframes | Silently ignored, no interpolation | Interpolates per the declared type |
| Empty or invalid value | Empty string; can invalidate the whole declaration | Falls back to initial-value, no breakage |
| Inheritance | Always inherits into descendants | inherits: true | false, your choice |
Example
Example 1 — Gradient animation with a typed angle property
This is the canonical demo for @property. The left button has no registration; its hover transition does nothing. The right button registers --hue as <angle> and transitions smoothly.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — Gradient Animation</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 48px;
display: flex;
gap: 48px;
align-items: flex-start;
background: #f5f5f5;
}
.demo {
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
}
.label {
font-size: 0.875rem;
color: #555;
text-align: center;
}
/* Button base */
.btn {
padding: 14px 28px;
border: none;
border-radius: 8px;
font-size: 1rem;
font-weight: 600;
color: #fff;
cursor: pointer;
}
/* WITHOUT @property: transition is ignored */
.btn-unregistered {
--hue-start: 220;
background: hsl(220deg 80% 50%);
transition: --hue-start 0.4s ease; /* does nothing */
}
.btn-unregistered:hover {
background: hsl(280deg 80% 50%); /* instant jump */
}
/* WITH @property: transition interpolates the angle */
@property --hue {
syntax: '<angle>';
inherits: false;
initial-value: 220deg;
}
.btn-registered {
--hue: 220deg;
background: hsl(var(--hue) 80% 50%);
transition: --hue 0.4s ease;
}
.btn-registered:hover {
--hue: 280deg;
}
</style>
</head>
<body>
<div class="demo">
<button class="btn btn-unregistered">Hover me</button>
<p class="label">Without @property<br>Jumps instantly, no animation</p>
</div>
<div class="demo">
<button class="btn btn-registered">Hover me</button>
<p class="label">With @property<br>Smoothly animates hue 220deg → 280deg</p>
</div>
</body>
</html>The key insight: transition: --hue 0.4s is valid syntax on the unregistered button, but the browser has nothing to interpolate, so nothing happens. On the registered button, the browser knows --hue is an <angle>, so it generates intermediate values at each frame.
Example 2 — Component isolation with inherits: false
Registering a variable with inherits: false prevents it from bleeding into nested components. The outer card's spacing variable stays local; the inner card uses its own value independently.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — inherits: false</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 32px;
background: #f0f0f0;
}
/* Register spacing as a non-inheriting <length> */
@property --card-padding {
syntax: '<length>';
inherits: false;
initial-value: 16px;
}
/* Card component */
.card {
background: #fff;
border: 1px solid #ddd;
border-radius: 8px;
padding: var(--card-padding);
max-width: 400px;
}
.card .title {
font-size: 1rem;
font-weight: 700;
margin: 0 0 8px;
}
.card .body {
font-size: 0.875rem;
color: #555;
margin: 0;
}
/* Outer card: large padding */
.card-outer {
--card-padding: 32px;
}
/* Inner card: small padding */
.card-inner {
--card-padding: 12px;
margin-top: 16px;
background: #f9f9f9;
}
</style>
</head>
<body>
<div class="card card-outer">
<h2 class="title">Outer Card (padding: 32px)</h2>
<p class="body">
This card sets --card-padding: 32px. Because --card-padding
is registered with inherits: false, the inner card does not
inherit this value.
</p>
<div class="card card-inner">
<h2 class="title">Inner Card (padding: 12px)</h2>
<p class="body">
This card sets --card-padding: 12px independently.
Without inherits: false, it would have inherited 32px
from the outer card.
</p>
</div>
</div>
</body>
</html>Without @property, the inner .card-inner would need to explicitly reset --card-padding to avoid inheriting the outer value. With inherits: false, the inner card starts from initial-value (16px) by default. It only shows --card-padding: 12px because its own declaration sets that value; the outer card's 32px never reaches it.
Example 3 — Animated conic-gradient progress ring
Registering the hue in Example 1 is a demo; registering an angle to drive a conic-gradient() is the pattern most teams actually reach for: progress rings, loading spinners, and animated gradient borders. Before @property, animating the gradient fill of any of these required JavaScript to update the value each frame, because a gradient function call is a single opaque string and two different angle values produce two different strings with nothing to interpolate between.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@property — Conic-Gradient Progress Ring</title>
<style>
body {
font-family: system-ui, sans-serif;
padding: 48px;
background: #f5f5f5;
}
@property --angle {
syntax: '<angle>';
inherits: false;
initial-value: 0deg;
}
.ring {
width: 160px;
height: 160px;
border-radius: 50%;
background: conic-gradient(#4f46e5 var(--angle), #e5e7eb 0deg);
transition: --angle 1.2s ease;
}
.ring.loaded {
--angle: 270deg;
}
</style>
</head>
<body>
<div class="ring" id="progress"></div>
<script>
// Trigger the transition after the first paint so the browser
// has a committed "from" value (0deg) to interpolate from.
requestAnimationFrame(() => {
document.getElementById('progress').classList.add('loaded');
});
</script>
</body>
</html>Register --angle as <angle>, transition --angle, and the conic-gradient() stop recomputes on every frame because the browser is animating the typed value feeding it, not the gradient string itself. Temani Afif's write-ups on animating CSS gradients popularized this recipe.
Best Practices
- MUST register any custom property that will be animated with
transitionor@keyframes. An unregistered property cannot be interpolated; the animation silently does nothing. - MUST provide
initial-valuewheninherits: false. The spec requires it: without a fallback, the browser has no safe value to use when the property is unset. - SHOULD set
inherits: falsefor component-scoped theming variables that MUST NOT propagate to descendant components. Explicit non-inheritance prevents silent bleed between components sharing the same variable name. - SHOULD prefer the
@propertyat-rule form overCSS.registerProperty()for static declarations that do not change at runtime. The at-rule lives with your other CSS, requires no script execution order management, and is easier to audit. - SHOULD use typed custom properties inside CSS math. Registering
--spacingas<length>gives you a computed, type-checked length and a guaranteedinitial-valuefallback. An unregistered--spacingstill works incalc()when its value is a valid length, but a malformed or unset value silently invalidates the whole declaration with no fallback. - SHOULD NOT use
syntax: '*'when a more specific type is available. The wildcard type behaves like an unregistered property for animation and type safety; you gain only theinitial-valueguarantee.
Design Thinking
Why custom properties are strings
CSS custom properties were introduced in CSS Custom Properties for Cascading Variables Module Level 1 (2012–2015). The design goal was a lightweight variable mechanism compatible with the existing cascade. The browser stores the raw token sequence verbatim and substitutes it wherever var(--name) appears, without parsing the value. This allows a single custom property to be used in any declaration context. You can assign a length to --x in one rule and a color to --x in another.
The downside: the browser cannot reason about the value. It does not know what type it holds, so it cannot perform typed operations such as animation, clamping, or arithmetic validation.
The gradient animation problem
This is the most common surprise with custom properties. A developer writes:
.button {
background: linear-gradient(var(--from-color), var(--to-color));
transition: background 0.4s;
}The transition on background does not work. linear-gradient(red, blue) and linear-gradient(blue, red) are different string values; the browser treats them as discrete, not interpolable. Gradients cannot be animated by transitioning background.
The fix is to animate a typed property inside the gradient, not the gradient itself. Example 1 registers --hue and transitions it instead of the hsl() output; Example 3 does the same thing for a conic-gradient() stop. In both cases the color function recomputes from the interpolated typed value on every frame.
Houdini lineage
@property originates from the CSS Houdini task force, a joint W3C effort to expose browser rendering internals to JavaScript. The Properties & Values API Level 1 originally specified CSS.registerProperty() as a JavaScript method; the @property at-rule was added later as a pure-CSS declaration form with identical semantics. Firefox shipped both CSS.registerProperty() and the @property at-rule together in version 128, released July 2024. Chrome shipped CSS.registerProperty() in version 78 and the @property at-rule in version 85, and Safari shipped both forms in 16.4.
Type checking and silent fallback
When a registered property receives a value that does not match its declared syntax, the browser reverts to initial-value. No error is thrown. For example, if --brand-hue is registered as <angle> and a rule sets --brand-hue: potato, the browser silently uses 220deg (or whatever initial-value is). This is intentional. The cascade should not break outright due to a type mismatch: it should degrade gracefully to a known value instead.
Deep Dive
Full syntax value types
@property supports the following syntax descriptors:
| Type | Example values |
|---|---|
<color> | red, #ff0, hsl(200 80% 50%) |
<length> | 16px, 1rem |
<length-percentage> | 50%, calc(100% - 16px) |
<number> | 0, 1.5, -3 |
<percentage> | 50%, 100% |
<angle> | 90deg, 1rad, 0.5turn |
<time> | 200ms, 1s |
<resolution> | 96dpi, 2dppx |
<transform-function> | rotate(45deg), scale(1.5) |
<transform-list> | rotate(45deg) scale(1.5) |
<image> | url(...), gradient functions |
<url> | url(image.png) |
<integer> | 0, 42, -1 |
<custom-ident> | Any valid CSS identifier |
<string> | "hello" |
* | Any value (same as unregistered) |
Note that <length> alone rejects percentages: a property registered as syntax: '<length>' treats 50% as invalid and falls back to initial-value. Use <length-percentage> when a value may be either.
List syntax variants are also supported: <color>+ means one or more space-separated colors; <length># means one or more comma-separated lengths.
@property vs CSS.registerProperty()
Both forms are semantically identical. The at-rule is preferred for static declarations because it lives with your CSS, requires no script, and is not subject to JavaScript execution order. Use CSS.registerProperty() when you need to register properties dynamically, for example when a component framework generates variable names at runtime.
// JS form, identical semantics to the @property at-rule
CSS.registerProperty({
name: '--brand-hue',
syntax: '<angle>',
inherits: false,
initialValue: '220deg'
});Note the camelCase initialValue in the JS API vs the hyphenated initial-value in the at-rule.
@property is global, not layer-scoped
Registered properties are global. Placing @property inside a @layer block does not scope it to that layer: the registration still applies to the entire document. This is consistent with how @keyframes and @font-face work inside layers. Plan your property names accordingly to avoid cross-component conflicts.
Type checking behavior
When a typed property receives an invalid value, it falls back to initial-value silently. This is distinct from a regular invalid CSS value, which falls back to the inherited value or the property's own initial. For registered properties, the explicit initial-value declaration is the authoritative fallback.
@property --opacity-level {
syntax: '<number>';
inherits: false;
initial-value: 1;
}
.element {
--opacity-level: not-a-number; /* invalid for <number> */
opacity: var(--opacity-level); /* resolves to 1, the initial-value */
}Progressive enhancement
CSS.registerProperty() and the @property at-rule are both supported in all modern browsers. For projects that must support older environments, the at-rule can be guarded with a @supports check:
@supports (syntax: '<angle>') {
@property --hue {
syntax: '<angle>';
inherits: false;
initial-value: 220deg;
}
.btn {
--hue: 220deg;
background: hsl(var(--hue) 80% 50%);
transition: --hue 0.4s ease;
}
}
/* Fallback for browsers without @property */
.btn {
background: hsl(220deg 80% 50%);
}
.btn:hover {
background: hsl(280deg 80% 50%);
}Browsers without @property receive the static fallback colors. Browsers with support receive the animated version.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 85 | Via CSS Properties and Values API |
| Firefox | 128 | Both @property and CSS.registerProperty() shipped together |
| Safari | 16.4 | Both at-rule and JS form |
| Edge | 85 | Chromium-based |
Feature detection in CSS:
@supports (syntax: '<angle>') {
/* @property at-rule is supported */
}Feature detection in JavaScript:
const supportsRegisterProperty = 'registerProperty' in CSS;As of 2026, @property is Baseline Newly Available across all major browsers. The last holdout was Firefox, which shipped both the @property at-rule and CSS.registerProperty() together in version 128, released July 2024; there is no Firefox version where one form works and the other does not. For projects that must support pre-128 Firefox, guard the at-rule with the @supports (syntax: '<angle>') check shown above and ship a static fallback, since neither registration form is available before 128.
Related Topics
- FEE-11200 CSS @scope:
@scopeand@propertyare complementary for component theming. Use@propertyto register typed, non-inheriting custom properties, then use@scopeto scope which elements receive initial values via:scope. Together they give you fully typed, component-local theming variables without Shadow DOM. - FEE-11002 Container Queries: CSS style queries (
@container style(--variant: featured)) query custom property values on a container. Registering those properties via@propertyensures type safety and predictable fallback behavior in style query conditions.
References
- MDN contributors, "@property," MDN Web Docs (2024). https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@property
- Una Kravets, "@property: giving superpowers to CSS variables," web.dev (2020). https://web.dev/articles/at-property
- Una Kravets, "@property: Next-gen CSS variables now with universal browser support," web.dev (2024). https://web.dev/blog/at-property-baseline
- Tab Atkins-Bittner, Alan Stearns, and Greg Whitworth (eds.), "CSS Properties and Values API Level 1," W3C Houdini Task Force, Editor's Draft. https://drafts.css-houdini.org/css-properties-values-api/
- Temani Afif, "We Can Finally Animate CSS Gradient," DEV Community (2021, updated 2024). https://dev.to/afif/we-can-finally-animate-css-gradient-kdk