DialogTrigger

DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the Dialog's open state with the trigger's press state. Additionally, it allows you to customize the type and positioning of the Dialog.

install	`yarn add @react-spectrum/dialog`
version	3.3.8
usage	`import {DialogTrigger, Dialog} from '@react-spectrum/dialog'`

View repository

GitHub

View package

NPM

Example#

Content#

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 DialogTrigger's close function to the Dialog's children. Dialogs that do not contain such interactive elements can simply provide the Dialog component as is to the DialogTrigger as its second child.

The example below demonstrates how to pass the DialogTrigger's close function to the Dialog's buttons.

Dialog types#

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 Dialogs create an underlay that blocks access to the underlying user interface until the Dialog is closed. Sizing options can be found on the Dialog page. Focus is trapped inside the Modal as per the accessibility guidelines laid out by W3C.

If a Dialog without an underlay is needed, consider using a Popover 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 option for more information.

Tray#

Tray Dialogs are typically used to portray information on mobile devices or smaller screens.

Fullscreen#

Fullscreen Dialogs are a fullscreen variant of the Modal Dialog, only revealing 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. This variant does not support isDismissible.

Fullscreen takeover#

Fullscreen takeover Dialogs are similar to the fullscreen variant except that the Dialog covers the entire screen.

Dismissable#

If your Modal Dialog doesn't require the user to make a confirmation, you can set isDismissable on the DialogTrigger. This adds a close button that the user can press to dismiss the Dialog.

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.

Dialog placement#

Popover Dialogs support a variety of placement options since they do not take over the user interface like Modal or Tray Dialogs.

Dialog anchor#

By default, popovers anchor themselves to their associated trigger. This can be overridden by providing a separate ref to the targetRef prop.

Placement#

The popover's placement with respect to its anchor element can be adjusted using the placement prop. See the props table below for a full list of available placement combinations.

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.

Flipping#

By default, DialogTrigger attempts to flip popovers on the main axis in situations where the original placement would cause it to render out of view. This can be overridden by setting shouldFlip={false}. To see the difference between the two options, scroll this page so that the example below is near the bottom of the window.

Container padding#

You can control the minimum padding required between the Popover Dialog and the surrounding container via the containerPadding prop. This affects the positioning breakpoints that determine when the Dialog will attempt to flip.

The example below will flip the Dialog from above the trigger button to below the trigger button if the Dialog cannot render fully while maintaining 50px of padding between itself and the top of the browser.

Events#

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.

Props#

Name	Type	Default	Description
`children`	`[ ReactElement, SpectrumDialogClose \| ReactElement ]`	—	The Dialog and its trigger element. See the DialogTrigger Content section for more information on what to provide as children.
`type`	`'modal' \| 'popover' \| 'tray' \| 'fullscreen' \| 'fullscreenTakeover'`	`'modal'`	The type of Dialog that should be rendered. See the DialogTrigger types section for an explanation on each.
`mobileType`	`'modal' \| 'tray' \| 'fullscreen' \| 'fullscreenTakeover'`	—	The type of Dialog that should be rendered when on a mobile device. See DialogTrigger types section for an explanation on each.
`hideArrow`	`boolean`	—	Whether a popover type Dialog's arrow should be hidden.
`targetRef`	`RefObject<HTMLElement>`	—	The ref of the element the Dialog should visually attach itself to. Defaults to the trigger button if not defined.
`isDismissable`	`boolean`	—	Whether a modal type Dialog should be dismissable.
`isKeyboardDismissDisabled`	`boolean`	—	Whether pressing the escape key to close the dialog should be disabled.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`placement`	`Placement`	`'bottom'`	The placement of the element with respect to its anchor element.
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

Events

Name	Type	Default	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.