Search pages
Search all CSS Showcase pages by name
CSS Custom Properties
Dynamic variables that revolutionise how you write CSS. Create flexible design systems, seamless theming, and maintainable stylesheets with native CSS variables.
What Are Custom Properties?
Custom properties (also called CSS variables) let you store values that you can reuse throughout your stylesheet. Unlike preprocessor variables (Sass, Less), these are native to CSS and live in the browser — which means you can change them dynamically with JavaScript!
Syntax Breakdown
- Defining:
--property-name: value;— Custom properties always start with-- - Using:
var(--property-name)— Thevar()function retrieves the value - Fallback:
var(--property-name, fallback)— Comma-separated fallback if the property isn't set
Scope & Inheritance
Custom properties follow CSS cascade rules. Define them globally on :root, or scope them to specific elements. Child elements inherit their parent's custom properties.
Pro Tip
Use :root for design system tokens (colours, spacing, typography), and local scope for component-specific values. This creates a clear hierarchy and makes your CSS more maintainable.
Theming Made Easy
Custom properties are perfect for theming. Change a few variables and your entire design transforms. This is how this very website implements its dark/light theme!
Light Theme
Clean and bright, perfect for daytime browsing.
Dark Theme
Easy on the eyes, great for nighttime coding.
Dynamic Updates with JavaScript
Unlike Sass variables that compile away, CSS custom properties exist at runtime. This means JavaScript can modify them on the fly, creating truly interactive experiences.
Dynamic Colour
The preview box uses hsl() with three custom properties. When JavaScript updates any of them, the background colour changes instantly — no class toggling required.
Advanced Patterns
Custom properties unlock powerful techniques that were impossible before. Here are some advanced patterns that'll level up your CSS game.
Instead of rewriting component styles in each media query, you only update the variables. This keeps your responsive code DRY and maintainable — change one value, and everything that references it adapts automatically.
Why Component APIs?
This pattern creates a clean API for your components. Instead of creating tons of modifier classes (.button-large, .button-danger), you expose custom properties that users can adjust. It's the same approach used by modern CSS frameworks.
Real-World Example: Design System
Let's build a complete mini design system using custom properties. This is how professional design systems (like Material Design or Chakra UI) are structured.
Design System Card
This card uses tokens from our custom property design system.
Browser Support
CSS custom properties have excellent browser support! They work in all modern browsers since 2016.
Best Practices
Key principles for getting the most out of CSS custom properties.
Use :root for Globals
Define design system tokens (colours, spacing, typography) on :root so they're available everywhere. Scope component-specific variables locally.
Name Descriptively
Use semantic names like --color-primary and --spacing-lg rather than --blue or --20px. Descriptive names make themes and refactors painless.
Always Provide Fallbacks
Use var(--prop, fallback) for resilience. If a variable isn't defined in the current scope, the fallback ensures your layout never breaks.