Source

migrating to v5

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

On this page

Dependencies

Dropped jQuery.
Upgraded from Popper v1.x to Popper v2.x.
Replaced Libsass with Dart Sass as our Sass compiler given Libsass was deprecated.
Migrated from Jekyll to Hugo for building our documentation

Browser support

Dropped Internet Explorer 10 and 11
Dropped Microsoft Edge < 16 (Legacy Edge)
Dropped Firefox < 60
Dropped Safari < 12
Dropped iOS Safari < 12
Dropped Chrome < 60

Documentation changes

Redesigned homepage, docs layout, and footer.
Added new Parcel guide .
Added new Customize section , replacing v4's Theming page , with new details on Sass, global configuration options, color schemes, CSS variables, and more.
Reorganized all form documentation into new Forms section , breaking apart the content into more focused pages.
Likewise, updated the Layout section , to flesh out grid content more clearly.
Renamed "Navs" component page to "Navs & Tabs".
Renamed "Checks" page to "Checks & radios".
Redesigned the navbar and added a new subnav to make it easier to get around our sites and docs versions.
Added new keyboard shortcut for the search field: Ctrl + /.

Sass

We've ditched the default Sass map merges to make it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like $theme-colors. Check out how to deal with Sass maps .
BreakingRenamed color-yiq()function and related variables to color-contrast()as it's no longer related to YIQ colorspace. See #30168.
- $yiq-contrasted-thresholdis renamed to $min-contrast-ratio.
- $yiq-text-darkand $yiq-text-lightare respectively renamed to $color-contrast-darkand $color-contrast-light.
BreakingMedia query mixins parameters have changed for a more logical approach.
- media-breakpoint-down()uses the breakpoint itself instead of the next breakpoint (eg, media-breakpoint-down(lg)instead of media-breakpoint-down(md)targets viewports smaller than lg).
- Similarly, the second parameter in media-breakpoint-between()also uses the breakpoint itself instead of the next breakpoint (eg, media-between(sm, lg)instead of media-breakpoint-between(sm, md)targets viewports between smand lg).
BreakingRemoved print styles and $enable-print-stylesvariables. Print display classes are still around. See #28339 .
BreakingDropped color(), theme-color(), and gray()functions in favor of variables. See #29083 .
BreakingRenamed theme-color-level()function to color-level()and now accepts any color you want instead of only $theme-colorcolors. See #29083 Watch out: color-level() was later on dropped in v5.0.0-alpha3.
BreakingRenamed $enable-prefers-reduced-motion-media-queryand $enable-pointer-cursor-for-buttonsto $enable-reduced-motionand $enable-button-pointersfor brevity.
BreakingRemoved the bg-gradient-variant()mixin. Use the .bg-gradientclass to add gradients to elements instead of the generated .bg-gradient-*classes.
Breaking Removed previously deprecated mixins:
- hover, hover-focus, plain-hover-focus, andhover-focus-active
- float()
- form-control-mixin()
- nav-divider()
- retina-img()
- text-hide()(also dropped the associated utility class, .text-hide)
- visibility()
- form-control-focus()
BreakingRenamed scale-color()function to shift-color()avoid collision with Sass's own color scaling function.
box-shadowmixins now allow nullvalues and drop nonefrom multiple arguments. See #30394 .
The border-radius()mixin now has a default value.

color system

The color system which worked with color-level()and $theme-color-intervalwas removed in favor of a new color system. All lighten()and darken()functions in our codebase are replaced by tint-color()and shade-color(). These functions will mix the color with either white or black instead of changing its lightness by a fixed amount. The shift-color()will either tint or shade a color depending on whether its weight parameter is positive or negative. See #30622 for more details.
Added new tints and shades for every color, providing nine separate colors for each base color, as new Sass variables.
Improved color contrast. Bumped color contrast ratio from 3:1 to 4.5:1 and updated blue, green, cyan, and pink colors to ensure WCAG 2.1 AA contrast. Also changed our color contrast color from $gray-900to $black.
To support our color system, we've added new custom tint-color()and shade-color()functions to mix our colors appropriately.

Grid updates

