Favorites

Understanding the CSS :root Pseudo-Class

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee
CSS Root Pseudo

What is :root?

:root is a pseudo-class: a keyword added to a selector that matches elements in a particular state or position. It matches the root element of the document, the one element that contains everything else. In an HTML page, that's always the <html> element.

:root {
  font-size: 100%;
  color-scheme: light dark;
}

Because every other element sits inside it, :root is the natural home for page-wide settings, and above all for custom properties (CSS variables) that you want to use everywhere.

Custom properties in :root

A custom property is a value you name and store once, then reuse anywhere. Its name always starts with two dashes:

:root {
  --accent: #1d4ed8;
  --radius: 8px;
  --space: 16px;
}

To use a custom property, read it with the var() function:

.button {
  padding: calc(var(--space) / 2) var(--space);
  color: #ffffff;
  background: var(--accent);
  border-radius: var(--radius);
}

Change --accent in :root, and every button, link and border that uses it updates together. That's why custom properties make sites so much easier to keep consistent.

Fallback values

var() accepts a second value, which is used if the custom property hasn't been set:

.badge {
  background: var(--badge-color, #be185d);  /* pink unless --badge-color is set */
}

Good to know: custom property names are case-sensitive, so --Accent and --accent are two different properties. Using lower case with hyphens, like --accent-dark, avoids mix-ups.

Why :root and not html?

In an HTML page, :root and html select exactly the same element. There are two reasons people prefer :root for custom properties:

  • Specificity. Specificity is the score browsers use to decide which rule wins when two rules conflict. Pseudo-classes count like classes, so :root scores higher than the element selector html, and a :root rule wins over an html rule whatever order they're in.
  • It works in other documents. CSS isn't only used in HTML. In a standalone SVG file, for example, the root element is <svg>, and :root still matches it.

A common convention is to use :root for custom properties and global settings, and html or body for ordinary styles such as fonts and colours. Either works, as long as you're consistent.

Overriding values locally

Custom properties are inherited: a value set on an element passes down to everything inside it. Setting them on :root makes them available everywhere, but you can also set a new value on any element, and it applies to that element and everything inside it:

:root {
  --accent: #1d4ed8;
}

.card-sale {
  --accent: #be185d;  /* only this card and its contents */
}

.card-new {
  --accent: #15803d;
}
Results
DefaultStandard planView
SalePro planView
NewTeam planView

All three cards use exactly the same CSS for their borders, headings and buttons. Only the value of --accent changes. This is a very tidy way to create variations of a component without writing new rules for every part of it.

Themes and dark mode

Custom properties in :root are ideal for colour themes. Set the theme colours once, use the custom properties throughout your CSS, and switch themes by changing just those values.

Modern CSS makes dark mode especially simple with the light-dark() function, which picks the first value in light mode and the second in dark mode:

:root {
  color-scheme: light dark;  /* follow the visitor's device setting */

  --bg: light-dark(#ffffff, #111827);
  --text: light-dark(#1f2937, #f3f4f6);
  --accent: light-dark(#1d4ed8, #93c5fd);
}

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

The panels below use the same custom properties. One has color-scheme forced to light and the other to dark:

Results
Light mode

The same CSS, with different values from light-dark().

A themed link
Dark mode

The same CSS, with different values from light-dark().

A themed link

The light-dark() function works in all major browsers. For more ways to build a dark theme, including a theme switch, see our CSS dark mode guide.

Responsive values

You can also change custom properties inside media queries, so that one change adjusts spacing or sizes across the whole site:

:root {
  --space: 16px;
}

@media (min-width: 900px) {
  :root {
    --space: 24px;
  }
}

Changing values with JavaScript

Unlike variables in preprocessors like Sass, custom properties exist in the browser, so JavaScript can read and change them while the page is running:

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

// Change a value
root.style.setProperty('--accent', '#be185d');

// Read the current value
const accent = getComputedStyle(root).getPropertyValue('--accent');

Try it below. The colour picker and slider each change one custom property, and everything inside the demo updates at once:

Results
Your theme preview

To keep it from affecting the rest of this page, the demo changes the custom properties on its own container rather than on :root. On your own site, you'd usually set them on document.documentElement to change the whole page, for example, for a theme picker.

Other settings that belong in :root

As well as custom properties, a few page-wide settings work best on the root element:

:root {
  color-scheme: light dark;   /* native dark mode for scrollbars and form controls */
  font-size: 100%;            /* respect the visitor's browser font size */
  scroll-padding-top: 80px;   /* leave room for a sticky header when jumping to #links */
}

@media (prefers-reduced-motion: no-preference) {
  :root {
    scroll-behavior: smooth;  /* smooth scrolling, only for people who don't mind motion */
  }
}
  • color-scheme tells the browser your page supports light and dark modes, so it can style scrollbars, form controls and the default background to match.
  • font-size on the root element sets what 1rem equals. Avoid a fixed pixel value here, because it overrides the text size people have chosen in their browser settings.
  • scroll-padding-top stops a sticky header from covering headings when someone follows a link to a section of the page.
  • scroll-behavior: smooth animates jumps to links on the same page. Wrapping it in prefers-reduced-motion keeps it off for people who find movement uncomfortable.

Going further with @property

Normally the browser treats a custom property's value as plain text, so it can't animate between two values. The @property rule tells the browser what type of value a custom property holds, such as a colour, a length or an angle, which makes it animatable:

@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@keyframes spin {
  to { --angle: 360deg; }
}

.glow-border {
  padding: 4px;
  border-radius: 14px;
  background: conic-gradient(from var(--angle), #2563eb, #db2777, #f59e0b, #2563eb);
  animation: spin 4s linear infinite;
}
Results
A card with an animated gradient border

Here, animating the --angle custom property rotates the gradient behind the card. Without @property, the angle would jump straight from 0 to 360 degrees instead. The rule also sets an initial-value, which acts as a built-in default. @property works in all major browsers.

Common gotchas

  • A missing var(): writing color: --accent does nothing. Always wrap the name, as in var(--accent).
  • Units can't be added afterwards: --size: 20 and then var(--size)px doesn't work. Either store the unit (--size: 20px) or multiply: calc(var(--size) * 1px).
  • Invalid values fail quietly: if a custom property holds something that doesn't suit the property using it, such as a colour in width, the browser ignores the declaration and uses the default value, without any error message. Your browser's developer tools show the actual values.

Wrapping up

:root selects the top-level element of the page, which makes it the perfect place for custom properties and page-wide settings. Define your colours, spacing and sizes there once, override them locally for variations, switch them for dark mode with light-dark(), and change them live with JavaScript. It's one of the simplest ways to make your CSS consistent, flexible and easy to maintain.

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee