AlertDialog

AlertDialogs are a specific type of Dialog. They display important information that users need to acknowledge.

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

View guidelines

Spectrum

Example#

<DialogTrigger>
  <ActionButton>Save</ActionButton>
  <AlertDialog
    title="Low Disk Space"
    variant="warning"
    primaryActionLabel="Confirm">
    You are running low on disk space.
    Delete unnecessary files to free up space.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Save</ActionButton>
  <AlertDialog
    title="Low Disk Space"
    variant="warning"
    primaryActionLabel="Confirm">
    You are running low on disk space.
    Delete unnecessary files to free up space.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Save
  </ActionButton>
  <AlertDialog
    title="Low Disk Space"
    variant="warning"
    primaryActionLabel="Confirm"
  >
    You are running low
    on disk space.
    Delete unnecessary
    files to free up
    space.
  </AlertDialog>
</DialogTrigger>

Content#

Unlike Dialog, the layout in AlertDialog is very deliberate. The body of an AlertDialog can be provided by passing children to the component. The AlertDialog also supports having up to three buttons in its footer: a primary button, a secondary button, and a cancel button. Each button can be rendered by providing a string to the primaryActionLabel, secondaryActionLabel, and cancelLabel respectively. Be sure to localize any strings provided to the AlertDialog and to the button labels as well. AlertDialogs do not support a Fullscreen mode.

AlertDialogs should always have a visible title, specified by passing a string as the title prop. This string should be localized so that it is properly internationalized.

<DialogTrigger>
  <ActionButton>Exit</ActionButton>
  <AlertDialog
    variant="information"
    title="Register profile"
    primaryActionLabel="Register"
    secondaryActionLabel="Remind me later"
    cancelLabel="Cancel">
    You have not saved your profile information
    for this account. Would you like to register now?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Exit</ActionButton>
  <AlertDialog
    variant="information"
    title="Register profile"
    primaryActionLabel="Register"
    secondaryActionLabel="Remind me later"
    cancelLabel="Cancel">
    You have not saved your profile information
    for this account. Would you like to register now?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Exit
  </ActionButton>
  <AlertDialog
    variant="information"
    title="Register profile"
    primaryActionLabel="Register"
    secondaryActionLabel="Remind me later"
    cancelLabel="Cancel"
  >
    You have not saved
    your profile
    information for
    this account. Would
    you like to
    register now?
  </AlertDialog>
</DialogTrigger>

Accessibility#

If any of the buttons in the AlertDialog's footer should be focused when it opens, specify which one via the autoFocusButton prop.

<DialogTrigger>
  <ActionButton>Save</ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Save file"
    primaryActionLabel="Save"
    cancelLabel="Cancel"
    autoFocusButton="primary">
    A file with the same name already exists. Overwrite?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Save</ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Save file"
    primaryActionLabel="Save"
    cancelLabel="Cancel"
    autoFocusButton="primary">
    A file with the same name already exists. Overwrite?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Save
  </ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Save file"
    primaryActionLabel="Save"
    cancelLabel="Cancel"
    autoFocusButton="primary"
  >
    A file with the
    same name already
    exists. Overwrite?
  </AlertDialog>
</DialogTrigger>

Events#

AlertDialog accepts an onPrimaryAction, onSecondaryAction and onCancel prop, triggered when the AlertDialog's confirm or cancel buttons are pressed respectively.

The example below uses onPrimaryAction, onSecondaryAction and onCancel to tell the user which button was pressed to close the AlertDialog.

function Example() {
  let onPrimaryAction = () => alert('Primary button pressed.');
  let onSecondaryAction = () => alert('Secondary button pressed.');
  let alertCancel = () => alert('Cancel button pressed.');

  return (
    <DialogTrigger>
      <ActionButton>
        Publish
      </ActionButton>
      <AlertDialog
        variant="confirmation"
        title="Confirm Publish"
        primaryActionLabel="Publish"
        secondaryActionLabel="Save as draft"
        cancelLabel="Cancel"
        onCancel={alertCancel}
        onPrimaryAction={onPrimaryAction}
        onSecondaryAction={onSecondaryAction}>
        Are you sure you want to publish this document?
      </AlertDialog>
    </DialogTrigger>
  );
}

