angle-uparrow-clockwisearrow-counterclockwisearrow-down-uparrow-leftatcalendarcard-listchatcheckenvelopefolderhouseinfo-circlepencilpeoplepersonperson-fillperson-plusphoneplusquestion-circlesearchtagtrashx

Migrating from Bootstrap 4 to Bootstrap 5

In December 2020, Bootstrap 5 Beta 1 was released. After reading all the changes and additions, one can only conclude that this is another big step forward.

17 January 2021 Updated 17 January 2021
post main image
https://unsplash.com/@davidboca

Nowadays, websites use a lot of CSS and Javascript. When you build websites, you can't test them all the time with the major browsers. Instead, you need a framework that supports all the major browsers. This framework needs to be well supported and that means only a few remain.

For this site, I chose Bootstrap 4. This is not a coincidence. A few years ago I was looking for the best framework for a large number of websites for a client. After an extensive selection, Bootstrap came out as number one.

I really like Bootstrap. I am not an expert, but a backend developer who uses it for the frontend. This means that I look at Bootstrap mostly from a technical perspective. I'm also not a graphic designer, but I know graphic designers who also like it.

Why upgrade to Bootstrap 5?

In December 2020, Bootstrap 5 Beta 1 was released. After reading all the changes and additions, one can only conclude that this is another big step forward. Bootstrap 5 Beta replaced Bootstrap 4 on the Bootstrap website homepage, which means that they at least consider it suitable for new designs.

Why did I want to upgrade Bootstrap 4 to Bootstrap 5? Last weekend I upgraded my development PC and laptop from Ubuntu 18.04 to Ubuntu 20.04. So I thought, while I'm still in upgrade mode, why not upgrade Bootstrap too, I probably want to do this sometime this year anyway.

RTL, right-to-left languages

Many won't need this, but it's a great thing if you want to support right-to-left languages. There are about 300 million native speakers of these languages. To activate this, all you need to do is add dir="rtl" to the <html> element. You can try this yourself. 

To enable RTL add '?rtl=on' to the url

To disable RTL add '?rtl=off' to the url

Do you need to upgrade?

Like many people, I use Bootstrap as is, so as from a CDN, only I host it on my own web server. If you use a lot of customization, SCSS, it can become difficult. In this post I share my notes on upgrading this website.

Some questions and answers:

  • Was the migration successful?
    Yes. This website is now running with Bootstrap 5.
  • Was the upgrade difficult?
    No.
  • How much time did it take?
    Five days. Most of the time was spent converting the form fields. I also had to modify the form generation functions.
  • Were there any problems?
    Yes, there were some problems. At least one is still unresolved at this time. In Bootstrap 4, the toggler (hamburger icon) changes to an 'X' and vice versa. I have no idea how to do this in Bootstrap 5.
  • Should you upgrade?
    It's up to you. I suggest you first look at the difficult parts like the dropdown menu. Read the rest of this post and look at the problems on Github.
  • What took the most time?
    Rearranging the form fields.

Bootstrap 5 ditched jQuery, but I can't live without it....

Bootstrap 5 no longer uses jQuery. I can imagine this. They only needed some of it and can now fix problems, incompatibilities, themselves. One less dependency.

I use jQuery everywhere and I'm certainly not going to replace all my code for regular Javascript. The main reason is that I don't have time to solve browser problems, security problems. Does this mean you have to load more Javascript? Not really. Bootstrap also took the necessary code from popper.js and bundled it with their own code.

Tool to convert Bootstrap classes

I couldn't find a tool to convert Bootstrap classes, so I used Rexxer, a general search and replace tool for Linux. This worked fine, but was sometimes very slow because of all the files it had to search. But I'm not complaining. I could also have written a tool in Python, but that would take another four hours. You may want to wait until more upgrade tools become available.

Step 1: Check the Bootstrap migration documents

On the Bootstrap website, there is a page called 'Migrating to v5'. While not everything is listed here, I often found myself returning to this page to see changes to certain classes, for example. The Bootstrap website also now (finally) has a fantastic search box with autocompletion. 

Step 2: Modify the base template

Moving your base template to Bootstrap 5 is nothing special. The most interesting part is removing popper.js. The code is now in bootstrap.bundle.min.js. After performing this step, you might be thinking: what happened to my beautiful website? Don't despair!

Bootstrap 4 base template:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link href="/static/vendor/bootstrap/4.5.0-dist/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous" rel="stylesheet">
</head>
<body>
	
<header>
</header>

<main>
</main>

<footer>
</footer>

