Customizing Bootstrap with CSS Variables — Runtime Theme Changes

DodaTech Updated 2026-06-28 4 min read

In this tutorial, you will learn about Customizing Bootstrap with CSS Variables. We cover key concepts, practical examples, and best practices to help you master this topic.

Bootstrap 5 uses CSS custom properties (variables) for runtime theming. Overriding --bs-* variables in your stylesheet changes Bootstrap's appearance without recompiling Sass.

What You'll Learn

You will learn how Bootstrap uses CSS custom properties, override theme variables at runtime, create dark mode toggles, and combine CSS variables with Sass for flexible theming.

Why It Matters

CSS variables enable client-side theme switching. DodaTech uses CSS variables to implement dark mode across all its products without rebuilding CSS.

Real-World Use

Doda Browser's settings page allows users to toggle between light and dark themes by changing CSS custom properties via JavaScript.

flowchart LR
    A[Sass Customization] --> B[CSS Variables]
    B --> C[Built-in Variables]
    B --> D[Runtime Override]
    B --> E[Dark Mode]
    B --> F[Custom Properties]
    style B fill:#7952b3,stroke:#563d7c,color:#fff
    style D fill:#22c55e,stroke:#16a34a,color:#fff

Bootstrap's CSS Variable System

Bootstrap defines its theme as CSS custom properties on the :root element:

:root {
  --bs-primary: #0d6efd;
  --bs-secondary: #6c757d;
  --bs-success: #198754;
  --bs-danger: #dc3545;
  --bs-body-font-family: system-ui, sans-serif;
  --bs-body-font-size: 1rem;
  --bs-border-radius: 0.375rem;
}

These variables are used throughout Bootstrap's components. Changing them at runtime updates all dependent components.

Overriding Variables at Runtime

:root {
  --bs-primary: #7c3aed;
  --bs-primary-rgb: 124, 58, 237;
  --bs-border-radius: 0.75rem;
  --bs-body-font-family: "Inter", system-ui, sans-serif;
}

Expected output: All Bootstrap components using the primary color now show purple. Border radius is larger everywhere. Font family changes globally.

The -rgb variant is used for rgba() functions (like backgrounds with opacity). Always override both --bs-primary and --bs-primary-rgb.

Dark Mode with CSS Variables

:root {
  --bs-body-bg: #ffffff;
  --bs-body-color: #212529;
  --bs-border-color: #dee2e6;
}

[data-theme="dark"] {
  --bs-body-bg: #0f172a;
  --bs-body-color: #e2e8f0;
  --bs-border-color: #334155;
  --bs-primary: #818cf8;
  --bs-primary-rgb: 129, 140, 248;
}

<html data-theme="dark">

Expected output: A dark-themed page where all Bootstrap components use dark colors. Toggle the data-theme attribute to switch themes.

Use a JavaScript toggle:

function toggleTheme() {
  var html = document.documentElement;
  var current = html.getAttribute('data-theme');
  html.setAttribute('data-theme', current === 'dark' ? 'light' : 'dark');
}

Component-Specific Variables

.card {
  --bs-card-border-color: #e2e8f0;
  --bs-card-border-radius: 1rem;
  --bs-card-box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  --bs-card-cap-bg: #f8fafc;
}

.btn {
  --bs-btn-border-radius: 999px;
  --bs-btn-padding-x: 1.5rem;
}

Expected output: Cards have custom border color, larger radius, box shadow, and light header background. Buttons become pill-shaped with wider padding.

Variables vs Sass

// Compile-time (Sass) — fixed when CSS is built
$primary: #7c3aed;

// Runtime (CSS variables) — changeable in browser
:root {
  --bs-primary: #7c3aed;
}

Sass customization is permanent after compilation. CSS variable customization can change dynamically. Use Sass for brand identity and CSS variables for user preferences.

Variable Reference

/* Color */
--bs-primary
--bs-primary-rgb
--bs-secondary
--bs-success
--bs-danger
--bs-warning
--bs-info
--bs-light
--bs-dark

/* Body */
--bs-body-bg
--bs-body-color
--bs-body-font-family
--bs-body-font-size
--bs-body-line-height

/* Borders */
--bs-border-color
--bs-border-width
--bs-border-radius
--bs-border-radius-sm
--bs-border-radius-lg
--bs-border-radius-xl
--bs-border-radius-xxl
--bs-border-radius-pill

Common Mistakes

1. Overriding Variables Without rgb Variants

CSS variables that use rgba() need the -rgb variant. Overriding only --bs-primary without --bs-primary-rgb causes transparency issues.

2. Variable Specificity Conflicts

CSS variables set on :root have lower specificity than those set on specific elements. Override at the correct level.

3. Not Targeting All Themed Elements

Dark mode changes need to cover all CSS variables Bootstrap uses, including borders, backgrounds, text colors, and component-specific variables.

4. Forgetting Component-Specific Variables

Changing --bs-body-bg does not affect all component backgrounds. Each component has its own variables like --bs-card-bg and --bs-navbar-bg.

5. Mixing Sass and CSS Variable Approaches

Sass variables are evaluated at compile time. CSS variables are evaluated at runtime. They can be combined but understanding the difference prevents confusion.

Practice Questions

What is the naming pattern for Bootstrap's CSS custom properties? --bs-{component}-{property} pattern, like --bs-primary, --bs-card-bg.
Why do some variables have an -rgb suffix? The -rgb variant provides the color as comma-separated RGB values for use with rgba() opacity functions.
How do you implement dark mode with Bootstrap? Override CSS custom properties under a [data-theme="dark"] selector and toggle the attribute with JavaScript.
Can CSS variables and Sass variables be used together? Yes. Sass handles compile-time values. CSS variables handle runtime values.
What is the advantage of CSS variables over Sass for theming? CSS variables can change at runtime without recompilation, enabling user-facing theme switching.

Challenge

Create a theme switcher that toggles between light, dark, and high-contrast themes by changing CSS custom properties. Each theme should change at least 10 Bootstrap CSS variables.

FAQ

Do CSS variables work in all browsers?

Yes. CSS custom properties are supported in all modern browsers including Chrome, Firefox, Safari, and Edge.

Can I use CSS variables with Bootstrap's utility classes?

Yes. Utility classes like text-primary reference the CSS variable internally. Changing --bs-primary updates all utility class colors.

How do I find all available CSS variables?

Inspect the :root pseudo-class in browser devtools or check Bootstrap's source code under scss/_root.scss.

Can I define my own CSS variables for custom components?

Yes. Define custom variables under your own namespace like --doda-* and reference them in your CSS.

Do CSS variables affect performance?

CSS variables have negligible performance impact. Browsers optimize them well.

Mini Project

Build a theme switcher demo page with three buttons: Light, Dark, and Custom. Clicking each button changes CSS custom properties to apply the selected theme. Include a card, button, navbar, and form elements to demonstrate theme changes.

What's Next

Learn Bootstrap JavaScript for programmatic component control. Then build the Bootstrap Project to apply everything you have learned.

← Previous Customizing Bootstrap with Sass — Variables and Theme Customization Next → Bootstrap JavaScript — Programmatic Component Control

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Bootstrap