@property
Registers a CSS variable with a type, an initial value, and an inheritance rule. Such a variable can be animated smoothly, e.g. a gradient angle.
Example
#@property --angle {
syntax: "<angle>";
inherits: false;
initial-value: 0deg;
}
.card {
border: 3px solid transparent;
border-radius: 14px;
background:
linear-gradient(#18181b, #18181b) padding-box,
conic-gradient(from var(--angle), #7c3aed, #0ea5e9, #10b981, #7c3aed) border-box;
animation: spin 4s linear infinite;
}
@keyframes spin {
to { --angle: 360deg; }
}<div class="card" style="padding: 16px 18px;">
<strong>Premium account</strong>
<p style="margin: 4px 0 0; color: #a1a1aa;">All worlds unlocked, no fuel limit.</p>
</div>Definition and usage
#An ordinary CSS variable (--name) is just a string to the browser. The browser does not know that --angle: 45deg is an angle, so it cannot compute intermediate values and changes it in a single jump during an animation. The @property rule registers a variable with a specific type, and the browser then treats it like a real property.
Registration has three descriptors. syntax defines the type, e.g. "<angle>", "<color>", "<length>", "<number>", "<integer>", or "<percentage>", and "*" means any value. inherits says whether descendants inherit the value. initial-value is the default value, required for every type except "*". It must be computationally independent, so it cannot be e.g. 2em. The syntax and inherits descriptors are mandatory.
The biggest benefit is animation. In most browsers, swapping one gradient for another happens in a jump, but you can animate a registered variable that the gradient uses: the angle in conic-gradient(), a color stop position, or the color itself. An <integer> number combined with a CSS counter can even count smoothly from 0 to 100.
You can also register a variable from JavaScript with CSS.registerProperty(). The type also works as a safeguard: a value that does not match the type, e.g. a number in a <color> variable, is rejected and the variable takes the initial or inherited value.
Syntax
#@property --name {
syntax: "<type>";
inherits: true | false;
initial-value: <value>;
}Descriptors and types
#the bar fills smoothly
The--pvariable sets where the green color of the gradient ends. Thanks to registration with a percentage type, the bar fills smoothly.the bar jumps
The same animation without registration. The browser does not know the variable’s type, so instead of intermediate values it switches it from 0% to 100% halfway through.a rotating gradient
A variable holding an angle controls the starting point of a conic gradient (from var(--angle)). Animating the angle from 0 to 360 degrees gives a rotating ring.a counter from 0 to 100
An integer passed to a CSS counter (counter-reset) and displayed throughcontent. The animation counts smoothly from 0 to 100.a color in a gradient
You usually cannot transition the gradient itself smoothly, but a color stored in a registered variable you can. The left end goes from purple to amber.the child does not inherit
The parent sets--accentto green and has a green border, but the child does not inherit that value. It gets the initial value, which is gray. An ordinary unregistered variable would be green in the child.the value when nothing is set
Nobody has set the--radiusvariable, yet it has the value 24px frominitial-value. Without registration,var(--radius)would have nothing to insert and the rounding would disappear.
Descriptors and types in practice
#syntax: "<percentage>"
--p variable sets where the green color of the gradient ends. Thanks to registration with a percentage type, the bar fills smoothly.@property --p {
syntax: "<percentage>";
inherits: false;
initial-value: 0%;
}
.bar {
animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }without @property
.bar {
animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }syntax: "<angle>"
from var(--angle)). Animating the angle from 0 to 360 degrees gives a rotating ring.@property --angle {
syntax: "<angle>";
inherits: false;
initial-value: 0deg;
}
.ring {
animation: turn 2.5s linear infinite;
}
@keyframes turn { to { --angle: 360deg; } }syntax: "<integer>"
counter-reset) and displayed through content. The animation counts smoothly from 0 to 100.@property --n {
syntax: "<integer>";
inherits: false;
initial-value: 0;
}
.count {
counter-reset: n var(--n);
animation: count 3s infinite alternate;
}
@keyframes count { to { --n: 100; } }syntax: "<color>"
@property --c {
syntax: "<color>";
inherits: false;
initial-value: #7c3aed;
}
.swatch {
animation: tint 2s infinite alternate;
}
@keyframes tint { to { --c: #f59e0b; } }inherits: false
--accent to green and has a green border, but the child does not inherit that value. It gets the initial value, which is gray. An ordinary unregistered variable would be green in the child.@property --accent {
syntax: "<color>";
inherits: false;
initial-value: #52525b;
}
.parent {
--accent: #10b981;
border: 3px solid var(--accent);
}
.child { background: var(--accent); }initial-value
--radius variable, yet it has the value 24px from initial-value. Without registration, var(--radius) would have nothing to insert and the rounding would disappear.@property --radius {
syntax: "<length>";
inherits: false;
initial-value: 24px;
}
.tile { border-radius: var(--radius); }More examples
#@property --fill {
syntax: "<percentage>";
inherits: false;
initial-value: 0%;
}
.btn {
background: linear-gradient(90deg, #7c3aed var(--fill), #27272a var(--fill));
transition: --fill 0.4s ease-out;
}
.btn:hover {
--fill: 100%;
}<button class="btn" type="button" style="padding: 10px 18px; border: 0; border-radius: 10px; color: #fff; font: 600 15px system-ui, sans-serif; cursor: pointer;">Hover over me</button>Hover over the button. A registered variable can also be transitioned with an ordinary transition, not only with a @keyframes animation.
CSS.registerProperty({
name: '--angle',
syntax: '<angle>',
inherits: false,
initialValue: '0deg'
})It works the same as the @property rule. It is useful when a library registers the variables or when the type depends on data in a script.
Browser support
#Newly available · since 2024
Works in the current versions of all major browsers. Older versions may not support it.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Register only the variables you animate or want to give a type. Ordinary variables holding theme colors and spacing do not need registration.
- Register animated variables with
inherits: false. The browser then does not have to recompute their values in all descendants. - Make sure the result looks reasonable without the animation. An older browser without
@propertysupport will change the variable in a jump, but the gradient will still render.
Related entries
#- var()Inserts the value of a CSS variable, that is, a custom property written as --name. It also lets you provide a fallback value.
- @keyframesDefines the stages of an animation, known as keyframes.
- conic-gradient()Creates a colour transition around a point, like a clock hand. It draws pie charts, colour wheels, and rotating borders.
- transitionA shorthand that makes CSS value changes happen smoothly instead of abruptly.
- animationA shorthand that sets all the parameters of an animation based on @keyframes.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.