New breakpoint! Added new xxlbreakpoint for 1400pxand up. No changes to all other breakpoints.
Improved gutters. Gutters are now set in rems, and are narrower than v4 ( 1.5rem, or about 24px, down from 30px). This aligns our grid system's gutters with our spacing utilities.
- Added new gutter class ( .g-*, .gx-*, and .gy-*) to control horizontal/vertical gutters, horizontal gutters, and vertical gutters.
- BreakingRenamed .no-guttersto .g-0match new gutter utilities.
Columns no longer have position: relativeapplied, so you may have to add .position-relativeto some elements to restore that behavior.
BreakingDropped several .order-*classes that often went unused. We now only provide .order-1to .order-5out of the box.
BreakingDropped the .mediacomponent as it can be easily replicated with utilities. See #28265 and the flex utilities page for an example .
Breaking bootstrap-grid.cssnow only applies box-sizing: border-boxto the column instead of resetting the global box-sizing. This way, our grid styles can be used in more places without interference.
$enable-grid-classesno longer disables the generation of container classes anymore. See #29146.
Updated the make-colmixin to default to equal columns without a specified size.

Content, Reboot, etc

RFS is now enabled by default. Headings using thefont-size()mixin will automatically adjust theirfont-sizeto scale with the viewport. This feature was previously opt-in with v4.
BreakingOverhauled our display typography to replace our $display-*variables and with a $display-font-sizesSass map. Also removed the individual $display-*-weightvariables for a single $display-font-weightand adjusted font-sizes.
Added two new .display-*heading sizes, .display-5and .display-6.
Links are underlined by default (not just on hover), unless they're part of specific components.
Redesigned tables to refresh their styles and rebuild them with CSS variables for more control over styling.
BreakingNested tables do not inherit styles anymore.
Breaking .thead-lightand .thead-darkare dropped in favor of the .table-*variant classes which can be used for all table elements ( thead, tbody, tfoot, tr, thand td).
BreakingThe table-row-variant()mixin is renamed to table-variant()and accepts only 2 parameters: $color(color name) and $value(color code). The border color and accent colors are automatically calculated based on the table factor variables.
Split table cell padding variables into -yand -x.
BreakingDropped .pre-scrollableclass. See #29135
Breaking .text-*utilities do not add hover and focus states to links anymore. .link-*helper classes can be used instead. See #29267
BreakingDropped .text-justifyclass. See #29793
Breaking <hr>elements now use heightinstead of borderto better support the sizeattribute. This also enables use of padding utilities to create thicker dividers (eg, <hr class="py-1">).
Reset default horizontal padding-lefton <ul>and <ol>elements from browser default 40pxto 2rem.
Added $enable-smooth-scroll, which applies scroll-behavior: smoothglobally—except for users asking for reduced motion through prefers-reduced-motionmedia query. See #31877

RTL

Horizontal direction specific variables, utilities, and mixins have all been renamed to use logical properties like those found in flexbox layouts—eg, startand endin lieu of leftand right.

Forms

Added new floating forms! We've promoted the Floating labels example to fully supported form components. See the new Floating labels page.
Breaking Consolidated native and custom form elements. Checkboxes, radios, selects, and other inputs that had native and custom classes in v4 have been consolidated. Now nearly all our form elements are entirely custom, most without the need for custom HTML.
- .custom-checkis now .form-check.
- .custom-check.custom-switchis now .form-check.form-switch.
- .custom-selectis now .form-select.
- .custom-fileand .form-filehave been replaced by custom styles on top of .form-control.
- .custom-rangeis now .form-range.
- Dropped native .form-control-fileand .form-control-range.
BreakingDropped .input-group-appendand .input-group-prepend. You can now just add buttons and .input-group-textas direct children of the input groups.
The longstanding Missing border radius on input group with validation feedback bug is finally fixed by adding an additional .has-validationclass to input groups with validation.
Breaking Dropped form-specific layout classes for our grid system. Use our grid and utilities instead of .form-group, .form-row, or .form-inline.
BreakingForm labels now require .form-label.
Breaking .form-textno longer sets display, allowing you to create inline or block help text as you wish just by changing the HTML element.
Validation icons are no longer applied to <select>s with multiple.
Rearranged source Sass files under scss/forms/, including input group styles.

Components

Unified paddingvalues for alerts, breadcrumbs, cards, dropdowns, list groups, modals, popovers, and tooltips to be based on our $spacervariable. See #30564 .

