Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 58 ยท Quality

Migrating from Bootstrap 4 and Using Icons

Upgrade a Bootstrap 4 page to Bootstrap 5: renamed classes, removed jQuery and data-bs-* attributes. Then add Bootstrap Icons as a font or an SVG sprite.

A huge number of websites still run Bootstrap 4, and a lot of tutorials, templates and Stack Overflow answers use its class names. If you copy such code into a Bootstrap 5 page, parts of it quietly stop working: margins vanish, switches look like plain checkboxes, and a modal never opens. Knowing what changed lets you fix those pages in minutes and read old code without confusion.

This lesson lists the changes that matter in practice, shows an old snippet and its modern version side by side, and then covers the second half of the title: icons. Bootstrap ships no icons inside its CSS, but the project publishes a free companion library, Bootstrap Icons, which you can load as a font or as an SVG sprite. You will also learn how to line icons up with text so they do not look off by a pixel or two.

What changed, in one picture

Bootstrap 5 did three big things. It removed jQuery, so every plugin now works with plain JavaScript. It replaced direction words (left, right) with logical words (start, end) so layouts flip correctly in right-to-left languages. And it dropped many special-purpose components in favor of utilities you already know.

flowchart LR
  B4["Bootstrap 4"] --> J["jQuery plugins<br/>data-toggle"]
  B4 --> L["left and right<br/>ml-3, float-right"]
  B4 --> C["Special components<br/>jumbotron, media, form-group"]
  J --> J5["Plain JavaScript<br/>data-bs-toggle"]
  L --> L5["start and end<br/>ms-3, float-end"]
  C --> C5["Utilities and the grid<br/>p-5 bg-light, d-flex, mb-3"]

Three families of changes: scripting, direction names and removed components.

JavaScript: no jQuery, new attributes

Bootstrap 4 needed jQuery, Popper and its own script, in that order. Bootstrap 5 needs only its own bundle (which includes Popper). You can delete the jQuery <script> tag unless your own code uses it.

Every data attribute gained a bs prefix, so Bootstrap's attributes can never clash with yours:

Bootstrap 4 Bootstrap 5
data-toggle="modal" data-bs-toggle="modal"
data-target="#box" data-bs-target="#box"
data-dismiss="alert" data-bs-dismiss="alert"
data-ride="carousel" data-bs-ride="carousel"
data-parent="#acc" data-bs-parent="#acc"

If you call plugins from your own code, jQuery syntax such as $('#box').modal('show') becomes bootstrap.Modal.getOrCreateInstance(document.getElementById('box')).show(). The events changed from jQuery events to native DOM events, so $('#box').on('shown.bs.modal', fn) turns into box.addEventListener('shown.bs.modal', fn). See Bootstrap JavaScript Plugins and Plugin Events and Programmatic Control for the full story.

Renamed and removed classes

The most common renames follow the left/right to start/end rule. The rest are tidier names for old ideas.

Bootstrap 4 Bootstrap 5
ml-*, mr-*, pl-*, pr-* ms-*, me-*, ps-*, pe-*
float-left, float-right float-start, float-end
text-left, text-right text-start, text-end
border-left, rounded-right border-start, rounded-end
font-weight-bold, font-italic fw-bold, fst-italic
text-monospace font-monospace
sr-only visually-hidden
no-gutters g-0
badge-primary, badge-pill bg-primary, rounded-pill
custom-select form-select
custom-control, custom-switch form-check, form-switch
close btn-close
dropdown-menu-right dropdown-menu-end
embed-responsive ratio
thead-light table-light

And these were removed with no direct replacement, because utilities cover them:

  • jumbotron: use p-5 mb-4 bg-body-tertiary rounded-3.
  • form-group and form-row: use mb-3 on a wrapper and row g-2.
  • input-group-append and -prepend: put the button or text directly inside input-group.
  • media: use d-flex with flex-shrink-0 on the image.
  • card-deck: use row row-cols-* with g-* (see Cards).
  • btn-block: put the button in a d-grid wrapper, or use w-100.
  • form-control-file and custom-file: a normal form-control on type="file" is enough.

