A custom property is for practical purposes a variable in CSS: --spacing names the property, 1.2rem is its value, and var(--spacing) is how that value gets used elsewhere in the stylesheet.
.card {
--spacing: 1.2rem;
padding: var(--spacing);
margin-bottom: var(--spacing);
}
The main argument for them is DRY code. Because the value lives in a single declaration, editing 1.2rem in one place updates every rule that references it — in the example above, two things change from one edit. That gives CSS a capability long taken for granted in programming languages.
There is a fair amount to cover on custom properties, so the sections below work through the details.
What custom properties are good for
Native custom properties pay off in a few concrete ways: they keep stylesheets DRY, so a single change propagates to many places (though abstracting too aggressively can hurt readability); they make color themes straightforward; and because they participate in the cascade, they open up CSS patterns that were previously out of reach. They can also be updated from JavaScript, which extends the possibilities further.
Syntax and naming
A custom property has to live inside a selector and its name must begin with two dashes (--):
/* Nope, not within a selector */
--foo: 1;
body {
/* No, 0 or 1 dash won't work */
foo: 1;
-foo: 1;
/* Yep! */
--foo: 1;
/* OK, but they're different properties */
--FOO: 1;
--Foo: 1;
/* Totally fine */
--mainColor: red;
--main-color: red;
/* Special characters are a no */
--color@home: red;
--black&blue: black;
--black^2: black;
}
Letters, numbers, and dashes are the safe choice for names. One custom property can also take its value from another:
html {
--red: #a24e34;
--green: #01f3e6;
--yellow: #f0e765;
--error: var(--red);
--errorBorder: 1px dashed var(--red);
--ok: var(--green);
--warning: var(--yellow);
}
This style of layering lets a descriptively named property feed a more functionally named one. Be aware, though, that there is a significant gotcha when custom properties reference other custom properties.
What values are allowed
The value syntax is remarkably permissive. Hex values, color functions, any unit, and plain strings of text all work:
body {
--brand-color: #990000;
--transparent-black: rgba(0, 0, 0, 0.5);
--spacing: 0.66rem;
--max-reading-length: 70ch;
--brandAngle: 22deg;
--visibility: hidden;
--my-name: "Chris Coyier";
}
Splitting values into parts
Multi-part values can be decomposed so that each piece becomes its own custom property. With a color function like rgba(), every channel can be a separate property, which makes it easy to adjust only the alpha for one use case or to build themes.
Colors
HSL is a natural fit for splitting. When the background of a button is composed from separate H, S, and L properties, hover, focus, and disabled states can override just the relevant channel — without redeclaring background at all.
button {
--h: 100;
--s: 50%;
--l: 50%;
--a: 1;
background: hsl(var(--h) var(--s) var(--l) / var(--a));
}
button:hover { /* Change the lightness on hover */
--l: 75%;
}
button:focus { /* Change the saturation on focus */
--s: 75%;
}
button[disabled] { /* Make look disabled */
--s: 0%;
--a: 0.5;
}
That is control over parts of a value that plain CSS never offered.
Shadows and gradients
box-shadow has no shorthand for the spread value alone, but the spread can be pulled out into a custom property and changed independently.
button {
--spread: 5px;
box-shadow: 0 0 20px var(--spread) black;
}
button:hover {
--spread: 10px;
}
Gradients work the same way: there is no background-gradient-angle property, but with custom properties you can alter just the angle as if one existed.
body {
--angle: 180deg;
background: linear-gradient(var(--angle), red, blue);
}
body.sideways {
--angle: 90deg;
}
Comma-separated lists
Any property accepting multiple comma-separated values is a candidate for splitting, since CSS cannot target a single item in such a list on its own.
/* Lots of backgrounds! */
background-image:
url(./img/angles-top-left.svg),
url(./img/angles-top-right.svg),
url(./img/angles-bottom-right.svg),
url(./img/angles-bottom-left.svg),
url(./img/bonus-background.svg);
Removing one of several backgrounds at a media query, for instance, becomes trivial:
body {
--bg1: url(./img/angles-top-left.svg);
--bg2: url(./img/angles-top-right.svg);
--bg3: url(./img/angles-bottom-right.svg);
--bg4: url(./img/angles-bottom-left.svg);
--bg5: url(./img/bonus-background.svg);
background-image: var(--bg1), var(--bg2), var(--bg3), var(--bg4);
}
@media (min-width: 1500px) {
body {
background-image: var(--bg1), var(--bg2), var(--bg3), var(--bg4), var(--bg5);
}
}
Grids
grid-template-columns values can be abstracted into custom properties to produce a flexible grid system:
.grid {
display: grid;
--edge: 10px;
grid-template-columns: var(--edge) 1fr var(--edge);
}
@media (min-width: 1000px) {
.grid {
--edge: 15%;
}
}
Transforms
Individual transform properties are on the way in CSS, but custom properties offer the pattern now: declare every transform the element might receive up front, then control each one as needed.
button {
transform: var(--scale, scale(1)) var(--translate, translate(0));
}
button:active {
--translate: translate(0, 2px);
}
button:hover {
--scale: scale(0.9);
}
Building units by multiplication
You cannot concatenate 24 and px into 24px. You can, however, multiply a raw number by a unit-carrying value to get the same result.
body {
--value: 24;
--unit: px;
/* Nope */
font-size: var(--value) + var(--unit);
/* Yep */
font-size: calc(var(--value) * 1px);
/* Yep */
--pixel_converter: 1px;
font-size: calc(var(--value) * var(--pixel_converter));
}
The cascade at work
Inheritance through the cascade is arguably the most valuable trait of custom properties. A property defined high up, on body say, and redefined on a specific class behaves differently depending on where it is consumed.
body {
--background: white;
}
.sidebar {
--background: gray;
}
.module {
background: var(--background);
}
<body> <!-- --background: white -->
<main>
<div class="module">
I will have a white background.
</div>
<main>
<aside class="sidebar"> <!-- --background: gray -->
<div class="module">
I will have a gray background.
</div>
</aside>
</body>

