Before diving in, you need to be comfortable with a few ideas. If any of these are new, read the short explanation given here · then carry on.

What is a CSS Variable (Custom Property)?

A CSS variable is a name you create yourself, starting with two dashes · , that stores a value you can reuse.

/* Storing a colour in a variable */
:root {
  --brand-colour: tomato;
}

/* Using it */
h1 {
  color: var(--brand-colour);
}

Output (visual): The <h1> heading appears in the colour tomato (a vivid red-orange).

The problem: The browser treats regular CSS variables as plain text strings · it just does a find-and-replace. It has no idea the value is a colour, a number, or a length. This means it cannot smoothly transition between two variable values during an animation.

What is a CSS Transition?

A CSS transition smoothly changes a property from one value to another over a set time.

div {
  background-color: blue;
  transition: background-color 1s ease;
}

div:hover {
  background-color: red;
}

Output (visual): When you hover over the div, the background slowly fades from blue to red over 1 second.

Key idea: Transitions only work when the browser understands the type of value (colour, length, number, etc.). CSS variables without @property are opaque text · the browser cannot animate them.

What is a CSS Animation (Keyframes)?

An animation plays a sequence of style changes automatically.

@keyframes fadeIn {
  from { opacity: 0; }
  to   { opacity: 1; }
}

p {
  animation: fadeIn 2s ease;
}

Output (visual): The paragraph fades in from invisible to fully visible over 2 seconds.

Now you are ready for @property.

What is the @property Rule?

The @property rule is a special CSS instruction that lets you register a custom CSS property (a variable) with the browser. When you register a property, you tell the browser three important things:

1. What type of value it holds · for example, is it a colour, a length, a number, or a percentage?
2. Whether it inherits from parent elements · like how font-size passes down to children.
3. What its initial (default) value is · so if no value is set, the browser still knows what to display.

Analogy: Think of a CSS variable as an unmarked box. The browser does not know if the box contains a colour, a word, or a number · it just passes the box around. @property is like labelling the box: "This box contains a COLOUR. Its default is red. It passes down to children." Now the browser can treat the contents intelligently · including animating between values.

Why Does @property Exist?

The problem it solves is animating custom properties. Before @property, you could not smoothly animate a CSS variable value because the browser treated it as plain text. With @property, the browser understands the value type and can smoothly interpolate (calculate intermediate steps) between two values during an animation.

This was a feature that previously required JavaScript to achieve. Now it is pure CSS.

The Syntax of @property

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

Let's break down every single part of this:

Important: All three descriptors · syntax, inherits, and initial-value · are required. If any one is missing, the @property rule is invalid.

The syntax Descriptor · Data Types

The syntax field tells the browser what kind of data the property holds. Here are the most common types:

Example 1 · Registering a Simple Colour Property

This is the most minimal, isolated example. We register a custom colour property, give it a default value, and use it on a box.

/* Step 1: Register the property */
@property --box-colour {
  syntax: '<color>';
  inherits: false;
  initial-value: lightblue;
}

/* Step 2: Use the property */
div {
  background-color: var(--box-colour);
  width: 200px;
  height: 100px;
}

<div></div>

Expected output: A rectangle 200px wide and 100px tall with a light blue background.

What happened:

• @property · box-colour registered a new custom property named · box-colour.
• syntax: '<color>' told the browser it holds a colour value.
• inherits: false means child elements inside the div do not automatically get this value.
• initial-value: lightblue sets the default · so even without a · box-colour value anywhere in the CSS, the box shows light blue.
• var( · box-colour) reads the variable value just like a normal CSS variable.

Thinking prompt: What happens if you remove the initial-value line? The @property rule becomes invalid and the property is ignored entirely!

Example 2 · Overriding the Registered Property's Value

Now we set a different value on an element, overriding the initial-value.

@property --box-colour {
  syntax: '<color>';
  inherits: false;
  initial-value: lightblue;
}

.card {
  --box-colour: coral;   /* Override the default */
  background-color: var(--box-colour);
  width: 200px;
  height: 100px;
}

.plain {
  background-color: var(--box-colour);
  width: 200px;
  height: 100px;
}

<div class="card"></div>
<div class="plain"></div>

Expected output:

• .card shows a coral (salmon-orange) background.
• .plain shows a light blue background (falls back to initial-value).

Why this matters: The .plain div never sets · box-colour, so the browser uses the registered initial-value of lightblue. This is much safer than a regular CSS variable which would produce nothing (invalid value) if not set.

Thinking prompt: What would .plain look like if · box-colour were a regular CSS variable with no default? It would have no background colour at all · transparent!

Example 3 · Registering a Number Property

Numbers (without units) are useful for controlling transparency, scale, or counters.

@property --opacity-level {
  syntax: '<number>';
  inherits: false;
  initial-value: 1;
}

.box {
  background-color: steelblue;
  width: 150px;
  height: 150px;
  opacity: var(--opacity-level);
}

.faded {
  --opacity-level: 0.3;
}

<div class="box">Normal</div>
<div class="box faded">Faded</div>

Expected output:

• First box: Fully opaque steelblue square.
• Second box: Same square at 30% opacity (very light/transparent).

Example 4 · The Power of @property: Animating a Custom Colour (The Big Moment!)

This is the key example · the reason @property exists. Notice how the colour smoothly animates. Without @property, this would not work.

