Bootstrap 5 Loading Overlay
A Loading Overlay is a full-screen or container-scoped UI layer that blocks interaction and signals to the user that an asynchronous operation is in progress: such as a form submission, data fetch, or file upload. In Bootstrap 5, it is constructed using positioning utilities, backdrop styling, and a spinner component rather than a dedicated built-in class. Use it whenever the UI needs to prevent duplicate actions and communicate processing state clearly.
Bootstrap class
No dedicated Bootstrap class
Common use cases
- Blocking a multi-step checkout form while a payment gateway processes a transaction, preventing users from clicking 'Pay' multiple times
- Covering a data dashboard panel while live analytics are being fetched from an API on initial page load or filter change
- Displaying over an image upload area while a file is being resized, compressed, and sent to cloud storage before showing the preview
- Locking a settings form while user preferences are being saved and validated server-side, then dismissing once a success response is received
Variants and classes
| Variant | Description and classes |
|---|---|
| Container overlay | Covers one card or section, not the whole page.position-relative + position-absolute top-0 start-0 w-100 h-100 |
| Centred spinner | Spinner in the middle of the overlay.d-flex align-items-center justify-content-center + spinner-border |
| Translucent backdrop | Content stays faintly visible underneath.bg-white bg-opacity-75 |
| Button loading state | Spinner inside a disabled button.btn + spinner-border spinner-border-sm + disabled attribute |
Code example
<div class="position-relative">
<!-- Content being overlaid -->
<div class="card p-4">
<h5 class="card-title">Order Summary</h5>
<p class="card-text">Processing your payment details. Please do not close this window.</p>
</div>
<!-- Loading Overlay -->
<div id="loadingOverlay"
class="position-absolute top-0 start-0 w-100 h-100 d-flex align-items-center justify-content-center"
style="background-color: rgba(255, 255, 255, 0.85); z-index: 10;">
<div class="text-center">
<div class="spinner-border text-primary mb-3" role="status" style="width: 3rem; height: 3rem;">
<span class="visually-hidden">Processing payment…</span>
</div>
<p class="fw-semibold text-primary mb-0">Securing your payment…</p>
</div>
</div>
</div>
<!-- Toggle script -->
<script>
// Show overlay
document.getElementById('loadingOverlay').classList.remove('d-none');
// Hide overlay after async operation completes
// document.getElementById('loadingOverlay').classList.add('d-none');
</script>Live examples
Basic Loading Overlay
Canvas template variants
Canvas Builder builds pages on the Canvas HTML template, which adds its own styled versions of Bootstrap 5 components. Variants you can ask for in a prompt:
- Canvas Builder generated loading overlay with custom colours
- Loading Overlay with interactive states
- Responsive loading overlay for all screen sizes
Best practices
Use position-relative on the parent, not the page body
Scoping the overlay to its immediate parent container with position-relative prevents it from blocking unrelated UI, for example, keeping the navigation and sidebar interactive while only the main content panel shows a loading state.
Always include a visually hidden label inside the spinner
Bootstrap's spinner-border has no accessible text by default. Add <span class='visually-hidden'>Loading…</span> inside it so screen readers announce the loading state, satisfying WCAG 2.1 criterion 4.1.3.
Control overlay visibility with d-none rather than removing from the DOM
Toggling Bootstrap's d-none utility class via JavaScript is faster than creating and destroying DOM nodes on each operation, and it preserves the overlay's transition state and event listeners across multiple async calls.
Add a semi-transparent backdrop using rgba on the background-color
A fully opaque overlay hides context entirely. Use rgba(255, 255, 255, 0.85) for light themes or rgba(0, 0, 0, 0.6) for dark themes so users can see the content they submitted beneath the overlay, reducing perceived uncertainty.
FAQ
How do I make a full-page loading overlay in Bootstrap 5 instead of just covering one component?
position-fixed instead of position-absolute and set top-0 start-0 w-100 h-100 with a high z-index (e.g., style='z-index: 9999;'). Use position-fixed on the overlay div and place it as a direct child of <body>. This ensures it covers the entire viewport regardless of scroll position. Combine with Bootstrap's vw-100 vh-100 or inline styles for guaranteed full coverage.Can I customise the spinner colour and size to match my brand in Bootstrap 5?
text-primary, text-success, text-danger, or a custom colour via style='color: #e63946;'. For size, either use the built-in spinner-border-sm modifier for a small variant, or override width and height inline (e.g., style='width: 4rem; height: 4rem;'). You can also use spinner-grow instead of spinner-border for a pulsing animation that suits softer brand aesthetics.How does Canvas Builder generate Loading Overlay components?
position-relative on the parent and position-absolute on the overlay, includes the visually-hidden accessibility span, and wires up d-none toggle logic in vanilla JavaScript so the overlay works without any additional dependencies.