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, meaning you can override that default value in your own Sass. Copy and paste variables as needed, modify the 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. This means that your modified Sass variables should be called before you import Bootstrap Sass files. For example, to change out the `background-color` and `color` for the `<body>`, you'd do the following::

{% highlight scss %}
// Your variable overwrite first or a Sass file containing the modifications
$body-bg: #000;
$body-color: #111;

// Then import Bootstrap
@import "node_modules/bootstrap/scss/bootstrap";
{% endhighlight %}

Do the same for any variable you need to override, including the global options listed 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
Added examples to the existing docs change for more clarity 2017-09-21 16:57:36 +02:00			Every Sass variable in Bootstrap 4 includes the `!default` flag, meaning you can override that default value in your own Sass. Copy and paste variables as needed, modify the 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. This means that your modified Sass variables should be called before you import Bootstrap Sass files. For example, to change out the `background-color` and `color` for the `<body>`, you'd do the following::
Update docs to include mention of the custom variables file 2016-01-18 01:04:18 +01:00
			`{% highlight scss %}`
Added examples to the existing docs change for more clarity 2017-09-21 16:57:36 +02:00			`// Your variable overwrite first or a Sass file containing the modifications`
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
			`// Then import Bootstrap`
			`@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 %}`

			`Do the same for any variable you need to override, including the global options listed below.`

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