CSS Custom Properties (Variables) — Practical Examples

CSS custom properties — officially called CSS custom properties for cascading variables — are properties that you define yourself, always beginning with two dashes. They follow the full CSS cascade: they can be declared on any selector, they inherit down the DOM tree, and they can be overridden in more specific selectors or child elements. The var() function reads the nearest ancestor's value for a given property name.

The scope of a custom property is defined by the selector it is declared in. Declaring on :root makes a variable available everywhere because :root matches the html element, the root of all other elements. Declaring on .card means the variable is only available to .card and its descendants. Declaring on a child element does not make the variable available to parent or sibling elements — inheritance is downward only.

Custom properties are resolved at computed value time, not at parse time. This means the browser substitutes the variable's value when it computes styles for a specific element. If --color is declared as invalid at computed time — for example, if its value is not a valid color for a color property — the property falls back to its inherited value or initial value, not to the var() fallback. The var() fallback only applies when the variable is not defined, not when it is invalid.

Custom properties are case-sensitive. --Primary-Color and --primary-color are two different properties. This is a common source of bugs when developers declare a variable in one place and reference a differently cased name elsewhere. Always use a consistent naming convention — lowercase with hyphens is the standard.

Open Chrome DevTools and select the element where the variable is not working. In the Computed panel, find the property that should be using the variable and check its resolved value. If it shows the initial value or a different color, the variable is either not defined in an ancestor, is defined with a typo, or the value is invalid for the property.

In the Styles panel, click on any var() reference — Chrome DevTools will show the resolved value in a tooltip or inline. This lets you confirm what value the variable holds at that specific element's scope without hunting through the stylesheet.

To check the inheritance chain, inspect the element's ancestors one by one and look for the --variable-name declaration in their Styles panels. Each element's Styles panel shows properties declared on that element and the inherited custom properties in the Inherited section. Walk up the tree to find where the variable is — or confirm it is missing.

For JavaScript-driven variable changes, use the Console panel. Run getComputedStyle(document.documentElement).getPropertyValue('--primary-color') to read the current value from the root. If it returns an empty string, the variable is not set. Remember that getPropertyValue returns a string with possible leading whitespace — always call .trim() on the result before comparing or parsing it.

Firefox DevTools surfaces custom properties differently from Chrome. In Firefox, open the Inspector panel, select the element, and look in the Rules panel for the var() call highlighted in a different color — hovering it shows the resolved value. Firefox also shows custom property values in the Fonts panel when variables are used for font-size or font-family, which can be handy for typography debugging. When a variable appears valid in Chrome but resolves incorrectly in Firefox, check whether the value uses @property registration that may have limited support in the browser version under test.

For a missing variable, confirm the variable name matches exactly — dash case, exact spelling — and that it is declared on an ancestor of the using element. If the variable is meant to be global, always declare it on :root rather than on a component-specific selector.

For dark mode theming, the two most reliable patterns are: a [data-theme='dark'] attribute on the html element toggled by JavaScript, and a @media (prefers-color-scheme: dark) block that overrides variable values. Both patterns work by re-declaring the same variable names with different values. The media query approach requires no JavaScript and respects the system setting. The data attribute approach allows explicit user control.

For JavaScript integration, always use el.style.setProperty('--variable-name', value) to write custom properties — not el.style['--variable-name'] = value, which does not work. The double-dash prefix must be included in the property name string. To read from the computed value, use getComputedStyle(el).getPropertyValue('--variable-name').trim(). The extra .trim() is important because browsers may include a leading space in the returned value.

For calc() with variables, ensure that units are compatible. calc(var(--spacing) * 2) works when --spacing is declared with units (--spacing: 1rem). If --spacing is declared as a unitless number (--spacing: 16), then calc(var(--spacing) * 1px) is needed to give it a unit before math operations. Using unitless variables requires more careful usage at every call site.

