DevLab
#
CSSbeginner

CSS Variables Cheatsheet

complete CSS custom properties reference with examples

By Bikram NathLast updated

A syntax reference for CSS custom properties covering declaration, `var()` usage, fallback chains, and JavaScript read/write. Handy when you need to look up the exact JS call to read a variable at runtime: `getComputedStyle(el).getPropertyValue('--spacing-base').trim()` returns the computed string including any whitespace. Unlike generic CSS references, this cheatsheet surfaces the two-argument fallback form and the `el.style.setProperty()` write path in one place.

Try it now — free, instant, no signup

What is CSS Variables Cheatsheet?

The CSS Variables Cheatsheet is a focused reference for CSS custom properties syntax — how to declare them (`--token-name: value` inside any selector, not just `:root`), consume them with `var(--token-name)`, define fallback chains, and bridge them into JavaScript with `getComputedStyle` and `setProperty`. A concrete example: declare `--theme-bg: #1a1a1a` on a `.dark` class, then read it in a canvas script to keep JS color values in sync with CSS without duplicating literals.

When you need to understand a specific syntax edge case, this cheatsheet is faster than scanning MDN's full custom properties article or the CSS Cascading Variables spec. MDN covers the same ground but includes browser compatibility tables and extended prose; reach for MDN when you need historical browser support or spec citations. Sass and Less docs cover preprocessor variables, which look similar but are a different concept entirely.

The most common gotcha is the fallback comma rule: `var(--font, Georgia, serif)` has a single fallback value of `Georgia, serif` — everything after the first comma is the fallback, not a list of separate fallbacks. This surprises developers expecting each comma-separated item to be tried in order. A second sharp edge: custom properties cannot appear in media query conditions. `@media (max-width: var(--bp-md))` is invalid and silently ignored; breakpoints must be hardcoded or set via JavaScript on a container element.

When to use CSS Variables Cheatsheet

✓Audit your token declarations before refactoring a design system to confirm fallback syntax is correct.
→Look up the exact `getPropertyValue` call needed when syncing a CSS color variable into a Canvas 2D context.
⚡Verify scoping rules when a variable declared on a child selector unexpectedly overrides the `:root` value.

Frequently Asked Questions

Can I use a CSS variable inside a media query condition, like `@media (max-width: var(--bp))`?
No. The CSS spec explicitly prohibits custom properties in media query conditions because custom properties are resolved during the cascade, which runs after the media query is evaluated. The browser ignores the rule silently. The workaround is to set breakpoint values directly in CSS or, if you need them dynamic, set a data attribute or class on the `<html>` element from JavaScript and scope your custom property overrides to that class. The `@property` at-rule (Chrome 85+, Firefox 128+) does not change this limitation.
Why does `var(--color, red, blue)` use `red, blue` as the fallback instead of trying `red` first, then `blue`?
The `var()` function treats everything after the first comma as a single fallback value. So `var(--color, red, blue)` resolves to the literal string `red, blue` if `--color` is not defined — which is a valid fallback for a `font-family` property but nonsensical for `color`. There is no waterfall of fallbacks inside a single `var()` call. To chain independent fallbacks you nest: `var(--primary, var(--secondary, blue))`. The inner `var()` is the fallback for the outer one.
When I read a CSS variable in JavaScript with `getPropertyValue`, the value includes leading whitespace. Is that a bug?
It is expected behavior. The CSS parser preserves whitespace around custom property values because the spec does not define the value as any particular type — it is stored as a token sequence. If you write `--gap: 16px` with a space after the colon, `getPropertyValue('--gap')` returns `' 16px'` with the leading space intact. Always call `.trim()` on the result before using it in JavaScript calculations or `parseInt`/`parseFloat` parsing. This is a frequent source of subtle bugs when values are read and written programmatically.
What is the `@property` rule and how does it change how CSS variables behave?
The `@property` at-rule lets you register a custom property with an explicit syntax type, initial value, and inheritance flag. For example, registering `--hue` as a `<number>` allows CSS transitions and animations to interpolate it smoothly — unregistered custom properties animate as discrete steps. Browser support is Chrome 85+, Firefox 128+, and Safari 16.4+. If `@property` is not supported, the custom property still works as an unregistered variable; the registration adds type-checking and animation capability on top. The cheatsheet covers the `var()` and declaration syntax; the `@property` spec lives in CSS Houdini documentation.
Do CSS variables inherit into Shadow DOM?
Yes, custom properties cross the Shadow DOM boundary by default, which makes them the standard mechanism for theming web components from the outside. A host page can set `--component-bg: navy` on `:root` and a shadow tree that reads `var(--component-bg)` will pick it up because custom properties participate in the normal CSS inheritance chain, even across shadow boundaries. However, JavaScript `getPropertyValue` must query the shadow host's computed style or the element inside the shadow root directly — querying the document root will not reflect values scoped to the host element.

Related Tools

CSS
CSS Flexbox Generator
generate CSS flexbox layouts with a visual editor
CSS
CSS Grid Generator
generate CSS grid templates visually with live preview
CSS
CSS Specificity Calculator
calculate and compare CSS selector specificity scores
CSS
CSS Gradient Generator
generate CSS linear, radial, and conic gradients visually