--- layout: docs title: Migrating to v5 description: Track and review changes to the Bootstrap source files, documentation, and components to help you migrate from v4 to v5. group: migration aliases: "/migration/" toc: true --- ## v5.2.0 ### New `_maps.scss` Bootstrap v5.2.0 introduced a new Sass file, `_maps.scss`, that pulled out several Sass maps from `_variables.scss` to fix an issue where updates to an original map were not applied to secondary maps that extend them. For example, updates to `$theme-colors` were not being applied to other theme maps that relied on `$theme-colors`, breaking key customization workflows. In short, Sass has a limitation where once a default variable or map has been _used_, it cannot be updated. This is why variable customizations in Bootstrap have to come after `@import "functions"`, but before `@import "variables"` and the rest of our import stack. The same applies to Sass maps—you must override the defaults before the defaults get used. The following maps have been moved to the new `_maps.scss`: - `$theme-colors-rgb` - `$utilities-colors` - `$utilities-text` - `$utilities-text-colors` - `$utilities-bg` - `$utilities-bg-colors` - `$negative-spacers` - `$gutters` Your custom Bootstrap CSS builds should now look something like this with a separate maps import. ```diff // Functions come first @import "functions"; // Optional variable overrides here + $custom-color: #df711b; + $custom-theme-colors: ( + "custom": $custom-color + ); // Variables come next @import "variables"; + // Optional Sass map overrides here + $theme-colors: map-merge($theme-colors, $custom-theme-colors); + + // Followed by our default maps + @import "maps"; + // Rest of our imports @import "mixins"; @import "utilities"; @import "root"; @import "reboot"; // etc ``` ### Key changes - **Introduced new `$enable-container-classes` option.** Now when opting into the experimental CSS Grid layout, `.container-*` classes will still be compiled, unless this option is set to `false`. - **Thicker table dividers are now opt-in.** We've removed the thicker and more difficult to override border between table groups and moved it to an optional class you can apply, `.table-group-divider`. [See the table docs for an example.]({{< docsref "/content/tables#table-group-dividers" >}}) ## 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]({{< docsref "/getting-started/parcel" >}}). - Added [new Customize section]({{< docsref "/customize/overview" >}}), replacing [v4's Theming page](https://getbootstrap.com/docs/4.6/getting-started/theming/), with new details on Sass, global configuration options, color schemes, CSS variables, and more. - Reorganized all form documentation into [new Forms section]({{< docsref "/forms/overview" >}}), breaking apart the content into more focused pages. - Similarly, updated [the Layout section]({{< docsref "/layout/breakpoints" >}}), 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]({{< docsref "/customize/sass#maps-and-loops" >}}). - Breaking Renamed `color-yiq()` function and related variables to `color-contrast()` as it's no longer related to YIQ color space. [See #30168.](https://github.com/twbs/bootstrap/pull/30168/) - `$yiq-contrasted-threshold` is renamed to `$min-contrast-ratio`. - `$yiq-text-dark` and `$yiq-text-light` are respectively renamed to `$color-contrast-dark` and `$color-contrast-light`. - Breaking Media query mixins parameters have changed for a more logical approach. - `media-breakpoint-down()` uses the breakpoint itself instead of the next breakpoint (e.g., `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 (e.g., `media-between(sm, lg)` instead of `media-breakpoint-between(sm, md)` targets viewports between `sm` and `lg`). - Breaking Removed print styles and `$enable-print-styles` variable. Print display classes are still around. [See #28339](https://github.com/twbs/bootstrap/pull/28339). - Breaking Dropped `color()`, `theme-color()`, and `gray()` functions in favor of variables. [See #29083](https://github.com/twbs/bootstrap/pull/29083). - Breaking Renamed `theme-color-level()` function to `color-level()` and now accepts any color you want instead of only `$theme-color` colors. [See #29083](https://github.com/twbs/bootstrap/pull/29083) **Watch out:** `color-level()` was later on dropped in `v5.0.0-alpha3`. - Breaking Renamed `$enable-prefers-reduced-motion-media-query` and `$enable-pointer-cursor-for-buttons` to `$enable-reduced-motion` and `$enable-button-pointers` for brevity. - Breaking Removed the `bg-gradient-variant()` mixin. Use the `.bg-gradient` class to add gradients to elements instead of the generated `.bg-gradient-*` classes. - Breaking **Removed previously deprecated mixins:** - `hover`, `hover-focus`, `plain-hover-focus`, and `hover-focus-active` - `float()` - `form-control-mixin()` - `nav-divider()` - `retina-img()` - `text-hide()` (also dropped the associated utility class, `.text-hide`) - `visibility()` - `form-control-focus()` - Breaking Renamed `scale-color()` function to `shift-color()` to avoid collision with Sass's own color scaling function. - `box-shadow` mixins now allow `null` values and drop `none` from multiple arguments. [See #30394](https://github.com/twbs/bootstrap/pull/30394). - The `border-radius()` mixin now has a default value. ## Color system - The color system which worked with `color-level()` and `$theme-color-interval` was 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](https://github.com/twbs/bootstrap/pull/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-900` to `$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 `xxl` breakpoint for `1400px` and 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]({{< docsref "/layout/gutters" >}}) (`.g-*`, `.gx-*`, and `.gy-*`) to control horizontal/vertical gutters, horizontal gutters, and vertical gutters. - Breaking Renamed `.no-gutters` to `.g-0` to match new gutter utilities. - Columns no longer have `position: relative` applied, so you may have to add `.position-relative` to some elements to restore that behavior. - Breaking Dropped several `.order-*` classes that often went unused. We now only provide `.order-1` to `.order-5` out of the box. - Breaking Dropped the `.media` component as it can be easily replicated with utilities. [See #28265](https://github.com/twbs/bootstrap/pull/28265) and the [flex utilities page for an example]({{< docsref "/utilities/flex#media-object" >}}). - Breaking `bootstrap-grid.css` now only applies `box-sizing: border-box` to the column instead of resetting the global box-sizing. This way, our grid styles can be used in more places without interference. - `$enable-grid-classes` no longer disables the generation of container classes anymore. [See #29146.](https://github.com/twbs/bootstrap/pull/29146) - Updated the `make-col` mixin to default to equal columns without a specified size. ## Content, Reboot, etc - **[RFS]({{< docsref "/getting-started/rfs" >}}) is now enabled by default.** Headings using the `font-size()` mixin will automatically adjust their `font-size` to scale with the viewport. _This feature was previously opt-in with v4._ - Breaking Overhauled our display typography to replace our `$display-*` variables and with a `$display-font-sizes` Sass map. Also removed the individual `$display-*-weight` variables for a single `$display-font-weight` and adjusted `font-size`s. - Added two new `.display-*` heading sizes, `.display-5` and `.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. - Breaking Nested tables do not inherit styles anymore. - Breaking `.thead-light` and `.thead-dark` are dropped in favor of the `.table-*` variant classes which can be used for all table elements (`thead`, `tbody`, `tfoot`, `tr`, `th` and `td`). - Breaking The `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 `-y` and `-x`. - Breaking Dropped `.pre-scrollable` class. [See #29135](https://github.com/twbs/bootstrap/pull/29135) - Breaking `.text-*` utilities do not add hover and focus states to links anymore. `.link-*` helper classes can be used instead. [See #29267](https://github.com/twbs/bootstrap/pull/29267) - Breaking Dropped `.text-justify` class. [See #29793](https://github.com/twbs/bootstrap/pull/29793) - Breaking ~~`
` elements now use `height` instead of `border` to better support the `size` attribute. This also enables use of padding utilities to create thicker dividers (e.g., `
`).~~ - Reset default horizontal `padding-left` on `