CSS Variables: Browser Support, Syntax, Fallbacks

What is CSS Variables?

CSS Variables are a W3C CSS Custom Properties for Cascading Variables Module Level 1 feature. They define reusable custom properties on any selector, prefixed with two dashes such as --main-color: blue, and read them back through the var() function. Variables cascade and inherit like any other CSS property.

Which browsers does CSS Variables support?

CSS Variables work in every modern desktop and mobile browser, with Chrome shipping support in Chrome 49, Firefox in Firefox 31, Safari in Safari 9.1, and Edge in Edge 16. Internet Explorer 5.5 to 11 never added support, and Opera Mini still does not support custom properties.

How does CSS Variables syntax work?

A CSS Variable is declared by writing a custom property prefixed with two dashes inside any selector, then read with the var() function. The browser resolves the value at runtime and inherits it down the DOM tree, so a value declared on :root is available to every descendant.

The example below declares three variables on :root, reads them inside .button, overrides one on .card.dark, and uses a variable inside calc().

/* Declare CSS Variables on :root for global scope */
:root {
  --main-color: #2962ff;
  --spacing: 1.5rem;
  --base-font: "Inter", system-ui, sans-serif;
}

/* Read them with var() and provide a fallback value */
.button {
  color: var(--main-color);
  padding: var(--spacing, 1rem);
  font-family: var(--base-font);
}

/* Override the variable on a child element */
.card.dark {
  --main-color: #ffffff;
}

/* Variables resolve through calc() and at-rules */
.grid {
  width: calc(100% - var(--spacing) * 2);
}

A few rules apply across every browser that ships CSS Variables:

• Names must start with two dashes: A property like --main-color or --space-2 is a valid custom property; anything without the leading -- is treated as a regular CSS property and ignored.
• Names are case-sensitive: --mainColor and --maincolor are two different variables, unlike standard CSS property names. A typo in casing returns an empty string from getComputedStyle, not a fallback.
• :root sets global scope: Declarations on the :root pseudo-class apply to the html element, so every descendant reads the same value. Scoped overrides on a child element shadow the global value down its subtree.
• var() takes an optional fallback: Write var(--space, 1rem) so the rule still resolves when the variable is missing or invalid in a supporting browser. The fallback is only used inside the var() function call.
• Variables work inside calc(), clamp(), and at-rules: Compose values like calc(100% - var(--gutter) * 2) or clamp(1rem, var(--fluid), 3rem). Variables also cascade through @media and @supports query bodies normally.
• JavaScript can read and write variables: Use element.style.setProperty('--name', value) to write and getComputedStyle(element).getPropertyValue('--name') to read, which makes runtime theme switching trivial.

How do you provide CSS Variables fallbacks for older browsers?

Pair every var() reference with either a literal fallback inside the function or a duplicate property declared above the var() line. The duplicate pattern is the only one that rescues Internet Explorer, since IE drops every declaration that contains a var() call, including the literal inside the function call itself.

