Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 58 ยท Customizing

Customizing with CSS Variables

Restyle Bootstrap 5.3 with its --bs-* CSS variables: change colors, fonts and radius on :root, tune single components, and know which variables really apply.

Every Bootstrap page looks like Bootstrap until you change something. The easiest way to change it is not Sass and not a pile of !important rules: it is CSS custom properties, usually called CSS variables. Since version 5.2, Bootstrap builds its look out of variables named --bs-*. Change a variable and everything that uses it follows, without a build step.

This lesson shows where those variables live, how to override them for the whole page, for one component type and for one single element, and which colors do not follow the obvious variable (a classic trap). If you want to change the source files instead, the next lesson, Customizing with Sass, covers that route.

Two kinds of variables

Bootstrap 5.3 defines variables on two levels.

Root variables are declared on :root (the <html> element) and describe the whole design: the palette, the body font and size, the border radius, the shadows, the link colors. A few examples:

Variable What it controls
--bs-body-bg, --bs-body-color Page background and default text color
--bs-body-font-family, --bs-body-font-size, --bs-body-line-height The base typography
--bs-border-color, --bs-border-width Borders on cards, inputs, tables and more
--bs-border-radius (and -sm, -lg, -xl, -pill) Rounded corners
--bs-box-shadow (and -sm, -lg) The shadow utilities
--bs-link-color, --bs-link-hover-color Link colors
--bs-primary, --bs-primary-rgb and the other theme colors The palette
--bs-primary-text-emphasis, --bs-primary-bg-subtle, --bs-primary-border-subtle Tinted variants used by alerts and subtle utilities

Component variables are declared on the component's own class, for example .btn, .card, .alert or .navbar. They describe that one component: --bs-btn-padding-x, --bs-card-bg, --bs-alert-border-radius, --bs-navbar-brand-font-size. The component's CSS then reads them: the padding of a button is literally padding: var(--bs-btn-padding-y) var(--bs-btn-padding-x).

Many component variables point back at a root variable. The default --bs-btn-border-radius is var(--bs-border-radius). That chain is why one change on :root can reshape buttons, cards, inputs and alerts at once.

flowchart TD
  R[":root<br/>--bs-border-radius: .375rem"] --> B[".btn<br/>--bs-btn-border-radius"]
  R --> C[".card<br/>--bs-card-border-radius"]
  R --> A[".alert<br/>--bs-alert-border-radius"]
  B --> P["Rendered button corners"]
  C --> Q["Rendered card corners"]
  A --> S["Rendered alert corners"]

A root variable feeds many component variables; each component reads only its own.

Using Bootstrap's variables in your own CSS

Because the variables exist in the browser, your own rules can use them. A custom panel that always matches the current theme looks like this:

CSS
.panel {
  background: var(--bs-body-bg);
  color: var(--bs-body-color);
  border: var(--bs-border-width) solid var(--bs-border-color);
  border-radius: var(--bs-border-radius-lg);
  box-shadow: var(--bs-box-shadow-sm);
}

If the site later changes --bs-border-radius-lg, or switches to dark mode, .panel follows automatically. You never copy a hex value, so there is nothing to keep in sync.

Changing the whole page from :root

To restyle the page, declare your own values for the root variables after Bootstrap's stylesheet. Same selector, later in the file, so yours wins.

Re-skin the page from :root

Compare this with writing .card { border-radius: 0.9rem } .btn { ... } .form-control { ... } by hand. One variable replaced a whole list of overrides.

Load order matters. Put your <style> or <link> after the Bootstrap stylesheet. Variables declared on :root in an earlier stylesheet are overridden by a later declaration of equal specificity.

The palette trap

You might expect that setting --bs-primary recolors everything that is "primary". It does not, and knowing why saves hours.