Another behavior change: Bootstrap 5 forms no longer need extra wrappers, but each control needs the form-label, form-control or form-check-* class on its own element. Floating labels (see Input Groups and Floating Labels) are new, and so are the xxl breakpoint, the gx-*/gy-* gutters and the Utility API.

Before and after

Here is a small Bootstrap 4 snippet that mixes several of the old names. It is read-only: with Bootstrap 5 loaded, it renders wrongly.

HTML
<div class="jumbotron">
  <h1 class="display-4 font-weight-bold">Welcome</h1>
  <span class="badge badge-primary badge-pill">New</span>
  <button class="close" data-dismiss="alert">&times;</button>
  <button class="btn btn-primary btn-block ml-3" data-toggle="modal" data-target="#m">Open</button>
</div>

The migrated version below uses the Bootstrap 5 names. Run it, then compare the structure with the snippet above.

The Bootstrap 5 version

Migration tip. Do not rename everything by hand in a large project. Search the codebase for each old name (ml-, data-toggle, custom-, sr-only), fix one family at a time, and load the page in a narrow and a wide window after each step. Bootstrap's own migration guide lists every change if you need a complete list.

Bootstrap 3 and 4 leftovers, and what replaces them

Old tutorials and pasted snippets keep bringing in components that no longer exist. This table covers the ones you will see most, beyond the renames above:

Old component Bootstrap 5 replacement
media, media-body (media object) d-flex with flex-shrink-0 on the image and flex-grow-1 ms-3 on the text
jumbotron a div with p-5 mb-4 bg-body-tertiary rounded-3
panel, panel-heading, panel-body (v3) card, card-header, card-body
well (v3) card card-body bg-body-tertiary, or p-3 border rounded
thumbnail (v3) img-thumbnail on the image, or a card with card-img-top
affix (v3 plugin) position-sticky with top-0 or the sticky-top helper
glyphicon glyphicon-* (v3 icon font) Bootstrap Icons or any SVG icon set
pull-left, pull-right (v3) float-start, float-end
hidden-xs, visible-md (v3) d-none d-sm-block, d-none d-md-block d-lg-none
col-xs-* (v3) col-* (the extra-small tier has no infix)
navbar-toggle, navbar-inverse (v3) navbar-toggler, and data-bs-theme="dark" on the navbar
label label-default (v3) badge text-bg-secondary
btn-default (v3) btn-secondary or btn-light
carousel-inner with item (v3) carousel-inner with carousel-item; active goes on the first item
data-toggle, data-target, data-dismiss (v3/v4) data-bs-toggle, data-bs-target, data-bs-dismiss
data-spy="scroll", data-offset (v3/v4 scrollspy) data-bs-spy="scroll" and data-bs-target; the offset became data-bs-offset in 5.0 and 5.1 and data-bs-root-margin from 5.2
dropleft, dropright (v4) dropstart, dropend
input-lg, input-sm, form-group-lg (v3) form-control-lg, form-control-sm, form-select-lg, form-select-sm
col-form-label-lg, col-form-label-sm (v4) unchanged: still the way to size a label that sits next to a large or small control in a horizontal form
navbar-expand-* with .navbar-light / .navbar-dark (v4) the same expand classes, but color the bar with data-bs-theme (and bg-body-tertiary or a bg-* class)

The most common cause of "my copied snippet does nothing" is the last row: v3 and v4 JavaScript attributes are ignored by v5, so a modal button with data-toggle="modal" silently does nothing. When you port a page, search for data-toggle, data-target and data-dismiss first.

A practical routine for old pages: search for the left-hand names above, replace them one by one, load the page at the three breakpoints (phone, tablet, desktop), and compare it with the original. Do not mix major versions on one page; two Bootstrap stylesheets will fight each other.