• Use the var() second argument for missing variables: Write color: var(--accent, #2962ff) so the rule still resolves to a literal value when --accent is undeclared at the call site. This rescues only modern browsers, not Internet Explorer.
• Declare a duplicate property above var() for IE 11: Stack two declarations like color: #2962ff; followed by color: var(--accent, #2962ff);. IE 11 reads the first line and ignores the second; modern browsers apply the second and override the first.
• Wrap blocks in @supports queries: Guard a rule that depends on custom properties with @supports (--probe: 0) so older browsers skip the block. Pair it with a flat fallback ruleset in the same stylesheet.
• Run PostCSS Custom Properties at build time: The postcss-custom-properties plugin replaces every var() call with the matching :root literal, so the deployed stylesheet works in IE while the source file stays clean.
• Compile to flat values with Sass or Less: Sites locked to IE traffic can move design tokens to Sass variables, compile to static values, and ship a separate stylesheet for that audience while modern browsers receive the var() build.
• Detect support before applying advanced features: Use window.CSS.supports inside JavaScript to choose between a class-based theme switch and a custom-property theme switch. The class-based path keeps IE consistent with modern browsers.

How do you check if a browser supports CSS Variables?

Run a quick CSS.supports probe in DevTools, or wrap a block in @supports inside your stylesheet. Both paths give a one-line yes or no without changing visible styling.

• Open DevTools: In Chrome, Edge, or Firefox, press F12 (or Cmd-Option-I on macOS) and switch to the Console tab.
• Probe with CSS.supports: Paste window.CSS.supports("(--probe: 0)") and press Enter. A return value of true means the engine implements custom properties.
• Inspect computed style: In the Elements panel, select the html element and confirm declared variables appear in the Computed pane with their resolved values.
• Add an @supports block in your stylesheet: Wrap modern rules in @supports (--probe: 0) so older browsers skip them and use the flat fallback above instead.
• Cross-check on real devices: Run the same console probe on iOS Safari, Android Chrome, and Samsung Internet, since older mobile builds and embedded WebViews lag desktop releases.

The console snippet below packages the probe and prints a one-line yes or no, then reads and writes a variable from JavaScript:

// Run in the browser DevTools Console
const ok = window.CSS && window.CSS.supports("(--probe: 0)");
console.log("CSS Variables:", ok ? "yes" : "no");

// Read or write a variable from JavaScript
const root = document.documentElement;
const main = getComputedStyle(root).getPropertyValue("--main-color");
console.log("Current --main-color:", main.trim());
root.style.setProperty("--main-color", "#ff5722");

If the probe returns false, fall back to a precompiled flat stylesheet built with PostCSS, Sass, or Less so the page still renders correctly.

What are the known issues with CSS Variables?

CSS Variables are well established now, but a few rough edges still trip developers up. The biggest hits are the no-fallback drop in Internet Explorer, animation limits without @property registration, and quirks around media query feature values.

• IE 11 drops the entire declaration: Internet Explorer ignores any property whose value contains a var() call, even when the call has a literal fallback. The browser does not fall back to the second argument; it skips the declaration and uses the previous cascade value instead.
• Plain custom properties cannot be animated: Animating var(--accent) between two colors with @keyframes does not interpolate, because the engine treats the property as a string. Register the variable through @property with a syntax type of color before animating.
• Media query features cannot read variables: @media (max-width: var(--bp)) is invalid because the media feature syntax is parsed before custom properties resolve. Use literal lengths or the @custom-media draft for theme-driven breakpoints.
• Names are case-sensitive: A typo like --MainColor and --maincolor produces silent failures. Standardize on lowercase kebab-case across the design system to avoid invisible bugs.
• Older Safari calc() quirks: Safari 9.1 to 11 mishandle some calc() expressions that mix a custom property with units, returning the wrong pixel value or failing the calc entirely. Targeting Safari 12+ avoids the bulk of these.
• WebView-based apps lag system browsers: Hybrid mobile apps shipped on top of an old Android System WebView or an old iOS WKWebView inherit the same gaps as the embedded engine, so CSS Variables may fail in production builds long after the system browser has updated.
• Computed style returns trimmed strings: getComputedStyle(el).getPropertyValue('--name') returns a string with leading whitespace from the source declaration. Trim the return value before comparing or parsing it.

In my experience, the most surprising failure happens with Internet Explorer 11. A page renders in what looks like default browser styling because IE drops every declaration that contains a var() call, including the literal fallback inside the function. The fix is to declare a duplicate property above the var() line so IE picks up the duplicate while modern browsers apply the variable on the line below.

Citations

All CSS Variables version numbers and platform notes in this guide come from these primary sources:

• W3C - CSS Custom Properties for Cascading Variables Module Level 1: w3.org/TR/css-variables-1
• MDN Web Docs - Using CSS custom properties (variables): developer.mozilla.org Using CSS custom properties
• MDN Web Docs - Custom properties (--*): developer.mozilla.org Custom properties
• MDN Web Docs - var() CSS function: developer.mozilla.org/en-US/docs/Web/CSS/var
• MDN Web Docs - @property at-rule: developer.mozilla.org/en-US/docs/Web/CSS/@property
• WebKit blog - CSS Variables in WebKit: webkit.org/blog/4554/css-variables-in-webkit
• Mozilla Hacks - CSS Variables in Firefox Nightly: hacks.mozilla.org CSS Variables in Firefox Nightly
• web.dev - Learn CSS: Custom properties: web.dev/learn/css/custom-properties
• web.dev - @property: Next-gen CSS variables now with universal browser support: web.dev/blog/at-property-baseline