Bootstrap 5.3 colors different parts in different ways:

  • Utilities such as .bg-primary, .text-primary, .text-bg-primary, .border-primary read --bs-primary-rgb (the three channels, 13, 110, 253), so they can apply opacity.
  • Links read --bs-link-color-rgb and --bs-link-hover-color-rgb, not --bs-primary at all.
  • Alerts, list-group items and subtle utilities read the -text-emphasis, -bg-subtle and -border-subtle variables.
  • Buttons such as .btn-primary set their own component variables with fixed values (--bs-btn-bg: #0d6efd and a hover, active and disabled set). They do not read --bs-primary.

So to move the primary color to purple you must change several things: the -rgb triple for utilities, the link variables, and the button's own variables.

Which parts follow --bs-primary-rgb?

The badge, the text and the link turn purple from the root changes. The first button stays blue. The second button, which adds btn-brand after btn-primary, turns purple because .btn-brand is declared later with the same specificity.

Some blues are not variables. The focus glow of form fields and a few other states use fixed colors in the compiled CSS. If you change the primary color and a focus ring stays blue, override it explicitly, or rebuild with Sass (which changes every derived color at once).

Overriding a single component type or element

Component variables are the right level for "all my cards look like this" and for "just this one button":

CSS
/* every card on the site */
.card {
  --bs-card-bg: var(--bs-tertiary-bg);
  --bs-card-spacer-y: 1.5rem;
  --bs-card-spacer-x: 1.5rem;
}
HTML
<!-- a single element, with an inline style -->
<div class="card" style="--bs-card-border-radius: 1.5rem;">...</div>

Setting a custom property inline is much safer than setting a normal property inline. style="--bs-card-border-radius: 1.5rem" changes one input to the card's own rules; it does not fight with them, and it is not !important. The component CSS still decides where the value is used.

Variables also inherit. A variable set on a wrapper reaches every descendant that reads it, so you can make a themed region:

HTML
<section style="--bs-body-bg: #101827; --bs-body-color: #e5e7eb;">
  <div class="card">...</div>
</section>
Tune one card, one section, one button

Changing variables with JavaScript

Since variables are plain CSS, you can set them from a script with style.setProperty(). That is how live "theme pickers" work. Here, two controls update --bs-border-radius and --bs-body-bg on the root element.

A tiny live theme editor

The script never touches a class or a rule. It writes a value, and the browser re-evaluates every place that reads it.

When variables are not enough

CSS variables are the lightest tool, and they have limits:

  • Derived shades are not recalculated. Bootstrap computes hover shades, subtle backgrounds and the tinted alert colors in Sass at build time. With variables only, you set each one by hand.
  • You cannot remove components or utilities you never use, so the file stays the same size.
  • Sass maps such as the theme colors list, the spacer scale or the grid breakpoints are not variables at all; they only exist at compile time.

When you hit these limits, move to Sass. Until then, a short override stylesheet of variables is easy to review, easy to keep through Bootstrap upgrades, and works with any hosting.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where must you declare your own :root variable overrides so that they win?

    Both rules have the same specificity, so the later declaration wins. Put your stylesheet after Bootstrap's.
  2. 2. You set --bs-primary on :root, but .btn-primary stays the old blue. Why?

    Each button variant defines its own component variables (background, border, hover, active, disabled), so you must override those on the button.
  3. 3. Which variable do .bg-primary and .text-primary read?

    They use rgba(var(--bs-primary-rgb), opacity) so that the opacity utilities can work, which is why the three-channel triple matters.
  4. 4. What is the safest way to change the corner radius of exactly one card?

    An inline custom property feeds the card's own rule without fighting specificity, and it affects only that element.
  5. 5. What is a limitation of customizing with CSS variables only?

    Hover shades, subtle tints and the Sass maps are compile-time features. Variables cannot recompute them or shrink the file.

Summary

  • Bootstrap 5.3 exposes its design as --bs-* custom properties: root variables on :root, component variables on each component class.
  • Override root variables after Bootstrap's CSS to restyle the whole page; many component variables chain to them.
  • Override component variables on a class for a component type, or inline for a single element.
  • .bg-primary and .text-primary use --bs-primary-rgb, links use --bs-link-color-rgb, and buttons use their own --bs-btn-* values.
  • Variables inherit, so setting them on a wrapper themes a whole region.
  • Use Sass when you need recomputed shades, a smaller file or changed maps.

Next lesson: Customizing with Sass.