Migration
Source: https://getbootstrap.com/docs/6.0/guides/migration
Track and review changes to the Bootstrap source files, documentation, and components to help you migrate from v5 to v6.
Upgrade
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.
Migrating with an AI coding agent? Bootstrap ships a v5-to-v6 migration skill (skills/bootstrap-v5-v6-migration) that walks coding agents through the upgrade phase by phase. Bootstrap 4 projects should start with the v4-to-v6 migration skill. Point your agent at the applicable SKILL.md file, then review its changes against this guide.
- Bump your Bootstrap dependency:
json
{
"dependencies": {
"bootstrap": "^6.0.0"
}
}
Replace @popperjs/core with @floating-ui/dom. If you use Datepicker, add vanilla-calendar-pro. The bundled JavaScript includes both peer dependencies. The standalone JavaScript requires installed packages or an import map.
- 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
@useto 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.
Check your browser support first. Bootstrap 6 raises the minimum browser versions sharply: Chrome and Edge 130, Firefox 132, and Safari 18 on both macOS and iOS. Bootstrap 5 supported Chrome and Firefox 60, and Safari 12. We build on light-dark(), :has(), container queries, content-visibility, and the native <dialog> element, and v6 ships no fallbacks, prefixes, or polyfills below the floor. Pages will not render correctly in older browsers. Check your own analytics before you upgrade, and see Browsers & devices for the full policy and the reason behind each version.
Changelog
CSS
- Clarified and simplified CSS-Sass setup. Read more about our approach for how we use Sass and CSS together to build and customize projects for your specific needs, in particular how we use CSS variables inside Sass maps as our first-class customization layer.
- Implemented CSS layers in
_root.scssand applied them to all our Sass files. - Layers are set in
_root.scssand then utilized across separate Sass partials. - We cannot, unfortunately, wrap
@useor@forwardstatements 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. - 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.scsswhere we setup all our global theming for how colors are applied - Updated lg, xl, and 2xl breakpoints and containers.
- Increased the
lgbreakpoint from 992px to 1024px; its container remains the same at 960px. - Increased the
xlbreakpoint from 1200px to 1280px, and its container from 1140px to 1200px. - Renamed
xxlto2xlfor better scaling with additional custom breakpoints - Increased the
2xlbreakpoint from 1400px to 1536px, and its container from 1320px to 1440px. - Adopted modern CSS color functions. All Sass color variables now use
oklch()notation (e.g.,$blue: oklch(60% 0.24 240)) and tint/shade scales are generated withcolor-mix(in oklch, ...)by default. Configure the color space with$color-mix-space. The v5$*-rgbCSS custom properties andrgba()patterns have been removed. This requires browser support forcolor-mix()andoklch(). - New theme token system with
.theme-*classes. Per-component color variant classes (like.alert-primary,.badge.bg-primary,.btn-primary,.table-primary) are replaced by a composable.theme-{name}pattern. Adding.theme-primaryto a component sets--theme-bg,--theme-fg,--theme-border,--theme-contrast, and other semantic CSS custom properties that the component reads. This applies across buttons, badges, alerts, tables, cards, accordions, and more. Use.theme-reseton a nested subtree to return to component defaults. - Root tokens now emit on
:root, :host. Custom properties live on both selectors so a shadow root that adopts Bootstrap’s stylesheet can read the tokens. If you override:rootonly, Web Components will not see those overrides—repeat them on:host, or use a selector that covers both. - Responsive and state classes now use a prefix instead of an infix or suffix. Class names follow the Tailwind-style
prefix:classpattern (e.g.,md:d-noneinstead ofd-md-none,hover:opacity-50instead ofopacity-50-hover). In HTML, use the unescaped colon:class="md:d-none". This applies to utilities, grid, pseudo-state variants, and all responsive components.
| Category | Before (v5) | After (v6) |
|---|---|---|
| Utilities | .d-md-none, .p-lg-3 |
.md:d-none, .lg:p-3 |
| State variants | .opacity-50-hover |
.hover:opacity-50 |
| Grid columns | .col-md-6 |
.md:col-6 |
| Row columns | .row-cols-md-3 |
.md:row-cols-3 |
| Offsets | .offset-md-2 |
.md:offset-2 |
| Gutters | .g-md-3, .gx-md-3 |
.md:g-3, .md:gx-3 |
| CSS Grid | .g-col-md-4 |
.md:g-col-4 |
| Containers | .container-sm |
.sm:container |
| Navbar | .navbar-expand-md |
.md:navbar-expand |
| Drawer | .offcanvas-md |
.md:drawer |
| Tables | .table-responsive-md |
.md:table-responsive |
| List group | .list-group-horizontal-md |
.md:list-group-horizontal |
| Sticky | .sticky-md-top |
.md:sticky-top |
| Stacks | .vstack-md |
.md:vstack |
| Dialog | .dialog-fullscreen-sm-down |
.sm-down:dialog-fullscreen |
.d-print-none |
.print:d-none |
The prefix syntax does not identify the query type. Utilities, grid columns, containers, drawers, and responsive tables use viewport queries. Stacks, CSS Grid columns, navbar expansion, horizontal list groups, card groups, and stacked tables use container queries. Add the query container that each component’s documentation requires.
- New motion utilities. Added
.transition-noneand.animation-noneto switch off a component’s transition or keyframe animation on a single element, plus decorative.animation-shakeand.animation-pophelpers. See the Motion utilities page. The decorative animations disable themselves underprefers-reduced-motion. - Checkboxes, radios, and switches now animate their marks. The checkbox tick, radio dot, and switch thumb ease in with a subtle overshoot, driven by shared
--control-transition-durationand--control-transition-timingtokens so all three move in sync. The motion is skipped for users who prefer reduced motion, and no markup changes are required. - Split the fade and collapse transition tokens. v5’s single
$transition-fadeand$transition-collapsevalues are now CSS custom property pairs—--transition-fade-duration/--transition-fade-timingand--transition-collapse-duration/--transition-collapse-timing—so duration and easing can be tuned independently. Overlay components (dialog, drawer, menu) also share a new--transition-timing-overlayeasing token. Update any overrides of the old values to the new token names. - New
.hover-lifthelper. Raises an element with a transform and deeper shadow on hover and keyboard focus, customizable via--hover-lift-*tokens and reduced-motion aware. See the Hover lift helper. - Removed the combined
--*-transitiontokens. Buttons, nav links, accordions, form controls, range thumbs, and floating labels each dropped their composed--*-transitionvalue. Each one now declares a--*-transition-property/--*-transition-duration/--*-transition-timingtrio. The old token packed a whole property list and one duration into thetransitionshorthand, where the duration binds to the last property only—so a button’scolor,background-color, andborder-colornever actually animated. These components now settransition-property,transition-duration, andtransition-timing-functionon their own, which repeats one duration and easing across every listed property. Replace overrides of--bs-btn-transitionand friends with the matching-durationand-timingtokens. - Transitions now opt in through
prefers-reduced-motion: no-preference. Our transition mixins used to emit a transition, then switch it off again inside aprefers-reduced-motion: reducequery. They now emit it only inside ano-preferencequery. A browser that does not support the media feature therefore gets no transition at all. Rules that forcetransition: nonestay outside the query, so they still reach every browser. - Every animated component now exposes a
-propertytoken. Dialog, drawer, menu, and toast join the trio the buttons and the accordion already had, so--bs-dialog-transition-property,--bs-drawer-transition-property,--bs-menu-transition-property, and--bs-toast-transition-propertyadd a property to the animation without a rewrite of the wholetransitiondeclaration. The accordion panel also gained its own--bs-accordion-panel-transition-*trio, which replaces a hard-coded.2s. See the new Transitions page for the full model.
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()andsubtract()functions. Usecalc()instead. - Removed
create-css-vars()mixin (unused). - Renamed
breakpoint-infix()tobreakpoint-prefix(). The function now returns a prefix string (e.g.,"md\:") instead of an infix (e.g.,"-md"). Theloop-breakpoints-upandloop-breakpoints-downmixins now expose$prefixinstead of$infix. Update any custom Sass that calls these functions or mixins. - CSS variable prefixing now handled by PostCSS. The
$prefixSass variable has been removed. CSS custom properties are now written without a prefix in the Sass source and prefixed automatically viapostcss-prefix-custom-propertiesduring the build. To customize the prefix, update your PostCSS configuration instead of Sass. - Removed RFS (Responsive Font Sizes). The
scss/vendor/_rfs.scssfile and all RFS mixins have been removed. Typography now uses fixedremvalues andclamp()for responsive sizing. If you relied on RFS for automatic font scaling, you’ll need to implement your own responsive typography or useclamp()directly. - Renamed Sass files for consistency.
_placeholders.scssis now_placeholder.scssand_spinners.scssis now_spinner.scss. Update any individual@useimports for these files. - Standardized focus styles with
focus-ringmixin. All component-specific*-focus-box-shadowSass variables (e.g.,$btn-focus-box-shadow,$input-focus-box-shadow,$accordion-button-focus-box-shadow) have been removed. Focus styles are now handled by a shared@mixin focus-ring()using--focus-ring,--focus-ring-width,--focus-ring-offset, and--focus-ring-colorCSS custom properties. Customize focus styles by overriding these tokens in_root.scssinstead of individual Sass variables. - Renamed
$grid-breakpointsto$breakpoints. - Theme and config maps now merge via
defaults().$theme-colors,$theme-bgs,$theme-fgs,$theme-borders,$badge-variants, and the other global maps accept a partial@use ... with ()override. v5 required a full map replacement. Set a key tonullto drop it. Nested theme-color maps merge one level deep—pass the whole sub-map to change one role. See Sass. - Removed
$enable-dark-mode. Dark mode support is always compiled; control it at runtime withdata-bs-theme(or thecolor-mode()mixin) instead of toggling a Sass flag. - Removed
$enable-caretand the caret mixins. Menu toggles lost their automatic caret when menus moved to Floating UI, so the flag had no effect. Thecaret(),caret-down(),caret-up(),caret-end(), andcaret-start()mixins, thescss/mixins/_caret.scssfile, and the$caret-width,$caret-vertical-align, and$caret-spacingvariables are gone too. Add an icon to the toggle markup if you want a caret. - Removes all deprecated Sass variables and values:
- Removed
$nested-kbd-font-weight, no replacement. - Removed
muted,black-50, andwhite-50from text colors utilities map - Removed the carousel dark Sass variables (
$carousel-dark-indicator-active-bg,$carousel-dark-control-icon-filter) and the.carousel-darkclass—they’re not reassigned. Dark carousels now usedata-bs-theme="dark"(see the carousel changes below). Carousel captions were removed entirely too. - Removed
$btn-close-white-filter. The close button no longer uses a filter—its icon is a CSS mask painted withcurrentcolor, so it adapts to dark backgrounds automatically. - Removed all
$border-radius-*variables (-xs,-sm, default,-lg,-xl,-xxl,-pill) in favor of the numeric$radiimap and--radius-*tokens—see Border radius tokens under Utilities. - Removed
$text-mutedfor secondary color. - Removed
$hr-bg-colorfor$hr-border-colorand$hr-heightfor$hr-border-width. - Renamed
$zindex-dropdownto$zindex-menu. - Removed unused
$dropdown-header-paddingfor the-x/-ysplit variables. - Removed unused
$accordion-button-focus-border-color. - Removed unused
$tooltip-arrow-color. - Removed unused
$popover-arrow-colorand$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-scaleand$list-group-item-color-scale(replaced by theme tokens) - Removed form validation Sass variables and files.
- Removed
scss/forms/_form-variables.scss. Feedback/tooltip Sass variables and validation icon SVG data URIs are gone. Validation styling now uses theme-derived CSS custom properties. - Renamed
scss/mixins/_forms.scsstoscss/mixins/_form-validation.scss. Contains only theform-validation-state-selectormixin. - Removed
$enable-validation-iconsfromscss/_config.scss. - Replaced
$form-validation-stateswith$validation-states(state name to theme key map).
