# AlertDialog

Asks you to confirm a critical action before it happens.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/AlertDialog.tsx)

## Overview

A modal confirmation that blocks the page until the user decides. It never closes on an outside press. It takes the parts and the `small` size of a [Dialog](/docs/components/dialog). Reserve it for decisions that need an explicit answer.

## Examples

### Basic

```tsx
import { AlertDialog, Button, ButtonGroup } from '@tempoxyz/ds'

export function Demo() {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger render={<Button />}>Delete key</AlertDialog.Trigger>
      <AlertDialog.Popup>
        <AlertDialog.Header>
          <AlertDialog.Title>Delete this key?</AlertDialog.Title>
          <AlertDialog.Description>
            Apps that use this key stop working immediately. You cannot undo this.
          </AlertDialog.Description>
        </AlertDialog.Header>
        <ButtonGroup>
          <AlertDialog.Close render={<Button size="large" variant="secondary" />}>
            Cancel
          </AlertDialog.Close>
          <AlertDialog.Close render={<Button size="large" variant="danger" />}>
            Delete key
          </AlertDialog.Close>
        </ButtonGroup>
      </AlertDialog.Popup>
    </AlertDialog.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/AlertDialog/Basic.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { AlertDialog, ButtonGroup } from '@tempoxyz/ds'

<AlertDialog.Root>
  <AlertDialog.Trigger />
  <AlertDialog.Popup>
    <AlertDialog.Header>
      <AlertDialog.Title />
      <AlertDialog.Description />
    </AlertDialog.Header>
    <AlertDialog.Body />
    <ButtonGroup>
      <AlertDialog.Close />
    </ButtonGroup>
  </AlertDialog.Popup>
</AlertDialog.Root>
```

## Guidelines

### When to Use

* Confirm an action you can't undo, such as Revoke key, Delete webhook, or Remove passkey.
* Ask before discarding unsaved work, such as Discard changes? on a settings page with edits.

### When Not to Use

* Use a [Dialog](/docs/components/dialog) for a task with fields, or to review a payment before sending it.
* For reversible actions, such as archiving an address, act at once and offer Undo in a [Toast](/docs/components/toast). The toast dismisses itself, so keep another way to restore the item.
* Use an [Alert](/docs/components/alert) or [Banner](/docs/components/banner) for a warning that needs no decision.
* Use a [Toast](/docs/components/toast) to report that an action finished.

### Focus the Safe Action

Opening focuses the first tabbable element in the popup. Place Cancel first in the DOM, or pass its ref to `initialFocus` on `AlertDialog.Popup`, so an Enter press right after opening cancels.

**Do:** Start focus on Cancel.

```tsx
/** Do example for "Focus the Safe Action" on the AlertDialog page: start focus on Cancel. @module */
import { Button, style } from '@tempoxyz/ds'
import { Focus } from '../../../components/mdx/Access.js'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Delete this webhook?</span>
      <p {...styles.description()}>
        Payment events stop reaching api.acme.com/hooks. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Focus>
          <Button size="small" variant="secondary">
            Cancel
          </Button>
        </Focus>
        <Button size="small">Delete webhook</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Start focus on the destructive action, where one Enter press confirms it.

```tsx
/**
 * Don't example for "Focus the Safe Action" on the AlertDialog page.
 * Don't start focus on the destructive action, where one Enter press confirms it.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { Focus } from '../../../components/mdx/Access.js'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Delete this webhook?</span>
      <p {...styles.description()}>
        Payment events stop reaching api.acme.com/hooks. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Focus>
          <Button size="small">Delete webhook</Button>
        </Focus>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

### Always Offer Cancel

Only Escape, `closeButton` and `AlertDialog.Close` close the dialog, so render a Cancel button with `AlertDialog.Close`.

**Do:** Pair the confirm button with Cancel.

```tsx
/** Do example for "Always Offer Cancel" on the AlertDialog page: pair the confirm button with Cancel. @module */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Revoke this API key?</span>
      <p {...styles.description()}>
        Apps that use the Production server key stop working immediately. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">Revoke key</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Render the confirm button alone. An outside press doesn't close the dialog.

