Skip to main content

Bootstrap 5 Migration Guide for Aeon Web Pages

This guide highlights the most frequent and important changes from the Bootstrap 5 upgrade in Aeon Default Web Pages. Use this as a quick reference when customizing Aeon pages or making edits to the upgraded pages.

Dependencies | Form Fields | Select Dropdowns | Spacing | Text Alignment | Font Weight | Data Attributes | Dropdowns | Badges | CSS Variables | Additional Resources

Dependencies Now Hosted Locally​

What Changed:

  • Bootstrap and Popper.js moved from CDN to local files
  • Improves security and eliminates external dependencies

Before (Bootstrap 4):

<link rel="stylesheet"
      href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" ...>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js"
        ...></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"
        ...></script>

After (Bootstrap 5):

<link rel="stylesheet" href="css/bootstrap.min.css">
<script src="js/popper.min.js"></script>
<script src="js/bootstrap.min.js"></script>

What This Means for You:

  • If you reference Bootstrap files, use the local paths shown above

Form Field Structure Changes​

What Changed:

  • The wrapper <div> around form fields uses a new class
  • Labels now require an explicit class in most cases

Before (Bootstrap 4):

<div class="form-group">
    <label for="username">Username</label>
    <input type="text" class="form-control" id="username">
</div>

After (Bootstrap 5):

<div class="field-wrapper">
    <label class="form-label" for="username">Username</label>
    <input type="text" class="form-control" id="username">
</div>

What This Means for You:

  • When adding new form fields, use field-wrapper instead of form-group
  • <label> elements now use class="form-label" or class="form-check-label"

Select Dropdowns Have a New Class​

What Changed:

  • The custom select styling class changed

Before (Bootstrap 4):

<select class="custom-select" id="mySelect">
    <option>Option 1</option>
</select>

After (Bootstrap 5):

<select class="form-select" id="mySelect">
    <option>Option 1</option>
</select>

What This Means for You:

  • Use form-select instead of custom-select for all dropdown fields
  • This provides consistent styling across all form elements

Spacing Classes Changed (RTL Support)​

What Changed:

  • Margin and padding classes now use logical properties (start/end instead of left/right)
  • This supports right-to-left (RTL) languages

Before (Bootstrap 4):

<button class="btn mr-2">Right Margin</button>
<div class="ml-3 pl-2">Left Margin and Padding</div>
<span class="pr-1">Right Padding</span>

After (Bootstrap 5):

<button class="btn me-2">End Margin</button>
<div class="ms-3 ps-2">Start Margin and Padding</div>
<span class="pe-1">End Padding</span>

Quick Reference Table:

Bootstrap 4Bootstrap 5Meaning
ml-*ms-*Margin-start (left in LTR)
mr-*me-*Margin-end (right in LTR)
pl-*ps-*Padding-start (left in LTR)
pr-*pe-*Padding-end (right in LTR)

What This Means for You:

  • Replace all ml-, mr-, pl-, pr- classes with ms-, me-, ps-, pe- equivalents
  • The number stays the same (e.g., mr-3 → me-3)

Text Alignment Classes Changed​

What Changed:

  • Text alignment now uses logical properties

Before (Bootstrap 4):

<div class="text-left">Left aligned</div>
<div class="text-right">Right aligned</div>

After (Bootstrap 5):

<div class="text-start">Start aligned</div>
<div class="text-end">End aligned</div>

What This Means for You:

  • Use text-start instead of text-left
  • Use text-end instead of text-right
  • text-center remains unchanged

Font Weight Classes Are Shorter​

What Changed:

  • Font weight classes now use abbreviated names

Before (Bootstrap 4):

<span class="font-weight-bold">Bold text</span>
<span class="font-weight-normal">Normal text</span>

After (Bootstrap 5):

<span class="fw-bold">Bold text</span>
<span class="fw-normal">Normal text</span>

What This Means for You:

  • Use fw-bold instead of font-weight-bold
  • Use fw-normal instead of font-weight-normal

Data Attributes Now Namespaced​

What Changed:

  • All Bootstrap data attributes now have a data-bs- prefix to avoid conflicts with other code libraries

Before (Bootstrap 4):

<button data-toggle="collapse" data-target="#myCollapse">Toggle</button>
<button data-toggle="dropdown">Dropdown</button>
<button data-toggle="modal" data-target="#myModal">Open Modal</button>

After (Bootstrap 5):

<button data-bs-toggle="collapse" data-bs-target="#myCollapse">Toggle</button>
<button data-bs-toggle="dropdown">Dropdown</button>
<button data-bs-toggle="modal" data-bs-target="#myModal">Open Modal</button>

What This Means for You:

  • Use data-bs-toggle and data-bs-target for interactive components
  • This applies to dropdowns, modals, collapsible sections, and other interactive elements

What Changed:

  • Dropdown alignment classes now use logical properties

Before (Bootstrap 4):

<div class="dropdown-menu dropdown-menu-right">...</div>
<div class="dropdown-menu dropdown-menu-left">...</div>

After (Bootstrap 5):

<div class="dropdown-menu dropdown-menu-end">...</div>
<div class="dropdown-menu dropdown-menu-start">...</div>

What This Means for You:

  • Use dropdown-menu-end instead of dropdown-menu-right
  • Use dropdown-menu-start instead of dropdown-menu-left

Badge Classes Restructured​

What Changed:

  • Badge color and shape classes use new naming conventions

Before (Bootstrap 4):

<span class="badge badge-primary">New</span>
<span class="badge badge-secondary badge-pill">5</span>

After (Bootstrap 5):

<span class="badge text-bg-primary">New</span>
<span class="badge text-bg-secondary rounded-pill">5</span>

What This Means for You:

  • Use text-bg-{color} format instead of badge-{color}
  • Use rounded-pill instead of badge-pill for pill-shaped badges
  • Available colors: primary, secondary, success, danger, warning, info, light, dark

CSS Variables Are Now Standard​

What Changed:

  • Bootstrap 5 extensively uses CSS custom properties (variables) for theming
  • Bootstrap variables use the --bs- prefix

New Pattern (examples):

:root {
  --bs-border-radius: .25rem;
  --bs-link-hover-color: #0056b3;
}

.btn-primary {
  --bs-btn-bg: #0d6efd;
  --bs-btn-border-color: #0d6efd;
  background-color: var(--bs-btn-bg);
}

What This Means for You:

  • You can customize Bootstrap by overriding CSS variables, useful as an alternative option for styling versus the prior approach of basic CSS properties
  • Variables are inherited and follow CSS cascade rules
  • See aeon.css for examples of variable usage

Additional Resources​