Sass map trickery for easier customization

[mdo]

Peep the CodePen demo.

This PR creates a !default empty Sass maps for our $grays, $colors, and $theme-colors lists and map-merges a default setting for all colors into them. This way, anyone can continue to map-merge in additional or replacement key: value pairs as needed without having to replace the entire original Sass map as @martinbean pointed out in #23112.

This technique was pointed out by @hokiecoder in #22891 (comment).

---

Thoughts? If folks are interested, we'll need to update the options.md docs page to explain this, and add some code comments in our Sass files.

[martinbean]

@mdo It’s an improvement in that we don’t have to re-define unnecessary variables to override a sub-set now 😀

Curious as to why the move to holding theme colours in a map now though, rather than simple variables? As my feeling is it was a lot easier to reference $brand-primary in custom Sass style sheets than map-get($theme-colors, "primary"). I think for designers and front-end developers not familiar with things like maps in Sass, this change may make Bootstrap less accessible to them and also steepen the learning curve.

[fluke]

@martinbean They iterate over the map when generating buttons, etc. so just by adding to the array you can add new theme colors for buttons, etc. which is useful.

If it's possible to dynamically generate Sass variables you could maybe iterate through the map and make flat variables which people could use.

[liquidvisual]

I agree with @martinbean regarding ease of use. I'm a designer, and I find the map-get($theme-colors, "primary") so cumbersome to write. I use $brand-primary everywhere, and it's a no-brainer to type.

[martinbean]

I’m getting an error when trying to override the primary colour.

My app.scss file:

@import "custom";
@import "node_modules/bootstrap/scss/bootstrap";

My _custom.scss file:

$theme-colors: (
  primary: #c00
);

The error I get when trying to compile:

Error: node_modules/bootstrap/scss/_forms.scss
Error: argument $color of rgba($color, $alpha) must be a color

Backtrace:
  node_modules/bootstrap/scss/_forms.scss:280, in function rgba
  node_modules/bootstrap/scss/_forms.scss:280
    on line 280 of node_modules/bootstrap/scss/_forms.scss
>> background-color: rgba($form-feedback-invalid-color,.8);

Looking at the beta’s _variables.scss, it looks like a default map isn‘t merged with the $theme-colors map, so it’s going to be expecting me to define it—and all of its dependent variables—in my _custom.scss file 😩

@mdo How come the implementation demonstrated in the aforementioned Pen not implemented for the beta? As that’s what I followed.

[mdo]

I'm a designer, and I find the map-get($theme-colors, "primary") so cumbersome to write. I use $brand-primary everywhere, and it's a no-brainer to type.

@liquidvisual You don't have to pull from the map at all times—we have all the variables there still. We use the Sass map to reduce overhead and iterate over all our variables to generate every component's themed modifier classes

How come the implementation demonstrated in the aforementioned Pen not implemented for the beta? As that’s what I followed.

I didn't have time to get this into the beta and this isn't a breaking change. It'll make it into beta 2.

[dfinucane]

@martinbean I think you are getting that error because you don't import functions before variables

[ddevault]

Having to use map-get everywhere is awful. Strong 👎

[notio]

I believe I have read all the tickets related to this issue, and now have no idea how to make basic customizations, thus a plea for updated documentation please! The typical case is: Install Bootstrap, change some colors. Ideally I could use the CDN version of Bootstrap and link to a simple css file with my overrides after the CDN link -- is this expected to work under the Sass map trickery scheme?

[martinbean]

now have no idea how to make basic customizations

This.

Bootstrap used to be so simple to customise. Maps may be a great data structure to hold things like colours of a theme, but they’re not accessible or great for beginners or non-full-time front-end developers to customise.

It’d be great if the top-level $brand- variables were brought back and a map used “under the hood” to hold the colours belonging to the theme, but I think the current solution is just going to frustrate and turn away a lot of users.

[ddevault]

It definitely turned me away. I reverted back to v4.0.0-alpha.6 and will not be upgrading so long as this is a problem.

[soullivaneuh]

I didn't have time to get this into the beta and this isn't a breaking change. It'll make it into beta 2.

@mdo You you have any eta for the release of the beta 2?

[braginteractive]

So does anyone know how to change the theme colors so it will edit all the elements that use primary, secondary, etc?

For example, I am looking to change the $primary color, so when I use things like btn-primary it will be my custom color. The following doesn't work:

$custom: #123;

$theme-colors: (
  primary: $custom
);

Is there another step to override and use the map defaults?

[dfinucane]

I have a file I named _custom_bootstrap.scss that contains something like the following

@import './bootstrap/scss/functions';

$gray-100: #f8f9fa;
$gray-600: #868e96;
$gray-800: #343a40;
$black:  #000;
$blue:    #0082cc;
$red:     #dc3545;
$yellow:  #ffc107;
$cyan:    #17a2b8;

$theme-colors:(
    primary: $blue,
    secondary: $gray-600,
    success: $blue,
    info: $cyan,
    warning: $yellow,
    danger: $red,
    light: $gray-100,
    dark: $gray-800
);

then in my applications styles.scss I have the following

@import 'custom_bootstrap';

@import 'bootstrap/scss/bootstrap';

The thing that helped me understand how this had to work was I realized that what SASS calls variables are really constants in that once they are defined they can't be changed. So knowing that all you need to do is import your _custom_bootstrap.scss before bootstrap defines those same 'variables'.

[braginteractive]

@dfinucane worked perfectly. Thanks

I was just trying to do:

$custom: #123;
$theme-colors:(
    primary: $custom
);

And it needed the whole map:

$custom: #123;
$theme-colors:(
    primary: $custom,
   secondary: $gray-600,
   success: $green,
   info: $cyan,
   warning: $yellow,
   danger: $red,
   light: $gray-100,
   dark: $gray-800
);

[fluke]

@braginteractive This PR is meant to fix the issue you just had. The name is a bit confusing but this is the main part.

This way, anyone can continue to map-merge in additional or replacement key: value pairs as needed without having to replace the entire original Sass map as @martinbean pointed out in #23112.

[philipchristopher]

@liquidvisual You can reduce some of the complexity of the "map-get" function by using bootstrap's "theme-color" function which simply returns the theme-color. Makes it a little less cumbersome.

@import "~bootstrap/scss/functions";

h2 {
  color: theme-color("primary");
  /* color: map-get( $theme-colors, primary); */
}

[martinbean]

@mdo Thanks for making customisation easier again in beta 2! 😘

[AvverbioPronome]

I believe the base color constants ($white to $cyan) should probably be separated in a different scss file. So that they can be imported before the maps are created to easily define the logical function colors ($primary to $dark) in customizations.

In beta2 this is really confusing, because you can easily override variables like $body-bg and $body-color after @import "variables"; but you cannot effectively do the same with $primary and the like.

[sazmer]

Has this changed or is about to change? I can't really see the logic right now:

// ---- custom.scss

// =========== BOOTSTRAP FUNCTIONS & CORE ===============================
@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/mixins";
// =========== VARIABLES ===================================

//Working fine:
$theme-colors: ( "primary": purple, "danger": #ff4136 );

//Not working. Is it possible?
//$body-bg: $green;

// =========== FULL BOOTSTRAP ===============================

@import '~bootstrap/scss/bootstrap';

// =========== STYLE OVERRIDES ==============================

//Working fine:
.custom-element {
color: gray("100");
background-color: theme-color("dark");
}

Maybe I'm not understanding it correctly, but I can't get my head around how this could be done. Or, if it can't be done, how it should be done. If I cant set $bg-color: $red without redefining red, how am I supposed to use it?