Migrating to MDB 5

How to migrate from Bootstrap 4 to Bootstrap 5? Convert your Bootstrap project to the latest version.

Introduction

MDB 5 was written from scratch. Literally every line of code has been rewritten to ensure the highest possible quality.

The changes are very significant and in many cases it was not possible to maintain backward compatibility. We chose the right quality over backward compatibility and it was a deliberate decision.

Therefore, whenever possible, we recommend that you create your project from scratch in MDB5, instead of updating old MDB 4 projects to MDB 5.

Note: The following list is not complete. Only the most key changes are listed, but you should bear in mind that no component has remained unchanged.

Migrating from v2 to v3

After updating the MDB Standard from version 2 to 3, there were some breaking changes that must be introduced in existing projects to keep them stable. These changes relate in particular to data attributes and RTL integration.

Data attributes refactor:

All JavaScript components are now namespaced to help distinguish MDB functionality from third parties and your own code. Infix mdb has been added to all attributes.

For example, we use data-mdb-toggle instead of data-toggle.

RTL integration:

Part of our approach to adding RTL to MDB was to add it in a way that felt future-friendly to ourselves and the web at large. As such, we’ve embraced the spirit of CSS logical properties and have renamed several classes and variables. It’s a risky change because of the size and impact of the change, but we hope you’ll appreciate it overall!

RTL migration checklist:

Components:

  • Renamed .dropleft and .dropright to .dropstart and dropend.
  • Renamed .dropdown-menu-*-left and .dropdown-menu-*-right to .dropdown-menu-*-start and .dropdown-menu-*-end.
  • Renamed .bs-popover-left and .bs-popover-right to .bs-popover-start and .bs-popover-end.
  • Renamed .bs-tooltip-left and .bs-tooltip-right to .bs-tooltip-start and .bs-tooltip-end.
  • Renamed .carousel-item-left and .carousel-item-right to .carousel-item-start and .carousel-item-end.

Utilities:

  • Renamed .left-* and .right-* to .start-* and .end-*.
  • Renamed .float-left and .float-right to .float-start and .float-end.
  • Renamed .border-left and .border-right to .border-start and .border-end.
  • Renamed .rounded-left and .rounded-right to .rounded-start and .rounded-end.
  • Renamed .ml-* and .mr-* to .ms-* and .me-*.
  • Renamed .pl-* and .pr-* to .ps-* and .pe-*.
  • Renamed .text-left and .text-right to .text-start and .text-end.

Mixins:

  • Renamed border-left-radius() and border-right-radius() to border-start-radius() and border-end-radius() — as well as their corner relative variants (eg. .border-bottom-left-radius became .border-bottom-start-radius).
  • Renamed caret-left() and caret-right() to caret-start() and caret-end() — subsequently, the caret() mixin now takes start and end as arguments instead of left and right.

Variables:

  • New $breadcrumb-divider-flipped if a different breadcrumb separator is needed in RTL.
  • Renamed $navbar-brand-margin-right to $navbar-brand-margin-end.
  • Renamed $pagination-margin-left to $pagination-margin-start.
  • Renamed $form-check-padding-left to $form-check-padding-start.
  • Renamed $form-switch-padding-left to $form-switch-padding-start.
  • Renamed $form-check-inline-margin-right to $form-check-inline-margin-end.
  • Renamed $form-select-feedback-icon-padding-right to $form-select-feedback-icon-padding-end.

