Sass
Source: https://getbootstrap.com/docs/6.0/customize/sass
Utilize our source Sass files to take advantage of variables, maps, mixins, and functions to help you build faster and customize your project.
About Sass
Sass is a CSS preprocessor that adds features like variables, nesting, mixins, and functions to standard CSS. You write .scss files, compile them, and the output is plain CSS that browsers understand. If you’re new to Sass, check out the Sass documentation to learn the basics.
Bootstrap is written in Sass. Our source .scss files use Sass maps to define design tokens, mixins to generate repetitive CSS patterns, and the @use/@forward module system to organize everything. When compiled, these Sass files produce the CSS that powers every Bootstrap component and utility. This lets you override token values, remove unused components, or extend the system with your own additions. If you don’t need that level of control, you can skip Sass entirely and customize via CSS custom properties at runtime instead.
New to working with Sass and Bootstrap? Start with our npm guide for a step-by-step setup, or check out our examples repository for ready-to-use starter projects.
File structure
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 or yarn, you’ll have a file structure that looks like this:
your-project/
├── scss/
│ └── custom.scss
└── node_modules/
│ └── bootstrap/
│ ├── js/
│ └── scss/
└── index.html
If you’ve downloaded our source files and aren’t using a package manager, you’ll want to manually create something similar to that structure, keeping Bootstrap’s source files separate from your own.
your-project/
├── scss/
│ └── custom.scss
├── bootstrap/
│ ├── js/
│ └── scss/
└── index.html
Importing
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.
// Custom.scss
// Option A: Include all of Bootstrap
@use "../node_modules/bootstrap/scss/bootstrap";
// Then add additional custom code here
// Custom.scss
// Option B: Include parts of Bootstrap
// 1. Include root first (configuration, colors, tokens, and CSS layers)
@use "../node_modules/bootstrap/scss/root";
// 2. Include any other partials as needed
@use "../node_modules/bootstrap/scss/content";
@use "../node_modules/bootstrap/scss/layout";
@use "../node_modules/bootstrap/scss/forms";
@use "../node_modules/bootstrap/scss/buttons";
// 3. Components
@use "../node_modules/bootstrap/scss/alert";
@use "../node_modules/bootstrap/scss/card";
// ...
// 4. Helpers and utilities
@use "../node_modules/bootstrap/scss/helpers";
@use "../node_modules/bootstrap/scss/utilities/api";
// 5. Add additional custom code here
With that setup in place, you can begin to modify any of the Sass token maps in your custom.scss. We suggest using the full import stack from our bootstrap.scss file as your starting point.
Compiling
In order to use your custom Sass code as CSS in the browser, you need a Sass compiler. Sass ships as a CLI package, but you can also compile it with other build tools like Gulp or Webpack, or with GUI applications. Some IDEs also have Sass compilers built in or as downloadable extensions.
We like to use the CLI to compile our Sass, but you can use whichever method you prefer. From the command line, run the following:
# Install Sass globally
npm install -g sass
# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css
Learn more about your options at sass-lang.com/install and compiling with VS Code.
Using Bootstrap with another build tool? Consider reading our guides for compiling with Webpack, Parcel, or Vite. We also have production-ready demos in our examples repository on GitHub.
Including
Once your CSS is compiled, you can include it in your HTML files. Inside your index.html you’ll want to include your compiled CSS file. Be sure to update the path to your compiled CSS file if you’ve changed it.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Custom Bootstrap</title>
<link href="/css/custom.css" rel="stylesheet"><!-- [!code highlight] -->
</head>
<body>
<h1>Hello, world!</h1>
</body>
</html>
Token architecture
Bootstrap v6 uses a layered token system built on CSS custom properties. Sass maps define the tokens at compile time, and CSS custom properties are generated from those maps for runtime use.
The layers, from lowest to highest level:
-
Color scales (
_colors.scss) — Base hue variables defined inoklch()generate a full scale of color steps (025–975) as CSS custom properties usingcolor-mix(). For example,--blue-500,--red-200,--gray-900. -
Theme colors (
_theme.scss) — The$theme-colorsmap defines semantic color roles likeprimary,success, anddanger. Each theme color is a nested map with sub-keys:base,text,text-emphasis,bg,bg-subtle,bg-muted,border,focus-ring, andcontrast. -
Global tokens (
_theme.scssand_root.scss) — Semantic tokens for backgrounds ($theme-bgs), foregrounds ($theme-fgs), and borders ($theme-borders) are defined alongside the$root-tokensmap, which aggregates everything into:rootCSS custom properties. -
Component tokens (e.g.,
_alert.scss) — Each component defines its own$*-tokensmap (e.g.,$alert-tokens) that gets output as CSS custom properties scoped to the component’s class.
Token defaults
Every token map in Bootstrap includes the !default flag, allowing you to override values before Bootstrap’s files are loaded. Since Bootstrap uses Sass modules (@use/@forward), you can override !default variables using the with () syntax. For CSS custom property tokens, you have two customization paths:
- At compile time — Override the Sass maps that generate the CSS custom properties.
- At runtime — Override the CSS custom properties directly in your stylesheet, no Sass required.
Compile-time overrides
To override token values at compile time, use @use ... with () when importing Bootstrap. You only need to include the keys you want to change — Bootstrap merges your overrides with its defaults using the defaults() function, so all other tokens remain intact.
@use "../node_modules/bootstrap/scss/bootstrap" with (
$root-tokens: (
--border-radius: .25rem,
--spacer: 1.5rem,
),
$alert-tokens: (
--alert-padding-x: 2rem,
--alert-border-radius: 1rem,
)
);
Under the hood, every token map uses a two-step pattern:
$alert-tokens: () !default;
$alert-tokens: defaults(
(
// Default tokens here
),
$alert-tokens
);
The () !default declaration receives your with() overrides. Then defaults() merges your entries on top of the built-in defaults, so unspecified keys keep their original values. Any keys set to null are removed from the map entirely, letting you drop tokens you don’t need.
Runtime overrides
Because tokens are output as CSS custom properties, you can override them directly in CSS without any Sass compilation:
:root {
--border-radius: .25rem;
--primary-base: oklch(55% 0.25 260);
--bg-body: #f8f9fa;
}
You can also scope overrides to specific components:
.alert {
--alert-padding-x: 2rem;
--alert-padding-y: 1.5rem;
--alert-border-radius: 1rem;
}
Maps and loops
Bootstrap includes several Sass maps that generate families of related CSS custom properties. These maps all include the !default flag and can be overridden.
Theme color map
The $theme-colors map defines the semantic color palette. Each entry is a nested map with sub-keys like base, text, bg, border, and more. See the Theme documentation for the full map, sub-key reference, and usage examples.
To add, modify, or remove theme colors at compile time, configure $theme-colors through the main entrypoint with @use ... with (). defaults() merges your map on top of the built-ins, so the standard themes stay intact and you only add what you need:
@use "../node_modules/bootstrap/scss/bootstrap" with (
$theme-colors: (
"brand": (
"base": var(--indigo-500),
"fg": light-dark(var(--indigo-600), var(--indigo-400)),
"fg-emphasis": light-dark(var(--indigo-800), var(--indigo-300)),
"bg": var(--indigo-500),
"bg-subtle": light-dark(var(--indigo-100), var(--indigo-900)),
"bg-muted": light-dark(var(--indigo-200), var(--indigo-800)),
"border": light-dark(var(--indigo-300), var(--indigo-600)),
"focus-ring": light-dark(color-mix(in oklch, var(--indigo-500) 50%, var(--bg-body)), color-mix(in oklch, var(--indigo-500) 75%, var(--bg-body))),
"contrast": var(--white)
)
)
);
Each theme color is a nested map, so the merge is one level deep. To change one sub-key of a built-in theme, pass the whole sub-map for that theme. A partial sub-map replaces the theme’s other sub-keys rather than merging with them. To remove a theme, set its key to null.
Global token maps
Background ($theme-bgs), foreground ($theme-fgs), and border ($theme-borders) token maps define semantic layer colors. These are also covered in the Theme documentation.
Root tokens ($root-tokens)
The $root-tokens map aggregates global design tokens like fonts, spacing, borders, and form variables. Theme colors, backgrounds, foregrounds, and border tokens are merged into it before output.
All root tokens are output to :root as CSS custom properties:
Component tokens
Each component defines its own token map that gets output as CSS custom properties scoped to the component’s class. This makes components self-contained and easy to customize.
Here’s the alert component as an example:
The tokens are output on the .alert class using the tokens() mixin:
.alert {
@include tokens($alert-tokens);
padding: var(--alert-padding-y) var(--alert-padding-x);
color: var(--alert-color);
background-color: var(--alert-bg);
border: var(--alert-border);
// ...
}
Override Sass tokens
Use with () to override specific component token values at compile time with Sass. Your overrides are merged with the defaults, so you only need to specify the keys you want to change:
@use "../node_modules/bootstrap/scss/bootstrap" with (
$alert-tokens: (
--alert-padding-x: 2rem,
--alert-bg: var(--bg-2),
--alert-border-radius: 0,
)
);
This works for every component: $card-tokens, $button-tokens, $menu-tokens, $nav-tokens, and so on — any $*-tokens map supports partial overrides through the same merge pattern.
