Modal
A Bootstrap modal is a dialog box that opens on top of the page and dims everything behind it, so the user has to deal with it before going back. Modals suit short, focused tasks: confirming a delete, showing a login form or displaying details about an item. In Bootstrap 5 they work through a set of classes plus the bundled JavaScript, with no jQuery required.
The parts of a modal
A modal is a nested structure, and each layer has a job:
.modalis the full-screen wrapper that is hidden until opened..modal-dialogcontrols width and position..modal-contentis the visible white box..modal-header,.modal-bodyand.modal-footerdivide that box into title, content and action areas.
Opening a modal without writing JavaScript
A trigger button uses data-bs-toggle="modal" and points to the modal's id with data-bs-target. Any element inside the modal with data-bs-dismiss="modal" closes it. The page must load bootstrap.bundle.min.js, which includes Popper and all components.
<button type="button" class="btn btn-danger"
data-bs-toggle="modal" data-bs-target="#deleteModal">
Delete file
</button>
<div class="modal fade" id="deleteModal" tabindex="-1"
aria-labelledby="deleteModalLabel" aria-hidden="true">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="deleteModalLabel">Delete this file?</h5>
<button type="button" class="btn-close"
data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
This cannot be undone.
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary"
data-bs-dismiss="modal">Cancel</button>
<button type="button" class="btn btn-danger" id="confirmDelete">Delete</button>
</div>
</div>
</div>
</div>
The fade class adds the slide-and-fade animation, and modal-dialog-centered centres the box vertically. The aria-labelledby attribute links the dialog to its title so screen readers announce it properly.
Controlling a modal from JavaScript
Sometimes you need to open a modal after an event, such as a failed save. Create or fetch an instance and call its methods:
const modalEl = document.getElementById('deleteModal');
const modal = bootstrap.Modal.getOrCreateInstance(modalEl);
document.getElementById('confirmDelete').addEventListener('click', () => {
deleteFile();
modal.hide();
});
modalEl.addEventListener('hidden.bs.modal', () => {
console.log('Modal fully closed');
});
Events such as show.bs.modal, shown.bs.modal and hidden.bs.modal let you load data before display or reset a form after closing.
Useful options
| Option or class | Effect |
|---|---|
data-bs-backdrop="static" | Clicking outside does not close the modal. |
data-bs-keyboard="false" | The Escape key does not close it. |
modal-sm, modal-lg, modal-xl | Change the dialog width. |
modal-fullscreen-sm-down | Fills the screen on small phones. |
modal-dialog-scrollable | Scrolls the body while header and footer stay visible. |
Pitfalls to avoid
The most frequent problem is a modal that does nothing when clicked. Usually the bundle script is missing, or the old Bootstrap 4 attributes data-toggle and data-target were copied from an old example; version 5 needs the bs prefix. Another issue is a modal placed deep inside a container with position: fixed or overflow: hidden, which can clip it or hide it under the backdrop. Keep modal markup near the end of <body>. Finally, do not open one modal on top of another; Bootstrap does not support stacked modals. If a flow needs two steps, change the content inside the same modal, or close the first and open the second from its hidden.bs.modal event. Also resist using modals for long reading or complex forms; on a phone they become cramped, and a separate page is often kinder to the user.
Remember
Use a modal for brief, focused interactions, build it from the dialog, content, header, body and footer layers, trigger it with data-bs- attributes or the bootstrap.Modal API, and keep its markup at the top level of the page.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.