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: falserenders it inline. - Built-in backdrop using the
::backdroppseudo-element (modal only); setbackdrop: "static"to lock clicks outside, orbackdrop: falseto hide it. - Escape key handling closes the dialog by default; set
keyboard: falseto 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
.hidingclass 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.
<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.
<>
<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.
<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.
<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.
<DialogOverlaysDemo />Animations
Instant
By default, dialogs animate with a fade on open and close. To disable animations, pass animation="instant" to Dialog.
<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.
<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.
<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.
<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.
<DialogSwapDemo />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)
<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.
| Size | Prop | Dialog max-width |
|---|---|---|
| Small | size="sm" | 280px |
| Default | — | 500px |
| Large | size="lg" | 800px |
| Extra large | size="xl" | 1140px |
<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.
<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.
| Prop | Fullscreen below |
|---|---|
fullscreen | Always |
fullscreen="sm" | 576px |
fullscreen="md" | 768px |
fullscreen="lg" | 1024px |
fullscreen="xl" | 1280px |
fullscreen="2xl" | 1536px |
<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.
| Variable | Default |
|---|---|
--bs-dialog-padding | 1rem |
--bs-dialog-width | 500px |
--bs-dialog-margin | 1.75rem |
--bs-dialog-color | var(--bs-fg-body) |
--bs-dialog-bg | var(--bs-bg-body) |
--bs-dialog-border-color | var(--bs-border-color-translucent) |
--bs-dialog-border-width | var(--bs-border-width) |
--bs-dialog-border-radius | var(--bs-radius-7) |
--bs-dialog-box-shadow | var(--bs-box-shadow-xl) |
--bs-dialog-transition-property | opacity, transform, visibility |
--bs-dialog-transition-duration | 0.3s |
--bs-dialog-transition-timing | var(--bs-transition-timing-overlay) |
--bs-dialog-backdrop-bg | light-dark(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.65)) |
--bs-dialog-backdrop-blur | 8px |
--bs-dialog-header-padding | 1rem |
--bs-dialog-header-border-color | var(--bs-border-color-translucent) |
--bs-dialog-header-border-width | var(--bs-border-width) |
--bs-dialog-footer-padding | 1rem |
--bs-dialog-footer-border-color | var(--bs-border-color-translucent) |
--bs-dialog-footer-border-width | var(--bs-border-width) |
--bs-dialog-footer-gap | 0.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
| Prop | Default | Description |
|---|---|---|
modal | true | Open with a backdrop, focus trapping, and top-layer rendering. |
backdrop | true | Close on an outside click; "static" keeps the backdrop without outside dismissal, and false hides it. |
keyboard | true | Close when Escape is pressed. |
scroll | false | Allow 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.