```tsx
/**
 * Don't example for "Always Offer Cancel" on the AlertDialog page.
 * Don't render the confirm button alone. An outside press doesn't close the dialog.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Revoke this API key?</span>
      <p {...styles.description()}>
        Apps that use the Production server key stop working immediately. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Button size="small">Revoke key</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

### Show Progress on the Confirm Button

If the action waits on the network, such as revoking a key:

1. Render the confirm button without `AlertDialog.Close`, and control `open` on `AlertDialog.Root`.
2. Set `loading` while the request runs.
3. Close the dialog on success. Show any error inside the dialog.

**Do:** Set `loading` on the confirm button and keep the dialog open.

```tsx
/**
 * Do example for "Show Progress on the Confirm Button" on the AlertDialog page.
 * Set `loading` on the confirm button and keep the dialog open.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Revoke this API key?</span>
      <p {...styles.description()}>
        Apps that use the Production server key stop working immediately. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small" loading>
          Revoke key
        </Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Add a separate spinner and leave the buttons active.

```tsx
/**
 * Don't example for "Show Progress on the Confirm Button" on the AlertDialog page.
 * Don't add a separate spinner and leave the buttons active.
 * @module
 */
import { Button, Spinner, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Revoke this API key?</span>
      <p {...styles.description()}>
        Apps that use the Production server key stop working immediately. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Spinner aria-label="Revoking key" />
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">Revoke key</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

## Content

### Ask a Specific Question

Write the title as one question that names the action and its object, such as Revoke this API key?

### State the Consequence

Always include an `AlertDialog.Description`. Say what stops working, then whether it can be recovered, without repeating the title.

### Repeat the Action Verb on the Confirm Button

Label the confirm button with the verb from the trigger and title, such as Revoke key after Revoke this API key?

**Do:** Repeat the action's verb on the confirm button, such as Revoke key.

```tsx
/** Do example for "Always Offer Cancel" on the AlertDialog page: pair the confirm button with Cancel. @module */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Revoke this API key?</span>
      <p {...styles.description()}>
        Apps that use the Production server key stop working immediately. You can’t undo this.
      </p>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">Revoke key</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

**Don't:** Ask Are you sure? or label the confirm button OK.

```tsx
/**
 * Don't example for "Repeat the Action Verb on the Confirm Button" on the AlertDialog page.
 * Don't ask Are you sure? or label the confirm button OK.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Are you sure?</span>
      <p {...styles.description()}>This action cannot be undone.</p>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">OK</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '16',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '24',
    rowGap: '8',
    width: '17rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'heading.h3' })
}
```

### Avoid Two Cancels

If the action cancels something, such as a scheduled payment, label the pair Keep payment and Cancel payment. A plain Cancel beside Cancel payment is ambiguous.

## Accessibility

Follows the [WAI-ARIA alert dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/).

### Semantics

* **AlertDialog.Trigger (button):** Announces the dialog and whether it is open.
* **AlertDialog.Popup (alertdialog):** The dialog is always modal.
* **AlertDialog.Title (h2):** Names the popup. Include it in every alert dialog.
* **AlertDialog.Description (aria-describedby):** Describes the popup. Include it in every alert dialog.
* **Page Behind (inert):** The page behind ignores input and stops scrolling.
* **Reduced Motion (prefers-reduced-motion):** The dialog fades in and out without scaling or sliding.

### Keyboard

* **Open or Activate (Enter or Space):** Opens the dialog from the trigger, and activates the focused action.
* **Move to the Next Action (Tab):** Moves focus to the next action, wrapping from the last to the first.
* **Move to the Previous Action (Shift+Tab):** Moves focus to the previous action, wrapping from the first to the last.
* **Close the Alert Dialog (Escape):** Closes the dialog and returns focus to the trigger that opened it.

### Focus

* **Opening:** Focuses the first tabbable element, or the popup on touch. Pass `initialFocus` to start on Cancel.
* **Trapping:** Focus stays inside the popup while it is open, and Tab never leaves it.
* **Outside Press:** Does not close the popup. Only Escape, `closeButton` or `AlertDialog.Close` closes it.
* **Closing:** Focus returns to the trigger. Pass `finalFocus` when the trigger is gone, such as after deleting its row.

### Your Responsibilities

* **Render a Title and Description:** Always render both in `AlertDialog.Header`. Without them, the popup has no name or description.

## Related

[Dialog](/docs/components/dialog)

Use for focused tasks with fields.

[Button](/docs/components/button)

Use for each action in the footer.

[ButtonGroup](/docs/components/button-group)

Use for the Cancel and confirm actions.

[Menu](/docs/components/menu)

Use for opening a confirmation from a destructive item.

[Toast](/docs/components/toast)

Use for Undo after reversible actions.

[Destructive Actions](/docs/patterns/destructive-actions)

Covers deleting and revoking.
