NodeBB Specific Bootstrap 3 to 5 Migration Guide

Julian Lam 9/12/2022, 9:59:35 AM

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

Buttons

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

Grid/Breakpoints

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

Display

  • inline-block changed to d-inline-block

Media Component

... has been removed completely, use flex display classes instead: 
<div>
  <div>
    image
  </div>
  <div>
    text
  </div>
</div>

Navbar

  • 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>
  • <div> changed to <div>

Forms

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

Dropdowns

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

Collapse

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

Modals

  • 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.