Modal dialog API

Import

Cimpress UI exports four modal dialog-related components:

• DialogRoot: component that connects a trigger button with its associated dialog.
• ModalDialog: component that displays an overlay element which blocks interaction with outside elements.
• ModalDialogBody: component that contains the main content of the modal dialog.
• ModalDialogActions: component that contains the actions of the modal dialog.

import { DialogRoot, ModalDialog, ModalDialogActions, ModalDialogBody } from '@cimpress-ui/react';

Accessibility notes

While a modal dialog is open, all content outside of it is hidden from assistive technologies.

By default, modal dialogs can be closed by interacting outside or by pressing the Escape key. This can be disabled by setting the isDismissible prop to false. Regardless of the isDismissible value, the modal dialog can always be closed using the close button in the modal dialog header.

If your modal dialog contains form fields, we recommend to automatically focus one of the fields when the modal dialog is opened. This can be achieved by setting the autoFocus prop on the field that you want focused.

ModalDialog requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Triggering a modal dialog

To open a modal dialog when a trigger button is pressed, wrap both the trigger button and the modal dialog component with a DialogRoot component. This will automatically associate the button with the modal dialog, without any manual setup.

It’s also possible to display a modal dialog programmatically (not as a result of a user action), or render it in a different part of the component tree than its trigger. In this case, you’ll have to manage the modal dialog’s open state manually.

Preview

Automatic trigger

Open modal dialog

Manual trigger

Open modal dialog

Code

import { Button, DialogRoot, ModalDialog, ModalDialogBody, Stack, Text } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Automatic trigger
        </Text>

        <DialogRoot>
          <Button>Open modal dialog</Button>
          <ModalDialog title="Modal dialog">
            <ModalDialogBody>
              This modal dialog can be opened by an automatically attached trigger button.
            </ModalDialogBody>
          </ModalDialog>
        </DialogRoot>
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Manual trigger
        </Text>

        <Button onPress={() => setIsOpen(true)}>Open modal dialog</Button>

        <ModalDialog title="Modal dialog" isOpen={isOpen} onOpenChange={setIsOpen}>
          <ModalDialogBody>This modal dialog's open state is managed manually.</ModalDialogBody>
        </ModalDialog>
      </Stack>
    </Stack>
  );
}

Closing programmatically

Modal dialogs can be closed programmatically by passing a function as children to the ModalDialog component, and using the close function provided as an argument to that function.

Preview

Open dialog

Code

import { Button, DialogRoot, ModalDialog, ModalDialogActions, ModalDialogBody } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <DialogRoot>
      <Button>Open dialog</Button>
      <ModalDialog title="Closing example">
        {({ close }) => (
          <>
            <ModalDialogBody>Pressing the button below will close this dialog.</ModalDialogBody>
            <ModalDialogActions>
              <Button onPress={close}>Close dialog</Button>
            </ModalDialogActions>
          </>
        )}
      </ModalDialog>
    </DialogRoot>
  );
}

API reference

DialogRoot

Encapsulates a dialog trigger and its associated dialog. The trigger can be any Cimpress UI button, and the dialog will be displayed when the trigger is activated.

DialogRootProps

children * ReactNode

The dialog trigger with its associated dialog. Provide the trigger as the first child, and the dialog as the second child.

isOpen boolean

Whether the dialog is open (controlled).

defaultOpen boolean

Whether the dialog is open by default (uncontrolled).

onOpenChange (isOpen: boolean) => void

Handler that is called when the dialog's open state changes.

ModalDialog

Displays an overlay element which blocks interaction with outside elements.

See modal dialog usage guidelines.

ref Ref<HTMLElement>

The ref type for this component.

ModalDialogProps

children * ReactNode | ((renderProps: ModalDialogRenderProps) => ReactNode)

The contents of the modal dialog. A function may be provided to access a function to close the modal dialog.

title * string

The title of the modal dialog.

size 'small' | 'medium' | 'large'

The size of the modal dialog.

Defaults to 'medium' .

isDismissible boolean

Whether to close the modal dialog when the user interacts outside of it or presses the Escape key.

Defaults to true .

isOpen boolean

Whether the modal dialog is open (controlled). If using DialogRoot, this prop has no effect - provide isOpen to DialogRoot instead.

defaultOpen boolean

Whether the modal dialog is open by default (uncontrolled). If using DialogRoot, this prop has no effect - provide defaultOpen to DialogRoot instead.

onOpenChange (isOpen: boolean) => void

Handler that is called when the modal dialog's open state changes. If using DialogRoot, this prop has no effect - provide onOpenChange to DialogRoot instead.

id string

The element's unique identifier. See MDN.

data-cim-style-root boolean

Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.

UNSAFE_className string

Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.

UNSAFE_style CSSProperties

Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.

aria-label string

Defines a string value that labels the current element.

aria-labelledby string

Identifies the element (or elements) that labels the current element.

aria-describedby string

Identifies the element (or elements) that describes the object.

aria-details string

Identifies the element (or elements) that provide a detailed, extended description for the object.

ModalDialogBody

Renders content within ModalDialog.

ModalDialogBodyProps

children * ReactNode

The content to render within the modal dialog.

ModalDialogActions

Renders actions within ModalDialog.

ModalDialogActionsProps

children * ReactNode

Actions that should be available in the modal dialog.