Customization

Bootstrap’s own source declares its hundreds of variables with !default, exactly the pattern documented in Variables: a value is assigned only if nothing has already defined that variable. Bootstrap’s own Sass files load each other with @import, not @use — so a project overriding Bootstrap must @import it too; @use "…" with (…​) (the module-system override syntax covered in Variables) has no effect on it, since with(…​) only configures the module being @use-d, not files that module itself later @import`s. `@import instead shares one global Sass scope, so a plain variable assignment placed before Bootstrap’s own @import "bootstrap/scss/variables"; configures its !default the same way any local variable would — no special syntax needed.

The ordering is not stylistic — it is required, and it runs in two passes for exactly the reason above: plain variable overrides must come before @import "bootstrap/scss/variables" (so they pre-empt its !default`s), but a map override that reads an existing map like `$theme-colors must come after that same import (so the map exists to read from in the first place).

Most of Bootstrap’s theming surface is not individual variables but maps — $theme-colors, $spacers, $font-sizes, $grid-breakpoints — for exactly the reason covered in Lists & Maps: a map is one source of truth that a loop consumes to generate many related outputs (utility classes, button variants, background/text color pairs) rather than each output being hand-maintained separately.

Adding one key to $theme-colors is enough to generate an entire family of component variants for that color — buttons, alerts, badges, text/background utilities — because every one of those components' Sass loops over $theme-colors rather than listing primary/secondary/success literally. This is the same mechanism, applied to component styles rather than utility classes, that The Utility API documents for $utilities specifically.

Importing the single bootstrap/scss/bootstrap entry point pulls in every component’s styles, whether or not a project uses them. For a project that only needs a handful of components, importing individual partials instead produces a meaningfully smaller compiled stylesheet:

Skipping @import "bootstrap/scss/card", …​/modal, …​/carousel, and every other unused component partial means their CSS — and, for components with a JS behavior, the incentive to load their JS bundle too — never ships. This is the Sass-level half of the story; the general compile pipeline (CLI vs. bundler, source maps, --style=compressed) that this build ultimately runs through is documented in full in Compilation.

Unlike a plain Sass variable, which is erased at compile time (see the comparison table in Variables), Bootstrap 5 also defines many of its values as CSS custom properties on :root, prefixed --bs-:

This is why a color mode can be switched at runtime — no recompile — via a single data-bs-theme attribute: Bootstrap 5.3 ships a [data-bs-theme="dark"] block that redefines the same --bs-* custom properties with dark-mode values, and every component that reads var(--bs-body-bg) rather than a hard-coded color picks up the change instantly:

A component’s own compiled CSS typically reads its custom property with a Sass-computed fallback, e.g. border-radius: var(--bs-border-radius, 0.375rem): the Sass variable still decides the value baked into the stylesheet at build time, but the custom property built from it can still be overridden live afterward, without touching the Sass source at all:

This two-layer model — a Sass variable decides the compiled default, a same-named CSS custom property lets that default be overridden per-element or per-theme at runtime — is exactly the pattern described generically in Variables's "Sass variables vs. CSS custom properties" section; Bootstrap 5 is simply the largest real-world example of applying it consistently across an entire component library.

Everything left of the compiler is resolved once, at build time, exactly like the generic Sass pipeline in Compilation. Everything right of it — the data-bs-theme switch, an element-scoped --bs-card-border-radius override — happens live in the browser, with no rebuild, because it targets the CSS custom properties the compiled stylesheet already shipped.