CSS Custom Properties: Variables for Your Stylesheet

Why it exists

Complex websites have large stylesheets with many repeated values, like a specific brand color used in hundreds of places. Changing that one color requires a risky, manual find-and-replace operation. Custom Properties were created to solve this by allowing you to define a value in one place and reuse it, following the Don't Repeat Yourself (DRY) principle.

The mental model

Think of CSS Custom Properties as variables for your styling. You assign a specific value, like a color hex code or a pixel size, to a named variable (e.g., --brand-color: #5b3a83;). Then, instead of hardcoding the value everywhere, you reference the variable's name. This makes your CSS more readable and far easier to maintain.

How it works

You declare a custom property with a name prefixed by two dashes, like --main-text-color: #333;. The selector you declare it on defines its scope. For global scope, it's common practice to define properties on the :root pseudo-class. To use the value, you call the var() function: color: var(--main-text-color);. These properties are part of the cascade, meaning they inherit and can be overridden by more specific selectors.

When to use it

Custom Properties are essential for theming (like light and dark modes), managing brand colors, defining consistent spacing units, or standardizing font stacks. By centralizing these values on :root, you create a single source of truth for your design system's core elements, making site-wide updates trivial.

When not to use it

The primary limitation is that custom properties can only hold property values. You cannot use a variable for a property name (var(--side): 10px; is invalid), a selector, or within the rules of a media query (@media (min-width: var(--breakpoint-md)) won't work). They are strictly for the values assigned to properties.

One canonical example

A classic use case is for theming. First, define your theme colors on the :root element: :root { --primary-color: blue; --text-color: black; }. Then, apply these variables throughout your site: body { color: var(--text-color); } and a { color: var(--primary-color); }. To change the entire site's primary color, you only need to update the single --primary-color declaration in :root.