.sidebar is a closer ancestor than body, thus --background resolves to gray there, but white in other places.Because custom properties inherit, the sidebar module picks up a gray background from the nearest ancestor where --background is defined. One declaration therefore renders differently in different contexts.
button {
--foo: Default;
}
button:hover {
--foo: I win, when hovered;
/* This is a more specific selector, so re-setting
custom properties here will override those in `button` */
}
Media queries leave specificity untouched, but they typically appear later in the file, so a value set inside one wins over the earlier declaration:
body {
--size: 16px;
font-size: var(--size);
}
@media (max-width: 600px) {
body {
--size: 14px;
}
}
Media queries also cover accessibility preferences, dark mode among them:
body {
--bg-color: white;
--text-color: black;
background-color: var(--bg-color);
color: var(--text-color);
}
/* If the user's preferred color scheme is dark */
@media screen and (prefers-color-scheme: dark) {
body {
--bg-color: black;
--text-color: white;
}
}
About :root
Setting custom properties on :root is simply a way of placing them as high in the tree as possible:
:root {
--color: red;
}
/* ...is largely the same as writing: */
html {
--color: red;
}
/* ...except :root has higher specificity, so remember that! */
Nothing requires it; html or body feels just as natural for values meant to be globally available. Nor is a broad scope mandatory — defining properties close to where they are used is often more readable. Note that setting a property on a component itself stops it from inheriting an ancestor's value unless it is explicitly set to inherit. Defining in one place, inheriting behind the scenes, and applying somewhere else entirely is exactly the point.
!important inside custom properties
The modifier can go inside or outside the variable:
.override-red {
/* this works */
--color: red !important;
color: var(--color);
/* this works, too */
--border: red;
border: 1px solid var(--border) !important;
}
Putting !important on --color makes that variable hard to override, though the color property itself can still ignore it. The behavior inside values is unusual: the flag is stripped from the final value, but it still decides which value wins.
- The
!importantis removed from the custom property's value. - It still participates in resolving which declaration wins.
div {
--color: red !important;
}
#id {
--color: yellow;
}
When both selectors match an element, the rule ignores #id's higher specificity: red wins on account of the !important, then applies without it. With the flag placed outside the property, as in the second example above, --border stays low-specificity and easy to override, but the declaration as a whole keeps !important, so changing how it applies is difficult.
Fallback values
The var() function is where fallbacks come from. Below, a scale() function is assigned with a comma-separated fallback of 1.2, used whenever --scale is not set:
.bigger {
transform: scale(var(--scale, 1.2));
}
Everything after the first comma belongs to the fallback, which means comma-separated fallbacks like a font stack are possible:
html {
font-family: var(--fonts, Helvetica, Arial, sans-serif);
}
Chaining variable fallbacks works too, but requires nesting:
.bigger {
transform: scale(var(--scale, var(--second-fallback, 1.2));
}
Undefined --scale leads to --second-fallback, and only if that is missing does it land on 1.2.
Pairing with calc()
Combining custom properties with math unlocks more. A common pattern:
main {
--spacing: 2rem;
}
.module {
padding: var(--spacing);
}
.module.tight {
/* divide the amount of spacing in half */
padding: calc(var(--spacing) / 2));
}
The same approach computes a complementary hue:
html {
--brand-hue: 320deg;
--brand-color: hsl(var(--brand-hue), 50%, 50%);
--complement: hsl(calc(var(--brand-hue) + 180deg), 50%, 50%);
}
And calc() accepts several custom properties at once:
.slider {
width: calc(var(--number-of-boxes) * var(--width-of-box));
}
Leaving calc() for later
Math on variables without a visible calc() looks odd:
body {
/* Valid, but the math isn't actually performed just yet ... */
--font-size: var(--base-font-size) * var(--modifier);
/* ... so this isn't going to work */
font-size: var(--font-size);
}
It resolves as long as the final use is wrapped in calc():
body {
--base-font-size: 16px;
--modifier: 2;
--font-size: var(--base-font-size) * var(--modifier);
/* The calc() is "deferred" down to here, which works */
font-size: calc(var(--font-size));
}
Worth doing when heavy math makes the wrapper noisy.
Typed properties with @property
@property declares the type of a custom property along with its initial value and inheritance behavior — effectively defining a real CSS property: name, syntax, cascade interaction, initial value.
@property --x {
syntax: '<number>';
inherits: false;
initial-value: 42;
}
The permitted types are length, number, percentage, length-percentage, color, image, url, integer, angle, time, resolution, transform-list, transform-function, and custom-ident.
With a type declared, the browser knows what it is handling instead of treating everything as a string, which enables animations that would otherwise fail. Rotating a star icon between 0deg and 360deg via @keyframes and transform simply will not work untyped, because the browser does not recognize those as angles.
.star {
--r: 0deg;
transform: rotate(var(--r));
animation: spin 1s linear infinite;
}
@keyframes spin {
100% {
--r: 360deg;
}
}
The fix is declaring an <angle> type:
@property --r {
syntax: '<angle>';
initial-value: 0deg;
inherits: false;
}
.star {
--r: 0deg;
transform: rotate(var(--r));
animation: spin 1s linear infinite;
}
@keyframes spin {
100% {
--r: 360deg;
}
}
Commas and advanced techniques
Comma handling is mostly intuitive here:
html {
--list: 1, 2, 3;
}
But in the next example the fallback is 1.2, 2: only the first comma separates it, and the rest is part of the value.
html {
transform: scale(var(--scale, 1.2, 2));
}
The initial / whitespace toggle
The premise mirrors a media query: one change, many effects. The mechanism relies on the fact that initial as a custom property value triggers a fallback while empty whitespace does not. Two global properties, ON and OFF:
:root {
--ON: initial;
--OFF: ;
}
A "dark" class then reads from a default --OFF flip-able to --ON:
.module {
--dark: var(--OFF);
}
.dark { /* could be a media query or whatever */
--dark: var(--ON);
}
Flipping --dark to --ON conditionally applies the values that depend on it. Lea Verou's writeup covers the technique in full.
Inline styles
Setting a custom property in an inline style attribute is perfectly legitimate and, like any inline style, carries very high specificity:
<div style="--color: red;"></div>
That is handy when HTML holds styling information too awkward for a static stylesheet — aspect ratio being a classic case:
<div style="--aspect-ratio: 16 / 9;"></div>
The CSS can then size a box accordingly, using the padded-box technique on a pseudo-element:
[style*="--aspect-ratio"] > :first-child {
width: 100%;
}
[style*="--aspect-ratio"] > img {
height: auto;
}
@supports (--custom: property) {
[style*="--aspect-ratio"] {
position: relative;
}
[style*="--aspect-ratio"]::before {
content: "";
display: block;
padding-bottom: calc(100% / (var(--aspect-ratio)));
}
[style*="--aspect-ratio"] > :first-child {
position: absolute;
top: 0;
left: 0;
height: 100%;
}
}
With a native aspect-ratio property in CSS today, though, an inline style may make more sense going forward:
<div style="aspect-ratio: 16 / 9;"></div>
Hover states from inline styles
Inline styles cannot address :hover or other pseudo classes and elements — unless custom properties do the work. Pass a hover color in as a property:
<div style="--hover-color: red;"><div>
<div style="--hover-color: blue;"><div>
<div style="--hover-color: yellow;"><div>
Then consume it from CSS, which is free to style the link's hover state:
div:hover {
background-color: var(--hover-color);
}
/* And use in other pseudos! */
div:hover::after {
content: "I am " attr(style);
border-color: var(--hover-color);
}
Driving custom properties from JavaScript
JavaScript can assign a custom property's value:
element.style.setProperty('--x', value);
In an example, a red square is positioned with custom properties that JavaScript updates from the mouse position.
The usual direction is JavaScript passing values to CSS, but it works in reverse too, since the accepted value is permissive enough to hold a logical statement:
html {
--logic: if (x > 5) document.body.style.background = "blue";
}
That value can be retrieved and executed in JavaScript:
const x = 10;
const logic = getComputedStyle(document.documentElement).getPropertyValue(
"--logic"
);
eval(logic);
Custom properties versus preprocessor variables
Sass, Less, and Stylus all offer variables, so the question is whether native custom properties are still worth using. Yes:
- They are more powerful. Integration with the DOM cascade is beyond anything preprocessor variables can do.
- They are dynamic. A change — from JavaScript or a media query — triggers the repaint the browser needs. Preprocessor variables resolve at compile time and stay put.
- They are future-proof. Native features need no preprocessing.
Preprocessor variables still win in a few narrow cases, such as stripping units off a value, which is easy in Sass and hard with CSS alone.
Preprocessing custom properties
Moving a Sass variable into a custom property is possible, but Sass only emits --brandColor: red; — it cannot process the custom property away. No CSS syntax transform can force a browser without native support to emulate them, and a JavaScript polyfill that parses and replicates your CSS is not advisable. The PostCSS Custom Properties plugin does help by resolving the value as best it can and emitting it alongside:
$brandColor: red;
body {
--brandColor: #{$brandColor};
}
Which produces output like this:
:root {
--brandColor: red;
}
body {
color: var(--brandColor);
}
Support degrades more gracefully, but none of the advanced custom property behavior is covered — the plugin does not attempt it. A limited result, but a reasonable one.
Availability
Preprocessor variables exist only during processing; $brandColor means nothing in HTML or JavaScript. A custom property, by contrast, works in inline styles and its current contextual value can be read from JavaScript. Apart from a few esoteric preprocessor capabilities, custom properties are the more capable and useful tool.
The Shadow DOM
Custom properties as styling hooks are among the most common and practical ways to style a Web Component, such as a <custom-component> with shadow DOM. The shadow DOM's isolation prevents styles from leaking in or out — short of an <iframe>, nothing else offers comparable isolation — yet styles still cascade inward even when selectors cannot reach. Custom properties flow straight through. The same applies to SVG and the <use> element. For video coverage, see "CSS Custom Properties Penetrate the Shadow DOM".
Support and feature queries
Desktop:
| Chrome | Firefox | IE | Edge | Safari |
|---|---|---|---|---|
| 49 | 31 | No | 16 | 10 |
Mobile / tablet:
| Android Chrome | Android Firefox | Android | iOS Safari |
|---|---|---|---|
| 157 | 160 | 157 | 10.0-10.2 |
Preprocessing with its heavy limits is the only route to deeper support. To branch on native support in CSS:
@supports (--custom: property) {
/* Isolated CSS for browsers that DOES support custom properties, assuming it DOES support @supports */
}
@supports not (--custom: property) {
/* Isolated CSS for browsers that DON'T support custom properties, assuming it DOES support @supports */
}


