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:
- Meet the Designer (Vlad Gerasimov)
- Bringing Back Better Bootswatch!
- NodeBB Specific Bootstrap 3 to 5 Migration Guide (👈 You are here)
- Migration Guide for v3
In general…
pull-left
changed tofloat-start
pull-right
changed tofloat-end
text-right
changed totext-end
img-responsive
changed toimg-fluid
Buttons
- 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> </div>
btn-xs
removed usebtn-sm
btn-default
removed usebtn-outline-secondary
Grid/Breakpoints
col-xs-<n>
changed tocol-<n>
Display
inline-block
changed tod-inline-block
Media Component
… has been removed completely, use flex display classes instead:<div class="d-flex"> <div class="flex-shrink-0"> image </div> <div class="flex-grow-1 ms-3"> text </div> </div>
Navbar
navbar-toggle
changed tonavbar-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 class="well">
changed to<div class="card card-body text-bg-light">
Forms
<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> </div>
form-group
,.form-row
, or.form-inline
are removed use spacing utilitieshelp-block
changed toform-text
Dropdowns
data-toggle="dropdown"
changed todata-bs-toggle="dropdown"
- Add
dropdown-item
to dropdown list item<a class="dropdown-item">Item 1</a>
dropdown-menu-right
changed todropdown-menu-end
- Divider changed to
dropdown-divider
Collapse
data-toggle="collapse"
changed todata-bs-toggle="collapse"
data-target=".classname"
changed todata-bs-target=".classname"
Modals
data-dismiss="modal"
changed todata-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.