Sass·续

Remove tokens with null

Set any map key to null to remove it entirely. The defaults() function strips null entries before the map is used, so no CSS is generated for those keys:

@use "../node_modules/bootstrap/scss/bootstrap" with (
  $alert-tokens: (
    --alert-margin-bottom: null,
  )
);

Override CSS tokens

You can also override the CSS custom properties directly without Sass:

.alert {
  --alert-padding-x: 2rem;
  --alert-bg: var(--bg-2);
  --alert-border-radius: 0;
}

Size maps

In addition to token maps, Bootstrap uses size maps to generate size variant classes like .btn-sm, .btn-lg, .form-control-sm, etc. These use the same defaults() function and support the same override and removal patterns.

Size maps accept a simple list of size names:

$button-sizes: () !default;
$button-sizes: defaults(
  ("xs", "sm", "lg"),
  $button-sizes
);

The loop then derives CSS custom property values from each size name:

@each $size, $_ in $button-sizes {
  .btn-#{$size} {
    --btn-min-height: var(--btn-input-#{$size}-min-height);
    --btn-padding-y: var(--btn-input-#{$size}-padding-y);
    // ...
  }
}

To remove a size, set its key to null via with():

@use "../node_modules/bootstrap/scss/bootstrap" with (
  $button-sizes: ("xs": null),
);

Variant maps

Some components use variant maps to generate style variants. For example, $button-variants defines solid, outline, subtle, and text button styles. These are also processed by defaults() and support null removal:

@use "../node_modules/bootstrap/scss/bootstrap" with (
  $button-variants: (
    "text": null,
    "subtle": null,
  ),
);

This removes the .btn-text and .btn-subtle classes from the compiled CSS while keeping .btn-solid and .btn-outline intact.

Required keys

Bootstrap assumes the presence of some specific keys within Sass maps as we use 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 $theme-colors, the primary, success, and danger keys are required for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues.

Functions

Defaults

The defaults() function is the backbone of Bootstrap’s customization system. It merges user overrides on top of built-in default tokens and strips any null entries from the result. Every token map, size map, and variant map uses it:

@function defaults($defaults, $overrides) { ... }

It accepts either a map or a list as the first argument. Lists are automatically converted to maps with true values, which is how size maps like $button-sizes work with a clean ("xs", "sm", "lg") syntax.

defaults() are generated on specific selectors with the tokens() mixin.

Color contrast

In order to meet the Web Content Accessibility Guidelines (WCAG) contrast requirements, authors must provide a minimum text color contrast of 4.5:1 and a minimum non-text color contrast of 3:1, with very few exceptions.

To help with this, we included the color-contrast function in Bootstrap. It uses the WCAG contrast ratio algorithm for calculating contrast thresholds based on relative luminance in an sRGB color space to automatically return a light (#fff), dark (#212529) or black (#000) contrast color based on the specified base color. This function is especially useful for mixins or loops where you’re generating multiple classes.

For example, to generate color swatches from our $theme-colors map:

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-contrast(map.get($value, "base"));
  }
}

Escape SVG

We use the escape-svg function to escape the <, > and # characters for SVG background images. When using the escape-svg function, data URIs must be quoted.

// Input — an inline SVG with special characters
$icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='#00000080' stroke-width='2' d='m2 5 6 6 6-6'/></svg>");

// After escape-svg(), the <, >, and # characters are percent-encoded
// so the data URI works reliably in CSS (e.g. as a mask-image or background-image)
.element {
  mask-image: escape-svg($icon);
}

Map helpers

We include several Sass functions for working with maps beyond what Sass provides natively.

Function Description
map-merge-multiple($maps...) Merges any number of maps into one, processing them left to right.
map-get-multiple($map, $values) Returns a subset of a map filtered to only the keys listed in $values.
map-get-nested($map, $nested-key) Extracts a single property from every nested map entry, returning a flat map.

map-merge-multiple($maps...)

@function map-merge-multiple($maps...) { ... }

// Example: combine spacers, negative spacers, and auto into a single values map
values: map-merge-multiple($spacers, $negative-spacers, (auto: auto))

map-get-multiple($map, $values)

@function map-get-multiple($map, $values) { ... }

// Example: extract only the flex and order utilities
$utilities: map-get-multiple(
  $utilities,
  ("flex", "flex-direction", "flex-grow", "order")
);

map-get-nested($map, $nested-key)

@function map-get-nested($map, $nested-key) { ... }

// Example: pull just the "font-size" value from each entry in $font-sizes
values: map-get-nested($font-sizes, "font-size")
// Returns: ("xs": clamp(...), "sm": clamp(...), ...)

