Loading...
Skip to main content

Dialog

A modern component built on the native <dialog> element with built-in accessibility and backdrop support that replaces the old Modal component.

How it works

The Dialog component leverages the browser’s native <dialog> element, providing built-in accessibility features, focus management, and backdrop handling without the complexity of custom implementations.

Key features of the native dialog:

  • Modal or inline via showModal() / show() — modal: true (default) promotes the dialog to the browser’s top layer with a backdrop and focus trapping; modal: false renders it inline.
  • Built-in backdrop using the ::backdrop pseudo-element (modal only); set backdrop: "static" to lock clicks outside, or backdrop: false to hide it.
  • Escape key handling closes the dialog by default; set keyboard: false to disable.
  • Accessibility — focus is trapped inside modal dialogs and returned to the trigger on close, with native <dialog> ARIA semantics.
  • Animated open and close — circumvent browser restrictions by using a .hiding class to keep dialogs in the top layer during close so the exit transition (including ::backdrop) are animated properly.

The animation effect of this component is dependent on the prefers-reduced-motion media query.

Example

Toggle a dialog by clicking the button below. The dialog uses the native showModal() API for true modal behavior.

Dialog title

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

document/component/Document/DialogDemo.tsx
<DialogDemo
label="Open dialog"
saveLabel="Save changes"
title="Dialog title"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>

Without JavaScript

Supported browsers can open and close a dialog with the Invoker Commands API—no Bootstrap JavaScript required. Set commandFor to the dialog’s id, use command="show-modal" to open, and command="close" to dismiss.

The Invoker Commands API is not supported in all browsers. For guaranteed support, use React-controlled open and onClose, as in the examples above, when you need wrapper options, events, or animated close.

Invoker Commands

This dialog opens with command="show-modal" and closes with command="close". No Bootstrap JavaScript is involved.

<>
<Button
command="show-modal"
commandfor="invokerDialog"
theme="primary"
variant="solid"
>
Open dialog
</Button>
<Dialog
aria-labelledby="invokerDialogTitle"
id="invokerDialog"
>
<DialogHeader>
<DialogTitle id="invokerDialogTitle">
Invoker Commands
</DialogTitle>
<CloseButton
aria-label="Close"
command="close"
commandfor="invokerDialog"
/>
</DialogHeader>
<DialogBody>
<p>
This dialog opens with{' '}
<code>
command="show-modal"
</code>
and closes with

<code>
command="close"
</code>
. No Bootstrap JavaScript is involved.
</p>
</DialogBody>
<DialogFooter>
<Button
command="close"
commandfor="invokerDialog"
theme="secondary"
variant="solid"
>
Close
</Button>
</DialogFooter>
</Dialog>
</>

Dark dialog

To make a dialog dark, pass theme="dark" to Dialog.

Dark dialog title

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

document/component/Document/DialogDemo.tsx
<DialogDemo
dark
label="Open dark dialog"
saveLabel="Save changes"
title="Dark dialog title"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>

Static backdrop

When backdrop is set to static, the dialog will not close when clicking outside of it. Click the button below to try it.

Static backdrop

I will not close if you click outside of me. Use the close button or press Escape.

document/component/Document/DialogDemo.tsx
<DialogDemo
backdrop="static"
label="Open static backdrop dialog"
saveLabel="Save changes"
title="Static backdrop"
>
<p>
I will not close if you click outside of me. Use the close button or press Escape.
</p>
</DialogDemo>

Overlays

Tooltips, popovers, and toasts all work inside dialogs, but require some extra care. Since dialogs render in the browser’s top layer, overlays appended to <body> will appear behind the dialog. Keep OverlayBox inside the dialog, or set its container to the dialog element, so tooltips and popovers render inside it. Toasts already work as long as they’re placed in the dialog markup.

Tooltips, popovers, toasts, and menus all work inside modal dialogs. Modal dialogs use showModal(), which promotes the dialog to the browser’s top layer -- a special rendering layer above everything else on the page.

Overlays inside dialogs

These components work inside modal dialogs.

Animations

Instant

By default, dialogs animate with a fade on open and close. To disable animations, pass animation="instant" to Dialog.

Instant dialog

This dialog doesn’t animate and appears instantly on open and close.

document/component/Document/DialogDemo.tsx
<DialogDemo
animation="instant"
label="Instant dialog"
saveLabel="Save changes"
title="Instant dialog"
>
<p>
This dialog doesn’t animate and appears instantly on open and close.
</p>
</DialogDemo>

Slide down

Pass animation="slide-down" to Dialog and it will slide down from the top of the viewport when opened.

Slide down dialog

This dialog slides down from the top of the viewport.

document/component/Document/DialogDemo.tsx
<DialogDemo
animation="slide-down"
label="Slide down dialog"
saveLabel="Save changes"
title="Slide down dialog"
>
<p>
This dialog slides down from the top of the viewport.
</p>
</DialogDemo>

Slide up

Pass animation="slide-up" to Dialog and it will slide up from the bottom of the viewport when opened.

Slide up dialog

This dialog slides up from the bottom of the viewport.

document/component/Document/DialogDemo.tsx
<DialogDemo
animation="slide-up"
label="Slide up dialog"
saveLabel="Save changes"
title="Slide up dialog"
>
<p>
This dialog slides up from the bottom of the viewport.
</p>
</DialogDemo>

Scrollable

Create a scrollable dialog that scrolls the dialog body while keeping the header and footer fixed. Pass scrollable to Dialog.

Scrollable body

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

This is some placeholder content to show the scrolling behavior for dialogs. We use repeated paragraphs to demonstrate how content can exceed the dialog’s inner height, showing scrolling within the body while the header and footer remain fixed.

