DialogContainer
A DialogContainer accepts a single Dialog as a child, and manages showing and hiding it in a modal. Useful in cases where there is no trigger element or when the trigger unmounts while the dialog is open.
| install | yarn add @react-spectrum/dialog |
|---|---|
| version | 3.3.8 |
| usage | import {DialogContainer, Dialog} from '@react-spectrum/dialog' |
Example#
Dialog triggered by a menu item#
DialogContainer is useful over a DialogTrigger when your have a trigger that can unmount while the dialog is open. For example, placing a DialogTrigger around a menu item would not work because the menu closes when pressing an item, thereby unmounting the DialogTrigger. When the trigger unmounts, so does the Dialog. In these cases, it is useful to place the dialog outside the tree that unmounts, so that the dialog is not also removed.
The following example shows a MenuTrigger containing a Menu with two actions: "edit" and "delete".
Each menu item opens a different dialog. This is implemented by using a DialogContainer that displays the edit dialog,
delete dialog, or no dialog depending on the current value stored in local state. Pressing a menu item triggers the menu's
onAction prop, which sets the state to the type of dialog to display, based on the menu item's key. This causes the associated
dialog to be rendered within the DialogContainer.
This example also demonstrates the use of the useDialogContainer hook, which allows the dialog to dismiss itself when a user
presses one of the buttons inside it. This triggers the DialogContainer's onDismiss event, which resets the state storing the
open dialog back to null. In addition, the user can close the dialog using the Escape key (unless the
isKeyboardDismissDisabled prop is set), or by clicking outside (if the isDismissable prop is set).
Props#
| Name | Type | Default | Description |
children | ReactNode | — | The Dialog to display, if any. |
type | 'modal'
| 'fullscreen'
| 'fullscreenTakeover' | 'modal' | The type of Dialog that should be rendered. See the visual options below for examples of each. |
isDismissable | boolean | — | Whether the Dialog is dismissable. See the Dialog docs for more details. |
isKeyboardDismissDisabled | boolean | — | Whether pressing the escape key to close the dialog should be disabled. |
Events
| Name | Type | Default | Description |
onDismiss | () => void | — | Handler that is called when the 'x' button of a dismissable Dialog is clicked. |
useDialogContainer#
The useDialogContainer hook can be used to allow a custom dialog component to access the type of container
the dialog is rendered in (e.g. modal, popover, fullscreen, etc.), and also to dismiss the dialog
programmatically. It works with both DialogContainer and DialogTrigger.
useDialogContainer(): DialogContainer
Visual options#
Full screen#
The type prop allows setting the type of modal to display. Set it to "fullscreen" to display a full screen dialog, which
only reveals a small portion of the page behind the underlay. Use this variant for more complex workflows that do not fit in
the available modal dialog sizes.
Full screen takeover#
Fullscreen takeover dialogs are similar to the fullscreen variant except that the dialog covers the entire screen.