Accordion

Added new accordion component .

Alerts

Alerts now have examples with icons .
Removed custom styles for <hr>s in each alert since they already use currentColor.

Badges

BreakingDropped all .badge-*color classes for background utilities (eg, use .bg-primaryinstead of .badge-primary).
BreakingDropped .badge-pill--use the .rounded-pillutility instead.
BreakingRemoved hover and focus styles for <a>and <button>elements.
Increased default padding for badges from .25em/ .5emto .35em/ .65em.

Breadcrumbs

Simplified the default appearance of breadcrumbs by removing padding, background-color, and border-radius.
Added new CSS custom property --bs-breadcrumb-dividerfor easy customization without needing to recompile CSS.

Buttons

Breaking Toggle buttons , with checkboxes or radios, no longer require JavaScript and have new markup. We no longer require a wrapping element, add.btn-checkto the<input>, and pair it with any.btnclasses on the<label>. See #30650 . The docs for this has moved from our Buttons page to the new Forms section.
Breaking Dropped .btn-blockfor utilities. Instead of using .btn-blockon the .btn, wrap your buttons with .d-gridand a .gap-*utility to space them as needed. Switch to responsive classes for even more control over them. Read the docs for some examples.
Updated our button-variant()and button-outline-variant()mixins to support additional parameters.
Updated buttons to ensure increased contrast on hover and active states.
Disabled buttons now have pointer-events: none;.

card

BreakingDropped .card-deckin favor of our grid. Wrap your cards in column classes and add a parent .row-cols-*container to recreate card decks (but with more control over responsive alignment).
BreakingDropped .card-columnsin favor of Masonry. See #28922 .
BreakingReplaced the .cardbased accordion with a new Accordion component .

Carousel

Added new .carousel-darkvariant for dark text, controls, and indicators (great for lighter backgrounds).
Replaced chevron icons for carousel controls with new SVGs from Bootstrap Icons .

close button

BreakingRenamed .closeto .btn-closefor a less generic name.
Close buttons now use a background-image(embedded SVG) instead of a ×in the HTML, allowing for easier customization without the need to touch your markup.
Added new .btn-close-whitevariant that uses filter: invert(1)to enable higher contrast dismiss icons against darker backgrounds.

collapse

Removed scroll anchoring for accordions.

Dropdowns

Added new .dropdown-menu-darkvariant and associated variables for on-demand dark dropdowns.
Added new variable for $dropdown-padding-x.
Darkened the dropdown divider for improved contrast.
BreakingAll the events for the dropdown are now triggered on the dropdown toggle button and then bubbled up to the parent element.
Dropdown menus now have a data-bs-popper="static"attribute set when the positioning of the dropdown is static and data-bs-popper="none"when dropdown is in the navbar. This is added by our JavaScript and helps us use custom position styles without interfering with Popper's positioning.
BreakingDropped flipoption for dropdown plugin in favor of native Popper configuration. You can now disable the flipping behavior by passing an empty array for fallbackPlacementsoption in flip modifier.
Dropdown menus can now be clickable with a new autoCloseoption to handle the auto close behavior . You can use this option to accept the click inside or outside the dropdown menu to make it interactive.
Dropdowns now support .dropdown-items wrapped in <li>s.

Jumbotron

BreakingDropped the jumbotron component as it can be replicated with utilities. See our new Jumbotron example for a demo.

List group

Added new .list-group-numberedmodifier to list groups.

Navs and tabs

Added new nullvariables for font-size, font-weight, color, and :hover colorto the .nav-linkclass.

Navbars

BreakingNavbars now require a container within (to drastically simplify spacing requirements and CSS required).

Offcanvas

Added the new offcanvas component .

Pagination

Pagination links now have customizable margin-leftthat are dynamically rounded on all corners when separated from one another.
Added transitions to pagination links.

Popovers

BreakingRenamed .arrowto .popover-arrowin our default popover template.
Renamed whiteListoption to allowList.

Spinners

Spinners now honor prefers-reduced-motion: reduceby slowing down animations. See #31882 .
Improved spinner vertical alignment.

toasts

Toasts can now be positioned in a .toast-containerwith the help of positioning utilities .
Changed default toast duration to 5 seconds.
Removed overflow: hiddenfrom toasts and replaced with proper border-radiuss with calc()functions.

