Skip to content
GitLab
Switch branch/tag
Find file Normal viewHistoryPermalink
theming.md 18.3 KB
Newer Older
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
1
2
3
4
5
6
7
8
9
10
11
12 
---
layout: docs
title: Theming Bootstrap
description: Customize Bootstrap 4 with our new built-in Sass variables for global style preferences for easy theming and component changes.
group: getting-started
toc: true
---

## Introduction

In Bootstrap 3, theming was largely driven by variable overrides in LESS, custom CSS, and a separate theme stylesheet that we included in our `dist` files. With some effort, one could completely redesign the look of Bootstrap 3 without touching the core files. Bootstrap 4 provides a familiar, but slightly different approach.
Gijs Boddeus's avatar
spelling changes to theming.md (#24444)    
Gijs Boddeus committed
13 
Now, theming is accomplished by Sass variables, Sass maps, and custom CSS. There's no more dedicated theme stylesheet; instead, you can enable the built-in theme to add gradients, shadows, and more.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
14
15
16 

## Sass
Martijn Cuppens's avatar
Sass precision documentation (#27705)    
Martijn Cuppens committed
17 
Utilize our source Sass files to take advantage of variables, maps, mixins, and more. In our build we've increased the Sass rounding precision to 6 (by default it's 5) to prevent issues with browser rounding.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
18
19
20 

### File structure
Mark Otto's avatar
fixes #24728    
Mark Otto committed
21 
Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you're using a package manager like npm, you'll have a file structure that looks like this:
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
22
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
23 
{{< highlight text >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
24
25
26
27
28
29
30 
your-project/
├── scss
│   └── custom.scss
└── node_modules/
    └── bootstrap
        ├── js
        └── scss
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
31 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
32
Mark Otto's avatar
fixes #24728    
Mark Otto committed
33
34 
If you've downloaded our source files and aren't using a package manager, you'll want to manually setup something similar to that structure, keeping Bootstrap's source files separate from your own.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
35 
{{< highlight text >}}
Mark Otto's avatar
fixes #24728    
Mark Otto committed
36
37
38
39
40
41 
your-project/
├── scss
│   └── custom.scss
└── bootstrap/
    ├── js
    └── scss
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
42 
{{< /highlight >}}
Mark Otto's avatar
fixes #24728    
Mark Otto committed
43
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
44
45 
### Importing
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
46
47 
In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two options: include all of Bootstrap, or pick the parts you need. We encourage the latter, though be aware there are some requirements and dependencies across our components. You also will need to include some JavaScript for our plugins.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
48 
{{< highlight scss >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
49
50
51 
// Custom.scss
// Option A: Include all of Bootstrap
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
52 
@import "../node_modules/bootstrap/scss/bootstrap";
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
53 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
54
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
55 
{{< highlight scss >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
56
57
58
59 
// Custom.scss
// Option B: Include parts of Bootstrap

// Required
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
60
61
62 
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
63
64 

// Optional
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
65
66
67
68
69 
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/code";
@import "../node_modules/bootstrap/scss/grid";
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
70 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
71
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
72 
With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
73
74
75 

### Variable defaults
Mark Otto's avatar
port latest from options for default vars    
Mark Otto committed
76 
Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
77
Martijn Cuppens's avatar
Make component colors configurable (#28035)    
Martijn Cuppens committed
78 
You will find the complete list of Bootstrap's variables in `scss/_variables.scss`. Some variables are set to `null`, these variables don't output the property unless they are overridden in your configuration.
Pierre GIRAUD's avatar
Be more explicit where to find variables (#25624)    
Pierre GIRAUD committed
79
Mark Otto's avatar
port latest from options for default vars    
Mark Otto committed
80
81
82 
Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap's Sass files.

Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
83
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
84 
{{< highlight scss >}}
Mark Otto's avatar
port latest from options for default vars    
Mark Otto committed
85
86
87
88
89 
// Your variable overrides
$body-bg: #000;
$body-color: #111;

// Bootstrap and its default variables
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
90 
@import "../node_modules/bootstrap/scss/bootstrap";
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
91 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
92
Mark Otto's avatar
port latest from options for default vars    
Mark Otto committed
93 
Repeat as necessary for any variable in Bootstrap, including the global options below.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
94
95
96
97
98 

### Maps and loops

Bootstrap 4 includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. We use Sass maps for our colors, grid breakpoints, and more. Just like Sass variables, all Sass maps include the `!default` flag and can be overridden and extended.
Mark Otto's avatar
Update Theming docs for removing map items (#25108)    
Mark Otto committed
99
100 
Some of our Sass maps are merged into empty ones by default. This is done to allow easy expansion of a given Sass map, but comes at the cost of making _removing_ items from a map slightly more difficult.
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
101
102 
#### Modify map
Mark Otto's avatar
Update Theming docs for removing map items (#25108)    
Mark Otto committed
103 
To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
104
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
105 
{{< highlight scss >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
106 
$theme-colors: (
Mark Otto's avatar
change away from vars    
Mark Otto committed
107
108 
  "primary": #0074d9,
  "danger": #ff4136
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
109 
);
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
110 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
111
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
112
113 
#### Add to map
Mark Otto's avatar
add new thing to a map    
Mark Otto committed
114
115 
To add a new color to `$theme-colors`, add the new key and value:
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
116 
{{< highlight scss >}}
Mark Otto's avatar
add new thing to a map    
Mark Otto committed
117
118
119 
$theme-colors: (
  "custom-color": #900
);
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
120 
{{< /highlight >}}
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
121
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
122
123 
#### Remove from map
ysds's avatar
Update themeing docs for more clearly how to remove from map (#25589)    
ysds committed
124 
To remove colors from `$theme-colors`, or any other map, use `map-remove`. Be aware you must insert it between our requirements and options:
Mark Otto's avatar
Update Theming docs for removing map items (#25108)    
Mark Otto committed
125
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
126 
{{< highlight scss >}}
ysds's avatar
Update themeing docs for more clearly how to remove from map (#25589)    
ysds committed
127 
// Required
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
128
129
130 
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
ysds's avatar
Update themeing docs for more clearly how to remove from map (#25589)    
ysds committed
131
132
133
134 

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

// Optional
Martijn Cuppens's avatar
Fix node_modules path (#26653)    
Martijn Cuppens committed
135
136
137 
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
ysds's avatar
Update themeing docs for more clearly how to remove from map (#25589)    
ysds committed
138 
...
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
139 
{{< /highlight >}}
Mark Otto's avatar
Update Theming docs for removing map items (#25108)    
Mark Otto committed
140
Mark Otto's avatar
Theming docs update (#25300)    
Mark Otto committed
141
142
143
144
145
146 
#### Required keys

Bootstrap assumes the presence of some specific keys within Sass maps as we used and extend these ourselves. As you customize the included maps, you may encounter errors where a specific Sass map's key is being used.

For example, we use the `primary`, `success`, and `danger` keys from `$theme-colors` for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues. In these instances, you'll need to modify the Sass code that makes use of those values.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
147
148 
### Functions
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
149 
Bootstrap utilizes several Sass functions, but only a subset are applicable to general theming. We've included three functions for getting values from the color maps:
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
150
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
151 
{{< highlight scss >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
152
153
154
155
156
157
158
159
160
161
162 
@function color($key: "blue") {
  @return map-get($colors, $key);
}

@function theme-color($key: "primary") {
  @return map-get($theme-colors, $key);
}

@function gray($key: "100") {
  @return map-get($grays, $key);
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
163 
{{< /highlight >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
164
165
166 

These allow you to pick one color from a Sass map much like how you'd use a color variable from v3.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
167 
{{< highlight scss >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
168
169
170
171 
.custom-element {
  color: gray("100");
  background-color: theme-color("dark");
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
172 
{{< /highlight >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
173
174
175 

We also have another function for getting a particular _level_ of color from the `$theme-colors` map. Negative level values will lighten the color, while higher levels will darken.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
176 
{{< highlight scss >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
177
178
179
180
181
182
183 
@function theme-color-level($color-name: "primary", $level: 0) {
  $color: theme-color($color-name);
  $color-base: if($level > 0, #000, #fff);
  $level: abs($level);

  @return mix($color-base, $color, $level * $theme-color-interval);
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
184 
{{< /highlight >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
185
186
187 

In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
188 
{{< highlight scss >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
189
190
191 
.custom-element {
  color: theme-color-level(primary, -10);
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
192 
{{< /highlight >}}
Mark Otto's avatar
functions aww yeah    
Mark Otto committed
193
194 

Additional functions could be added in the future or your own custom Sass to create level functions for additional Sass maps, or even a generic one if you wanted to be more verbose.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
195
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
196
197 
### Color contrast
Gijs Boddeus's avatar
spelling changes to theming.md (#24444)    
Gijs Boddeus committed
198 
One additional function we include in Bootstrap is the color contrast function, `color-yiq`. It utilizes the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
199
200
201 

For example, to generate color swatches from our `$theme-colors` map:
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
202 
{{< highlight scss >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
203
204
205
206
207 
@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-yiq($value);
  }
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
208 
{{< /highlight >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
209
210
211 

It can also be used for one-off contrast needs:
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
212 
{{< highlight scss >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
213
214
215 
.custom-element {
  color: color-yiq(#000); // returns `color: #fff`
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
216 
{{< /highlight >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
217
218
219 

You can also specify a base color with our color map functions:
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
220 
{{< highlight scss >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
221
222
223 
.custom-element {
  color: color-yiq(theme-color("dark")); // returns `color: #fff`
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
224 
{{< /highlight >}}
Mark Otto's avatar
document color-yiq function    
Mark Otto committed
225
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
226
227 
## Sass options
Mark Otto's avatar
port over variable options list    
Mark Otto committed
228
229 
Customize Bootstrap 4 with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
Pierre GIRAUD's avatar
Be more explicit where to find variables (#25624)    
Pierre GIRAUD committed
230 
You can find and customize these variables for key global options in Bootstrap's `scss/_variables.scss` file.
Mark Otto's avatar
port over variable options list    
Mark Otto committed
231
Martijn Cuppens's avatar
Move hand cursor for buttons to reboot    
Martijn Cuppens committed
232
233 
| Variable                                     | Values                             | Description                                                                            |
| -------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
XhmikosR's avatar
Add a docsref shortcode.    
XhmikosR committed
234 
| `$spacer`                                    | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
Martijn Cuppens's avatar
Move hand cursor for buttons to reboot    
Martijn Cuppens committed
235
236
237
238 
| `$enable-rounded`                            | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components. |
| `$enable-shadows`                            | `true` or `false` (default)        | Enables predefined `box-shadow` styles on various components. |
| `$enable-gradients`                          | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components. |
| `$enable-transitions`                        | `true` (default) or `false`        | Enables predefined `transition`s on various components. |
XhmikosR's avatar
Add a docsref shortcode.    
XhmikosR committed
239 
| `$enable-prefers-reduced-motion-media-query` | `true` (default) or `false`        | Enables the [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
Martijn Cuppens's avatar
Move hand cursor for buttons to reboot    
Martijn Cuppens committed
240
241
242
243 
| `$enable-hover-media-query`                  | `true` or `false` (default)        | **Deprecated** |
| `$enable-grid-classes`                       | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g., `.container`, `.row`, `.col-md-1`, etc.). |
| `$enable-caret`                              | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |
| `$enable-pointer-cursor-for-buttons`         | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
XhmikosR's avatar
Add a docsref shortcode.    
XhmikosR committed
244 
| `$enable-responsive-font-sizes`              | `true` or `false` (default)        | Enables [responsive font sizes]({{< docsref "/content/typography#responsive-font-sizes" >}}). |
Martijn Cuppens's avatar
Move hand cursor for buttons to reboot    
Martijn Cuppens committed
245 
| `$enable-validation-icons`                   | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
Martijn Cuppens's avatar
Add `deprecate()` mixin (#28092)    
Martijn Cuppens committed
246 
| `$enable-deprecation-messages`               | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
247
Mark Otto's avatar
bring over colors section    
Mark Otto committed
248 
## Color
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
249
Mark Otto's avatar
bring over colors section    
Mark Otto committed
250
251
252
253 
Many of Bootstrap's various components and utilities are built through a series of colors defined in a Sass map. This map can be looped over in Sass to quickly generate a series of rulesets.

### All colors
Pierre GIRAUD's avatar
Be more explicit where to find variables (#25624)    
Pierre GIRAUD committed
254 
All colors available in Bootstrap 4, are available as Sass variables and a Sass map in `scss/_variables.scss` file. This will be expanded upon in subsequent minor releases to add additional shades, much like the [grayscale palette](#grays) we already include.
Mark Otto's avatar
bring over colors section    
Mark Otto committed
255
256 

<div class="row">
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
257
258
259 
  {{< theme-colors.inline >}}
  {{- range $.Site.Data.colors }}
    {{- if (and (not (eq .name "white")) (not (eq .name "gray")) (not (eq .name "gray-dark"))) }}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
260 
    <div class="col-md-4">
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
261 
      <div class="p-3 mb-3 swatch-{{ .name }}">{{ .name | title }}</div>
Mark Otto's avatar
bring over colors section    
Mark Otto committed
262 
    </div>
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
263
264
265 
    {{ end -}}
  {{ end -}}
  {{< /theme-colors.inline >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
266
267
268
269 
</div>

Here's how you can use these in your Sass:
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
270 
{{< highlight scss >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
271
272
273
274
275 
// With variable
.alpha { color: $purple; }

// From the Sass map with our `color()` function
.beta { color: color("purple"); }
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
276 
{{< /highlight >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
277
XhmikosR's avatar
Add a docsref shortcode.    
XhmikosR committed
278 
[Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color`.
Mark Otto's avatar
bring over colors section    
Mark Otto committed
279
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
280 
{{< callout info >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
281 
In the future, we'll aim to provide Sass maps and variables for shades of each color as we've done with the grayscale colors below.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
282 
{{< /callout >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
283
284
285 

### Theme colors
Martijn Cuppens's avatar
Typo fix (#28920)    
Martijn Cuppens committed
286 
We use a subset of all colors to create a smaller color palette for generating color schemes, also available as Sass variables and a Sass map in Bootstrap's `scss/_variables.scss` file.
Mark Otto's avatar
bring over colors section    
Mark Otto committed
287
288 

<div class="row">
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
289
290 
  {{< theme-colors.inline >}}
  {{- range (index $.Site.Data "theme-colors") }}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
291 
    <div class="col-md-4">
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
292 
      <div class="p-3 mb-3 swatch-{{ .name }}">{{ .name | title }}</div>
Mark Otto's avatar
bring over colors section    
Mark Otto committed
293 
    </div>
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
294
295 
  {{ end -}}
  {{< /theme-colors.inline >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
296
297
298
299 
</div>

### Grays
Patrick H. Lauke's avatar
Docs: add note about the grays being "cool" (#27824)    
Patrick H. Lauke committed
300 
An expansive set of gray variables and a Sass map in `scss/_variables.scss` for consistent shades of gray across your project. Note that these are "cool grays", which tend towards a subtle blue tone, rather than neutral grays.
Mark Otto's avatar
bring over colors section    
Mark Otto committed
301
302
303 

<div class="row mb-3">
  <div class="col-md-4">
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
304
305
306
307
308 
    {{< theme-colors.inline >}}
    {{- range $.Site.Data.grays }}
      <div class="p-3 swatch-{{ .name }}">{{ .name }}</div>
    {{ end -}}
  {{< /theme-colors.inline >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
309
310
311 
  </div>
</div>
Pierre GIRAUD's avatar
Be more explicit where to find variables (#25624)    
Pierre GIRAUD committed
312 
Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
Mark Otto's avatar
bring over colors section    
Mark Otto committed
313
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
314 
{{< highlight scss >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
315 
$colors: (
Jesse Mandel's avatar
Update colors in _data and theming.md to match _variables.scss (#24355)    
Jesse Mandel committed
316
317
318
319 
  "blue": $blue,
  "indigo": $indigo,
  "purple": $purple,
  "pink": $pink,
Mark Otto's avatar
quote those to match source code    
Mark Otto committed
320
321
322
323
324 
  "red": $red,
  "orange": $orange,
  "yellow": $yellow,
  "green": $green,
  "teal": $teal,
Jesse Mandel's avatar
Update colors in _data and theming.md to match _variables.scss (#24355)    
Jesse Mandel committed
325 
  "cyan": $cyan,
Mark Otto's avatar
quote those to match source code    
Mark Otto committed
326
327 
  "white": $white,
  "gray": $gray-600,
Jesse Mandel's avatar
Update colors in _data and theming.md to match _variables.scss (#24355)    
Jesse Mandel committed
328 
  "gray-dark": $gray-800
Mark Otto's avatar
bring over colors section    
Mark Otto committed
329 
) !default;
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
330 
{{< /highlight >}}
Mark Otto's avatar
bring over colors section    
Mark Otto committed
331
332
333 

Add, remove, or modify values within the map to update how they're used in many other components. Unfortunately at this time, not _every_ component utilizes this Sass map. Future updates will strive to improve upon this. Until then, plan on making use of the `${color}` variables and this Sass map.
Mark Otto's avatar
Stub out new Theming page  
Mark Otto committed
334
335 
## Components
Mark Otto's avatar
add components section, remove todos    
Mark Otto committed
336
337
338
339
340
341
342
343 
Many of Bootstrap's components and utilities are built with `@each` loops that iterate over a Sass map. This is especially helpful for generating variants of a component by our `$theme-colors` and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you'll automatically see your changes reflected in these loops.

### Modifiers

Many of Bootstrap's components are built with a base-modifier class approach. This means the bulk of the styling is contained to a base class (e.g., `.btn`) while style variations are confined to modifier classes (e.g., `.btn-danger`). These modifier classes are built from the `$theme-colors` map to make customizing the number and name of our modifier classes.

Here are two examples of how we loop over the `$theme-colors` map to generate modifiers to the `.alert` component and all our `.bg-*` background utilities.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
344 
{{< highlight scss >}}
Mark Otto's avatar
add components section, remove todos    
Mark Otto committed
345
346
347
348
349
350
351
352
353
354
355 
// Generate alert modifier classes
@each $color, $value in $theme-colors {
  .alert-#{$color} {
    @include alert-variant(theme-color-level($color, -10), theme-color-level($color, -9), theme-color-level($color, 6));
  }
}

// Generate `.bg-*` color utilities
@each $color, $value in $theme-colors {
  @include bg-variant('.bg-#{$color}', $value);
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
356 
{{< /highlight >}}
Mark Otto's avatar
add components section, remove todos    
Mark Otto committed
357
358
359
360
361 

### Responsive

These Sass loops aren't limited to color maps, either. You can also generate responsive variations of your components or utilities. Take for example our responsive text alignment utilities where we mix an `@each` loop for the `$grid-breakpoints` Sass map with a media query include.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
362 
{{< highlight scss >}}
Mark Otto's avatar
add components section, remove todos    
Mark Otto committed
363
364
365
366
367
368
369
370
371 
@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {
    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);

    .text#{$infix}-left   { text-align: left !important; }
    .text#{$infix}-right  { text-align: right !important; }
    .text#{$infix}-center { text-align: center !important; }
  }
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
372 
{{< /highlight >}}
Mark Otto's avatar
add components section, remove todos    
Mark Otto committed
373
374 

Should you need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
Mark Otto's avatar
Add some documentation on using CSS vars (#25176)    
Mark Otto committed
375
376
377 

## CSS variables
Ethan Beyer's avatar
theming.md Typo Fix (#25875)    
Ethan Beyer committed
378 
Bootstrap 4 includes around two dozen [CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) in its compiled CSS. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser's Inspector, a code sandbox, or general prototyping.
Mark Otto's avatar
Add some documentation on using CSS vars (#25176)    
Mark Otto committed
379
380
381
382
383 

### Available variables

Here are the variables we include (note that the `:root` is required). They're located in our `_root.scss` file.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
384 
{{< highlight css >}}
Mark Otto's avatar
Add some documentation on using CSS vars (#25176)    
Mark Otto committed
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409 
:root {
  --blue: #007bff;
  --indigo: #6610f2;
  --purple: #6f42c1;
  --pink: #e83e8c;
  --red: #dc3545;
  --orange: #fd7e14;
  --yellow: #ffc107;
  --green: #28a745;
  --teal: #20c997;
  --cyan: #17a2b8;
  --white: #fff;
  --gray: #6c757d;
  --gray-dark: #343a40;
  --primary: #007bff;
  --secondary: #6c757d;
  --success: #28a745;
  --info: #17a2b8;
  --warning: #ffc107;
  --danger: #dc3545;
  --light: #f8f9fa;
  --dark: #343a40;
  --font-family-sans-serif: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
  --font-family-monospace: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
410 
{{< /highlight >}}
Mark Otto's avatar
Add some documentation on using CSS vars (#25176)    
Mark Otto committed
411
412
413
414
415 

### Examples

CSS variables offer similar flexibility to Sass's variables, but without the need for compilation before being served to the browser. For example, here we're resetting our page's font and link styles with CSS variables.
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
416 
{{< highlight css >}}
Mark Otto's avatar
Add some documentation on using CSS vars (#25176)    
Mark Otto committed
417
418
419
420
421
422 
body {
  font: 1rem/1.5 var(--font-family-sans-serif);
}
a {
  color: var(--blue);
}
XhmikosR's avatar
Switch to Hugo.    
XhmikosR committed
423 
{{< /highlight >}}