Skip to main content Skip to docs navigation

Migrating to v6

Track and review changes to the Bootstrap source files, documentation, and components to help you migrate from v4 to v5.

GitHub Edit on GitHub
On this page

v6.0.0 Migration

Bootstrap 6 is a major release with many breaking changes to modernize our codebase, adopt newer build tools, and improve customization. Keep reading for a guide on how to migrate from v5 to v6, and a full changelog of what's new.

  1. Bump your Bootstrap dependency:

    JSON
    {
  "dependencies": {
    "bootstrap": "^6.0.0"
  }
}

  2. If using all of Bootstrap's Sass files, include it in your Sass using @use:

    SCSS
    @use "bootstrap/scss/bootstrap";

    With this, you can then easily override Bootstrap's Sass variables and maps:

    SCSS
    @use "bootstrap/scss/bootstrap" with (
 $spacer: 1rem,
 $enable-reduced-motion: true,
);

  3. If using only certain parts of Bootstrap's Sass files, you can use @use to import them individually. Be aware that our Sass file structure has changed and you may need to adjust your imports accordingly.

    SCSS
    @use "bootstrap/scss/forms";

  4. Update HTML and CSS per the changelog and updates in the documentation.

  5. Recompile your Sass to see the changes.

v6.0.0 Changelog

CSS

  • Implemented CSS layers in _root.scss and applied them to all our Sass files.
    • Layers are set in _root.scss and then utilized across separate Sass partials.
    • We cannot, unfortunately, wrap @use or @forward statements in @layer—Sass expects those to be top level at all times. Also, while CSS allows @import "file.css" layer(name), Sass also does not support that.
  • Clarified and simplified CSS-Sass setup.
  • New, streamlined color modes and theming.
    • Removed _maps.scss
    • Removed _variables-dark.scss
    • Added _colors.scss, splitting them out from _variables.scss,
    • Added _theme.scss where we setup all our global theming for how colors are applied
  • Updated lg, xl, and 2xl breakpoints and containers.
    • Increased the lg breakpoint from 992px to 1024px; it's container remains the same at 960px.
    • Increased the xl breakpoint from 1200px to 1280px, and it's container from 1140px to 1200px.
    • Renamed 2xl to 2xl for better scaling with additional custom breakpoints
    • Increased the 2xl breakpoint from 1400px to 1536px, and it's container from 1320px to 1440px.

Sass

  • Dropped support for Node Sass, including no longer testing any of our source CSS against it.
    • Rearranged several Sass files in the process.
  • Removed add() and subtract() functions. Use calc() instead.
  • CSS variable prefixing now handled by PostCSS. The $prefix Sass variable has been removed. CSS custom properties are now written without a prefix in the Sass source and prefixed automatically via postcss-prefix-custom-properties during the build. To customize the prefix, update your PostCSS configuration instead of Sass.
  • Removes all deprecated Sass variables and values:
    • Removed $nested-kbd-font-weight, no replacement.
    • Removed muted, black-50, and white-50 from text colors utilities map
    • Consolidated carousel dark variables, removing $carousel-dark-indicator-active-bg, $carousel-dark-caption-color, and $carousel-dark-control-icon-filter for their reassigned counterparts.
    • Removed $btn-close-white-filter for $btn-close-filter-dark.
    • Removed $border-radius-2xl, use $border-radius-2xl.
    • Removed $text-muted for secondary color.
    • Removed $hr-bg-color for $hr-border-color and $hr-height for $hr-border-width.
    • Removed unused $dropdown-header-padding for the -x/-y split variables.
    • Removed unused $accordion-button-focus-border-color.
    • Removed unused $tooltip-arrow-color.
    • Removed unused $popover-arrow-color and $popover-arrow-outer-color
    • Removed unused $alert-bg-scale, $alert-border-scale, and $alert-color-scale (replaced by theme tokens)
    • Removed unused $list-group-item-bg-scale and $list-group-item-color-scale (replaced by theme tokens)

Reboot

  • Relocated heading classes (like .h1) and some type classes (.mark and .small) to Reboot from _type.scss. This avoids a dependency in Sass modules and we like to avoid extending selectors in general.

Forms

  • Refactor checks, radios, and switches.
    • Split apart _form-check.scss into separate stylesheets: _checkbox.scss, _radio.scss, and _switch.scss.
    • Also split apart the documentation pages for checks, radios, and switches.
    • Added new CSS variables on each of these components. Side note: we could've shared variables here, but chose not to for simplicity's sake.
    • Removed several now unused Sass variables.
    • Checkboxes now have a wrapping element and an SVG in the DOM for checked and indeterminate states. Radios and switches do not.
    • Revamped layout for checks, radios, and switches with labels (and descriptions). We now have custom elements for layout that include basic flexbox styling.
    • Refactored toggle buttons to use a nested input structure. The .btn-check class now goes on the label (not the input), with the input nested inside. This eliminates the need for id/for attributes and uses CSS :has() selector instead of sibling selectors. Example: <label class="btn-check btn-solid theme-primary"><input type="checkbox">Toggle</label>.
  • Consolidate .form-select into .form-control.
    • Removed .form-select—use .form-control on <select> elements now. Too much abstraction and duplication at the same time.
    • Adds new CSS variables on .form-control for easier customization without Sass compilation.
    • .form-control now has a min-height at all times as opposed to just on <textarea> elements. This reduces some CSS for us.

Helpers

  • Ratio helpers have been moved to utilities.
  • Dropped clearfix helper for .d-flow-root utility.

Utilities

  • Ratio helpers are now powered by the utility API and use simplified values without calc().
  • mdo-do: Need to refactor utilities API if we want to restore the commented out custom ratios.
  • Display utilities: added flow-root option for a modern clearfix.
  • Sizing utilities:
    • Renamed .mh-*/.mw-* to .max-h-*/.max-w-*
    • Added .min-h-* and .min-w-* utilities with two default values, 0 and 100%
    • Added auto, min-content, max-content, and fit-content to width and height utilities.
  • Flex & Grid utilities:
    • Added .place-items and .justify-items utilities.

Docs

  • Removed all AddedIn badges.
  • Rearranged utilities documentation to break apart larger pages that included groups of utilities. Sizing, spacing, flex, type, and more have been broken out into smaller pages with new sub-group headings in the sidebar.