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. If you do this, you must provide a way for the user to close the modal dialog.

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>
  );
}

Copy code Open in playground

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>
  );
}

Copy code Open in playground

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 the modal dialog can be closed by clicking the close button, clicking outside of the modal dialog, or pressing the Escape key. When false, the modal dialog can only be closed programmatically.

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.