/* Register with @property so the browser can animate it */
@property --bg-colour {
  syntax: '<color>';
  inherits: false;
  initial-value: orange;
}

.animated-box {
  --bg-colour: orange;
  background-color: var(--bg-colour);
  width: 200px;
  height: 200px;
  transition: --bg-colour 1s ease;   /* Animate the custom property */
}

.animated-box:hover {
  --bg-colour: purple;
}

<div class="animated-box"></div>

Expected output:

• Box starts as orange.
• When you hover over it, the colour smoothly transitions to purple over 1 second.
• When you move the mouse away, it smoothly returns to orange.

Why this is remarkable: The transition is applied directly to the custom property · bg-colour. Because @property registered it as a <color> type, the browser can calculate all the intermediate colour steps during the 1-second animation. Without @property, the box would just jump instantly from orange to purple · no smooth transition.

Thinking prompt: What if you changed syntax: '<color>' to syntax: '' (any value)? Try it · the transition would break and the colour would jump again, because '' means no type information.

Example 5 · Animating a Number Property (Gradient Rotation)

A very popular real-world use of @property is animating the angle of a gradient.

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

@keyframes spin-gradient {
  to {
    --gradient-angle: 360deg;
  }
}

.gradient-box {
  width: 250px;
  height: 250px;
  background: linear-gradient(var(--gradient-angle), red, blue);
  animation: spin-gradient 4s linear infinite;
}

<div class="gradient-box"></div>

Expected output: A box with a red-to-blue gradient that continuously rotates in a 360° loop every 4 seconds.

Line-by-line explanation:

Because · gradient-angle is registered as <angle>, the browser smoothly steps through 0°, 45°, 90°, 180°... all the way to 360°, creating a smooth spin effect.

Example 6 · Animating a Percentage (Animated Progress Bar)

@property --progress {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 0%;
}

@keyframes load {
  to { --progress: 80%; }
}

.progress-bar {
  width: var(--progress);
  height: 20px;
  background-color: green;
  animation: load 2s ease forwards;
}

.track {
  width: 300px;
  background-color: lightgrey;
  border-radius: 10px;
  overflow: hidden;
}

<div class="track">
  <div class="progress-bar"></div>
</div>

Expected output: A grey track bar. Inside it, a green bar animates from 0% width to 80% width over 2 seconds · like a loading bar filling up.

Mistake 1 · Missing a Required Descriptor

Wrong:

@property --my-colour {
  syntax: '<color>';
  initial-value: red;
  /* MISSING: inherits */
}

Problem: All three descriptors are required. Missing inherits makes the entire @property block invalid and ignored.

Correct:

@property --my-colour {
  syntax: '<color>';
  inherits: false;
  initial-value: red;
}

Mistake 2 · Wrong Syntax Value Format (Forgetting Quotes)

Wrong:

@property --my-colour {
  syntax: <color>;       /* Missing quotes! */
  inherits: false;
  initial-value: red;
}

Problem: The syntax value MUST be inside single quotes '<color>'. Without quotes, it is invalid.

Correct:

@property --my-colour {
  syntax: '<color>';
  inherits: false;
  initial-value: red;
}

Mistake 3 · initial-value Doesn't Match the syntax Type

Wrong:

@property --my-size {
  syntax: '<length>';
  inherits: false;
  initial-value: blue;   /* 'blue' is a colour, not a length! */
}

Problem: The initial value must be a valid value for the declared syntax type. blue is not a CSS length.

Correct:

@property --my-size {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

Mistake 4 · Forgetting to Set the Variable on the Element Before Transitioning

Wrong (transition may not work as expected):

@property --bg {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

.box {
  background-color: var(--bg);
  transition: --bg 1s ease;
}

.box:hover {
  --bg: red;
}

The transition from initial-value to the hover value may work, but it is best practice to explicitly set the starting value on the element itself for predictable results.

Better:

.box {
  --bg: blue;              /* Explicitly set */
  background-color: var(--bg);
  transition: --bg 1s ease;
}

Mistake 5 · Trying to Animate with syntax: '*'

Wrong:

@property --my-value {
  syntax: '*';             /* No type info */
  inherits: false;
  initial-value: red;
}

.box {
  background-color: var(--my-value);
  transition: --my-value 1s ease;   /* Will NOT animate */
}

Problem: syntax: '*' means "any type" · the browser still cannot interpolate (animate) because it does not know if it is a colour, number, or something else.

Correct: Use a specific type like syntax: '<color>'.

Mistake 6 · Using @property Without Browser Support Fallback

@property is a newer feature. Older browsers (especially older Firefox and Safari) may not support it.

Safe approach · always provide a fallback:

/* Fallback for browsers that don't support @property */
.box {
  background-color: orange;
}

/* Modern browsers will use @property + var() */
@property --box-bg {
  syntax: '<color>';
  inherits: false;
  initial-value: orange;
}

.box {
  background-color: var(--box-bg);
  transition: --box-bg 0.5s ease;
}

.box:hover {
  --box-bg: purple;
}

@property is used in professional web development for:

• Animated gradient backgrounds · rotating or shifting gradients on hero banners (as in the mini project).
• Theme switchers · smoothly transitioning between light and dark themes.
• Animated loaders and progress bars · using <percentage> or <length> types.
• Hover effects on buttons and cards · smooth colour transitions on interactive components.
• Data visualisations · animating chart bars, pie segments, or gauges using custom numeric properties.
• CSS-only animations that previously required JavaScript to achieve.