CSS Custom Property Not Working — Scope, Typos, Cycles, and JavaScript Fixes

CSS custom properties participate in the normal CSS inheritance cascade, which means they flow down the DOM tree from ancestor to descendant. A property declared on :root is visible to every element in the document. A property declared on .container is visible only to .container and its descendants. A property declared on a sibling, a cousin, or an unrelated element is completely invisible to the element trying to use it via var().

This inheritance model is what makes custom properties useful for theming — you declare all your design tokens on :root and every element in the page can access them. But it is also the most common cause of silent failure: developers declare a property on an element that has no descendant relationship with the element consuming it.

The case-sensitivity rule catches many developers off guard because regular CSS property names are case-insensitive. --myColor, --MyColor, and --mycolor are three distinct custom properties. If you declare --accentColor on :root and use var(--accentcolor) on a button, the var() resolves to the guaranteed-invalid value with no warning. The browser's Computed tab will show an empty value for the property.

Custom properties also interact with the CSS cascade in an unusual way when it comes to invalid values. If you declare --size: red on :root and then use width: var(--size), the browser resolves the custom property at computed time and finds that red is not a valid length. The declaration becomes invalid at computed value time — which is different from a parse-time error. The result is that the element uses the inherited value of width (usually auto) rather than the initial value, which can be surprising.

Open DevTools, select the element, and open the Computed tab. Type the custom property name in the filter box. If the property appears with a value, it is defined in scope and the issue is likely a typo in the consuming rule. If it does not appear, the property is not defined on any ancestor of this element.

To trace the cascade, open the Styles tab and look at all the rules that match the element. The Styles panel shows inherited properties if you scroll down or enable the Show all option. Alternatively, use the console: getComputedStyle(document.querySelector('.my-element')).getPropertyValue('--my-color'). This returns the resolved value as a string, or an empty string if the property is undefined or has an empty value.

For JavaScript-set properties, use the Sources panel to add a breakpoint in the code that calls setProperty. Verify the property name has exactly two leading dashes and no leading whitespace. A common mistake is calling element.style.setProperty('- -color', value) with a space between the dashes, which creates a property named - -color rather than --color. After setting the property, run getComputedStyle(element).getPropertyValue('--color') in the console to confirm it resolved.

For circular reference issues, the Computed tab will show both properties as empty even though they appear in the Styles panel. Temporarily replace one property with a literal value — set --spacing: 16px instead of calc(var(--gap) - 4px) — and check if the other property resolves. If it does, you have confirmed a circular dependency.

The DevTools filter search in the Styles panel also lets you find all usages of a specific variable across every rule that applies to the selected element. Type the variable name in the filter field at the top of the Styles tab and every rule containing that name is highlighted, making it fast to spot where a property is declared, overridden, or referenced without scrolling through hundreds of rules manually.

For scope issues, move the property declaration to the nearest common ancestor of all elements that need it. If a property needs to be available everywhere, declare it on :root. If it is specific to a component, declare it on the component's root element and use it only in that component's descendants. This keeps the property scoped and avoids polluting the global namespace.

For typos, adopt a consistent naming convention and enforce it. The most widely used convention is all-lowercase kebab-case: --primary-color, --border-radius, --font-size-lg. Avoid camelCase and PascalCase for custom property names because they create case-sensitivity risks. If you use a design token tool like Style Dictionary or Theo, configure it to output all property names in kebab-case.

For circular references, identify the cycle by drawing out the dependency graph. Every custom property should ultimately resolve to a literal value — a color hex code, a pixel value, a unitless number. A property that references another property that references another is fine as long as there is no loop. If you find a loop, introduce an anchor property with a literal value that breaks the cycle.