Chaining multiple fallbacks is supported by nesting var() calls inside the fallback position. The syntax var(--custom, var(--brand, #3b82f6)) tries --custom first, falls back to --brand if --custom is undefined, and uses the hardcoded value if both are undefined. This pattern is useful in design system components that expose optional override variables but always need a guaranteed resolved value regardless of how the component is configured by consumers.

CSS variables cannot be used as media query values. @media (max-width: var(--breakpoint)) does not work. The media query condition is evaluated before custom properties are resolved, so variables are always substituted as invalid in that position. Use PostCSS or Sass variables for breakpoint values that feed media queries — these are compile-time constants, not runtime values.

Within a media query, you can re-declare custom properties on :root to change their values at different viewport sizes. This is a powerful pattern for responsive spacing and typography. Declare --font-size:16px in the base style and --font-size:18px inside a @media (min-width: 768px) block. All elements using font-size:var(--font-size) automatically update when the breakpoint triggers.

Animating CSS variables requires @property with a registered type. Without registration, the browser cannot interpolate between two custom property values during a transition or animation — it jumps instantly from start to end. @property is supported in Chrome and Edge from 2021 and in Firefox from 2024. For Safari, check current support before using @property in production without a fallback.

Custom properties follow the cascade for inheritance, which means a variable declared on a child does not affect parents or siblings — only the child's own descendants. If a component needs to expose configuration points to its children, it should declare variables on the component's root element: .card { --card-bg: white; } gives all .card children access to --card-bg. External consumers can then override it: .dark-section .card { --card-bg: #1e293b; }.

When using @property to register a typed variable for animation, the syntax field supports a range of type keywords including angle, color, integer, length, number, percentage, and length-percentage. Choosing the right type is important: a variable declared with syntax:'<color>' enables smooth color interpolation in transitions, whereas an unregistered variable snaps. This mechanism is what powers smooth hue rotation animations, gradient position animations, and other effects that previously required JavaScript-driven requestAnimationFrame loops.

Declaring variables inside a media query block at the :root level is a common and valid pattern — but developers sometimes expect variables declared inside a block to be accessible outside it. They are not. A variable declared inside @media (min-width: 768px) on :root is only active when the media query matches. When it does not match, the variable falls back to its value from outside the media query, or it is undefined if no base value was declared.

Expecting var() to cascade upward is another misunderstanding. If a child declares --color: red, its parent cannot read --color. Custom property inheritance goes from parent to child, like all CSS inheritance. If you need a child's property to communicate a value upward, JavaScript is required.

Using var() for non-custom properties is a JavaScript mistake, not a CSS one. In JavaScript, el.style.getPropertyValue is used for both regular and custom properties. However, regular properties are read and written differently: el.style.color = 'red' (without dashes) for regular, and el.style.setProperty('--my-color', 'red') (with double dashes, using the method) for custom. Mixing these patterns silently fails.

Forgetting the initial-value in @property declarations. When you use @property to register a custom property, initial-value is required unless inherits is set to true. If you omit initial-value, the browser may throw an error or treat the property as unregistered. Always include initial-value with a valid value for the declared syntax.

Another common mistake is using a CSS variable inside a shorthand property where the shorthand has known parsing limitations. For example, font: var(--font-size)/var(--line-height) var(--font-family) can fail to parse correctly in some browsers because the shorthand parser applies strict token validation before custom properties are resolved. Splitting the shorthand into individual longhand properties — font-size, line-height, font-family — and using variables in each one separately is more reliable and easier to debug.

Organize your custom properties into logical groups: color tokens, spacing tokens, typography tokens, and component-specific overrides. Declare all global tokens on :root and document them with comments. Component-specific variables should be declared on the component's root class, with default values that make the component usable without any configuration.

Use a consistent naming convention. A common pattern is --[category]-[variant]-[property]: --color-primary-base, --color-primary-hover, --spacing-sm, --spacing-md. This makes the system discoverable and prevents naming conflicts as the codebase grows.

When building a design system, declare variables in layers. Use a base :root declaration for default values, then override in [data-theme] selectors for theme variants, and in component classes for component-level customization. This layered approach makes the cascade explicit and predictable.

Consider using @property for any variable you plan to animate. Even if you do not animate it today, registering a type prevents a class of bugs if animation is added later. It also allows the browser to perform type validation, catching invalid values at parse time rather than silently falling back at computed value time. The overhead of @property registration is negligible.

For design tokens shared between CSS, JavaScript, and native mobile platforms, generate CSS custom property declarations from a single source-of-truth token file — typically a JSON or YAML file processed by a build tool like Style Dictionary. This ensures that --color-primary in your CSS matches the exact same hex value used in your JavaScript theme object and your iOS color asset. Keeping tokens in one canonical format eliminates drift between platforms over time.

When scoping component variables, prefer declaring them on the component's own root element rather than :root, even when the values are the same as global defaults. This makes each component self-contained: a consumer can change a component's variable by targeting the component class without needing to understand or modify the global token system. It also makes it straightforward to support multiple instances of the same component with different visual configurations on the same page.