<script src="/static/vendor/jquery/3.5.1/jquery-3.5.1.min.js"></script>
<script src="/static/vendor/popper/1.16.0/umd/popper.min.js"></script>
<script src="/static/vendor/bootstrap/4.5.0-dist/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>

</body>
</html>

Bootstrap 5 base template:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link href="/static/vendor/bootstrap/5.0.0-beta1-dist/css/bootstrap.min.css" integrity="sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1" crossorigin="anonymous" rel="stylesheet">

<body>

<header>
</header>

<main>
</main>

<footer>
</footer>

<script src="/static/vendor/jquery/3.5.1/jquery-3.5.1.min.js"></script>
<script src="/static/vendor/bootstrap/5.0.0-beta1-dist/js/bootstrap.bundle.min.js" integrity="sha384-ygbV9kiqUc6oa4msXn9868pTtWMgiQaeYH7/t7LECLbyPA2x65Kgf80OJFdroafW" crossorigin="anonymous"></script>

</body>
</html>

Step 2: Rename Bootstrap classes

Next thing to do is to rename the Bootstrap classes. After changing the base template you will see a site with many problems. If you checked the 'Migrating to v5' page on the Bootstrap website, you will notice that a lot of Bootstrap classes have been renamed. There is not a nice single list on this page so I scraped the changes that were important for me:

Components
---
Rename .dropleft and .dropright to .dropstart and dropend.
Rename .dropdown-menu-*-left and .dropdown-menu-*-right to .dropdown-menu-*-start and .dropdown-menu-*-end.
Rename .bs-popover-left and .bs-popover-right to .bs-popover-start and .bs-popover-end.
Rename .bs-tooltip-left and .bs-tooltip-right to .bs-tooltip-start and .bs-tooltip-end.
Rename .carousel-item-left and .carousel-item-right to .carousel-item-start and .carousel-item-end.
Rename .close to .btn-close for a less generic name.

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

Text utilities
---
Rename .font-weight-* utilities as .fw-* for brevity and consistency.
Rename .font-style-* utilities as .fst-* for brevity and consistency.

Data utilities
---
Rename data-toggle to data-bs-toggle
Rename data-target to data-bs-target
Rename data-parent to data-bs-parent
Rename data-dismiss to data-bs-dismiss
Rename data-offset to data-bs-offset
Rename data-interval to data-bs-interval
Rename data-ride to data-bs-ride

Helpers
---
Rename .sr-only and .sr-only-focusable to .visually-hidden and .visually-hidden-focusable

Step 3: Fix broken

Next step is to fix all things that are broken. I maintain two additional CSS files:

  • default.css
    Can be changed for another theme.
  • custom.css
    Contains the CSS that always must be present.

Below are my notes. Not everything I did is listed here. I left out some form field conversions.

All links are now underlined by default. Horrible!

Fix: Add to default.css:

a, ... {
	color: #000000;
	text-decoration: none;
}

Headings too bold

Do not know if this really was a change.
Fix: Add to default.css:

h1, h2, h3, h4, h5, h6 {
	font-weight: 400!important;
}

Navbar toggler (hamburger) problems (unresolved)

This works different now. In Bootstrap 4 I toggle from hamburger to X and vice versa. This does not work anymore in Bootstrap 5 and I do not have a solution for this at the moment. I had to remove the 'X'.

Column ordering, left column and right column were swapped on mobile

Fix: I had to play a bit with the order classes to fix this.

Tags visually disappeared

The tags were using the badge class.There were some changes with the badge class.
Fix: I replaced the badge class by the button class. Better anyway.

Close button for alerts and modals

Fix: Remove '&times' symbol line.

Alerts. In Bootstrap 4 you have something like:

<div class="alert alert-warning alert-dismissible fade show" role="alert">
  <strong>Holy guacamole!</strong> You should check in on some of those fields below.
  <button type="button" class="close" data-dismiss="alert" aria-label="Close">
    <span aria-hidden="true">&times;</span>
  </button>
</div>

In Bootstrap 5 this becomes:

<div class="alert alert-warning alert-dismissible fade show" role="alert">
  <strong>Holy guacamole!</strong> You should check in on some of those fields below.
  <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
</div>

Same fix for modals.

Collapsed navbar brand and hamburger shifted to page left and right boundaries

With Bootstrap 4 I had to tweaked this.

Fix: Remove px-0 in container class.

From:

<div class="sticky-top z-index-30">
  <nav class="navbar navbar-expand-md {{ navbar_main_extra_class }} sticky-top z-index-30">
    <div class="container px-0 mx-auto max-width-site">

To:

<div class="sticky-top z-index-30">
  <nav class="navbar navbar-expand-md {{ navbar_main_extra_class }} sticky-top z-index-30">
    <div class="container mx-auto max-width-site">

