BaseDialog
Compose a modal trigger, backdrop, and content surface.
Anatomy#
Portal owns the mounted Overlay and Content subtree and preserves it through exit motion.
Usage#
Use BaseDialog when you compose trigger, backdrop, and content yourself. Use Dialog for a structured title, description, body, and footer. Use Sheet for a drawer from a viewport edge. Use Popover for anchored interactive content. Dialog and Sheet wrap this primitive; their Content parts include a Portal internally.
Composition#
Place BaseDialog.Overlay and BaseDialog.Content inside the same BaseDialog.Portal. The Portal mounts them
when open and keeps them present through exit animations. Without it, both parts render in place
and your application controls their mounting. One root owns one active Content; use a nested
BaseDialog root for a second surface.
To scroll content taller than the viewport inside the backdrop, set scrollable on BaseDialog.Overlay
and nest BaseDialog.Content inside it. To render without a backdrop, omit BaseDialog.Overlay.
BaseDialog.Content children may be JSX or a function that receives close. Give BaseDialog.Content an
accessible name with aria-label or aria-labelledby.
Focus and outside interaction#
modal defaults to true: focus stays inside the surface, outside content is hidden from assistive
technology, and native outside pointer actions are prevented. Closing restores focus to the
trigger. Use initialFocus to choose the element that receives focus on open, or false to skip
the move, and finalFocus to choose where focus returns. Both apply only while modal is true.
Setting modal={false} allows focus to leave, but Escape and outside interactions still request
closure. closeOnOverlayClick controls outside pointer dismissal and closeOnEscape controls
Escape. Both default to true. A false value blocks that gesture and reports it through
onClosePrevented. Scroll locking is independent: preventScroll defaults to true. To allow
background page interaction, set preventScroll={false} and omit BaseDialog.Overlay.
Styling and portal placement#
The root renders no element. Apply class and object style to rendered parts; root classes
and styles set their slot defaults. See Customization.
Set root mount for a chosen container, including controlled surfaces without a Trigger.
BaseDialog.Portal mount overrides that default.
State and exit lifecycle#
Use open with onOpenChange for controlled visibility. onExitComplete waits for the overlay
and content exit animations to finish. Root transition={false} skips those animations, so the
surfaces unmount as soon as the modal closes and onExitComplete runs at once.
Keyboard interaction#
| Key | Description |
|---|---|
| Esc | Requests dismissal when closeOnEscape is not false. |
| ⇥ | Moves focus forward within the modal focus scope. |
| Shift + Tab | Moves focus backward within the modal focus scope. |
Examples#
Compose a custom surface#
Mount overlay and content in one Portal. Content children can receive close from the render
callback.
Open from parent state#
A page button owns open through onOpenChange. Closing from inside still reports back to the
parent.
Omit the backdrop#
Leave BaseDialog.Overlay out when the host surface already provides context.
Drag a window by its title bar#
Compose a custom header that moves the surface. Reset the offset when the modal closes.
Track exit motion from a managed modal#
Own visibility and wait until overlay and content finish their exit animations before treating the modal as gone.
Count completed exits#
Open from a page button and increment a counter after exit motion completes.
API Reference#
Attributes#
data-closeddata-expandeddata-overlay-scrolldata-transitionProps#
BaseDialog#
Trigger#
Renders a <button> element by default.
Portal#
Overlay#
Renders a <div> element by default.
Content#
Renders a <div> element by default.
Close#
Renders a <button> element by default.