Getting started
Migrating
A cheat sheet from stock Bootstrap 5.3 markup to rb-bootstrap markup, one plugin at a time.
The short version
- Delete the script tag. There is no
bootstrap.bundle.min.jsand nothing to initialise. - Swap the stylesheet for
rb-bootstrap.css. - Re-count your spacing utilities. The scale is now 0–8 on a 4 px base.
- Replace each
data-bs-togglepattern below with its native equivalent.
<!-- Before -->
<link rel="stylesheet" href="bootstrap.min.css">
<script src="bootstrap.bundle.min.js"></script>
<!-- After -->
<meta name="color-scheme" content="light dark">
<link rel="stylesheet" href="rb-bootstrap.min.css">
Static markup keeps working: .collapse.show, .tab-pane.active,
.toast.show, .dropdown-menu.show and .navbar-collapse.show all render
as before. What stops working is the toggle, because nothing runs to flip the class. See
No JavaScript for the mechanisms.
Spacing scale
Stock Bootstrap has six steps (0–5) with 1 rem at step 3. rb-bootstrap has nine (0–8) with 1 rem at step 4.
Every m-*, p-*, gap-* and g-* class shifts.
| Value | Stock Bootstrap | rb-bootstrap |
|---|---|---|
| 0 | *-0 | *-0 |
| 0.25 rem | *-1 | *-1 |
| 0.5 rem | *-2 | *-2 |
| 0.75 rem | — | *-3 |
| 1 rem | *-3 | *-4 |
| 1.5 rem | *-4 | *-5 |
| 2 rem | — | *-6 |
| 3 rem | *-5 | *-7 |
| 4 rem | — | *-8 |
Rule of thumb: 3 → 4, 4 → 5, 5 → 7. Negative margins
(.mt-n2) are enabled. See Spacing.
Collapse
<!-- Before -->
<button class="btn btn-primary" data-bs-toggle="collapse" data-bs-target="#card">Show card</button>
<div class="collapse" id="card">
<div class="card card-body">Six matches.</div>
</div>
<!-- After -->
<details class="collapse" id="card">
<summary class="btn btn-primary">Show card</summary>
<div class="card card-body">Six matches.</div>
</details>
Open by default: add the open attribute instead of .show. Horizontal: details.collapse-horizontal. Collapse.
Accordion
<!-- Before -->
<div class="accordion" id="faq">
<div class="accordion-item">
<h2 class="accordion-header">
<button class="accordion-button" data-bs-toggle="collapse" data-bs-target="#faq-1">Rules</button>
</h2>
<div id="faq-1" class="accordion-collapse collapse show" data-bs-parent="#faq">
<div class="accordion-body">Pinfall, submission, count-out, DQ.</div>
</div>
</div>
</div>
<!-- After -->
<div class="accordion">
<details class="accordion-item" name="faq" open>
<summary class="accordion-button"><h2 class="accordion-header">Rules</h2></summary>
<div class="accordion-body">Pinfall, submission, count-out, DQ.</div>
</details>
</div>
The name attribute replaces data-bs-parent: items sharing a name are exclusive. Leave it off for an "always open" accordion. Accordion.
Dropdown
<!-- Before -->
<div class="dropdown">
<button class="btn btn-secondary dropdown-toggle" data-bs-toggle="dropdown">Finisher</button>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Leg drop</a></li>
</ul>
</div>
<!-- After: universal, no light-dismiss -->
<details class="dropdown">
<summary class="btn btn-secondary dropdown-toggle">Finisher</summary>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Leg drop</a></li>
</ul>
</details>
<!-- After: light-dismiss + Escape, anchored where supported -->
<div class="dropdown">
<button class="btn btn-secondary dropdown-toggle" popovertarget="finisher-menu">Finisher</button>
<ul class="dropdown-menu" popover id="finisher-menu">
<li><a class="dropdown-item" href="#">Leg drop</a></li>
</ul>
</div>
.dropup, .dropend, .dropstart, .dropdown-center and .dropdown-menu-end work on both. Dropdowns.
Navbar collapse
<!-- Before -->
<button class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#nav-main">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="nav-main">…</div>
<!-- After -->
<input type="checkbox" class="navbar-toggler-check" id="nav-main">
<label class="navbar-toggler" for="nav-main" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</label>
<div class="navbar-collapse">…</div>
Drop .collapse from the panel. Dropdowns inside the navbar become <details class="dropdown"> with <summary class="nav-link dropdown-toggle">. Navbar.
Tabs and pills
<!-- Before -->
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item"><button class="nav-link active" data-bs-toggle="tab" data-bs-target="#home">Home</button></li>
<li class="nav-item"><button class="nav-link" data-bs-toggle="tab" data-bs-target="#card">Card</button></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="home">…</div>
<div class="tab-pane" id="card">…</div>
</div>
<!-- After -->
<div class="tabs">
<ul class="nav nav-tabs" role="tablist">
<li class="nav-item">
<input type="radio" class="nav-check" name="main" id="tab-home" checked>
<label class="nav-link" for="tab-home">Home</label>
</li>
<li class="nav-item">
<input type="radio" class="nav-check" name="main" id="tab-card">
<label class="nav-link" for="tab-card">Card</label>
</li>
</ul>
<div class="tab-content">
<div class="tab-pane">…</div>
<div class="tab-pane">…</div>
</div>
</div>
Panes pair with tabs by position, so ids and .active go away. Wrap both in .tabs. Up to 12 tabs per group. Navs & tabs.
Modal
<!-- Before -->
<button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#confirm">Open</button>
<div class="modal fade" id="confirm" tabindex="-1">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Confirm</h5>
<button class="btn-close" data-bs-dismiss="modal"></button>
</div>
<div class="modal-body">…</div>
</div>
</div>
</div>
<!-- After -->
<button class="btn btn-primary" popovertarget="confirm" commandfor="confirm" command="show-modal">Open</button>
<dialog class="modal fade" popover id="confirm" aria-labelledby="confirm-title">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h2 class="modal-title h5" id="confirm-title">Confirm</h2>
<button class="btn-close" popovertarget="confirm" popovertargetaction="hide" aria-label="Close"></button>
</div>
<div class="modal-body">…</div>
</div>
</div>
</dialog>
data-bs-backdrop="static" becomes popover="manual". tabindex="-1" is no longer needed. Modal.
Offcanvas
<!-- Before -->
<button class="btn btn-primary" data-bs-toggle="offcanvas" data-bs-target="#menu">Menu</button>
<div class="offcanvas offcanvas-start" tabindex="-1" id="menu">
<div class="offcanvas-header">
<h5 class="offcanvas-title">Menu</h5>
<button class="btn-close" data-bs-dismiss="offcanvas"></button>
</div>
<div class="offcanvas-body">…</div>
</div>
<!-- After -->
<button class="btn btn-primary" popovertarget="menu">Menu</button>
<div class="offcanvas offcanvas-start" popover id="menu" aria-labelledby="menu-title">
<div class="offcanvas-header">
<h2 class="offcanvas-title h5" id="menu-title">Menu</h2>
<button class="btn-close" popovertarget="menu" popovertargetaction="hide" aria-label="Close"></button>
</div>
<div class="offcanvas-body">…</div>
</div>
Responsive variants (.offcanvas-lg) behave as before: a popover below the breakpoint, in-flow above it. Offcanvas.
Alert dismiss
<!-- Before -->
<div class="alert alert-warning alert-dismissible fade show" role="alert">
Bell has rung.
<button class="btn-close" data-bs-dismiss="alert"></button>
</div>
<!-- After -->
<dialog open class="alert alert-warning alert-dismissible">
Bell has rung.
<form method="dialog"><button class="btn-close" aria-label="Close"></button></form>
</dialog>
Drop role="alert" only if the dialog is static content; keep it for live announcements. Alerts.
Toast
<!-- Before -->
<div class="toast" role="status" id="saved">
<div class="toast-header"><strong class="me-auto">Saved</strong><button class="btn-close" data-bs-dismiss="toast"></button></div>
<div class="toast-body">Card updated.</div>
</div>
<script>new bootstrap.Toast(document.getElementById('saved')).show()</script>
<!-- After -->
<button class="btn btn-primary" popovertarget="saved" popovertargetaction="show">Save</button>
<div class="toast fade" popover="manual" id="saved" role="status">
<div class="toast-header">
<strong class="me-auto">Saved</strong>
<button class="btn-close" popovertarget="saved" popovertargetaction="hide" aria-label="Close"></button>
</div>
<div class="toast-body">Card updated.</div>
</div>
Add .toast-autohide (and optionally style="--bs-toast-delay: 8s") for the fade-out. A toast cannot show itself; a button or link must open it. Toasts.
Tooltip
<!-- Before -->
<button class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-title="Three count">Pin</button>
<script>new bootstrap.Tooltip(document.querySelector('[data-bs-toggle="tooltip"]'))</script>
<!-- After: same markup, no init -->
<button class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-title="Three count" data-bs-placement="bottom">Pin</button>
This is the one data-bs-toggle the CSS reads. title alone does nothing; use data-bs-title. Tooltips.
Popover
<!-- Before -->
<button class="btn btn-secondary" data-bs-toggle="popover" data-bs-title="Stipulation" data-bs-content="No DQ.">Details</button>
<script>new bootstrap.Popover(document.querySelector('[data-bs-toggle="popover"]'))</script>
<!-- After -->
<button class="btn btn-secondary" popovertarget="stip">Details</button>
<div class="popover fade" popover id="stip" data-bs-placement="top">
<div class="popover-arrow"></div>
<h3 class="popover-header">Stipulation</h3>
<div class="popover-body">No DQ.</div>
</div>
The content moves out of attributes and into a real element, so it can hold forms and links. Popovers.
Carousel
<!-- Before -->
<div class="carousel slide" id="hero" data-bs-ride="carousel">
<div class="carousel-indicators">
<button data-bs-target="#hero" data-bs-slide-to="0" class="active"></button>
<button data-bs-target="#hero" data-bs-slide-to="1"></button>
</div>
<div class="carousel-inner">
<div class="carousel-item active"><img src="1.jpg" class="d-block w-100" alt=""></div>
<div class="carousel-item"><img src="2.jpg" class="d-block w-100" alt=""></div>
</div>
<button class="carousel-control-prev" data-bs-target="#hero" data-bs-slide="prev">…</button>
<button class="carousel-control-next" data-bs-target="#hero" data-bs-slide="next">…</button>
</div>
<!-- After -->
<div class="carousel">
<div class="carousel-inner">
<div class="carousel-item" id="hero-1"><img src="1.jpg" class="d-block w-100" alt=""></div>
<div class="carousel-item" id="hero-2"><img src="2.jpg" class="d-block w-100" alt=""></div>
</div>
<div class="carousel-indicators">
<a href="#hero-1" aria-label="Slide 1"></a>
<a href="#hero-2" aria-label="Slide 2"></a>
</div>
</div>
No .slide, no .active, no data-bs-ride. Prev/next buttons are generated by the engine where ::scroll-button() exists. There is no auto-advance. Carousel.
Scrollspy
<!-- Before -->
<body data-bs-spy="scroll" data-bs-target="#toc" data-bs-offset="56">
<ul class="nav nav-pills" id="toc">
<li class="nav-item"><a class="nav-link" href="#intro">Intro</a></li>
</ul>
<section id="intro">…</section>
</body>
<!-- After -->
<div class="scrollspy" style="--bs-scrollspy-offset: 56px">
<ul class="nav nav-pills">
<li class="nav-item"><a class="nav-link" href="#intro">Intro</a></li>
</ul>
<div class="scrollspy-content">
<section id="intro">…</section>
</div>
</div>
Links and sections pair by position, up to 12. Needs scroll-driven animations; otherwise it is a plain anchor list. Scrollspy.
Button toggle
<!-- Before -->
<button class="btn btn-primary" data-bs-toggle="button">Favourite</button>
<!-- After -->
<input type="checkbox" class="btn-check" id="fav" autocomplete="off">
<label class="btn btn-primary" for="fav">Favourite</label>
This is Bootstrap's own .btn-check markup; the theme only removes the label bottom margin. Buttons.
Form validation
<!-- Before -->
<form class="needs-validation" novalidate>
<input class="form-control" required>
<div class="invalid-feedback">Required.</div>
</form>
<script>/* add .was-validated on submit */</script>
<!-- After -->
<form>
<input class="form-control" required>
<div class="invalid-feedback">Required.</div>
</form>
:user-invalid styles the field after the user has interacted with it, and
:user-invalid ~ .invalid-feedback shows the message. .is-invalid,
.is-valid and .was-validated still work for server-rendered state.
Validation.
Also changed
.fadeno longer hides an element. It opts into the fade transition only.- Dark mode is automatic from
prefers-color-scheme. Adddata-bs-theme="light"to<html>if you were relying on light-only. Color modes. - Headings h1–h3 switch to Big Shoulders Display. Display classes are uppercase. Typography.
- Buttons, inputs, badges, alerts and tabs have a 2 px radius; cards and modals keep 6 px. Tokens.
- CSS grid classes (
.grid,.g-col-*) are on. CSS grid.