How to use CSS custom properties for theming
Define color, spacing, and font variables in one place. Override them globally or per-class without editing every rule. Create maintainable themes in minutes.
Define CSS variables to store colors, spacing, and fonts in a single location. You can override these values globally or on specific elements without touching every rule. This approach creates a scalable theming system that works across projects.
Prerequisites
- A modern browser that supports CSS custom properties (CSS Level 4).
- Basic knowledge of CSS selectors and the cascade.
- Access to a code editor or HTML file to test the styles.
- Understanding of class naming conventions (BEM or utility classes).
Step 1: Create a global variable block
Open your main stylesheet, such as styles.css. Add a :root selector to the top of the file. This selector defines variables that apply to the entire site.
:root {
--color-primary: #2563eb;
--color-secondary: #475569;
--color-background: #ffffff;
--color-text: #1e293b;
--spacing-xs: 0.5rem;
--spacing-sm: 1rem;
--spacing-md: 2rem;
--font-family-base: system-ui, -apple-system, sans-serif;
--border-radius: 0.375rem;
}You will see the browser render the default theme immediately. These values act as the source of truth for your design system. Changing a hex code here updates every element using that variable.
Step 2: Use variables in component styles
Open your component file, for example card.css. Select the .card class. Replace hardcoded values with the variables you defined in the :root block.
.card {
background-color: var(--color-background);
color: var(--color-text);
padding: var(--spacing-md);
border-radius: var(--border-radius);
font-family: var(--font-family-base);
}Apply the same pattern to buttons and headers. Use var(--color-primary) for button backgrounds. Use var(--spacing-sm) for padding. This ensures consistency across the entire application.
Step 3: Create a dark theme variant
Open your stylesheet again. Create a new selector for the dark mode class, such as .theme-dark. Define a new set of variables inside this block that override the global defaults.
.theme-dark {
--color-background: #0f172a;
--color-text: #f1f5f9;
--color-secondary: #94a3b8;
--color-primary: #3b82f6;
}Apply this class to the body tag in your HTML. The browser calculates the new values based on the cascade. Elements inside the dark theme container will automatically switch colors.
Step 4: Scope variables to a specific section
Open your HTML file. Add a container div with a unique ID, for example id="promo-section". Create a CSS block for this ID. Define variables that only apply to this section.
#promo-section {
--promo-bg: #f0fdf4;
--promo-text: #166534;
}Inside this block, style the elements using the scoped variables. Use var(--promo-bg) for the background color. Use var(--promo-text) for the text color. This prevents the dark theme from affecting this specific promotional area.
Step 5: Extend variables for hover states
Open your stylesheet. Define variables for hover states inside the :root block. This allows you to create smooth transitions without hardcoding hex values.
:root {
--color-primary-hover: #1d4ed8;
--color-primary-hover-alpha: rgba(37, 99, 235, 0.8);
--transition-speed: 0.2s;
}Apply these to your button styles. Set the background to var(--color-primary). Set the hover background to var(--color-primary-hover). Add transition: background-color var(--transition-speed) to the element.
Verify the implementation
Create a simple HTML file named index.html. Paste the following code into it to test the variables.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>CSS Variables Test</title>
<style>
:root {
--color-primary: #2563eb;
--color-dark: #0f172a;
--color-light: #ffffff;
}
body {
color: var(--color-primary);
background: var(--color-light);
}
.dark-mode {
--color-primary: #60a5fa;
--color-light: #1e293b;
}
.dark-mode body {
color: var(--color-primary);
background: var(--color-light);
}
button {
background: var(--color-primary);
color: white;
border: none;
padding: 1rem;
border-radius: var(--border-radius);
cursor: pointer;
}
button:hover {
opacity: 0.9;
}
</style>
</head>
<body>
<h1>Default Theme</h1>
<button>Click Me</button>
<button class="dark-mode">Dark Mode Button</button>
<h2>Switch to Dark Mode</h2>
<button class="dark-mode">Dark Mode Button</button>
</body>
</html>Open index.html in your browser. You will see the default blue theme. The second button uses the dark theme variables. Click the buttons to verify the hover states work correctly. Inspect the computed styles to confirm the variables are resolving.
Troubleshooting
If your variables do not appear, check the browser console for errors. Ensure you are using var() syntax correctly. Verify that the :root selector is placed before the elements using it. If you are using a framework, check if it resets your custom properties. Use !important sparingly to override framework defaults if necessary. Clear your browser cache to ensure old styles do not persist.