Dialog·续
Swapping dialogs
When a toggle trigger is inside an open dialog, clicking it will swap dialogs—opening the new one before closing the current. This ensures the backdrop stays visible throughout the transition with no flash. The swap behavior is automatic when a data-bs-toggle="dialog" trigger is inside an already-open dialog.
Open first dialog </button>
<dialog class="dialog" id="swapDialog1"> <div class="dialog-header"> <h1 class="dialog-title">First dialog</h1> </div> <div class="dialog-body"> <p>Click below to swap to a second dialog. Notice the backdrop stays visible—no flash!</p> </div> <div class="dialog-footer"> <button type="button" class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button> <button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#swapDialog2">Go to second dialog</button><!-- [!code highlight] --> </div> </dialog>
<dialog class="dialog" id="swapDialog2"> <div class="dialog-header"> <h1 class="dialog-title">Second dialog</h1> </div> <div class="dialog-body"> <p>This is the second dialog. You can swap back to the first, or close this one entirely.</p> </div> <div class="dialog-footer"> <button type="button" class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button> <button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#swapDialog1">Back to first dialog</button><!-- [!code highlight] --> </div> </dialog>`} />
Non-modal dialogs
By default, dialogs open as modals using the browser-native showModal() method. You can also open dialogs as non-modal using show() by setting modal to false. Non-modal dialogs:
- Have no backdrop
- Don’t trap focus
- Don’t block interaction with the rest of the page
- Don’t render in the browser’s top layer
- Still respond to Escape key (if
keyboard: true)
<Example code={`<button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#nonModalDialog" data-bs-modal="false"><!-- [!code highlight] --> Open non-modal dialog </button>
<dialog class="dialog" id="nonModalDialog"> <div class="dialog-header"> <h1 class="dialog-title">Non-modal dialog</h1> </div> <div class="dialog-body"> <p>This dialog doesn’t block the page. You can still interact with content behind it.</p> </div> <div class="dialog-footer"> <button type="button" class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button> </div> </dialog>`} />
Use the modal option to create a non-modal dialog if building with JavaScript:
const dialog = new bootstrap.Dialog('#myDialog', { modal: false })
dialog.show()
Optional sizes
Dialogs have three optional sizes, available via modifier classes to be placed on a .dialog. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.
| Size | Class | Dialog max-width |
|---|---|---|
| Small | .dialog-sm |
280px |
| Default | — | 500px |
| Large | .dialog-lg |
800px |
| Extra large | .dialog-xl |
1140px |
<dialog class="dialog dialog-xl" id="exampleDialogXl"> <div class="dialog-header"> <h1 class="dialog-title">Extra large dialog</h1> </div> <div class="dialog-body"> <p>This is an extra large dialog using the <code>.dialog-xl</code> class.</p> </div> </dialog>
<dialog class="dialog dialog-lg" id="exampleDialogLg"> <div class="dialog-header"> <h1 class="dialog-title">Large dialog</h1> </div> <div class="dialog-body"> <p>This is a large dialog using the <code>.dialog-lg</code> class.</p> </div> </dialog>
<dialog class="dialog" id="exampleDialogMd"> <div class="dialog-header"> <h1 class="dialog-title">Medium (default) dialog</h1> </div> <div class="dialog-body"> <p>This is a medium (default) dialog—there’s no modifier class for this size.</p> </div> </dialog>
<dialog class="dialog dialog-sm" id="exampleDialogSm"> <div class="dialog-header"> <h1 class="dialog-title">Small dialog</h1> </div> <div class="dialog-body"> <p>This is a small dialog using the <code>.dialog-sm</code> class.</p> </div> </dialog>
Extra large dialog </button> <button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#exampleDialogLg"> Large dialog </button> <button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#exampleDialogMd"> Default dialog </button> <button type="button" class="btn-solid theme-primary" data-bs-toggle="dialog" data-bs-target="#exampleDialogSm"> Small dialog </button>`} />
<dialog class="dialog dialog-xl">…</dialog>
<dialog class="dialog dialog-lg">…</dialog>
<dialog class="dialog">…</dialog>
<dialog class="dialog dialog-sm">…</dialog>
Fullscreen dialog
Use .dialog-fullscreen to make the dialog cover the entire viewport.
Fullscreen dialog </button>
<dialog class="dialog dialog-fullscreen" id="exampleDialogFullscreen"> <div class="dialog-header"> <h1 class="dialog-title">Fullscreen dialog</h1> </div> <div class="dialog-body"> <p>This dialog covers the entire viewport.</p> </div> <div class="dialog-footer"> <button type="button" class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button> </div> </dialog>`} />
Responsive fullscreen variants are also available. These make the dialog fullscreen only below a specific breakpoint.
| Class | Fullscreen below |
|---|---|
.dialog-fullscreen |
Always |
.sm-down:dialog-fullscreen |
576px |
.md-down:dialog-fullscreen |
768px |
.lg-down:dialog-fullscreen |
1024px |
.xl-down:dialog-fullscreen |
1280px |
.2xl-down:dialog-fullscreen |
1536px |
Fullscreen below lg </button>
<dialog class="dialog lg-down:dialog-fullscreen" id="exampleDialogFullscreenLg"><!-- [!code highlight] --> <div class="dialog-header"> <h1 class="dialog-title">Fullscreen below lg</h1> </div> <div class="dialog-body"> <p>This dialog is fullscreen below the <code>lg</code> breakpoint.</p> </div> <div class="dialog-footer"> <button type="button" class="btn-solid theme-secondary" data-bs-dismiss="dialog">Close</button> </div> </dialog>`} />
CSS
Variables
Sass maps
Dialog sizes are defined in the $dialog-sizes Sass map. Each size specifies the dialog width.
JavaScript behavior
Via data attributes
Toggle a dialog without writing JavaScript. Set data-bs-toggle="dialog" on a controller element, like a button, along with a data-bs-target="#foo" to target a specific dialog to toggle.
| Attribute | Description |
|---|---|
data-bs-toggle="dialog" |
Opens or toggles the dialog from the trigger element. |
data-bs-target |
CSS selector for the dialog element to show or hide. |
data-bs-dismiss="dialog" |
On a control inside the dialog, closes the dialog when activated. |
<button type="button" data-bs-toggle="dialog" data-bs-target="#myDialog">
Launch dialog
</button>
Dismiss
Dismissal can be achieved with the data-bs-dismiss attribute on a button within the dialog:
<button type="button" data-bs-dismiss="dialog">Close</button>
Via JavaScript
Create a dialog with a single line of JavaScript:
const myDialog = new bootstrap.Dialog('#myDialog')
Dependencies
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-bs-, as in data-bs-backdrop="static".
| Name | Type | Default | Description |
|---|---|---|---|
backdrop |
boolean or 'static' |
true |
For modal dialogs, clicking the backdrop dismisses the dialog. Specify static for a backdrop which doesn’t close the dialog when clicked. Has no effect on non-modal dialogs. |
keyboard |
boolean | true |
Closes the dialog when escape key is pressed. |
modal |
boolean | true |
When true, opens the dialog as a modal using showModal() with backdrop, focus trapping, and top layer rendering. When false, opens as a non-modal dialog using show() without backdrop or focus trapping. |
Methods
Passing options
Activates your content as a dialog. Accepts an optional options object.
const myDialog = new bootstrap.Dialog('#myDialog', {
keyboard: false
})
| Method | Description |
|---|---|
show |
Opens the dialog. Returns a promise that resolves once the dialog is shown (i.e. after the shown.bs.dialog event fires). |
hide |
Hides the dialog. Returns a promise that resolves once the dialog is hidden (i.e. after the hidden.bs.dialog event fires). |
toggle |
Toggles the dialog. Returns a promise that resolves once the dialog is shown or hidden (i.e. after the shown.bs.dialog or hidden.bs.dialog event fires). |
handleUpdate |
Provided for API consistency with Modal. Native dialogs handle their own positioning. |
dispose |
Destroys an element’s dialog. |
getInstance |
Static method which allows you to get the dialog instance associated with a DOM element. |
getOrCreateInstance |
Static method which allows you to get the dialog instance associated with a DOM element, or create a new one in case it wasn’t initialized. |
Events
Bootstrap’s dialog class exposes a few events for hooking into dialog functionality.
| Event | Description |
|---|---|
show.bs.dialog |
Fires immediately when the show instance method is called. |
shown.bs.dialog |
Fired when the dialog has been made visible to the user (will wait for CSS transitions to complete). |
hide.bs.dialog |
Fires immediately when the hide instance method is called. |
hidden.bs.dialog |
Fired when the dialog has finished being hidden from the user (will wait for CSS transitions to complete). |
hidePrevented.bs.dialog |
Fired when the dialog is shown, its backdrop is static, and a click outside the dialog or an escape key press is performed (with keyboard set to false). |
cancel.bs.dialog |
Fired when the user presses Escape and the dialog is about to close. |
const myDialog = document.getElementById('myDialog')
myDialog.addEventListener('hidden.bs.dialog', event => {
// do something...
})
