Key Bootstrap SCSS Mechanisms

When to Use

Use this to understand Bootstrap's internal architecture, troubleshoot customization issues, and leverage built-in systems effectively.

You need to understand Bootstrap's internal architecture
You're troubleshooting customization issues
You want to leverage Bootstrap's built-in systems effectively

Variable Override System

How Bootstrap's `!default` Flag Works

Bootstrap Variables (in _variables.scss):

$primary: #0d6efd !default;
$secondary: #6c757d !default;

Your Override (before importing Bootstrap):

$primary: #0066cc;  // Your value (no !default)

@import "bootstrap/scss/variables";
// Bootstrap sees $primary is already defined
// Skips its default due to !default flag
// Result: $primary = #0066cc

Key Concept: The !default flag means "only set this variable if it doesn't already exist."

Map Merging System

Pattern: Safe Map Extension

Bootstrap Map (in _maps.scss):

$theme-colors: (
  "primary": $primary,
  "secondary": $secondary,
  // ... other colors
) !default;

Your Extension:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";

// Merge your additions with Bootstrap defaults
$theme-colors: map-merge($theme-colors, (
  "brand": #0066cc,      // Add new color
  "custom": #ff6600,     // Add another color
));

@import "bootstrap/scss/maps";
// Bootstrap now has ALL colors (defaults + yours)

Common Map-Merge Operations:

// Add to map
$spacers: map-merge($spacers, (
  "3xs": 2px,
));

// Remove from map
$theme-colors: map-remove($theme-colors, "info", "light");

// Get value from map
$primary-color: map-get($theme-colors, "primary");

// Nested map merge (for utilities)
$utilities: map-merge($utilities, (
  "width": map-merge(
    map-get($utilities, "width"),
    ( responsive: true )
  )
));

Mixin Usage System

Common Bootstrap Mixins

Color Manipulation:

@import "bootstrap/scss/functions";

$hover-color: tint-color($primary, 20%);   // Lighten by 20%
$active-color: shade-color($primary, 20%); // Darken by 20%

Button Variant:

@import "bootstrap/scss/mixins/buttons";

.btn-custom {
  @include button-variant(
    $background: #0066cc,
    $border: #0066cc,
    $color: #fff,
    $hover-background: darken(#0066cc, 7.5%),
    $hover-border: darken(#0066cc, 10%),
    $active-background: darken(#0066cc, 10%)
  );
}

Media Query Breakpoints:

@import "bootstrap/scss/mixins/breakpoints";

.custom-component {
  font-size: 1rem;

  @include media-breakpoint-up(md) {
    font-size: 1.25rem;  // Tablet and up
  }

  @include media-breakpoint-up(lg) {
    font-size: 1.5rem;   // Desktop and up
  }
}

Border Radius:

@import "bootstrap/scss/mixins/border-radius";

.custom-box {
  @include border-radius($border-radius);

  // Or specific corners
  @include border-top-radius($border-radius-lg);
}

CSS Custom Properties Generation

How Bootstrap Generates CSS Variables

SCSS Variables:

$primary: #0066cc;
$secondary: #6c757d;

Bootstrap Root Generation (in _root.scss):

:root {
  --#{$prefix}primary: #{$primary};
  --#{$prefix}secondary: #{$secondary};
  --#{$prefix}primary-rgb: #{to-rgb($primary)};
  --#{$prefix}secondary-rgb: #{to-rgb($secondary)};
}

Result in CSS:

:root {
  --bs-primary: #0066cc;
  --bs-secondary: #6c757d;
  --bs-primary-rgb: 0, 102, 204;
  --bs-secondary-rgb: 108, 117, 125;
}

Usage in CSS:

.custom-component {
  background: var(--bs-primary);
  color: rgba(var(--bs-primary-rgb), 0.5);
}

Key Limitations: - Cannot use in media queries - CSS spec limitation - Cannot use in SCSS calculations - Use SCSS variables for math - Read-only from SCSS perspective - Generated by Bootstrap, not directly customizable

Common Mistakes

Wrong: Setting a variable without !default in a file meant to be overridden → Right: Use !default for variables you want consumers to override
Wrong: Reassigning a Bootstrap map directly → Right: Use map-merge() to preserve Bootstrap's existing entries
Wrong: Calling a breakpoint or gradient mixin without importing its file → Right: Import the specific mixins/_*.scss file first
Wrong: Trying to use a Bootstrap CSS custom property inside a @media query or SCSS calculation → Right: Use the underlying SCSS variable for those cases