0Pricing
Frontend Academy · Lesson

CSS Custom Properties: declaring and updating

Declare variables with -- on :root, reference them with var(), and update them dynamically with JavaScript for live theming.

CSS Custom Properties: declaring and updating is a free Frontend Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Frontend Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Recap: Declaring and Scoping

CSS custom properties are declared with -- prefix on any element. Properties declared on :root are globally available. Child elements inherit the values, and can override them locally.

:root {
  --spacing: 8px;
  --color-brand: #6366f1;
}
.card {
  --spacing: 12px; /* local override for .card and its children */
  padding: var(--spacing);
}

Live Updates via JavaScript

Custom properties can be changed at runtime. Use element.style.setProperty('--name', value) for element-level overrides, or update a global variable on :root to affect all consumers instantly.

// Change globally:
document.documentElement.style.setProperty('--color-brand', '#ef4444');

// Change locally on one element:
const card = document.querySelector('.card');
card.style.setProperty('--bg', '#f9f9f9');

Reading Custom Property Values in JS

Read a custom property with getComputedStyle(element).getPropertyValue('--name').trim(). This reads the computed (cascaded) value, not just the inline one.

const brandColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-brand')
  .trim();
console.log(brandColor); // '#6366f1'

Animating Custom Properties

Custom properties can be interpolated by the browser using @property (Houdini) or used in transitions when combined with calc(). Without @property, browsers can't transition between variable values directly.

@property — Registered Custom Properties

The CSS @property rule registers a custom property with a type, initial value, and inheritance rule. Registered properties can be transitioned and animated natively.

@property --brand-opacity {
  syntax: '<number>';
  inherits: false;
  initial-value: 1;
}

.card {
  opacity: var(--brand-opacity);
  transition: --brand-opacity 0.3s;
}
.card:hover {
  --brand-opacity: 0.7;
}

Token Systems with Custom Properties

Design tokens model: store all design decisions as custom properties. Components consume tokens, not hardcoded values. Changing a token propagates everywhere.

:root {
  /* Colour tokens */
  --token-primary: #6366f1;
  --token-primary-hover: #4f46e5;
  --token-surface: #ffffff;
  --token-on-surface: #1f2937;

  /* Spacing tokens */
  --token-space-sm: 8px;
  --token-space-md: 16px;
  --token-space-lg: 24px;
}

Responsive Custom Properties

Change custom property values inside media queries. Components that use the variables automatically adapt — cleaner than writing separate component rules per breakpoint.

:root {
  --container-max: 640px;
  --font-size-base: 15px;
}
@media (min-width: 1024px) {
  :root {
    --container-max: 1280px;
    --font-size-base: 16px;
  }
}

Custom Properties in calc()

Use variables inside calc() for derived spacing and sizing. This creates a coherent, mathetically consistent sizing system.

:root { --base-space: 8px; }
.m-2 { margin: calc(var(--base-space) * 2); }  /* 16px */
.m-4 { margin: calc(var(--base-space) * 4); }  /* 32px */
.p-3 { padding: calc(var(--base-space) * 3); } /* 24px */

Theming Multiple Brands

Set different theme tokens per data-attribute. One page can support multiple themes for white-labelling.

[data-theme='brand-a'] { --primary: #2563eb; }
[data-theme='brand-b'] { --primary: #16a34a; }
[data-theme='brand-c'] { --primary: #dc2626; }

Custom Properties in SVG

SVG attributes like fill and stroke can use custom properties. This lets you theme icons from CSS without modifying the SVG markup.

/* CSS */
:root { --icon-fill: #6366f1; }

/* SVG inline or referenced */
svg { fill: var(--icon-fill); }

Debugging Custom Properties

In Chrome DevTools, select an element and look in the Computed tab for custom property values. The Styles pane shows where each variable is declared. The Inherited section shows variables from parent elements.

Quick Check

Which JavaScript method updates a CSS custom property on an element?

Recap: CSS Custom Properties in Depth

Declare on :root for globals; override on descendants for local scope. Update with style.setProperty from JS. Read with getComputedStyle. @property enables native transitions. Use as design tokens for a single source of truth. Override in media queries for responsive tokens.

Frequently asked questions

Is the “CSS Custom Properties: declaring and updating” lesson free?

Yes — the full text of “CSS Custom Properties: declaring and updating” is free to read here on the web, and the Frontend Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Frontend Academy course, upgrade to CoddyKit PRO.

What will I learn in “CSS Custom Properties: declaring and updating”?

Declare variables with -- on :root, reference them with var(), and update them dynamically with JavaScript for live theming. You practise Frontend Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Frontend Academy?

No prior experience is required. Frontend Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “CSS Custom Properties: declaring and updating” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Frontend Academy lesson?

Yes. Every Frontend Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. CSS Custom Properties: declaring and updating
  2. Transitions: property duration timing
  3. @keyframes Animations
  4. Respecting prefers-reduced-motion
← Back to Frontend Academy