negativify-map($map)

Turns a map into its negative variant by prefixing each key with n and negating the value. Keys equal to 0 are skipped. Use it when a custom utility needs negative values.

@function negativify-map($map) { ... }

// Example: generate negative values from part of the spacer scale
$custom-spacers: (0: 0, 1: .25rem, 2: .375rem, 3: .5rem);
$negative-spacers: negativify-map($custom-spacers);
// Returns: ("n1": -.25rem, "n2": -.375rem, "n3": -.5rem)

Theme color values

The theme-color-values($key) function in scss/_theme.scss extracts a specific sub-key from every entry in the $theme-colors map, returning a flat map of color names to values. Since each theme color is a nested map with sub-keys like base, text, bg, border, etc., this function lets you pull one of those sub-keys across all colors at once. It powers most of the color-related utilities in _utilities.scss:

// In _utilities.scss — generate .focus-ring-{color} classes
"focus-ring": (
  property: --focus-ring-color,
  class: focus-ring,
  values: theme-color-values("focus-ring"),
),

// Merge theme color backgrounds with semantic border tokens for .border-{color} classes
"border-color": (
  property: (
    "--border-color": null,
    "border-color": var(--border-color)
  ),
  class: border,
  values: map.merge(theme-color-values("bg"), $theme-borders),
),

Theme opacity values

The theme-opacity-values($color-var, $opacities) function in scss/_theme.scss generates a map of opacity variants for a CSS custom property using color-mix(). The $opacities argument defaults to $util-opacity (10 through 100 in steps of 10). At 100, it returns the variable directly; for all other steps, it mixes the variable against transparent:

// In _utilities.scss — generate .border-{opacity} classes
"border-opacity": (
  class: border,
  property: border-color,
  values: theme-opacity-values(--border-color)
),

// Generate .fg-{opacity} classes
"fg-opacity": (
  class: fg,
  property: color,
  values: theme-opacity-values(--fg)
),

Mixins

Our scss/mixins/ directory has snippets of code that power Bootstrap and can also be used across your own project.

Tokens

The tokens() mixin outputs a Sass map as CSS custom properties. Every component uses it to render its token map:

.alert {
  @include tokens($alert-tokens);
  // Outputs: --alert-padding-x: ...; --alert-padding-y: ...; etc.
}

Color schemes

A shorthand mixin for the prefers-color-scheme media query is available with support for light and dark color schemes. See the color modes documentation for information on our color mode mixin.

.custom-element {
  @include color-scheme(light) {
    // Insert light mode styles here
  }

@include color-scheme(dark) {
    // Insert dark mode styles here
  }
}

Theme classes

The generate-theme-classes() mixin loops over the $theme-colors map and outputs a .theme-* class for each color. Each class maps generic --theme-* custom properties to the color’s specific values, so components can reference --theme-base, --theme-bg, etc., and pick up the right palette from a parent .theme-* class. It also emits .theme-reset, which sets those tokens to initial so nested components use their own defaults again:

@include generate-theme-classes();
// Outputs:
// .theme-primary { --theme-base: var(--primary-base); --theme-bg: var(--primary-bg); ... }
// .theme-success { --theme-base: var(--success-base); --theme-bg: var(--success-bg); ... }
// .theme-reset { --theme-base: initial; --theme-bg: initial; ... }
// ...

Mask icons

The mask-icon() mixin renders an SVG icon via a CSS mask so the shape is painted with the element’s background-color. This lets an icon inherit the current text color, enabling automatic dark mode without a separate SVG. We use this for the close button, navbar toggler, checkbox marks, breadcrumb dividers, datepicker arrows, and carousel controls.

Some form controls can’t use mask because they don’t support pseudo-elements and masking would clip the whole field. The <select> chevron and inputs using .form-control-caret are two examples, which keep separate light and dark background-image SVGs instead as non-masked background images.

Set background-color on the element yourself (the mixin only outputs the mask-* properties), then pass your icon as the mask image. Pass null for the icon when it’s applied conditionally, such as per state or direction.

.custom-icon {
  // Declare a custom CSS variable for the icon. This could be on the same
  // element, `:root`, or a parent element. We're using a custom × icon. Be
  // sure to wrap in `escape-svg()` as well.
  --custom-icon: #{escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><path fill='none' stroke='black' stroke-linecap='round' stroke-width='2' d='m4 4 8 8m0-8-8 8'/></svg>"))};

width: 1rem;
  height: 1rem;
  background-color: currentcolor;
  @include mask-icon($icon: var(--custom-icon));
}