For the var()-in-media-query limitation, use a CSS preprocessor variable instead of a custom property. In Sass, $breakpoint-md: 768px can be used as @media (min-width: #{$breakpoint-md}), and the preprocessor resolves it to a literal value at build time. Container Queries are an alternative that does not require a breakpoint at all — @container (min-width: 400px) targets the container's width rather than the viewport, making them a better fit for reusable components.

The @property at-rule allows you to register a custom property with a specific syntax type, an initial value, and an inheritance setting. @property --border-radius { syntax: "<length>"; inherits: false; initial-value: 4px; } means --border-radius will not inherit from parent elements and defaults to 4px if unset. If the value assigned to a registered property does not match the syntax descriptor, the browser uses the initial-value instead of the guaranteed-invalid value, which can make it harder to notice an assignment error.

Shadow DOM creates a boundary for custom property inheritance. Custom properties declared on the host element are visible inside the Shadow DOM, but properties declared inside the Shadow DOM are not visible outside it. This is intentional and is the mechanism that allows web components to expose a theming API through custom properties while encapsulating their internal implementation. If your component's custom properties are not working inside a Shadow DOM, check whether the property is being declared on the host or passed through the host's CSS custom property API.

When setting custom properties via JavaScript, there are two methods with different scopes. element.style.setProperty('--color', '#f00') sets an inline style that is scoped to that element and its descendants, with the highest specificity. document.documentElement.style.setProperty('--color', '#f00') sets it on the html element, making it globally available as a high-specificity override. Use getComputedStyle(element).getPropertyValue('--color').trim() to read the resolved value — the trim() call removes any leading whitespace that the browser may include in the returned string.

On iOS Safari, custom properties inside @keyframes have historically had inconsistent behavior. An animation that changes a custom property value at different keyframe percentages may not interpolate correctly in Safari older than version 15.4. If you need to animate a custom property value (for example, changing --hue across keyframes), use @property with the correct syntax type, which enables the browser to interpolate the typed value rather than treating it as an opaque string.

Declaring custom properties inside a media query block works but does not mean the property is available only inside that breakpoint. The property is still inherited. What changes inside the media query is the value: @media (max-width: 768px) { :root { --sidebar-width: 0px; } } changes the value of --sidebar-width at that breakpoint. This is the correct pattern for responsive design tokens. The mistake is thinking the property itself is conditionally defined — it is always available, but its value changes.

Using an empty string as a custom property value is not the same as deleting it. element.style.setProperty('--color', '') sets the property to an empty string, which is a valid (non-empty) custom property value — specifically, it is a whitespace-only value. Any var(--color) reference will resolve to an empty string, not to the inherited value. To remove an inline custom property and allow inheritance to resume, use element.style.removeProperty('--color').

Nesting custom property references too deeply creates maintenance problems. A chain like --button-primary uses var(--brand-action), which uses var(--color-indigo-600), which uses var(--color-indigo-base), is hard to trace. Keep chains to at most two or three levels. Use a tool like Token Studio or Style Dictionary to manage the token hierarchy and generate the CSS output automatically.

Failing to account for the guaranteed-invalid value cascade. When a custom property resolves to invalid, the browser uses the inherited value for inherited properties and the initial value for non-inherited properties — not the unset value or the value from a previous rule. For example, if background is set to var(--bg-color) and --bg-color is invalid, background does not fall back to the previous background rule; it uses the initial value (transparent). This is why providing fallbacks in var() is important for any property where the invalid cascade behavior would be harmful.

Use a consistent naming scheme and document it. All-lowercase kebab-case is the dominant convention and avoids case-sensitivity bugs. Prefix component-specific properties with the component name: --nav-bg, --nav-text, --nav-border-radius. This makes it immediately clear which component owns the property and prevents accidental overrides from unrelated components that happen to use the same token name.

Always provide fallback values in var() for any property used outside a tightly controlled component boundary. var(--primary-color, #6366f1) ensures the element displays correctly even if the token file fails to load or the property is accidentally removed from the token set. The fallback value also serves as documentation of the expected type and scale.

Register critical custom properties with @property for browser-enforced type safety and smooth animation support. Properties that animate (such as --hue, --saturation, or --progress) must be registered with the correct syntax type for the browser to interpolate them. Properties that are used in calc() benefit from registration with a length or number type because the browser can catch type mismatches at assignment time rather than failing silently at computed value time.

Keep a token reference in your repository. A markdown file or a Storybook page that lists all available custom properties, their types, default values, and which components use them reduces the risk of typos and orphaned properties. Tools like Style Dictionary, Token Studio, and Theo can generate this documentation automatically from a JSON token source, keeping it in sync with the actual CSS output.

For teams that need both CSS and JavaScript access to design tokens, maintain a single tokens file — a _tokens.css partial or a tokens.js module — that exports both CSS custom properties and JavaScript constants from one source of truth. Build tooling like Style Dictionary can generate both formats simultaneously from a shared JSON definition, ensuring that the --color-primary custom property and the COLOR_PRIMARY JavaScript constant always match without manual synchronization.