September 26, 2022

NodeBB Specific Bootstrap 3 to 5 Migration Guide

What is this?

Version 2 of NodeBB using the Persona theme (and many child themes based off of Persona) used Bootstrap 3 as its front-end CSS framework.

As part of the upgrade to version 3, we are upgrading to Bootstrap 5, whose migration comes with a number of updates and changes, many of which are incompatible with previous versions of Bootstrap.

Do I need this?

If your theme or child theme updates the templates folder, you will need this guide to update your templates to use Bootstrap 5 components and classes.

If your templates are based off of an older version of Persona (that is, you copied an existing template and modified it), you simply need to copy the latest template from Persona and re-apply your changes.

The main migration docs for migrating from Bootstrap 3 to 5 can be found on the Bootstrap website:

… however, they are exhaustively complete and likely contain a lot of content that does not necessarily pertain to your theme. We have distilled some of the common migration steps below for easier consumption.

This blog post is the third in a series of posts related to the release of NodeBB v3

Please see our other articles related to v3:

In general…

  • pull-left changed to float-start
  • pull-right changed to float-end
  • text-right changed to text-end
  • img-responsive changed to img-fluid


  • Vertically stacked buttons change from .btn-block to using display/spacer classes.
<div class="d-grid gap-2">
  <button class="btn btn-primary" type="button">Button</button>
  <button class="btn btn-primary" type="button">Button</button> 
  • btn-xs removed use btn-sm
  • btn-default removed use btn-outline-secondary


  • col-xs-<n> changed to col-<n>


  • inline-block changed to d-inline-block

Media Component

… has been removed completely, use flex display classes instead:
<div class="d-flex">
  <div class="flex-shrink-0">
  <div class="flex-grow-1 ms-3">


  • navbar-toggle changed to navbar-toggler

Panels, Wells, and Jumbotrons

… have all been removed in favour of the “card” component.

To convert a panel into a card:

<div class=”card”>
  <div class=”card-header”>header</div>
  <div class=”card-body”>body</div>
  <div class=”card-footer”>footer</div>
  • <div class="well"> changed to <div class="card card-body text-bg-light">


  • <select class="form-control"> changed to <select class="form-select">
  • Add form-label class to labels
  • Add form-check-input to checkboxes. Sample checkbox with label:
<div class="”form-check”">
  <input class="”form-check-input”" type="”checkbox”" />
  <label class="”form-check-label”">a checkbox</label>
  • form-group, .form-row, or .form-inline are removed use spacing utilities
  • help-block changed to form-text


  • data-toggle="dropdown" changed to data-bs-toggle="dropdown"
  • Add dropdown-item to dropdown list item <a class="dropdown-item">Item 1</a>
  • dropdown-menu-right changed to dropdown-menu-end
  • Divider changed to dropdown-divider


  • data-toggle="collapse" changed to data-bs-toggle="collapse"
  • data-target=".classname" changed to data-bs-target=".classname"


  • data-dismiss="modal" changed to data-bs-dismiss="modal"

Responsive Breakpoints

Instead of using media queries using old Bootstrap 3 variables (e.g. @media (max-width: @screen-sm-max) { ... }), Bootstrap 5 introduces a new mixin for breakpoints.

Read more about it in Bootstrap 5’s article re: responsive breakpoints.

© 2014 – 2023 NodeBB, Inc. — Made in Canada.