function Example() {
  let onPrimaryAction = () =>
    alert('Primary button pressed.');
  let onSecondaryAction = () =>
    alert('Secondary button pressed.');
  let alertCancel = () => alert('Cancel button pressed.');

  return (
    <DialogTrigger>
      <ActionButton>
        Publish
      </ActionButton>
      <AlertDialog
        variant="confirmation"
        title="Confirm Publish"
        primaryActionLabel="Publish"
        secondaryActionLabel="Save as draft"
        cancelLabel="Cancel"
        onCancel={alertCancel}
        onPrimaryAction={onPrimaryAction}
        onSecondaryAction={onSecondaryAction}
      >
        Are you sure you want to publish this document?
      </AlertDialog>
    </DialogTrigger>
  );
}

function Example() {
  let onPrimaryAction =
    () =>
      alert(
        'Primary button pressed.'
      );
  let onSecondaryAction =
    () =>
      alert(
        'Secondary button pressed.'
      );
  let alertCancel = () =>
    alert(
      'Cancel button pressed.'
    );

  return (
    <DialogTrigger>
      <ActionButton>
        Publish
      </ActionButton>
      <AlertDialog
        variant="confirmation"
        title="Confirm Publish"
        primaryActionLabel="Publish"
        secondaryActionLabel="Save as draft"
        cancelLabel="Cancel"
        onCancel={alertCancel}
        onPrimaryAction={onPrimaryAction}
        onSecondaryAction={onSecondaryAction}
      >
        Are you sure you
        want to publish
        this document?
      </AlertDialog>
    </DialogTrigger>
  );
}

Props#

Name	Type	Default	Description
`title`	`string`	—	The title of the AlertDialog.
`children`	`ReactNode`	—	The contents of the AlertDialog.
`primaryActionLabel`	`string`	—	The label to display within the confirm button.
`variant`	`'confirmation' \| 'information' \| 'destructive' \| 'error' \| 'warning'`	—	The visual style of the AlertDialog.
`cancelLabel`	`string`	—	The label to display within the cancel button.
`secondaryActionLabel`	`string`	—	The label to display within the secondary button.
`isPrimaryActionDisabled`	`boolean`	—	Whether the primary button is disabled.
`isSecondaryActionDisabled`	`boolean`	—	Whether the secondary button is disabled.
`autoFocusButton`	`'cancel' \| 'primary' \| 'secondary'`	—	Button to focus by default when the dialog opens.

Events

Name	Type	Default	Description
`onCancel`	`() => void`	—	Handler that is called when the cancel button is pressed.
`onPrimaryAction`	`() => void`	—	Handler that is called when the primary button is pressed.
`onSecondaryAction`	`() => void`	—	Handler that is called when the secondary button is pressed.

Layout

Name	Type	Default	Description
`flex`	`Responsive<string \| number \| boolean>`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'>`	—	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'>`	—	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`Responsive<number>`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`Responsive<DimensionValue>`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`Responsive<DimensionValue>`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`Responsive<DimensionValue>`	—	The width of the element. See MDN.
`minWidth`	`Responsive<DimensionValue>`	—	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	—	The maximum width of the element. See MDN.
`height`	`Responsive<DimensionValue>`	—	The height of the element. See MDN.
`minHeight`	`Responsive<DimensionValue>`	—	The minimum height of the element. See MDN.
`maxHeight`	`Responsive<DimensionValue>`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`Responsive<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	—	Specifies how the element is positioned. See MDN.
`top`	`Responsive<DimensionValue>`	—	The top position for the element. See MDN.
`bottom`	`Responsive<DimensionValue>`	—	The bottom position for the element. See MDN.
`left`	`Responsive<DimensionValue>`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`Responsive<DimensionValue>`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`Responsive<DimensionValue>`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`Responsive<DimensionValue>`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`Responsive<number>`	—	The stacking order for the element. See MDN.
`isHidden`	`Responsive<boolean>`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Variant#

View guidelines

Confirmation

<DialogTrigger>
  <ActionButton>Exit</ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Exit instance?"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel">
    Exit dungeon instance and return to main hub?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Exit</ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Exit instance?"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel">
    Exit dungeon instance and return to main hub?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Exit
  </ActionButton>
  <AlertDialog
    variant="confirmation"
    title="Exit instance?"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel"
  >
    Exit dungeon
    instance and return
    to main hub?
  </AlertDialog>
</DialogTrigger>

Information

