Modal dialog usage guidelines

A modal dialog is an overlay element which blocks interaction with outside elements. It can be used to focus the user’s attention on a specific subtask.

When to use

• To display additional content or settings without navigating away from the page.
• To capture user input for a short form or interaction, like renaming a file or changing a setting.
• To display system feedback that must be acknowledged.

When not to use

• For content that can be shown inline, use a disclosure.
• If the user can continue their workflow without immediate interaction, use an alert or a toast instead.
• For long or complex workflows, use a dedicated page.

Usage

Preview

Open dialog

Press the button to make the modal dialog appear.

Code

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

export default function Demo() {
  return (
    <Stack gap={16}>
      <DialogRoot>
        <Button>Open dialog</Button>
        <ModalDialog title="Modal dialog">
          <ModalDialogBody>
            Modal dialogs can be used to focus the user's attention on a specific subtask.
          </ModalDialogBody>
        </ModalDialog>
      </DialogRoot>

      <Text as="p" variant="medium">
        Press the button to make the modal dialog appear.
      </Text>
    </Stack>
  );
}

Properties

Size

Preview

SmallMediumLarge

Press the buttons to make the modal dialogs appear.

Code

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

export default function Demo() {
  return (
    <Stack gap={16}>
      <Stack gap={16} direction="horizontal" wrap>
        <DialogRoot>
          <Button>Small</Button>
          <ModalDialog title="Small modal dialog" size="small">
            <ModalDialogBody>This is a small modal dialog.</ModalDialogBody>
          </ModalDialog>
        </DialogRoot>

        <DialogRoot>
          <Button>Medium</Button>
          <ModalDialog title="Medium modal dialog" size="medium">
            <ModalDialogBody>This is a medium modal dialog.</ModalDialogBody>
          </ModalDialog>
        </DialogRoot>

        <DialogRoot>
          <Button>Large</Button>
          <ModalDialog title="Large modal dialog" size="large">
            <ModalDialogBody>This is a large modal dialog.</ModalDialogBody>
          </ModalDialog>
        </DialogRoot>
      </Stack>

      <Text as="p" variant="medium">
        Press the buttons to make the modal dialogs appear.
      </Text>
    </Stack>
  );
}

Value	Use cases
Small	For short information or quick inputs (1-2 lines of text).
Medium	Standard dialog for most actions, including forms and decisions.
Large	When more content is needed, like previews, detailed forms, or multiple fields.

Formatting and layout

Placement

Modal dialogs are centered on the screen, and placed on top of a darkened overlay to call the user’s attention to the dialog.

Content

Modal dialogs can contain any other components. Design best practices should continue to be followed within a modal dialog.

Actions

Modal dialogs can contain actions for the user to take. These actions are displayed at the bottom of the modal dialog. The example below shows a modal dialog with actions:

Preview

Open dialog

Press the button to make the modal dialog appear.

Code

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

export default function Demo() {
  return (
    <Stack gap={16}>
      <DialogRoot>
        <Button>Open dialog</Button>
        <ModalDialog title="Dialog with actions">
          {({ close }) => (
            <>
              <ModalDialogBody>This dialog contains actions.</ModalDialogBody>
              <ModalDialogActions>
                <Button onPress={close}>Cancel</Button>
                <Button variant="primary" onPress={close}>
                  Save
                </Button>
              </ModalDialogActions>
            </>
          )}
        </ModalDialog>
      </DialogRoot>

      <Text as="p" variant="medium">
        Press the button to make the modal dialog appear.
      </Text>
    </Stack>
  );
}

Content writing

• Use clear, concise, and distinct titles that make it obvious what the modal dialog contains.
• Use clear labels for action buttons and links.
• If the content gets unreasonably long or space becomes an issue, consider using a different solution.

Behaviors

Dismissing modal dialogs

Users can close the modal dialog via the close button in the top right, clicking outside, or pressing the Escape key.