Skip to content

Report 15 — Bootstrap 4.4.1 to 5.3.3 Upgrade

Date: 2026-02-26 Updated: 2026-02-27 Phase: 4 (ALL SUB-PHASES COMPLETE) Status: COMPLETE

Overview

The Progress Credit Union v17 site currently uses Bootstrap 4.4.1. The client has requested an upgrade to Bootstrap 5.3.3 (latest stable). This is a significant breaking-change upgrade that affects HTML data attributes, CSS class names, JavaScript API, and removed components.

Scope

  • Source framework: Bootstrap 4.4.1 (bundled via libman.json or NuGet)
  • Target framework: Bootstrap 5.3.3
  • Files in scope: All .cshtml views, partials, and layout files in dbl.Progress/src/www/Views/
  • CSS in scope: Client CSS files in wwwroot/css/ (163 files)
  • JS in scope: Custom scripts referencing Bootstrap JS API

Key Breaking Changes in Bootstrap 5

  1. jQuery dependency removed -- Bootstrap 5 no longer requires jQuery
  2. Data attributes renamed -- data-* to data-bs-* (e.g., data-toggle to data-bs-toggle)
  3. CSS class renames -- multiple utility and component classes renamed
  4. Dropped components -- Jumbotron removed; media object replaced by utilities
  5. RTL support added
  6. CSS logical properties used for spacing/layout
  7. New utilities API for generating utility classes

Package Changes

Package Old Version New Version Notes
Bootstrap CSS 4.4.1 5.3.3 Major upgrade
Bootstrap JS 4.4.1 5.3.3 Major upgrade
jQuery 3.x Optional No longer required by Bootstrap; may still be needed for other plugins
Popper.js 1.x 2.x (bundled) Now bundled with Bootstrap JS bundle

Installation

Bootstrap 5.3.3 installed via libman.json (commit 643174b). Popper.js 2.x bundled with Bootstrap JS bundle.

Data Attribute Migration

All Bootstrap 4 data-* attributes must be prefixed with data-bs-* in Bootstrap 5.

Common Renames

Bootstrap 4 Bootstrap 5 Used In
data-toggle data-bs-toggle Modals, dropdowns, collapse, tabs, tooltips
data-target data-bs-target Modals, collapse
data-dismiss data-bs-dismiss Modals, alerts, toasts
data-slide data-bs-slide Carousels
data-slide-to data-bs-slide-to Carousel indicators
data-ride data-bs-ride Carousels
data-parent data-bs-parent Accordion/collapse
data-backdrop data-bs-backdrop Modals
data-keyboard data-bs-keyboard Modals
data-spy data-bs-spy Scrollspy
data-offset data-bs-offset Scrollspy
data-content data-bs-content Popovers
data-placement data-bs-placement Tooltips, popovers
data-container data-bs-container Tooltips, popovers
data-interval data-bs-interval Carousels

File-by-File Audit

COMPLETE. All data-* attributes updated to data-bs-* across 45 page templates, 121 blockgrid components, 7 blocklist components, 18 SiteLayout partials, and all calculator/loanbox/news/form partials.

Key commits: - 4cfa267 -- page templates + site layouts - 7cd8ee8 + f7f697c -- blockgrid component views + other partials - 08e9a5d -- JS files + remaining partials - 7ae1735 -- stickyNav.cshtml data-toggle to data-bs-toggle HTML/JS mismatch fix

CSS Class Renames

Utility Classes

Bootstrap 4 Bootstrap 5 Category
ml-* ms-* Margin start (left in LTR)
mr-* me-* Margin end (right in LTR)
pl-* ps-* Padding start
pr-* pe-* Padding end
text-left text-start Text alignment
text-right text-end Text alignment
float-left float-start Float
float-right float-end Float
border-left border-start Border
border-right border-end Border
rounded-left rounded-start Border radius
rounded-right rounded-end Border radius
no-gutters g-0 Grid gutters
font-weight-* fw-* Font weight
font-style-* fst-* Font style
font-italic fst-italic Font style
sr-only visually-hidden Screen reader
sr-only-focusable visually-hidden-focusable Screen reader

Component Classes

Bootstrap 4 Bootstrap 5 Component
badge-* (colors) bg-* + text-* Badges
badge-pill rounded-pill Badges
close btn-close Close button
custom-control form-check Form controls
custom-checkbox form-check Checkboxes
custom-radio form-check Radio buttons
custom-switch form-switch Switches
custom-select form-select Select inputs
custom-file form-control File inputs
custom-range form-range Range inputs
form-group (removed) Form layout
form-row row + g-* Form layout
form-inline d-flex utilities Form layout
input-group-append (removed, use markup) Input groups
input-group-prepend (removed, use markup) Input groups
media d-flex utilities Media objects
jumbotron (removed) Jumbotron
card-deck row + col + cards Card layout
embed-responsive ratio Responsive embeds
embed-responsive-* ratio-* Responsive embeds

File-by-File Audit

COMPLETE. All 1,142 BS4 CSS patterns replaced across 159 files (commit a6a776e).

Breakdown: - .sr-only to .visually-hidden: 158 occurrences - .form-group to .mb-3: 389 occurrences - .badge-primary to .bg-primary: 397 occurrences - .col-xs-* to .col-*: 76 occurrences - .text-left/.text-right to .text-start/.text-end: 35 occurrences - .pl-N/.pr-N to .ps-N/.pe-N: 67 occurrences - no-gutters to g-0: commit bd117a3

