Dialog asChild composition
All Dialog parts (Trigger, Overlay, Content, Close, Title, Description) support the asChild prop which changes the default rendered element to the one passed as a child, merging their props and behavior.
Radix Primitives · all subjects
dialog
44 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Dialog controlled API example
To close a Dialog after an asynchronous form submission, use controlled props: import * as React from "react"; import { Dialog } from "radix-ui"; const wait = () => new Promise((resolve) => setTimeout(resolve, 1000)); export default () => { const [open, setOpen] = React.useState(false); return ( <Dialog.Root open={open} onOpenChange={setOpen}> <Dialog.Trigger>Open</Dialog.Trigger> <Dialog.Portal> <Dialog.Overlay /> <Dialog.Content> <form onSubmit={(event) => { wait().then(() => setOpen(false)); event.preventDefault(); }}> {/** some inputs */} <button type="submit">Submit</button> </form> </Dialog.Content> </Dialog.Portal> </Dialog.Root> ); };
Dialog scrollable overlay example
To create a scrollable dialog overlay, move Dialog.Content inside Dialog.Overlay and apply CSS: .DialogOverlay { background: rgba(0 0 0 / 0.5); position: fixed; top: 0; left: 0; right: 0; bottom: 0; display: grid; place-items: center; overflow-y: auto; } .DialogContent { min-width: 300px; background: white; padding: 30px; border-radius: 4px; }
Dialog custom portal container example
To customize the element that the dialog portals into, use the container prop on Dialog.Portal: import * as React from "react"; import { Dialog } from "radix-ui"; export default () => { const [container, setContainer] = React.useState(null); return ( <div> <Dialog.Root> <Dialog.Trigger /> <Dialog.Portal container={container}> <Dialog.Overlay /> <Dialog.Content>...</Dialog.Content> </Dialog.Portal> </Dialog.Root> <div ref={setContainer} /> </div> ); };
Dialog custom API abstraction example
Create a custom Dialog API by abstracting Dialog.Overlay and Dialog.Close. Usage: import { Dialog, DialogTrigger, DialogContent } from "./your-dialog"; export default () => ( <Dialog> <DialogTrigger>Dialog trigger</DialogTrigger> <DialogContent>Dialog Content</DialogContent> </Dialog> ); Implementation: import * as React from "react"; import { Dialog as DialogPrimitive } from "radix-ui"; import { Cross1Icon } from "@radix-ui/react-icons"; export const DialogContent = React.forwardRef( ({ children, ...props }, forwardedRef) => ( <DialogPrimitive.Portal> <DialogPrimitive.Overlay /> <DialogPrimitive.Content {...props} ref={forwardedRef}> {children} <DialogPrimitive.Close aria-label="Close"> <Cross1Icon /> </DialogPrimitive.Close> </DialogPrimitive.Content> </DialogPrimitive.Portal> ), ); export const Dialog = DialogPrimitive.Root; export const DialogTrigger = DialogPrimitive.Trigger;
Dialog focus management
Dialog automatically traps focus within the modal. The onOpenAutoFocus handler is called when focus moves into the component after opening, and onCloseAutoFocus is called when focus moves to the trigger after closing. Both can be prevented with event.preventDefault.
Dialog modal mode behavior
When Dialog modal prop is true (default), interaction with outside elements is disabled and only dialog content is visible to screen readers. When modal prop is false, the dialog operates in non-modal mode.
Dialog controlled vs uncontrolled
Dialog can be used in two ways: uncontrolled mode using defaultOpen prop, or controlled mode using open and onOpenChange props together.
Dialog description and purpose
A Dialog is a window overlaid on either the primary window or another dialog window, rendering the content underneath inert.
Dialog anatomy parts
Dialog is composed of the following parts: Dialog.Root (contains all parts), Dialog.Trigger (button that opens the dialog), Dialog.Portal (portals overlay and content into body), Dialog.Overlay (layer covering inert portion), Dialog.Content (contains content to render), Dialog.Title (accessible title announced when opened), Dialog.Description (optional accessible description announced when opened), and Dialog.Close (button that closes the dialog).
Dialog Root props
Dialog.Root accepts the following props: defaultOpen (boolean, sets initial open state for uncontrolled usage), open (boolean, controlled open state used with onOpenChange), onOpenChange ((open: boolean) => void, called when open state changes), and modal (boolean, required: false, default: true, controls modality - when true disables interaction with outside elements and makes only dialog content visible to screen readers).
Dialog Trigger props and data attributes
Dialog.Trigger accepts asChild (boolean, required: false, default: false). It has the data attribute [data-state] with values: open, closed.
Dialog Portal props
Dialog.Portal accepts the following props: forceMount (boolean, forces mounting for animation control, inherited by Dialog.Overlay and Dialog.Content), and container (HTMLElement, default: document.body, specifies where to portal content).
Dialog Overlay props and data attributes
Dialog.Overlay accepts asChild (boolean, required: false, default: false) and forceMount (boolean, forces mounting for animation control, inherits from Dialog.Portal). It has the data attribute [data-state] with values: open, closed.
Dialog Content props
Dialog.Content accepts the following props: asChild (boolean, required: false, default: false), forceMount (boolean, forces mounting for animation control, inherits from Dialog.Portal), onOpenAutoFocus ((event: Event) => void, called when focus moves into component after opening, preventable with event.preventDefault), onCloseAutoFocus ((event: Event) => void, called when focus moves to trigger after closing, preventable with event.preventDefault), onEscapeKeyDown ((event: KeyboardEvent) => void, called when escape key is pressed, preventable with event.preventDefault), onPointerDownOutside ((event: PointerDownOutsideEvent) => void, called for pointer events outside bounds, preventable with event.preventDefault), and onInteractOutside ((event: React.FocusEvent | MouseEvent | TouchEvent) => void, called for interactions outside bounds, preventable with event.preventDefault). It has the data attribute [data-state] with values: open, closed.
Dialog Close props
Dialog.Close accepts asChild (boolean, required: false, default: false).
Dialog Title props
Dialog.Title accepts asChild (boolean, required: false, default: false). It is an accessible title announced when the dialog is opened. To hide the title visually, wrap it inside Visually Hidden utility with asChild prop.
Dialog Description props
Dialog.Description accepts asChild (boolean, required: false, default: false). It is an optional accessible description announced when the dialog is opened. To hide the description visually, wrap it inside Visually Hidden utility with asChild prop. To remove the description entirely, remove this part and pass aria-describedby={undefined} to Dialog.Content.
Dialog ARIA references fix July 2026
Fixed broken ARIA references in Dialogs where title or description elements are not rendered.
Dialog non-modal Safari re-opening
Prevent non-modal dialog from re-opening when closing using trigger in Safari.
Dialog focus trapping with deleted items
Ensure focus trapping is maintained in Dialog when the focused item is deleted.
Dialog allowPinchZoom trackpad
Fix allowPinchZoom bug for trackpad users in Dialog.
Dialog textarea scrollable Firefox
Fix issue with textarea elements not being scrollable in Firefox within Dialog.
Dialog iOS text selection and editing bug
Fixed a bug where iOS text selection and editing on HTML inputs within dialogs were broken.
Dialog disabled pointer events in closed dialogs
Fixed a bug causing disabled pointer events in closed dialogs.
Dialog title requirement warning
Log an error when an accessible title via the Dialog.Title part is missing.
Dialog description requirement warning
Log a warning when an accessible description via the Dialog.Description part is missing.
Dialog.Portal added for portalling behavior
Dialog now has a Portal part. To avoid regressions, this part should be used if portalling behavior is desired.
Dialog allowPinchZoom prop removed, defaults to true
The allowPinchZoom prop was removed from Dialog.Root as it now defaults to true.
Dialog.Title is now required
Dialog.Title is now a required part and will throw an error if not used. If no title is needed, aria-describedby={undefined} must be passed to Dialog.Content.
Dialog basic example with edit profile form
Example showing a basic dialog with Trigger opening a modal dialog containing Title, Description, form fields (Name and Email using TextField.Root), and Close buttons for Cancel and Save actions.
Dialog Content width props
Dialog.Content accepts width, minWidth, and maxWidth props to control the dialog width, used in conjunction with the size prop.
Dialog with Inset component for table content
Example showing a dialog with Title, Description, and an Inset component used to align table content flush with the sides of the dialog, with a close button.
Dialog Root component structure
Dialog.Root contains all the parts of a dialog. It is the wrapper component that manages the dialog state and composition.
Dialog Title announces on open
Dialog.Title is an accessible title that is announced when the dialog is opened. This part is based on the Heading component with pre-defined font size and leading trim on top.
Dialog Description is optional and announces on open
Dialog.Description is an optional accessible description that is announced when the dialog is opened. It is based on the Text component with a pre-defined font size. To remove the description entirely, remove this part and pass aria-describedby={undefined} to Content.
Dialog Close wraps the close control
Dialog.Close wraps the control that will close the dialog when activated.
Dialog Content maxWidth prop
Dialog.Content accepts a maxWidth prop to control the maximum width of the dialog, for example maxWidth="450px".
Dialog Content based on div element
Dialog.Content contains the content of the dialog and is based on the div element.
Dialog Trigger wraps the open control
Dialog.Trigger wraps the control that will open the dialog when activated.
Dialog modal prop unavailable in themed component
The Dialog themed component is designed around the modal pattern, so the modal prop is unavailable.
Dialog Content size prop controls padding and border-radius
The Dialog.Content size prop controls the padding and border-radius of the content. Valid sizes are 1, 2, 3, and 4.
Radix Themes 3.0.5 AlertDialog and Dialog Content props
Radix Themes version 3.0.5 added `align`, `height`, `minHeight`, and `maxHeight` props to AlertDialog.Content and Dialog.Content.
Radix Themes 3.0.0 AlertDialog and Dialog default maxWidth
Radix Themes 3.0.0 set AlertDialog and Dialog Content parts to have maxWidth="600px" by default, slightly larger than the previous 580px value.