Release notes for Bootstrap 5 upgrade

Summary of Changes

Note that this will have a significant impact on any scss and html customizations you may have made to your fork of this project.

The following links will be helpful:

Get started with Bootstrap v5.2.3
Migrating to v4
How to Migrate from Bootstrap Version 3 to 4
Migrating to v5
How to Migrate from Bootstrap Version 4 to 5
Use Bootstrap 5 with Ruby on Rails 6 and webpack
What happened to $grid-float-breakpoint in Bootstrap 4. And screen size breakpoint shift from 3 -> 4
What are media queries in Bootstrap 4?

Key changes

• Node package changes:
  • Changed version of bootstrap "^3.4.1" --> "^5.2.3"
  • Added @popperjs/core.
  • Removed bootstrap-3-typeahead, bootstrap-sass & popper.js
• Stylesheet changes

  • In app/assets/stylesheets/application.scss:

    • removed bootstrap-sass import
      and replaced with
      @import "../../../node_modules/bootstrap/scss/bootstrap";

  • The order of the import statements have been changed to import the blocks/ and utils/ after the default bootstrap stylesheets

  • In app/assets/stylesheets/blocks/:

    • Replaced in relevant files:
      • @use "../../../../node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss" as * ;
        with
        @use "../../../../node_modules/bootstrap/scss/bootstrap" as *;
    • Enclosed all division calculations using symbol / with calc() function,
      e.g., replaced
      padding-right: $grid-gutter-width / 2;
      with
      padding-right: calc($grid-gutter-width / 2);
      
    • Replaced breaking media queries since Bootstrap 3:

      • @media (max-width: $grid-float-breakpoint-max) {}
        with
        @include media-breakpoint-down(md){}

      • @media (max-width: $grid-float-breakpoint-max) {}
        with
        @include media-breakpoint-down(md) {}

  • Deleted app/javascript/src/utils/popoverHelper.js.

• Mixins
  • Media query mixins parameters have changed for a more logical approach.
    • media-breakpoint-down() uses the breakpoint itself instead of the next breakpoint (e.g., media-breakpoint-down(lg) instead of media-breakpoint-down(md) targets viewports smaller than lg).
• Color system
  • All lighten()and darken() functions replaced. These functions will mix the color with either white or black instead of changing its lightness by a fixed amount.
    • Replaced lighten() by tint-color().
    • Replaced darken() by shade-color().

Components & HTML

• Accordion & spinners
  • Bespoke versions replaced by Bootstrap 5 accordion and spinner now.
  • Accordion
    • Changed the default Bootstrap arrow icon for the accordion to use the fontawesome icons plus and minus icons. Created a several accordion specific colour variables:
      // Accordion colors
      $color-accordion-button: $color-primary-text;
      $color-accordion-button-icon: $color-primary-text;
      $color-accordion-button-bg: $color-primary-background;
      $color-accordion-button-active-bg: shade-color($color-accordion-button-bg, 30%);
      (See app/assets/stylesheets/blocks/_accordion.scss and app/assets/stylesheets/variables/_colours.scss for details.)
    • The drag icon in app/views/org_admin/sections/_section.html.erb now appears after the plus (or minus) icon.
  • The spinner block now uses classd-none instead ofhidden to hide.
• Buttons
  • Bootstrap dropped btn-block class for utilities. So we removed any styling using it.
  • Close Buttons: Renamed close tobtn-close.
  • Renamed btn-default to btn-secondary and variable $btn-default-color changed to $btn-secondary-color.
• Dropdowns
  • Dropdown list items with class dropdown have class dropdown-item added usually withpx-3 for positioning.
  • Added new dropdown-menu-dark variant and associated variables for on-demand dark dropdowns.
  • Data attributes changes required by Bootstrap 5 (as used by accordion and dropdown buttons):
    • data-display --> data-bs-display
    • data-parent --> data-bs-parent
    • data-target --> data-bs-target
    • data-toggle --> data-bs-toggle
  • Bootstrap 5 Popover added to some dropdown-menu items by adding attribute data-bs-toggle="popover"
• Form
  • form-group class replaced with form-control.
  • Form labels now require form-label or form-check-label to go with form-control and form-check respectively. So all obsolete control-label replaced by form-label and missing ones added.
  • Dropped form-specific layout classes for our grid system. Use Bootstrap grid and utilities instead of form-group, form-row, or form-inline.
  • form-text no longer sets display, allowing you to create inline or block help text as you wish just by changing the HTML element.
  • Input group addons are now specific to their placement relative to an input. So input-group-addon and in our case we replaced with input-group-addon.
  • Renamed checkbox and radio into form-check.
• Images
  • Renamed img-responsive to img-fluid.
• Labels and badges
  • Class label has been removed and replaced by badge to disambiguate from the <label> element.
    • Renamed label class to badge
    • Replaced label-default by bg-secondary
    • Replaced label-info by bg-info
    • Replaced label-warning by bg-warning .text-dark
    • Replaced label-danger by bg-danger
• Links
  • Links are underlined by default (not just on hover), unless they're part of specific components. So we had to add css to remove underline in many cases.
• Navs & navbars
  • Bootstrap rewrote component with flexbox. Dropped nearly all > selectors for simpler styling via un-nested classes. Instead of HTML-specific selectors like .nav > li > a, we use separate classes for .navs, .nav-items, and .nav-links. This makes your HTML more flexible while bringing along increased extensibility. So we have dropped HTML-specific selectors and css in _navs.scss e.g.,
    .nav-tabs > li > a:hover -->nav-tabs nav-link:hover,
    .nav-pills > li > a:hover -->nav-pills .nav-link:hover.
    • Pages with css classes nav andnavbar updated to work with Bootstrap 5. So app/assets/stylesheets/blocks/_navbars.scss and app/assets/stylesheets/blocks/_navs.scss updated.
      • Replacednav navbar-nav combination --> navbar-nav
      • Replacednavbar-toggle --> navbar-toggler
      • Replaced multiple spans innavbar-toggle button with classicon-bar
        --> single span withtoggler-icon
      • Lists with nav navbar-nav have classnav-item added to list elements.
• Notifications
  • Notifications now use classes d-block and d-none to show and hide respectively.
• Panels, thumbnails & wells (replacements)
  • Bootstrap 5 dropped panels, thumbnails and wells. So pages with them updated with Bootstrap 5 replacements.
    • All views with css classespanel, panel-body, panel-* Have panel replaced by card to give card, card_body, card-*, etc.
    • As panel-default and some otherpanel css classes don't have card equivalents with same suffixes we have added these classes temporarily in _cards.sccs, e.g.,.card-default, etc.
• Utilities
  • Bootstrap renamed several utilities to use logical property names instead of directional names with the addition of RTL support:
    • Renamed left-* and right-* to start-* and end-*.
    • Renamed float-left and float-right to float-start and float-end.
    • Renamed ml-* and mr-* to ms-* and me-*.
    • Renamed pl-* and pr-* to ps-* and pe-*.
    • Renamed text-left and text-right to text-start and text-end.
  • The hidden and show classes have been removed because they conflicted with jQuery's.
    • Replaced hidden with d-none.
  • Text utilities
    • As Bootstrap 5.2 dropped class text-justify we have created a custom version based on comment https://github.com/twbs/bootstrap/pull/29793#issuecomment-1814683346
    • text-* utilities do not add hover and focus states to links anymore. link-* helper classes can be used instead.