Migrating to v6

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.

Bump your Bootstrap dependency:

JSON

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

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,
);
```
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";
```
Update HTML and CSS per the changelog and updates in the documentation.
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 colors out to their own file
- Removed _variables.scss, consolidating all variables into _config.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 xxl 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-xxl, 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.
- Renamed $zindex-dropdown to $zindex-menu.
- 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)

JavaScript

Bootstrap's JavaScript is now ESM-only. We no longer ship UMD bundles. All dist files (bootstrap.js, bootstrap.bundle.js, and their minified versions) are native ES modules. The plugin APIs themselves are unchanged—only how you load and reference them is different.
- CDN <script> tags must add type="module":
  HTML
```
<script type="module" src="bootstrap.bundle.min.js"></script>
```
- In v5, the UMD bundle automatically created a window.bootstrap global. ES modules don't do this, so there is no longer a bootstrap global object. If you called plugin APIs through the global namespace, you must update to explicit imports:
  
  Before (v5):
  JavaScript
```
const tooltip = bootstrap.Tooltip.getOrCreateInstance(el)
```
  After (v6):
  JavaScript
```
import { Tooltip } from './bootstrap.bundle.min.js'
const tooltip = Tooltip.getOrCreateInstance(el)
```
- Data attribute APIs are unchanged. If you only use data-bs-toggle, data-bs-dismiss, and other data attributes—without calling the JavaScript API directly—the only change you need is adding type="module" to your script tag. All data attribute behavior continues to work automatically.
- For modern ESM-based bundler setups (Vite, Webpack 5, Parcel 2, Rollup, etc.), no changes are needed — import { Tooltip } from 'bootstrap' works as before and now supports full tree shaking. Projects still using CommonJS require() calls will need to update to ESM import syntax.
Removed the separate bootstrap.esm.js and bootstrap.esm.min.js files — bootstrap.js is now the ESM entry point.
Removed js/index.umd.js entry point.
Removed jQuery support and the js-test-jquery test target.
Replaced the Dropdown component with Menu. All .dropdown-* classes are now .menu-* classes, and data-bs-toggle="dropdown" is now data-bs-toggle="menu". See the Menu docs for full details.
- Renamed CSS classes: .dropdown-menu to .menu, .dropdown-item to .menu-item, .dropdown-divider to .menu-divider, .dropdown-header to .menu-header, .dropdown-submenu to .submenu.
- Removed the .dropdown-toggle class — menu toggles no longer require a toggle class.
- Removed the .dropdown wrapper — no wrapper element is required. The toggle and .menu are direct siblings.
- Simplified markup from <ul><li><a class="dropdown-item"> to a flat <div class="menu"><a class="menu-item"> structure.
- Removed .dropdown-toggle-split — button group border radius for split menus is now handled automatically via :has(+ .menu).
- Renamed the JavaScript export from Dropdown to Menu — update imports to import { Menu } from 'bootstrap'.
- Renamed events: show.bs.dropdown to show.bs.menu, shown.bs.dropdown to shown.bs.menu, hide.bs.dropdown to hide.bs.menu, hidden.bs.dropdown to hidden.bs.menu.
- Renamed the data key from bs.dropdown to bs.menu (affects Menu.getInstance() and Menu.getOrCreateInstance()).
Added new Combobox component. A searchable select built on top of Menu, with single and multi-select support. See the Combobox docs.
Replaced Popper.js (@popperjs/core) with Floating UI (@floating-ui/dom) for menu, tooltip, and popover positioning.
Added Vanilla Calendar Pro (vanilla-calendar-pro) as a peer dependency for the new Datepicker component.
Removed the jspm configuration from package.json.
Added "sideEffects" metadata to package.json to enable tree shaking in bundlers while preserving the Data API event listeners that Bootstrap's plugins register at the top level.
Added "exports" map to package.json for explicit subpath access to source, dist, and Sass files.

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.
Added new Combobox form component. A searchable, filterable select with single and multi-select modes, built on top of the Menu component. See the Combobox docs.

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.