See Report 17 for full CSS pattern audit details.

Removed Components

Jumbotron

The .jumbotron class is removed in Bootstrap 5. Replace with utility classes:

<!-- BS4 -->
<div class="jumbotron">...</div>

<!-- BS5 -->
<div class="bg-light p-5 rounded-3">...</div>

Media Object

The .media component is removed. Replace with flex utilities:

<!-- BS4 -->
<div class="media">
  <img class="mr-3" src="...">
  <div class="media-body">...</div>
</div>

<!-- BS5 -->
<div class="d-flex">
  <img class="me-3" src="...">
  <div>...</div>
</div>

Form Groups

.form-group is removed. Use spacing utilities (mb-3) instead:

<!-- BS4 -->
<div class="form-group">...</div>

<!-- BS5 -->
<div class="mb-3">...</div>

Client CSS Theme Audit

Status: COMPLETE (commit a6a776e)

163 client CSS files in wwwroot/cssCreditUnion/ audited and updated. 159 files contained BS4 patterns; 1,142 total occurrences replaced. 4 files had zero BS4 patterns (CambrianStyles-cy.css, PremierStyles.css, SmartMoneyStyles-cy.css, ThurlesStyles.css).

All risk areas resolved: 1. .form-group overrides updated to .mb-3 2. .media component -- not used in client CSS (zero occurrences) 3. .pl-*/.pr-* renamed to .ps-*/.pe-* (67 occurrences) 4. JavaScript selectors updated in Phase 4D commits

JavaScript Migration

Status: COMPLETE (commits 08e9a5d, 7ae1735)

Bootstrap JS API Changes

BS4 API BS5 API Notes
$('#modal').modal('show') bootstrap.Modal.getOrCreateInstance(el).show() No jQuery dependency
$('[data-toggle="tooltip"]').tooltip() bootstrap.Tooltip.getOrCreateInstance(el) Vanilla JS
$('.carousel').carousel() bootstrap.Carousel.getOrCreateInstance(el) Vanilla JS
$('.collapse').collapse() bootstrap.Collapse.getOrCreateInstance(el) Vanilla JS

Migration Approach

jQuery is retained for other plugins (Slick, OwlCarousel, matchHeight). Bootstrap 5 jQuery compatibility layer handles the single remaining .tooltip() call in progressCore.js. All data attributes, event listeners, and class names are BS5-native. See Report 18 for full JS audit.

The stickyNav.js selected [data-bs-toggle="sticky-onscroll"] but HTML used data-toggle="sticky-onscroll". Fixed by updating stickyNav.cshtml to data-bs-toggle.

Regression Testing Checklist

All code changes are complete. The following areas need manual regression testing at runtime:

Layout & Grid

  • [ ] Page layouts render correctly at all breakpoints (xs, sm, md, lg, xl, xxl)
  • [ ] Container classes behave correctly
  • [ ] Grid columns stack/flow properly
  • [ ] Gutters are consistent with v8 design (no-gutters to g-0 applied)
  • [ ] Main navigation opens/closes on mobile
  • [ ] Dropdown menus work (data-bs-toggle applied)
  • [ ] Sticky/fixed navigation works (stickyNav bug fixed in commit 7ae1735)
  • [ ] Mobile hamburger toggle works

Components

  • [ ] Modals open and close correctly (data-bs-dismiss applied)
  • [ ] Carousels auto-play and navigate (data-bs-ride, data-bs-slide applied)
  • [ ] Accordion/collapse sections toggle (data-bs-parent applied)
  • [ ] Tabs switch content panels
  • [ ] Tooltips and popovers display (jQuery compat layer active)
  • [ ] Alert dismiss buttons work

Forms

  • [ ] Form validation styling works
  • [ ] Custom select/checkbox/radio styling renders
  • [ ] Input groups render correctly
  • [ ] Form layout spacing is correct (form-group to mb-3)

Page-Specific

  • [ ] Homepage hero/slider
  • [ ] Calculator pages (sliders, inputs, results)
  • [ ] LoanBox modes (Tabs, Boxes, FlipCards, Accordion)
  • [ ] Testimonial carousel
  • [ ] News listings and article pages
  • [ ] Data protection grid components
  • [ ] FAQ accordion
  • [ ] Gallery lightbox
  • [ ] Contact form
  • [ ] Login/authenticated pages

CSS Theme

  • [ ] Client brand colors preserved
  • [ ] Font sizes and spacing consistent (sr-only to visually-hidden, pl/pr to ps/pe)
  • [ ] Responsive breakpoints match design
  • [ ] No visual regressions in any page template

Progress Log

Date Agent Update
2026-02-26 docs-agent Initial report created with framework structure
2026-02-26 bs5-package Phase 4A: Bootstrap 5.3.3 package swap (commit 643174b)
2026-02-26 bs5-templates Phase 4B: Page templates + site layouts (commit 4cfa267)
2026-02-26 bs5-components Phase 4C: BlockGrid component views (commits 7cd8ee8, f7f697c)
2026-02-26 bs5-js Phase 4D: JS files + partials (commits 08e9a5d, 7ae1735, bd117a3)
2026-02-27 bs5-css-audit Phase 4E: CSS audit complete -- 1,142 patterns across 159 files (commit a6a776e)

ALL PHASES COMPLETE. Bootstrap 5.3.3 fully applied to views, JS, and CSS.

Migration documentation by Double for Progress Credit Union