<DialogTrigger>
  <ActionButton>New file</ActionButton>
  <AlertDialog
    variant="information"
    title="Connect your account"
    primaryActionLabel="Continue"
    cancelLabel="Cancel">
    Please connect an existing account to sync any new files.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>New file</ActionButton>
  <AlertDialog
    variant="information"
    title="Connect your account"
    primaryActionLabel="Continue"
    cancelLabel="Cancel"
  >
    Please connect an existing account to sync any new
    files.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    New file
  </ActionButton>
  <AlertDialog
    variant="information"
    title="Connect your account"
    primaryActionLabel="Continue"
    cancelLabel="Cancel"
  >
    Please connect an
    existing account to
    sync any new files.
  </AlertDialog>
</DialogTrigger>

Destructive

<DialogTrigger>
  <ActionButton>Delete</ActionButton>
  <AlertDialog
    variant="destructive"
    title="Delete file"
    primaryActionLabel="Delete"
    cancelLabel="Cancel">
    This will permanently delete the selected file. Continue?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Delete</ActionButton>
  <AlertDialog
    variant="destructive"
    title="Delete file"
    primaryActionLabel="Delete"
    cancelLabel="Cancel"
  >
    This will permanently delete the selected file.
    Continue?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Delete
  </ActionButton>
  <AlertDialog
    variant="destructive"
    title="Delete file"
    primaryActionLabel="Delete"
    cancelLabel="Cancel"
  >
    This will
    permanently delete
    the selected file.
    Continue?
  </AlertDialog>
</DialogTrigger>

Error

<DialogTrigger>
  <ActionButton>Login</ActionButton>
  <AlertDialog
    variant="error"
    title="Unable to connect"
    primaryActionLabel="Retry"
    cancelLabel="Cancel">
    Something went wrong while connecting to the server.
    Please try again in a couple minutes.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Login</ActionButton>
  <AlertDialog
    variant="error"
    title="Unable to connect"
    primaryActionLabel="Retry"
    cancelLabel="Cancel">
    Something went wrong while connecting to the server.
    Please try again in a couple minutes.
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Login
  </ActionButton>
  <AlertDialog
    variant="error"
    title="Unable to connect"
    primaryActionLabel="Retry"
    cancelLabel="Cancel"
  >
    Something went
    wrong while
    connecting to the
    server. Please try
    again in a couple
    minutes.
  </AlertDialog>
</DialogTrigger>

Warning

<DialogTrigger>
  <ActionButton>Enter</ActionButton>
  <AlertDialog
    variant="warning"
    title="Raid instance"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel">
    The following encounter meant for parties of 4 or more. Enter anyways?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Enter</ActionButton>
  <AlertDialog
    variant="warning"
    title="Raid instance"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel"
  >
    The following encounter meant for parties of 4 or
    more. Enter anyways?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Enter
  </ActionButton>
  <AlertDialog
    variant="warning"
    title="Raid instance"
    primaryActionLabel="Confirm"
    cancelLabel="Cancel"
  >
    The following
    encounter meant for
    parties of 4 or
    more. Enter
    anyways?
  </AlertDialog>
</DialogTrigger>

Primary action disabled#

Disables the primary button.

<DialogTrigger>
  <ActionButton>Upgrade</ActionButton>
  <AlertDialog
    isPrimaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    cancelLabel="Cancel">
    Upgrade subscription for an additional $14.99 a month?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Upgrade</ActionButton>
  <AlertDialog
    isPrimaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    cancelLabel="Cancel">
    Upgrade subscription for an additional $14.99 a month?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Upgrade
  </ActionButton>
  <AlertDialog
    isPrimaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    cancelLabel="Cancel"
  >
    Upgrade
    subscription for an
    additional $14.99 a
    month?
  </AlertDialog>
</DialogTrigger>

Secondary action disabled#

Disables the secondary button.

<DialogTrigger>
  <ActionButton>Upgrade</ActionButton>
  <AlertDialog
    isSecondaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    secondaryActionLabel="Apply Coupon"
    cancelLabel="Cancel">
    Upgrade subscription for an additional $14.99 a month?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>Upgrade</ActionButton>
  <AlertDialog
    isSecondaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    secondaryActionLabel="Apply Coupon"
    cancelLabel="Cancel">
    Upgrade subscription for an additional $14.99 a month?
  </AlertDialog>
</DialogTrigger>

<DialogTrigger>
  <ActionButton>
    Upgrade
  </ActionButton>
  <AlertDialog
    isSecondaryActionDisabled
    variant="confirmation"
    title="Upgrade subscription"
    primaryActionLabel="Upgrade"
    secondaryActionLabel="Apply Coupon"
    cancelLabel="Cancel"
  >
    Upgrade
    subscription for an
    additional $14.99 a
    month?
  </AlertDialog>
</DialogTrigger>