---
title: "Custom Property"
slug: "custom-property"
category: "glossary"
tags: ["glossary", "css", "custom-property", "custom-properties", "cascade", "frontend"]
status: "stable"
last_updated: 2026-08-14
summary: "CSS custom property: a `--name` property referenced via `var()`, enabling design tokens, runtime theming, and reuse without preprocessors."
related:
  [
    "[[glossary/cascade]]",
    "[[glossary/specificity]]",
    "[[glossary/has-selector]]",
    "[[glossary/container-query]]",
    "[[frontend/css]]",
    "[[frontend/tailwind]]",
  ]
---

## Overview

This page is the atomic definition. Full CSS guidance lives at [[frontend/css]]; Tailwind's token implementation lives at [[frontend/tailwind]]. A custom property (`--name`) holds an arbitrary value consumed via `var()`, inherits through the DOM, and resolves at runtime, which makes it the standard mechanism for design tokens and live theming.

## Definition

A CSS custom property is any property whose name begins with two hyphens (`--`). Its value is an arbitrary token sequence. The value is consumed by the `var()` function with an optional fallback: `var(--color-primary, navy)`. Custom properties inherit through the DOM like `color` and `font-size`; setting `--spacing-base: 8px` on `:root` makes it available everywhere unless overridden on a descendant.

Custom properties are resolved at computed-value time, not parse time, so their value can change at runtime (via JavaScript `element.style.setProperty('--hue', '220')`) or in a media query or container query, enabling runtime theming without class toggling.

Unlike Sass variables, custom properties are live in the browser. A `prefers-color-scheme` media query can swap the entire theme by redefining a handful of custom properties on `:root`, and every `var()` reference updates automatically.

Custom properties follow the standard cascade rules (specificity, then source order) like regular properties.

## When it applies

Use custom properties for design tokens (colors, spacing, border radius, typography). Define them on `:root` for global values; override on a component root for scoped values. Prefer `@property` to declare typed custom properties (color, length, integer) when you need transitions or type safety.

## Example

```css
:root {
  --color-bg: #fff;
  --color-text: #111;
  --radius-card: 8px;
}

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

.card {
  background: var(--color-bg);
  color: var(--color-text);
  border-radius: var(--radius-card);
}
```

## Related concepts

- [[glossary/cascade]] - custom properties inherit and cascade like standard properties.
- [[glossary/specificity]] - specificity determines which custom property declaration wins.
- [[glossary/has-selector]] - style container queries read custom property values via `:has()` patterns.
- [[glossary/container-query]] - `@container style()` queries check custom property values.
- [[frontend/tailwind]] - Tailwind 4 uses CSS custom properties for its design tokens.

## Citing this term

> See [[glossary/custom-property|Custom Property]] (llmbestpractices.com/glossary/custom-property).

## Related

- [[glossary/cascade]]
- [[glossary/specificity]]
- [[glossary/container-query]]
- [[frontend/css]]
- [[frontend/tailwind]]