Bootstrap Icons as a font

Bootstrap Icons is a separate library of more than 1,900 SVG icons. The easiest way to use it is the icon font: add one stylesheet and write <i class="bi bi-NAME"></i>. The stylesheet pulls the font file from the same CDN.

Icon font

An icon font is text, so everything that styles text works on icons: fs-* sets the size, text-* the color, and me-1 or ms-1 adds a gap. Two cautions. First, a font icon has no meaning to a screen reader; if it sits next to a visible label (as above) that is fine, but an icon-only button needs aria-label on the button. Second, the font is a download of every glyph even when you use five. For a handful of icons, an SVG sprite or inline SVG is lighter.

SVG sprites and inline SVG

An SVG sprite is one file (or one hidden block) of <symbol> definitions. Each place you need an icon, you write a tiny <svg> that points at a symbol with <use>. The real library ships bootstrap-icons.svg, and you would reference it as <use href="/icons/bootstrap-icons.svg#heart-fill">. Note that browsers only load a <use> file from the same origin as the page, so you must host the sprite yourself instead of linking the CDN copy.

Inside this site's sandboxed preview the page has no origin to share, so the demo below puts the symbols inline in the same document. The pattern is identical.

An inline SVG sprite

The shared .icon class sets the size to 1em, so each icon grows with the surrounding text, and stroke: currentColor makes it follow text-* classes. aria-hidden="true" hides decorative icons from screen readers; the icon-only button gets its name from aria-label.

flowchart TD
  Q["How many icons do you need?"] -->|"Many, prototype quickly"| F["Icon font<br/>class bi bi-name"]
  Q -->|"A handful, performance matters"| S["Sprite or inline SVG<br/>use href"]
  Q -->|"One-off logo or art"| I["Inline SVG in the page"]

Choosing an icon delivery method.

Aligning icons with text

Icons look misaligned when they sit on the text baseline. Two fixes cover almost every case:

  1. Flex the container. Give the button or link d-inline-flex align-items-center gap-2. The icon and the text are centered on the same line, and gap-2 replaces margins that would have to flip for right-to-left.
  2. Use vertical-align: -0.125em on the icon (Bootstrap's own sprite examples do this) when it is inline in running text.

Size icons with the font size of the parent or with fs-*, and let them inherit color. Avoid fixed pixel widths in many places, which makes later changes tedious.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which attribute opens a modal in Bootstrap 5?

    All Bootstrap 5 data attributes carry the bs prefix: data-bs-toggle plus data-bs-target. data-toggle was Bootstrap 4.
  2. 2. A migrated page has lost its left margin on a button. The old class was ml-3. What is the Bootstrap 5 class?

    Left and right became start and end, so margin-left is ms-3. me-3 is the margin on the end side.
  3. 3. Why does a cross-origin SVG sprite referenced with use href fail to load?

    External use references are same-origin only, so host the sprite file on your own domain or inline the symbols.
  4. 4. What should an icon-only button have for accessibility?

    An icon alone has no text for a screen reader. aria-label gives the button a name; decorative icons next to text get aria-hidden.
  5. 5. Which replaces the removed Bootstrap 4 btn-block?

    Bootstrap 5 uses utilities: put the button in d-grid, or add w-100 for a single full-width button.

Summary

  • Bootstrap 5 removed jQuery; use the bundle and data-bs-* attributes, and native events and getOrCreateInstance from your own code.
  • Left/right names became start/end (ms-*, me-*, float-end, text-start), and several helpers were renamed (fw-bold, visually-hidden, g-0, btn-close, form-select, form-switch).
  • Removed components (jumbotron, media, form-group, card-deck, btn-block) are rebuilt with utilities and the grid.
  • Bootstrap Icons come as a font (bi bi-name), a same-origin SVG sprite or inline SVG.
  • Align icons with d-inline-flex align-items-center gap-2, size them with font size, and give icon-only buttons an aria-label.

Next lesson: Project: Landing Page.