Bootstrap/docs/4.0/getting-started/options.md

---
layout: docs
title: Customization options
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
---

## Customizing variables

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.

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:

{% highlight scss %}
// Your variable overrides
$body-bg: #000;
$body-color: #111;

// Bootstrap and its default variables
@import "node_modules/bootstrap/scss/bootstrap";
{% endhighlight %}

Repeat as necessary for any variable in Bootstrap, including the global options below.

## Global options

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.

You can find and customize these variables for key global options in our `_variables.scss` file.

| Variable                    | Values                             | Description                                                                            |
| --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
| `$spacer`                   | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/). |
| `$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.                                |
| `$enable-hover-media-query` | `true` or `false` (default)        | ...                                                                                    |
| `$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-print-styles`      | `true` (default) or `false`        | Enables styles for optimizing printing.                                |

## Color

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

All colors available in Bootstrap 4, available as Sass variables and a Sass map in our `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.

<div class="row">
  {% for color in site.data.colors %}
    {% unless color.name == "white" or color.name == "gray" or color.name == "gray-dark" %}
    <div class="col-md-4">
        <div class="p-3 mb-3 swatch-{{ color.name }}">{{ color.name | capitalize }}</div>
    </div>
    {% endunless %}
  {% endfor %}
</div>

Here's how you can use these in your Sass:

{% highlight scss %}
// With variable
.alpha { color: $purple; }

// From the Sass map with our `color()` function
.beta { color: color("purple"); }
{% endhighlight %}

[Color utility classes]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/colors/) are also available for setting `color` and `background-color`.

{% callout info %}
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.
{% endcallout %}

### Theme colors

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 our `scss/_variables.scss` file.

<div class="row">
  {% for color in site.data.theme-colors %}
    <div class="col-md-4">
      <div class="p-3 mb-3 swatch-{{ color.name }}">{{ color.name | capitalize }}</div>
    </div>
  {% endfor %}
</div>

### Grays

An expansive set of gray variables and a Sass map in `scss/_variables.scss` for consistent shades of gray across your project.

<div class="row mb-3">
  <div class="col-md-4">
    {% for color in site.data.grays %}
      <div class="p-3 swatch-{{ color.name }}">{{ color.name | capitalize }}</div>
    {% endfor %}
  </div>
</div>

Within `_variables.scss`, you'll find our color variables and Sass map. Here's an example of the `$colors` Sass map:

