References

Beginner-friendly references for web development, with live, editable examples.

The CSS @property at-rule

At-rule CSS All modern browsers Updated
Quick answer

The CSS @property at-rule registers a custom property with a syntax (its type), an initial-value and whether it inherits. The big payoff: a typed custom property can be animated. Registering --angle as an <angle> lets you animate a gradient's rotation — something a plain custom property cannot do.

Overview

A plain custom property is just a string as far as the browser is concerned, which is why you cannot animate one — the browser has no idea how to interpolate between two unknown values. @property fixes that by giving a custom property a real type.

You register it with three descriptors: syntax (the value type, written like "<angle>", "<color>" or "<length>"), an initial-value (a fallback when none is set), and inherits (true or false). Once a property is typed, the browser knows how to animate it — which unlocks effects that were impossible before, like a smoothly rotating conic-gradient driven by an animated --angle.

Beyond animation, registration adds a bit of safety: an invalid value falls back to the initial-value instead of breaking, and the type is enforced. You can also register a property from JavaScript with CSS.registerProperty(), but the @property at-rule keeps it declarative and in your stylesheet where it belongs.

Syntax

@property --angle {
  syntax: "<angle>";
  initial-value: 0deg;
  inherits: false;
}

@keyframes spin { to { --angle: 360deg; } }
.ring {
  background: conic-gradient(from var(--angle), #1c7ce9, #6d28d9, #1c7ce9);
  animation: spin 3s linear infinite;
}

Example

Live example 
<style>
  @property --a { syntax: "<angle>"; initial-value: 0deg; inherits: false; }
  @keyframes spin { to { --a: 360deg; } }
  .ring {
    width: 96px; height: 96px; border-radius: 50%;
    margin: 14px auto;
    background: conic-gradient(from var(--a), #1c7ce9, #6d28d9, #1c7ce9);
    animation: spin 3s linear infinite;
  }
</style>
<div class="ring"></div>

Best practices

  • Register a custom property with @property when you need to animate or transition it.
  • Always provide an initial-value so an invalid or missing value falls back gracefully.
  • Set inherits deliberately — true to flow down the tree, false to stay local.
  • Write the syntax string with CSS value-type names like <color>, <length> or <angle>.

Frequently asked questions

What is @property in CSS?
An at-rule that registers a custom property with a type, an initial value and inheritance, which lets the browser animate the property.
How do I animate a CSS variable?
Register it with @property and a syntax type (e.g. "<angle>"), then animate it in @keyframes. Plain unregistered variables cannot be animated.
What does the syntax descriptor do?
It declares the property's value type, like "<color>" or "<length>", so the browser knows how to validate and interpolate it.
What is the difference between @property and a plain --variable?
A plain custom property is an untyped string and cannot be animated. @property gives it a type, an initial value and inheritance, which enables animation and type safety.
@page @supports