document/component/Document/DialogDemo.tsx
<DialogDemo
label="Launch scrollable body dialog"
saveLabel="Save changes"
scrollable
title="Scrollable body"
>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
<p>
This is some placeholder content to show the scrolling behavior for dialogs. We use
repeated paragraphs to demonstrate how content can exceed the dialog’s inner height,
showing scrolling within the body while the header and footer remain fixed.
</p>
</DialogDemo>

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 React demo coordinates the two open props rather than using data-attribute triggers.

First dialog

Click below to swap to a second dialog. The React state change opens the next dialog while the current one closes.

Second dialog

This is the second dialog. You can swap back to the first, or close this one entirely.

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)

Non-modal dialog

This dialog doesn’t block interaction with the rest of the page.

document/component/Document/DialogDemo.tsx
<DialogDemo
label="Open non-modal dialog"
modal={false}
saveLabel="Save changes"
title="Non-modal dialog"
>
<p>
This dialog doesn’t block interaction with the rest of the page.
</p>
</DialogDemo>

Use modal={false} to create a non-modal Dialog.

Optional sizes

Dialogs have three optional sizes, available via the size prop on Dialog. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.

SizePropDialog max-width
Smallsize="sm"280px
Default—500px
Largesize="lg"800px
Extra largesize="xl"1140px

Default dialog

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

SM dialog

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

LG dialog

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

XL dialog

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

document/component/Document/DialogDemo.tsx
<div className="d-flex flex-wrap gap-3">
<DialogDemo
label="Default dialog"
saveLabel="Save changes"
title="Default dialog"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
label="SM dialog"
saveLabel="Save changes"
size="sm"
title="SM dialog"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
label="LG dialog"
saveLabel="Save changes"
size="lg"
title="LG dialog"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
label="XL dialog"
saveLabel="Save changes"
size="xl"
title="XL dialog"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
</div>

Fullscreen dialog

Pass fullscreen to make the dialog cover the entire viewport.

Fullscreen dialog

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

document/component/Document/DialogDemo.tsx
<DialogDemo
fullscreen
label="Fullscreen dialog"
saveLabel="Save changes"
title="Fullscreen dialog"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>

Responsive fullscreen variants are also available. These make the dialog fullscreen only below a specific breakpoint.

PropFullscreen below
fullscreenAlways
fullscreen="sm"576px
fullscreen="md"768px
fullscreen="lg"1024px
fullscreen="xl"1280px
fullscreen="2xl"1536px

Fullscreen below sm

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

Fullscreen below md

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

Fullscreen below lg

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

Fullscreen below xl

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

Fullscreen below 2xl

This is a native dialog element. It uses the browser’s built-in modal behavior for accessibility and focus management.

document/component/Document/DialogDemo.tsx
<div className="d-flex flex-wrap gap-3">
<DialogDemo
fullscreen="sm"
label="Fullscreen below sm"
saveLabel="Save changes"
title="Fullscreen below sm"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
fullscreen="md"
label="Fullscreen below md"
saveLabel="Save changes"
title="Fullscreen below md"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
fullscreen="lg"
label="Fullscreen below lg"
saveLabel="Save changes"
title="Fullscreen below lg"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
fullscreen="xl"
label="Fullscreen below xl"
saveLabel="Save changes"
title="Fullscreen below xl"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
<DialogDemo
fullscreen="2xl"
label="Fullscreen below 2xl"
saveLabel="Save changes"
title="Fullscreen below 2xl"
>
<p>
This is a native dialog element. It uses the browser’s built-in modal behavior for
accessibility and focus management.
</p>
</DialogDemo>
</div>

CSS

Variables

Local CSS custom properties expose the component’s colors, spacing, borders, and transitions. Override them through style or a CSS module. The defaults below come from the Bootstrap stylesheet used by Idea React; see the upstream variable reference.

VariableDefault
--bs-dialog-padding1rem
--bs-dialog-width500px
--bs-dialog-margin1.75rem
--bs-dialog-colorvar(--bs-fg-body)
--bs-dialog-bgvar(--bs-bg-body)
--bs-dialog-border-colorvar(--bs-border-color-translucent)
--bs-dialog-border-widthvar(--bs-border-width)
--bs-dialog-border-radiusvar(--bs-radius-7)
--bs-dialog-box-shadowvar(--bs-box-shadow-xl)
--bs-dialog-transition-propertyopacity, transform, visibility
--bs-dialog-transition-duration0.3s
--bs-dialog-transition-timingvar(--bs-transition-timing-overlay)
--bs-dialog-backdrop-bglight-dark(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.65))
--bs-dialog-backdrop-blur8px
--bs-dialog-header-padding1rem
--bs-dialog-header-border-colorvar(--bs-border-color-translucent)
--bs-dialog-header-border-widthvar(--bs-border-width)
--bs-dialog-footer-padding1rem
--bs-dialog-footer-border-colorvar(--bs-border-color-translucent)
--bs-dialog-footer-border-widthvar(--bs-border-width)
--bs-dialog-footer-gap0.5rem

JavaScript behavior

Control Dialog with open; update application state from onClose. The wrapper handles the browser’s native dialog methods and focus restoration.

Options

PropDefaultDescription
modaltrueOpen with a backdrop, focus trapping, and top-layer rendering.
backdroptrueClose on an outside click; "static" keeps the backdrop without outside dismissal, and false hides it.
keyboardtrueClose when Escape is pressed.
scrollfalseAllow the document body to scroll.
animation"fade"Choose fade, instant, slide-down, or slide-up.

Events

Native onCancel and onClose callbacks are forwarded. onClose runs when the native dialog closes, including after an animated close.

Documentation navigation
On this page
On this page