{% highlight scss %}
$colors: (
  red: $red,
  orange: $orange,
  yellow: $yellow,
  green: $green,
  teal: $teal,
  blue: $blue,
  pink: $pink,
  purple: $purple,
  white: $white,
  gray: $gray-600,
  gray-dark: $gray-900
) !default;
{% endhighlight %}

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.
stub out that customize page 2015-04-19 03:12:18 +02:00			`---`
Massive cleanup - Simpler main nav on all pages - Back to purple masthead on homepage instead of dark graphite - Active link styles on the main nav - Cleaned up sidebar nav - New docs layout name - Homepage copy edits - Updated bright purple docs color 2015-08-15 07:45:55 +02:00			`layout: docs`
tweak options, renamed from customize 2015-08-10 19:05:38 +02:00			`title: Customization options`
redo intro 2017-06-16 05:30:02 +02:00			`description: Customize Bootstrap 4 with our new built-in Sass variables for global style preferences for easy theming and component changes.`
restore page headers, use partial and page frontmatter to organize it 2015-08-06 02:47:45 +02:00			`group: getting-started`
revamp getting started docs to use new toc 2017-05-28 07:03:48 +02:00			`toc: true`
stub out that customize page 2015-04-19 03:12:18 +02:00			`---`

Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00			`## Customizing variables`
spec out variables customize docs 2015-06-10 01:28:09 +02:00
Updates to customizing variables docs (#24186) * Variable overrides within the same Sass file can come before or after the default value, but across files they must come first. * Removed the double :: at the end of the paragraph. * Fixed usage of overwrite when we mean override. 2017-10-01 08:57:50 +02:00			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.

			`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:
Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00
			`{% highlight scss %}`
Updates to customizing variables docs (#24186) * Variable overrides within the same Sass file can come before or after the default value, but across files they must come first. * Removed the double :: at the end of the paragraph. * Fixed usage of overwrite when we mean override. 2017-10-01 08:57:50 +02:00			`// Your variable overrides`
Changed hex values to follow bootstrap coding guidelines 2017-09-21 19:44:13 +02:00			`$body-bg: #000;`
			`$body-color: #111;`
Added examples to the existing docs change for more clarity 2017-09-21 16:57:36 +02:00
Updates to customizing variables docs (#24186) * Variable overrides within the same Sass file can come before or after the default value, but across files they must come first. * Removed the double :: at the end of the paragraph. * Fixed usage of overwrite when we mean override. 2017-10-01 08:57:50 +02:00			`// Bootstrap and its default variables`
Added examples to the existing docs change for more clarity 2017-09-21 16:57:36 +02:00			`@import "node_modules/bootstrap/scss/bootstrap";`
Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00			`{% endhighlight %}`

Updates to customizing variables docs (#24186) * Variable overrides within the same Sass file can come before or after the default value, but across files they must come first. * Removed the double :: at the end of the paragraph. * Fixed usage of overwrite when we mean override. 2017-10-01 08:57:50 +02:00			`Repeat as necessary for any variable in Bootstrap, including the global options below.`
Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00
			`## Global options`

revamp getting started docs to use new toc 2017-05-28 07:03:48 +02:00			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.

Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00			You can find and customize these variables for key global options in our `_variables.scss` file.
spec out variables customize docs 2015-06-10 01:28:09 +02:00
Document $enable-grid-classes variable Closes #19532 [skip sauce] 2016-03-13 17:24:34 +01:00			`\| Variable \| Values \| Description \|`
			`\| --------------------------- \| ---------------------------------- \| -------------------------------------------------------------------------------------- \|`
Fix broken links in doc (#23324) 2017-08-11 16:40:41 +02:00			\| `$spacer` \| `1rem` (default), or any value > 0 \| Specifies the default spacer value to programmatically generate our [spacer utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/). \|
Document $enable-grid-classes variable Closes #19532 [skip sauce] 2016-03-13 17:24:34 +01:00			\| `$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. \|
			\| `$enable-hover-media-query` \| `true` or `false` (default) \| ... \|
elaborate on those classes 2016-07-27 05:21:45 +02:00			\| `$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.). \|
Document $enable-print-styles (#21474) 2016-12-31 06:31:25 +01:00			\| `$enable-print-styles` \| `true` (default) or `false` \| Enables styles for optimizing printing. \|
render the colors 2017-06-15 20:16:40 +02:00
			`## Color`

			`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`

			All colors available in Bootstrap 4, available as Sass variables and a Sass map in our `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.

			`<div class="row">`
			`{% for color in site.data.colors %}`
Don't create empty columns in documentation 2017-09-07 19:11:26 +02:00			`{% unless color.name == "white" or color.name == "gray" or color.name == "gray-dark" %}`
render the colors 2017-06-15 20:16:40 +02:00			`<div class="col-md-4">`
			`<div class="p-3 mb-3 swatch-{{ color.name }}">{{ color.name \| capitalize }}</div>`
			`</div>`
Don't create empty columns in documentation 2017-09-07 19:11:26 +02:00			`{% endunless %}`
render the colors 2017-06-15 20:16:40 +02:00			`{% endfor %}`
			`</div>`

			`Here's how you can use these in your Sass:`

			`{% highlight scss %}`
			`// With variable`
			`.alpha { color: $purple; }`

			// From the Sass map with our `color()` function
			`.beta { color: color("purple"); }`
			`{% endhighlight %}`

			[Color utility classes]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/colors/) are also available for setting `color` and `background-color`.

callout for future sass implementation [skip ci] 2017-06-30 17:55:16 +02:00			`{% callout info %}`
			`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.`
			`{% endcallout %}`

render the colors 2017-06-15 20:16:40 +02:00			`### Theme colors`

			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 our `scss/_variables.scss` file.

			`<div class="row">`
			`{% for color in site.data.theme-colors %}`
			`<div class="col-md-4">`
update rendering of colors in options.md 2017-06-26 03:12:50 +02:00			`<div class="p-3 mb-3 swatch-{{ color.name }}">{{ color.name \| capitalize }}</div>`
render the colors 2017-06-15 20:16:40 +02:00			`</div>`
			`{% endfor %}`
			`</div>`

			`### Grays`

			An expansive set of gray variables and a Sass map in `scss/_variables.scss` for consistent shades of gray across your project.

			`<div class="row mb-3">`
			`<div class="col-md-4">`
			`{% for color in site.data.grays %}`
			`<div class="p-3 swatch-{{ color.name }}">{{ color.name \| capitalize }}</div>`
			`{% endfor %}`
			`</div>`
			`</div>`

			Within `_variables.scss`, you'll find our color variables and Sass map. Here's an example of the `$colors` Sass map:

			`{% highlight scss %}`
			`$colors: (`
			`red: $red,`
			`orange: $orange,`
			`yellow: $yellow,`
			`green: $green,`
			`teal: $teal,`
			`blue: $blue,`
			`pink: $pink,`
			`purple: $purple,`
			`white: $white,`
Drop the old $gray- variables for the new color range 2017-06-30 08:15:16 +02:00			`gray: $gray-600,`
			`gray-dark: $gray-900`
render the colors 2017-06-15 20:16:40 +02:00			`) !default;`
			`{% endhighlight %}`

			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.