Alert dialog API

Import

Cimpress UI exports four alert dialog-related components:

• DialogRoot: component that connects a trigger button with its associated dialog.
• AlertDialog: component that displays an overlay element which blocks interaction with outside elements.
• AlertDialogBody: component that contains the main content of the alert dialog.
• AlertDialogActions: component that contains the actions of the alert dialog.

import { AlertDialog, AlertDialogActions, AlertDialogBody, DialogRoot } from '@cimpress-ui/react';

Accessibility notes

While an alert dialog is open, all content outside of it is hidden from assistive technologies.

Alert dialog has no built-in way of dismissing the dialog, and it can only be closed by taking action inside of the dialog. Make sure that your dialog has at least one action, and that the action will cause the dialog to close. See the Closing programmatically section for more information.

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

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

Triggering an alert dialog

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

It’s also possible to display an alert 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 alert dialog’s open state manually.

Preview

Automatic trigger

Open alert dialog

Manual trigger

Open alert dialog

Code

import { AlertDialog, AlertDialogActions, AlertDialogBody, Button, DialogRoot, 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 alert dialog</Button>
          <AlertDialog tone="info" title="Alert dialog">
            {({ close }) => (
              <>
                <AlertDialogBody>
                  This alert dialog can be opened by an automatically attached trigger button.
                </AlertDialogBody>
                <AlertDialogActions>
                  <Button variant="primary" onPress={close}>
                    I understand
                  </Button>
                </AlertDialogActions>
              </>
            )}
          </AlertDialog>
        </DialogRoot>
      </Stack>

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

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

        <AlertDialog tone="info" title="Alert dialog" isOpen={isOpen} onOpenChange={setIsOpen}>
          <AlertDialogBody>This alert dialog's open state is managed manually.</AlertDialogBody>
          <AlertDialogActions>
            <Button variant="primary" onPress={() => setIsOpen(false)}>
              I understand
            </Button>
          </AlertDialogActions>
        </AlertDialog>
      </Stack>
    </Stack>
  );
}

Copy code Open in playground

Closing programmatically

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

Preview

Open dialog

Code

import { AlertDialog, AlertDialogActions, AlertDialogBody, Button, DialogRoot } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <DialogRoot>
      <Button>Open dialog</Button>
      <AlertDialog tone="info" title="Closing example">
        {({ close }) => (
          <>
            <AlertDialogBody>Pressing the button below will close this dialog.</AlertDialogBody>
            <AlertDialogActions>
              <Button variant="primary" onPress={close}>
                Close dialog
              </Button>
            </AlertDialogActions>
          </>
        )}
      </AlertDialog>
    </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.

AlertDialog

Renders an overlay that interrupts user activity and requires a user action.

See alert dialog usage guidelines.

ref

Ref<HTMLElement>

The ref type for this component.

AlertDialogProps

title *

string

The title of the alert dialog.

children *

ReactNode | ((renderProps: AlertDialogRenderProps) => ReactNode)

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

tone *

'success' | 'info' | 'warning' | 'critical'

The tone of the alert dialog.

isOpen

boolean

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

defaultOpen

boolean

Whether the 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 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.

AlertDialogBody

Renders content within AlertDialog.

AlertDialogBodyProps

children *

ReactNode

The content to render within the alert dialog.

AlertDialogActions

Renders actions within AlertDialog.

AlertDialogActionsProps

children *

ReactNode

Actions that should be available in the alert dialog.