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.

  1. 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.

  1. 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, );

  1. 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";

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

  2. 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.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.
  • 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; its container remains the same at 960px.
  • Increased the xl breakpoint from 1200px to 1280px, and its 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 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 with color-mix(in oklch, ...) by default. Configure the color space with $color-mix-space. The v5 $*-rgb CSS custom properties and rgba() patterns have been removed. This requires browser support for color-mix() and oklch().
  • 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-primary to 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-reset on 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 :root only, 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:class pattern (e.g., md:d-none instead of d-md-none, hover:opacity-50 instead of opacity-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
Print .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-none and .animation-none to switch off a component’s transition or keyframe animation on a single element, plus decorative .animation-shake and .animation-pop helpers. See the Motion utilities page. The decorative animations disable themselves under prefers-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-duration and --control-transition-timing tokens 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-fade and $transition-collapse values are now CSS custom property pairs—--transition-fade-duration / --transition-fade-timing and --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-overlay easing token. Update any overrides of the old values to the new token names.
  • New .hover-lift helper. 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 --*-transition tokens. Buttons, nav links, accordions, form controls, range thumbs, and floating labels each dropped their composed --*-transition value. Each one now declares a --*-transition-property / --*-transition-duration / --*-transition-timing trio. The old token packed a whole property list and one duration into the transition shorthand, where the duration binds to the last property only—so a button’s color, background-color, and border-color never actually animated. These components now set transition-property, transition-duration, and transition-timing-function on their own, which repeats one duration and easing across every listed property. Replace overrides of --bs-btn-transition and friends with the matching -duration and -timing tokens.
  • Transitions now opt in through prefers-reduced-motion: no-preference. Our transition mixins used to emit a transition, then switch it off again inside a prefers-reduced-motion: reduce query. They now emit it only inside a no-preference query. A browser that does not support the media feature therefore gets no transition at all. Rules that force transition: none stay outside the query, so they still reach every browser.
  • Every animated component now exposes a -property token. 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-property add a property to the animation without a rewrite of the whole transition declaration. 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() and subtract() functions. Use calc() instead.
  • Removed create-css-vars() mixin (unused).
  • Renamed breakpoint-infix() to breakpoint-prefix(). The function now returns a prefix string (e.g., "md\:") instead of an infix (e.g., "-md"). The loop-breakpoints-up and loop-breakpoints-down mixins now expose $prefix instead of $infix. Update any custom Sass that calls these functions or mixins.
  • 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.
  • Removed RFS (Responsive Font Sizes). The scss/vendor/_rfs.scss file and all RFS mixins have been removed. Typography now uses fixed rem values and clamp() for responsive sizing. If you relied on RFS for automatic font scaling, you’ll need to implement your own responsive typography or use clamp() directly.
  • Renamed Sass files for consistency. _placeholders.scss is now _placeholder.scss and _spinners.scss is now _spinner.scss. Update any individual @use imports for these files.
  • Standardized focus styles with focus-ring mixin. All component-specific *-focus-box-shadow Sass 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-color CSS custom properties. Customize focus styles by overriding these tokens in _root.scss instead of individual Sass variables.
  • Renamed $grid-breakpoints to $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 to null to 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 with data-bs-theme (or the color-mode() mixin) instead of toggling a Sass flag.
  • Removed $enable-caret and the caret mixins. Menu toggles lost their automatic caret when menus moved to Floating UI, so the flag had no effect. The caret(), caret-down(), caret-up(), caret-end(), and caret-start() mixins, the scss/mixins/_caret.scss file, and the $caret-width, $caret-vertical-align, and $caret-spacing variables 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, and white-50 from text colors utilities map
  • Removed the carousel dark Sass variables ($carousel-dark-indicator-active-bg, $carousel-dark-control-icon-filter) and the .carousel-dark class—they’re not reassigned. Dark carousels now use data-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 with currentcolor, so it adapts to dark backgrounds automatically.
  • Removed all $border-radius-* variables (-xs, -sm, default, -lg, -xl, -xxl, -pill) in favor of the numeric $radii map and --radius-* tokens—see Border radius tokens under Utilities.
  • 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)
  • 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.scss to scss/mixins/_form-validation.scss. Contains only the form-validation-state-selector mixin.
  • Removed $enable-validation-icons from scss/_config.scss.
  • Replaced $form-validation-states with $validation-states (state name to theme key map).