Tooltips

BreakingRenamed .arrowto .tooltip-arrowin our default tooltip template.
BreakingThe default value for the fallbackPlacementsis changed to ['top', 'right', 'bottom', 'left']for better placement of popper elements.
BreakingRenamed whiteListoption to allowList.

Utilities

BreakingRenamed several utilities to use logical property names instead of directional names with the addition of RTL support:
- Renamed .left-*and .right-*to .start-*and .end-*.
- Renamed .float-leftand .float-rightto .float-startand .float-end.
- Renamed .border-leftand .border-rightto .border-startand .border-end.
- Renamed .rounded-leftand .rounded-rightto .rounded-startand .rounded-end.
- Renamed .ml-*and .mr-*to .ms-*and .me-*.
- Renamed .pl-*and .pr-*to .ps-*and .pe-*.
- Renamed .text-leftand .text-rightto .text-startand .text-end.
BreakingDisabled negative margins by default.
Added new .bg-bodyclass for quickly setting the <body>'s background to additional elements.
Added new position utilities for top, right, bottom, and left. Values include 0, 50%, and 100%for each property.
Added new .translate-middle-x& .translate-middle-yutilities to horizontally or vertically center absolute/fixed positioned elements.
Added new border-widthutilities .
BreakingRenamed .text-monospaceto .font-monospace.
BreakingRemoved .text-hideas it's an antiquated method for hiding text that shouldn't be used anymore.
Added .fs-*utilities for font-sizeutilities (with RFS enabled). These use the same scale as HTML's default headings (1-6, large to small), and can be modified via Sass map.
BreakingRenamed .font-weight-*utilities as .fw-*for brevity and consistency.
BreakingRenamed .font-style-*utilities as .fst-*for brevity and consistency.
Added .d-gridto display utilities and new gaputilities ( .gap) for CSS Grid and flexbox layouts.
BreakingRemoved .rounded-smand rounded-lg, and introduced a new scale of classes, .rounded-0to .rounded-3. See #31687 .
Added new line-heightutilities: .lh-1, .lh-sm, .lh-baseand .lh-lg. See here .
Moved the .d-noneutility in our CSS to give it more weight over other display utilities.
Extended the .visually-hidden-focusablehelper to also work on containers, using :focus-within.

Helpers

Breaking Responsive embed helpers have been renamed to ratio helpers with new class names and improved behaviors, as well as a helpful CSS variable.
- Classes have been renamed to change byto xin the aspect ratio. For example, .ratio-16by9is now .ratio-16x9.
- We've dropped the .embed-responsive-itemand element group selector in favor of a simpler .ratio > *selector. No more class is needed, and the ratio helper now works with any HTML element.
- The $embed-responsive-aspect-ratiosSass map has been renamed to $aspect-ratiosand its values have been simplified to include the class name and the percentage as the key: valuepair.
- CSS variables are now generated and included for each value in the Sass map. Modify the --bs-aspect-ratiovariable on the .ratioto create any custom aspect ratio .
Breaking “Screen reader” classes are now “visually hidden” classes .
- Changed the Sass file from scss/helpers/_screenreaders.scsstoscss/helpers/_visually-hidden.scss
- Renamed to .sr-onlyand _.sr-only-focusable.visually-hidden.visually-hidden-focusable
- Renamed sr-only()and sr-only-focusable()mixins to visually-hidden()and visually-hidden-focusable().
bootstrap-utilities.cssnow also includes our helpers. Helpers don't need to be imported in custom builds anymore.

JavaScript

Dropped jQuery dependency and rewrote plugins to be in regular JavaScript.
BreakingData attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use data-bs-toggleinstead of data-toggle.
All plugins can now accept a CSS selector as the first argument. You can either pass a DOM element or any valid CSS selector to create a new instance of the plugin:
```
var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
```
popperConfigcan be passed as a function that accepts the Bootstrap's default Popper config as an argument, so that you can merge this default configuration in your way. Applies to dropdowns, popovers, and tooltips.
The default value for the fallbackPlacementsis changed to ['top', 'right', 'bottom', 'left']for better placement of Popper elements. Applies to dropdowns, popovers, and tooltips.
Removed underscore from public static methods like _getInstance()→ getInstance().