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...
})