Is there a difference between CSS custom properties and CSS variables?

Question

In all of the material I've read online, it appears that CSS custom properties and CSS variables are the same thing. However, at the end of an example in the Inheritance of CSS Variables section of the Mozilla Developer Network documentation, there is this confusing statement:

Keep in mind that these are custom properties, not actual CSS variables. The value is computed where it is needed, not stored for use in other rules. For instance, you cannot set a property for an element and expect to retrieve it in a sibling's descendant's rule. The property is only set for the matching selector and its descendants, like any normal CSS.

Which gives me the impression that these two concepts are not synonymous.

What is the difference between custom properties and variables?

Answer 1

A CSS Custom Property is the same thing as a CSS Variable. But that seems to come of some clumsy naming.

They weren't wrong to title the page: Using CSS custom properties (variables)

However a CSS Variable is not a variable in the traditional sense, as there is no way to define it so that it is globally scoped like in a programming language, or CSS Preprocessor (LESS/Sass).

Even a root scoped custom property/variable is not global. Changing the value of a property in a child will not change the value above or for siblings of that scope. If someone is expecting to be global, it may cause confusion and I suspect that's what Mozilla's writers are trying to point out.

if you look at

w3.org's CSS Custom Properties for Cascading Variables

This module introduces a family of custom author-defined properties known collectively as custom properties

Custom properties are definitions that can be referenced using var(--my-custom-prop). Like a variable!

quote continued...

as one only has to change the value once, in the custom property, and the change will propagate to all uses of that variable automatically.

Awkward... The above statement is not true exactly. It seems Mozilla Developer Network documentation is trying clarify that idea so that it's less confusing. Repeating the original quote:

Keep in mind that these are custom properties, not actual CSS variables. The value is computed where it is needed, not stored for use in other rules. For instance, you cannot set a property for an element and expect to retrieve it in a sibling's descendant's rule. The property is only set for the matching selector and its descendants, like any normal CSS.

They're pointing out it's not a variable in the traditional sense of a programming language. But that it is computed just like styles, adhering to the general cascade/scoping rules of CSS.

Thus var(--my-custom-prop) could resolve to very different things based on where it is declared, and that declarations don't propagate out to a higher scope.

Here's a codepen to mess around with if you'd like to try it out.

So think of CSS Custom Property the same as CSS Variable but be sure to remember that values cascade, and there's no global scope.