Example
Related
- Dialog — Common layout component regardless of modality or type of dialog.
- DialogContainer — A controller for dialog state, without the requirement for a trigger element.
Usage
The DialogTrigger accepts exactly two children: the element which triggers opening of the dialog and the dialog itself. The trigger must be the first child passed into the DialogTrigger and should be an element that supports press events.
If your dialog has buttons within it that should close the dialog when pressed, you must wrap the dialog in a function in order to propagate the close function to the dialog’s children. TODO: explain/link info about render functions. Dialogs that do not contain such interactive elements can simply provide the dialog component as is to the DialogTrigger as its second child.
Props
Type
By providing a type prop, you can specify the “type” of dialog that is rendered by your DialogTrigger. Note that pressing the Esc key will close the dialog regardless of its type.
Modal
Modal dialogs include a blanket that blocks access to the underlying interface until the dialog is closed. Sizing options can be found on the Dialog page. Focus is “trapped” inside the dialog until it’s closed.
The term “modal” is sometimes used interchangeably with “dialog”, but this is a misnomer. A dialog is considered modal if it blocks interaction with the rest of the application.
Popover
If a dialog without a blanket is needed, consider using a "popover" type dialog. See dialog placement for how you can customize the positioning. Note that popovers are automatically rendered as modals on mobile by default. See the mobile type prop for more information.
Tray
Tray dialogs are typically used to portray information on mobile devices or smaller screens. They should only ever be displayed on devices with small screens, for interfaces where popovers wouldn’t be appropriate.
Fullscreen
Fullscreen dialogs are a fullscreen variant of the “modal” dialog, only revealing a small portion of the page behind the blanket. Use this variant for more complex workflows that do not fit in the available modal dialog sizes. This variant does not support isDismissible.
Mobile type
The mobileType prop allows you to specify what kind of Dialog should be displayed when viewed on mobile devices or smaller viewports. Note that on mobile, Popovers are not supported and will display as modals by default.
The example below renders as a Popover on desktop but switches to a Tray on mobile.
Placement
The popover’s placement with respect to its anchor element can be adjusted using the placement prop.
Dismissable
If your "modal" dialog doesn’t require the user to make a confirmation, you can set isDismissable on the DialogTrigger. In addition to the added close button, users can press the blanket to dismiss the dialog.
Offset and cross offset
The popover dialog’s offset with respect to its anchor element can be adjusted using the offset and crossOffset props. The offset prop controls the spacing applied along the main axis between the element and its anchor element whereas the crossOffset prop handles the spacing applied along the cross axis.
Below is a popover offset by an additional 50px above the trigger.
Below is a popover cross offset by an additional 100px to the right of the trigger.
Open state
DialogTrigger accepts an onOpenChange handler which is triggered whenever the dialog is opened or closed.
The example below uses onOpenChange to update a separate element with the current open state of the dialog.