Other important changes:

  • Added .fs-* utilities for font-size utilities (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.
  • Renamed .font-weight-* utilities as .fw-* for brevity and consistency.
  • Renamed .font-style-* utilities as .fst-* for brevity and consistency.
  • Added .d-grid to display utilities
  • Added new gap utilities (.gap) for CSS Grid layouts

Browser support

See the browser and devices page for details on what is currently supported in Bootstrap 5. Since v4, here’s what’s changed to our browser support:

  • Dropped support for Internet Explorer 10 and 11
  • Dropped support for Microsoft Edge Legacy
  • Dropped support for Firefox NN - MM
  • Dropped support for Safari NN
  • Dropped support for iOS Safari NN
  • Dropped support for Chrome NN
  • Dropped support for Android NN

JavaScript

Changes to our source and compiled JavaScript files.

  • Dropped jQuery dependency and rewrote plugins to be in regular JavaScript.
  • Auto Initialization for all components (no need for initializing components like sidenav or select as it was in MDB 4).
  • Ability to work on the server, with module bundlers and with the browser thanks to the compilation to the UMD (Universal Module Definition) format.
  • Three ways of initializing and customizing any advanced component (via data attributes, via JavaScript, via jQuery).
  • ES6 friendly components importing as a single module or a library.
  • Optional jQuery integration.

Grid and layout

Changes to any layout tools and our grid system.

  • Dropped the .media component as it can be built with utility classes.
  • Remove position: relative from grid columns.
  • The horizontal padding is added to the direct children in a row instead of the columns themselves.
    • This simplifies our codebase.
    • The column classes can now be used stand alone. Whenever they are used outside a .row, horizontal padding won’t be added.
  • The responsive gutter classes can be used to control the gutter width in horizontal, vertical or both directions.
  • The gutter width is now set in rem and decreased from 30px to 1.5rem (24px).
  • bootstrap-grid.css now only applies box-sizing: border-box to the column instead of resetting the global box-sizing. This way the grid system can be used, even if box-sizing: border-box is not applied to each element.

Input fields

All forms were completely rewritten. The syntax has also been standardized to ensure consistency throughout the project.

  • Default and material 1.0 inputs were dropped. Only outline inputs are available now.
  • Rename .md-form to .form-outline
  • Combined native and custom checkboxes and radios into single .form-check class.
    • New checks support sizing via em/font-size or explicit modifier classes now.
    • New checks now appear larger by default for improved usability.
    • Dropped .custom-control and associated classes.
    • Renamed most $custom-control variables to $form-control ones.
  • Updated file input component
    • Refactored .form-file markup to resolve some visual bugs while allowing translation and button text changes via HTML instead of CSS.
    • Dropped native .form-control-file and .form-control-range components entirely.
    • Renamed .custom-file to .form-file (including variables).
    • Added support for :focus and :disabled styles.
  • Renamed .custom-range to .form-range (including variables).
  • Dropped .form-group for margin utilities (we’ve replaced our docs examples with .mb-3).
  • Dropped .form-row for the more flexible grid gutters.
  • Dropped .form-inline for the more flexible grid.
  • Dropped support for .form-control-plaintext inside .input-groups.
  • Dropped .input-group-append and .input-group-prepend. You can now just add buttons and .input-group-text as direct children of the input groups.

Disabled states

  • Disabled states of the buttons, close button, pagination link & form range now have pointer-events: none added. This simplifies our codebase and makes it easier to override active states in CSS.

Jumbotron

  • The jumbotron component is removed in favor of utility classes like .bg-light for the background color and .p-* classes to control padding.

Navbars

  • All navbars now require a container within. This drastically simplifies spacing requirements and removes the need for extensive CSS overrides we added for responsive containers in v4.

Pagination

  • Pagination links now have customizable margin-left that are dynamically rounded on all corners when separated from one another.

Utilities

  • Renamed .text-monospace to .font-monospace
  • Decreased the number of responsive order utilities per breakpoint. The highest order utility with a number now is .order-5 instead of .order-12.
  • New line-height utilities: .lh-1, .lh-sm, .lh-base and .lh-lg.
  • Added .bg-body for quickly setting the <body>'s background to additional elements.
  • Negative margin utilities are disabled by default. You can re-enable them by setting $enable-negative-margins: true, but keep in mind this can increase the file size quite a lot.
  • Added .fs-* utilities for font-size utilities (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.
  • Renamed .font-weight-* utilities as .fw-* for brevity and consistency.
  • Renamed .font-style-* utilities as .fst-* for brevity and consistency.
  • Added .d-grid to display utilities
  • Added new gap utilities (.gap) for CSS Grid layouts

Completely rewritten components

Below is a list of components with completely changed syntax and source code. For this reason, their migration from MDb 4 to MDB 5 is practically impossible, because they are actually completely different components. Therefore, they should be created from scratch in the project.