Skip to content
Mar 1

CSS Variables and Custom Properties

MT
Mindli Team

AI-Generated Content

CSS Variables and Custom Properties

CSS Variables and Custom Properties revolutionize how we write and maintain stylesheets by introducing true dynamic values into CSS. Unlike preprocessor variables, which are compiled away, native CSS custom properties are live, cascade through the DOM, and can be manipulated at runtime with JavaScript. This capability is the cornerstone of creating scalable design systems, implementing dynamic themes, and achieving a level of maintainability previously difficult with static CSS.

Defining and Using Custom Properties

At its core, a CSS custom property is a user-defined entity that holds a specific value. You define it using a name that begins with two hyphens (e.g., --primary-color). These properties are typically declared within a ruleset, most often on the :root pseudo-class for global scope, but they can be set on any selector.

:root {
  --primary-color: #3498db;
  --spacing-unit: 1rem;
  --font-heading: 'Georgia', serif;
}

To use the value stored in a custom property, you employ the var() function. This function substitutes the property's value into your CSS declaration. A crucial feature of var() is its ability to accept a fallback value, which is used if the referenced custom property is invalid or not defined.

.button {
  background-color: var(--primary-color, #2980b9); /* Fallback to #2980b9 if --primary-color is unavailable */
  margin-bottom: var(--spacing-unit);
  font-family: var(--font-heading, 'Times New Roman');
}

The Cascade and Inheritance of Custom Properties

CSS custom properties fully participate in the cascade. This means their values are resolved based on specificity and source order, just like any other CSS property. More importantly, they are inheritable. A custom property defined on a parent element is available to all its children unless overridden.

This behavior is the engine behind dynamic theming. You can define a base theme on :root and then override specific variables within a component or a section of your page by redeclaring them on a more specific selector.

:root {
  --theme-bg: white;
  --theme-text: black;
}

.dark-mode {
  --theme-bg: #2c3e50;
  --theme-text: #ecf0f1;
}

body {
  background-color: var(--theme-bg);
  color: var(--theme-text);
}

In this example, adding the class .dark-mode to the <body> element (or any ancestor) instantly switches the color scheme for all elements that use those variables, as the new values cascade down. This approach is far more efficient and performant than manually overwriting individual style rules.

Dynamic Theming with JavaScript

Because custom properties are part of the live DOM, they can be read and modified at runtime using JavaScript. This unlocks a world of interactive possibilities, from user-selectable themes to real-time style adjustments. You interact with them using the standard getComputedStyle() and setProperty() methods.

// Get the root element
const root = document.documentElement;

// Read a custom property value
const currentColor = getComputedStyle(root).getPropertyValue('--primary-color').trim();

// Set a new value for a custom property
root.style.setProperty('--primary-color', '#e74c3c');
root.style.setProperty('--spacing-unit', '1.5rem');

This simple API allows you to build theme togglers, style editors, or adjust layouts based on user interaction or application state. The browser immediately recalculates and repaints any elements using the updated variables, providing a smooth, efficient update without needing to manipulate individual element styles.

Building Design Token Systems

The most powerful application of CSS custom properties is in formalizing design tokens. Design tokens are the visual design atoms of a system—named entities that store values for color, spacing, typography, and more. Using custom properties as the delivery mechanism for these tokens creates a single source of truth that bridges design and development.

A robust token system is organized and semantic. Instead of --blue-500, you create tokens based on usage, like --color-interactive-primary. This abstraction means designers can change the underlying hex value without developers needing to search-and-replace code, and the purpose of the token remains clear.

:root {
  /* Color Tokens */
  --color-interactive-primary: #3498db;
  --color-surface-background: #ffffff;
  --color-text-primary: #2c3e50;

  /* Spacing Tokens */
  --spacing-xs: 0.5rem;
  --spacing-md: 1rem;
  --spacing-xl: 2rem;

  /* Typography Tokens */
  --font-size-body: 1rem;
  --line-height-tight: 1.25;
}

.component {
  background: var(--color-surface-background);
  color: var(--color-text-primary);
  padding: var(--spacing-md);
  font-size: var(--font-size-body);
  line-height: var(--line-height-tight);
}

This approach ensures visual consistency across an entire application. To change the global spacing scale, you only update the spacing token values in the :root declaration. Every component that uses --spacing-md will automatically reflect the new value.

Common Pitfalls

  1. Misunderstanding the Fallback Value: The fallback in var(--my-var, fallback) is only used if --my-var is unset or invalid. It is not a way to provide a second choice if the first value doesn't "look right." If --my-var is set to an invalid property value for that context, the declaration will fail and potentially revert to the browser's default, not the fallback.
  • Correction: Always ensure the custom property itself holds a valid value for its context. Use fallbacks primarily for defensive coding and progressive enhancement.
  1. Overcomplicating Scope: While scoping variables to components is useful, defining all custom properties exclusively in component scopes can lead to duplication and make global theming difficult.
  • Correction: Adopt a clear strategy. Define global design tokens (colors, spacing, typography scales) on :root. Define component-specific overrides or unique variables within the component's own selector.
  1. Using Variables for Non-Token Values: It's tempting to create variables for every value, but this can reduce readability. For example, margin: var(--spacing) var(--spacing) calc(var(--spacing)*2); is harder to parse than margin: 1rem 1rem 2rem; if --spacing is just 1rem.
  • Correction: Use custom properties for values that are meant to be reused, shared, or dynamically changed. Static, one-off values often don't benefit from being variables.

Summary

  • CSS Custom Properties (--property-name) are native, live variables that you define and access using the var() function, with optional fallback values.
  • They follow standard CSS cascade and inheritance rules, making them perfect for scoped theming—change a variable on a parent, and it updates all children.
  • JavaScript can interact with custom properties via setProperty() and getComputedStyle(), enabling real-time, dynamic theme switching and UI adjustments.
  • When used to implement a design token system, custom properties become the single source of truth for visual style, ensuring consistency and dramatically improving the maintainability of large-scale applications.

Write better notes with AI

Mindli helps you capture, organize, and master any subject with AI-powered summaries and flashcards.