CSS Variables

What Are CSS Variables?

CSS variables are reusable custom properties that begin with two hyphens --. You define a variable once and reuse it with the var() function.

:root {
  --color-primary: #0d6efd;
  --space-md: 1rem;
}

.button {
  background-color: var(--color-primary);
  padding: var(--space-md);
}

In this example, --color-primary and --space-md are CSS variables.

Why CSS Variables Are Important

• Store reusable design values in one place.
• Make colors, spacing, typography, and shadows easier to update.
• Reduce repeated CSS values across components.
• Support themes, dark mode, and design systems.
• Allow scoped component-level styling.
• Work dynamically with media queries and JavaScript.
• Improve maintainability in large CSS codebases.

CSS Variables Cheatsheet

The following table explains the most useful CSS variable patterns.

CSS Variable Syntax

A CSS variable name starts with two hyphens and is usually written in lowercase with hyphen-separated words.

selector {
  --variable-name: value;
}

selector {
  property: var(--variable-name);
}

Example:

:root {
  --font-body: system-ui, sans-serif;
  --radius-md: 0.75rem;
  --shadow-md: 0 0.5rem 1rem rgba(0, 0, 0, 0.12);
}

Global CSS Variables with :root

The :root selector targets the root element of the document. It is commonly used to define global CSS variables.

:root {
  --color-primary: #0d6efd;
  --color-text: #212529;
  --color-bg: #ffffff;

  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 2rem;

  --radius-md: 0.75rem;
  --shadow-md: 0 0.5rem 1rem rgba(0, 0, 0, 0.12);
}

Variables defined in :root can be used throughout the page.

The CSS var() Function

The var() function reads the value of a CSS variable.

.card {
  color: var(--color-text);
  background-color: var(--color-bg);
  padding: var(--space-md);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-md);
}

If the variable changes, every property using that variable updates automatically.

CSS Variable Fallback Values

You can provide a fallback value when a variable is missing or invalid.

.button {
  background-color: var(--button-bg, #0d6efd);
  color: var(--button-color, #ffffff);
}

In this example, the button uses fallback colors if --button-bg or --button-color is not defined.

Scoped CSS Variables

CSS variables inherit. You can define variables globally or scope them to a component.

.alert {
  --alert-bg: #cff4fc;
  --alert-color: #055160;

  background-color: var(--alert-bg);
  color: var(--alert-color);
  padding: 1rem;
  border-radius: 0.75rem;
}

.alert-danger {
  --alert-bg: #f8d7da;
  --alert-color: #842029;
}

This pattern makes component variants easy to create.

CSS Variables for Themes

CSS variables are perfect for theme systems because you can swap values without rewriting component styles.

:root {
  --page-bg: #ffffff;
  --page-text: #212529;
  --card-bg: #ffffff;
}

[data-theme="dark"] {
  --page-bg: #121212;
  --page-text: #f8f9fa;
  --card-bg: #1f1f1f;
}

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

.card {
  background-color: var(--card-bg);
}

Dark Mode with CSS Variables

You can combine CSS variables with prefers-color-scheme for automatic dark mode support.

:root {
  --bg: #ffffff;
  --text: #212529;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #121212;
    --text: #f8f9fa;
  }
}

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

This updates the page colors based on the user’s system preference.

Responsive CSS Variables

Variables can change inside media queries. This makes responsive spacing, typography, and layout values easier to maintain.

:root {
  --section-space: 2rem;
  --grid-gap: 1rem;
}

@media (min-width: 768px) {
  :root {
    --section-space: 4rem;
    --grid-gap: 1.5rem;
  }
}

.section {
  padding-block: var(--section-space);
}

.grid {
  display: grid;
  gap: var(--grid-gap);
}

CSS Variables with calc()

CSS variables can be used inside calc() for dynamic sizing.

:root {
  --sidebar-width: 280px;
  --page-gap: 2rem;
}

.layout {
  grid-template-columns: var(--sidebar-width) calc(100% - var(--sidebar-width) - var(--page-gap));
  gap: var(--page-gap);
}

Use calc() carefully and keep formulas readable.

CSS Variables as Design Tokens

In design systems, CSS variables often act as design tokens. Tokens store decisions such as brand colors, spacing scales, typography sizes, shadows, and radius values.

:root {
  --color-brand-primary: #0d6efd;
  --color-brand-success: #198754;
  --font-size-body: 1rem;
  --font-size-heading: 2rem;
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 1rem;
  --radius-1: 0.25rem;
  --radius-2: 0.5rem;
  --shadow-1: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
}

Design tokens make websites more consistent and easier to scale.

Updating CSS Variables with JavaScript

JavaScript can read and update CSS variables dynamically.

document.documentElement.style.setProperty("--color-primary", "#6610f2");

This is useful for theme switchers, live previews, design tools, dashboards, and user customization features.

CSS Variables and Accessibility

• Use variables to maintain consistent contrast-friendly colors.
• Create accessible focus color tokens.
• Test light and dark themes for readability.
• Avoid changing only color when communicating important state.
• Use semantic token names like --color-danger and --color-success.
• Keep font size and spacing tokens comfortable for reading.

CSS Variables and SEO

CSS variables do not directly affect rankings, but they improve maintainability, consistency, page quality, accessibility, theming, and user experience.

• Consistent design improves trust and readability.
• Accessible color tokens improve content usability.
• Maintainable CSS makes content updates easier.
• Theme support can improve user comfort.
• Cleaner CSS architecture supports long-term site quality.

Common CSS Variable Mistakes

• Forgetting that CSS variable names are case-sensitive.
• Using unclear names like --blue instead of semantic names like --color-primary.
• Defining too many variables without a clear system.
• Using variables for one-off values that do not need reuse.
• Forgetting fallback values when a variable may be missing.
• Creating theme colors without checking contrast.
• Making formulas with calc() too complex.
• Expecting variables to work before they are defined in the cascade.

CSS Variable Best Practices

• Define global tokens in :root.
• Use semantic variable names such as --color-primary or --space-md.
• Use scoped variables for component variants.
• Use fallback values when variables may not exist.
• Keep variable naming consistent across the project.
• Use variables for colors, spacing, typography, shadows, radius, and z-index scales.
• Use media queries to update responsive variables.
• Test themes for contrast and readability.
• Document your token system in large projects.

Key Takeaways

• CSS variables are custom properties that start with --.
• The var() function reads CSS variable values.
• :root is commonly used for global variables.
• Variables can be scoped to components and inherited by children.
• Fallback values make variables safer.
• CSS variables are useful for themes, dark mode, responsive design, and design tokens.
• Good variable naming improves maintainability and scalability.