Migrating from Bootstrap 4 and knowing the limits

The Bootstrap 4 to 5 breaking changes that actually break builds, then an honest comparison with Tailwind and plain CSS.

The breaking changes that matter

# A first pass that finds the worst offenders before you open a browser
grep -rEo 'data-(toggle|target|dismiss|slide|ride|spy|parent)=' src/ | sort | uniq -c
grep -rEo '\b(ml|mr|pl|pr)-[0-5a]' src/ | sort | uniq -c
grep -rnE '\$\(.*\)\.(modal|collapse|tooltip|dropdown|tab)\(' src/

# and a safety net while you migrate
npm install bootstrap@5 bootstrap-icons

• Rename every data-* attribute to data-bs-* first: it is mechanical and unblocks the interactive components immediately.
• Then fix the direction-aware spacing classes. These fail silently, so a visual diff of each page is the only reliable check.
• jQuery calls have to be rewritten one by one; keep jQuery loaded during the transition so unconverted code still runs.
• popper.js v1 must go — Bootstrap 5 needs @popperjs/core, and leaving the old one in a bundle produces confusing positioning bugs.

Running the migration

// Before (Bootstrap 4 + jQuery)
// $('.modal').modal('show');
// $('#collapse').collapse('hide');

// After (Bootstrap 5, no jQuery)
import { Modal, Collapse } from 'bootstrap';

Modal.getOrCreateInstance(document.querySelector('#confirm')).show();
Collapse.getOrCreateInstance(document.querySelector('#panel')).hide();

// Delegated equivalents for markup injected later
document.addEventListener('click', (event) => {
  const modalTrigger = event.target.closest('[data-bs-toggle="modal"]');
  if (modalTrigger) {
    Modal.getOrCreateInstance(document.querySelector(modalTrigger.dataset.bsTarget)).show();
  }
});

1. Pin the version in your lockfile and load Bootstrap 5's CSS alongside Bootstrap 4's for one release, on a staging environment only.
2. Convert the CSS layer first — classes and markup — while the old JavaScript still drives behaviour.
3. Convert the JavaScript layer second, page by page, deleting the jQuery reference only when the last call is gone.
4. Audit the compiled bundle: dropping jQuery plus Popper v1 typically removes 40-60 KB gzipped on its own.
5. Keep a visual regression baseline per page; most Bootstrap 5 regressions are spacing and alignment, which automated tests will not catch.

When Bootstrap is the wrong choice

• Choose Bootstrap for internal tools, admin surfaces and marketing pages where consistency beats originality — the components you would otherwise rebuild are the value.
• Avoid it for a highly bespoke brand system: you will spend the effort fighting specificity and end up overriding more than you write.
• Bootstrap is a poor fit for a very small page where a 30 KB stylesheet is more than the whole rest of the site.
• Mixing Bootstrap with Tailwind is almost always a mistake: the two utility systems overlap and the reset rules conflict.

The honest summary: the framework saves the most time on the parts nobody enjoys writing — modals, dropdown focus handling, form validation states, a grid that does not break at odd widths. Its cost is a recognisable look and an upgrade path with real breaking changes. Decide which side is larger for the specific project instead of arguing in the abstract.

FAQ

Related

Utilities and Sass customisation The grid system

Last refreshed 2026-09-18.