CSS at-ruleAt-rules

@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.

On this page

Example

#
CSS
@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; }
}
Preview

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

#
Syntax
@property --name {
  syntax: "<type>";
  inherits: true | false;
  initial-value: <value>;
}

Descriptors and types

#
  • syntax: "<percentage>"

    the bar fills smoothly

    The --p variable sets where the green color of the gradient ends. Thanks to registration with a percentage type, the bar fills smoothly.
  • without @property

    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.
  • syntax: "<angle>"

    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.
  • syntax: "<integer>"

    a counter from 0 to 100

    An integer passed to a CSS counter (counter-reset) and displayed through content. The animation counts smoothly from 0 to 100.
  • syntax: "<color>"

    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.
  • inherits: false

    the child does not inherit

    The parent sets --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.
  • initial-value

    the value when nothing is set

    Nobody has set the --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.

Descriptors and types in practice

#

syntax: "<percentage>"

The --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

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.
.bar {
  animation: fill 2s infinite alternate;
}
@keyframes fill { to { --p: 100%; } }

syntax: "<angle>"

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.
@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

.ring {
  animation: turn 2.5s linear infinite;
}
@keyframes turn { to { --angle: 360deg; } }

syntax: "<integer>"

An integer passed to a CSS counter (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>"

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.
@property --c {
  syntax: "<color>";
  inherits: false;
  initial-value: #7c3aed;
}

.swatch {
  animation: tint 2s infinite alternate;
}
@keyframes tint { to { --c: #f59e0b; } }

inherits: false

The parent sets --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

Nobody has set the --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

#
A button that fills on hover
CSS
@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%;
}
Preview

Hover over the button. A registered variable can also be transitioned with an ordinary transition, not only with a @keyframes animation.

Registration from JavaScript
JavaScript
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 @property support will change the variable in a jump, but the gradient will still render.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.