Discover how to override theme colors in Bootstrap 5 using Sass

Steven     29.12.2020

Bootstrap Sass override variables by using the right import sequence

Bootstrap 5 (and before) allows overriding Sass variables by declaring them before actually importing Bootstrap. That’s the meaning of the !default declaration in _variables.scss.

// Override whatever Bootstrap variable you want right here
@import "variables";
// Then have Bootstrap do it's magic with these new values
@import "../node_modules/bootstrap/scss/bootstrap";

Like this, in the latest v4.5 version, overriding theme colors is easy. You declare them in your own variables.scss file e.g. like this:

$theme-colors: (
  primary: #25408f, // override some or all base color definitions
  secondary: #8f5325,
  success: #3e8d63,
  dark: #343a40,
  facebook: #3b5998, // you can add as many 'custom' colors as you like
  twitter: #55acee,
  linkedin: #007bb5,
  gmail: #dd5347,
  whatsapp: #12af0a

Bootstrap 5 changes the $theme-colors definition

Whereas in v4.5.3 the $theme-colors map was defined as a merge between the existing variable and the default map, in v5.0.0 the merge statement disappeared:

//Bootstrap 4.5.3
$theme-colors: () !default;
$theme-colors: map-merge(
  "primary": $primary,
  "secondary": $secondary,
  "success": $success,
  "info": $info,
  "warning": $warning,
  "danger": $danger,
  "light": $light,
  "dark": $dark

//Bootstrap 5.0.0
$theme-colors: (
  "primary": $primary,
  "secondary": $secondary,
  "success": $success,
  "info": $info,
  "warning": $warning,
  "danger": $danger,
  "light": $light,
  "dark": $dark
) !default;

With the merge command, the keys in the second map (your own definitions) take priority over the keys in the first map. That is, in case they are identical.

Without this merge command, default Bootstrap variables are left out of the resulting $theme-colors map. Thus, make sure to include also the defaults when you override $theme-colors in v5.0.0-beta2. That is, if you need those defaults of course.


Bootstrap 5 variables utilize $primary instead of $theme-color(“primary”)

We illustrate with an example below. Many more similar declarations are present in _variables.scss.

//Bootstrap v4.5.3
$link-color: theme-color("primary") !default;

//Bootstrap v5
$link-color: $primary !default;


So you override the $theme-colors map, only to find out that also the individual default variables are used directly in the toolkit.

The right way to override $theme-colors in Bootstrap 5

In order to make sure the toolkit always works with your custom colors, a somewhat overhead definition is needed:

// First override some or all individual color variables
$primary: #25408f;
$secondary: #8f5325;
$success: #3e8d63;
$info: #13101c;
$warning: #945707;
$danger: #d62518;
$light: #f8f9fa;
$dark: #343a40;

// Then add them to your custom theme-colors map, together with any additional colors you might need
$theme-colors: (
  primary: $primary,
  secondary: $secondary,
  success: $success,
  info: $info,
  warning: $warning,
  danger: $danger,
  light: $light,
  dark: $dark,
  // add any additional color below

Only this way, the Bootstrap 5 toolkit will utilize your custom colors in a consistent manner throughout the complete stylesheet.

Github discussion board topic

Below additional background information on the Bootstrap github discussion board:

23.09.2021 - 17:26

unfortunately I can’t get map-merge working. My code in style.scss:
//add colors to theme
$custom-colors: (
“bb”: coral,

$theme-colors: map-merge($theme-colors, $custom-colors);

@import “../node_modules/bootstrap/scss/bootstrap.scss”;

Nothing happens… 🙁

08.10.2021 - 17:34

Hey Peter,

the $theme-colors variable is only filled when importing the bootstrap stylesheet. I suspect therefor that your $theme-colors map will only contain your $custom-colors items.
Try declaring the $theme-colors map as advised in this article. You don’t need the map-merge command for that!
Just make sure to include all default colors ànd any custom colors you need, and declare them in one common $theme-colors variable.

Let me know how it works out!

31.08.2021 - 01:25

Hello Steven, would you put these ‘color declarations/maps before the @import “../node_modules/bootstrap/scss/bootstrap”; or between other @imports, the article is not really clear on that. Thank you.

31.08.2021 - 06:24

Hey Mike,

these definitions need to go _before_ the main bootstrap import statement. Otherwise, they don’t have their desired effect.
I collect all my bootstrap overrides in a separate file (variables.scss). Import then goes as follows:

// variable overrides, including theme-color overrides
@import “variables”;
@import “../node_modules/bootstrap/scss/bootstrap”;

21.03.2021 - 19:24

This is not what is described in the Bootstrap 5 documentation:

I actually can’t get what is described in the documentation to work. Is it inaccurate?

21.03.2021 - 19:34

Hey Jeannie,

the documentation is accurate, but neglects information regarding template order. The map-merge command will only succeed when the bootstrap $theme-color is already defined. It’s defined in _variables.scss, meaning for the ‘documented’ way to work you need something like this:

// modify any default color variables
$primary: #0074d9;
$danger: #ff4136;

// load the _variables.scss file
@import "variables";

// add any custom colors by creating your own map and merging with the (now-defined) $theme-colors map
// Create your own map
$custom-colors: (
"custom-color": #900
// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

Imo, this is cumbersome. I’d like to define all colors in a single file, not cluttered by the import statement. Hence my suggestion above to completely redefine the $theme-colors map. This is much less error-prone and does not need the import statement in between definitions.



The right way to serve responsive images (srcset and sizes attribute) with WordPress and Bootstrap 5

The most confusing thing when you inspect responsive images is the fact that the browser takes into account the DPR (Device Pixel Ratio) in order to download the most appropriate image size. Find out here how to serve your visitors responsive images.

Package.json for Bootstrap WordPress theme

Here are the basics to get started with a fully customizable Wordpress theme based on the Bootstrap framework. It uses Yarn as package manager, Esbuild and SASS for JS and SCSS compilation respectively.

Yay, we’re on the new Bootstrap v5.0.2!

Bootstrap v5 has reached beta status. That means no more new features or breaking changes in the future releases of the V5 branch. We're testing it out on this website.