Increased margin left and right on XS and SM

Fix: Reduce margin by adding px-0 and px-md-2.

From:

<main role="main" class="container-fluid px-0 px-sm-3 pb-3 pt-5">
  <div class="row no-gutters mx-auto max-width-site">
    <div class="col">

To:

<main role="main" class="container-fluid px-0 px-sm-3 pb-3 pt-5">
  <div class="row no-gutters mx-auto max-width-site">
    <div class="col px-0 px-md-2">

Form - no margin below form fields

The form-group class was removed.

Fix: add to custom.css:

.form-group {
	margin-bottom: 1rem;
}

Forms - Input group

Search bar in navbar became ugly. This is an Input group. Bootstrap 5 dropped .input-group-append and .input-group-prepend.

Fix: Use Bootstrap documentation for Input group.

In Bootstrap 4 you have:

<div class="input-group mb-3">
  <input type="text" class="form-control" placeholder="Recipient's username" aria-label="Recipient's username" aria-describedby="basic-addon2">
  <div class="input-group-append">
    <span class="input-group-text" id="basic-addon2">@example.com</span>
  </div>
</div>

In Bootstrap 5 this becomes:

<div class="input-group mb-3">
  <input type="text" class="form-control" placeholder="Recipient's username" aria-label="Recipient's username" aria-describedby="basic-addon2">
  <span class="input-group-text" id="basic-addon2">@example.com</span>
</div>

Forms - Form field labels now require the .form-label class

Fix: Add form-label class.

In Bootstrap 4 you have:

  <div class="form-group">
    <label for="exampleInputEmail1">Email address</label>
    <input type="email" class="form-control" id="exampleInputEmail1" aria-describedby="emailHelp">
  </div>

In Bootstrap 5 this becomes:

<div class="mb-3">
  <label for="exampleFormControlInput1" class="form-label">Email address</label>
  <input type="email" class="form-control" id="exampleFormControlInput1" placeholder="name@example.com">
</div>

Forms - Custom select was removed

Fix: change the class.

In Bootstrap 4 you have:

<select class="custom-select">
...

In Bootstrap 5 this becomes:

<select class="form-select" aria-label="Default select example">

Forms - Custom checkbox was removed

It is now identical to the Bootstrap 4 checkbox.

In Bootstrap 4 you have:

<div class="custom-control custom-checkbox">
  <input type="checkbox" class="custom-control-input" id="customCheck1">
  <label class="custom-control-label" for="customCheck1">
    Check this custom checkbox
  </label>
</div>

In Bootstrap 5 this becomes:

<div class="form-check">
  <input class="form-check-input" type="checkbox" value="" id="flexCheckDefault">
  <label class="form-check-label" for="flexCheckDefault">
    Default checkbox
  </label>
</div>

Some things I like and some things I still wish

Like:

  • More control over the layout
  • Some inconsistencies removed
  • New default font
  • Responsive fonts
  • Borders with widths
  • Gutter control
    Now it is possible to change the gutter space very easily. I applied the gx-3 class immediately!

Wish:

  • More width classes, such as w-10, w-40
  • Responsive width classes, like w-md-25
  • Responsive borders, e.g. ditch boundaries on mobile

Summary

The migration from Bootstrap 4 to Bootstrap 5 took a lot of time. It is done for about 90%. And I only use a limited set. Most of the time was spent converting the form fields. I generate forms with fields with a Jinja script and had to make a lot of changes. But a good thing is that Bootstrap 5 removed the custom fields.
If you have a website running for a few more years then migrating to Bootstrap 5 is definitely worth it. You can also wait a few months, by then most of your problems probably have been solved by others.

Links / credits

Bootstrap 5 Beta 1
https://blog.getbootstrap.com/2020/12/07/bootstrap-5-beta-1/

Build fast, responsive sites with Bootstrap
https://getbootstrap.com/

Migrating to v5
https://getbootstrap.com/docs/5.0/migration/

Reboot
https://getbootstrap.com/docs/5.0/content/reboot/

twbs / bootstrap
https://github.com/twbs/bootstrap

Read more

Bootstrap

Leave a comment

Comment anonymously or log in to comment.

Comments (1)

Leave a reply

Reply anonymously or log in to reply.

avatar

I created a really cool tool to help on this. What do you think?
It works pretty good, and can help. I put a live version of my script, which is available on the webpage downloadable or usable. It is licensed under the GNU, so please feel free to modify it.
https://properprogramming.com/tools/converters/bootstrap-4-to-bootstrap-5-converter/