# Alert dialog (/cloud/primitives/alert-dialog)



```ts title="Import"
import {
  AlertDialog,
  AlertDialogClose,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@nyte-ai/ui";
```

Implemented in `packages/ui/src/components/ui/alert-dialog.tsx`, wrapping
[`@nyte-ai/ui/alert-dialog`](/cloud/headless/alert-dialog). It reuses `dialogStyles` from
Dialog, so the two look identical; the difference is behavior.

## Usage [#usage]

* Use for a decision the user cannot back out of by clicking away: delete, discard, overwrite,
  revoke.
* The footer **must** offer an explicit way out (a Cancel `AlertDialogClose`). There is no ✕ and
  outside press does nothing.
* Title states the question; description states the consequence. Both are required.
* The destructive action is the last button and uses `variant="destructive"`.

## Anatomy [#anatomy]

```tsx
<AlertDialog>
  <AlertDialogTrigger />
  <AlertDialogContent>
    {/* Portal › Backdrop › Popup */}
    <AlertDialogTitle />
    <AlertDialogDescription />
    <AlertDialogFooter>
      <AlertDialogClose /> {/* cancel */}
      <AlertDialogClose /> {/* confirm */}
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

`AlertDialog`, `AlertDialogTrigger`, and `AlertDialogClose` are the Base UI parts re-exported
without styling.

## Example [#example]

<Preview>
  <AlertDialogDemo />
</Preview>

```tsx
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="destructive" />}>Delete session</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogTitle>Delete this session?</AlertDialogTitle>
    <AlertDialogDescription>
      The history tree and every head under it are removed. This cannot be undone.
    </AlertDialogDescription>
    <AlertDialogFooter>
      <AlertDialogClose render={<Button variant="ghost" />}>Cancel</AlertDialogClose>
      <AlertDialogClose render={<Button variant="destructive" />}>Delete</AlertDialogClose>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## Props [#props]

### AlertDialog (Root) [#alertdialog-root]

Groups all parts of the alert dialog.
Doesn't render its own HTML element.

**Root Props:**

| Prop                 | Type                                                                           | Default | Description                                                                                                                                                                                                                                                      |
| :------------------- | :----------------------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultOpen          | `boolean`                                                                      | `false` | Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.                                                                                                                                                                |
| open                 | `boolean`                                                                      | -       | Whether the dialog is currently open.                                                                                                                                                                                                                            |
| onOpenChange         | `((open: boolean, eventDetails: AlertDialog.Root.ChangeEventDetails) => void)` | -       | Event handler called when the alert dialog is opened or closed.                                                                                                                                                                                                  |
| actionsRef           | `React.RefObject<AlertDialog.Root.Actions \| null>`                            | -       | A ref to imperative actions. `unmount`: Manually unmounts the alert dialog.&#xA;Call this after any externally controlled closing animation finishes.`close`: Closes the alert dialog imperatively when called.                                                  |
| defaultTriggerId     | `string \| null`                                                               | -       | ID of the trigger that the dialog is associated with.&#xA;This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.                                                                                                          |
| handle               | `AlertDialog.Handle<Payload>`                                                  | -       | A handle to associate the alert dialog with a trigger.&#xA;If specified, allows external triggers to control the alert dialog's open state.&#xA;Can be created with the AlertDialog.createHandle() method.                                                       |
| onOpenChangeComplete | `((open: boolean) => void)`                                                    | -       | Event handler called after any animations complete when the dialog is opened or closed.                                                                                                                                                                          |
| triggerId            | `string \| null`                                                               | -       | ID of the trigger that the dialog is associated with.&#xA;This is useful in conjunction with the `open` prop to create a controlled dialog.&#xA;There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set). |
| children             | `React.ReactNode \| PayloadChildRenderFunction<Payload>`                       | -       | The content of the dialog.&#xA;This can be a regular React node or a render function that receives the `payload` of the active trigger.                                                                                                                          |

### AlertDialogContent [#alertdialogcontent]

`StyledProps<AlertDialog.Popup.Props>`. Channels apply to the Popup.

A container for the dialog contents.
Renders a `<div>` element.

**Popup Props:**

| Prop         | Type                                                                                                                          | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| :----------- | :---------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| initialFocus | `boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)`  | -       | Determines the element to focus when the dialog is opened.&#xA;By default, focus moves to the first tabbable element inside the popup, except when the dialog&#xA;is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. `false`: Do not move focus.`true`: Move focus based on the default behavior (first tabbable element or popup).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).&#xA;Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing. |
| finalFocus   | `boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` | -       | Determines the element to focus when the dialog is closed. `false`: Do not move focus.`true`: Move focus based on the default behavior (trigger or previously focused element).`RefObject`: Move focus to the ref element.`function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).&#xA;Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.                                                                                                                                                                                               |
| className    | `string \| ((state: AlertDialog.Popup.State) => string \| undefined)`                                                         | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| style        | `React.CSSProperties \| ((state: AlertDialog.Popup.State) => React.CSSProperties \| undefined)`                               | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| render       | `ReactElement \| ((props: HTMLProps, state: AlertDialog.Popup.State) => ReactElement)`                                        | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**Popup Data Attributes:**

| Attribute               | Type | Description                                                      |
| :---------------------- | :--- | :--------------------------------------------------------------- |
| data-open               | -    | Present when the dialog is open.                                 |
| data-closed             | -    | Present when the dialog is closed.                               |
| data-nested             | -    | Present when the dialog is nested within another dialog.         |
| data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
| data-starting-style     | -    | Present when the dialog begins animating in.                     |
| data-ending-style       | -    | Present when the dialog is animating out.                        |

**Popup CSS Variables:**

| Variable           | Type     | Description                                   |
| :----------------- | :------- | :-------------------------------------------- |
| `--nested-dialogs` | `number` | Indicates how many dialogs are nested within. |

### AlertDialogTitle, AlertDialogDescription, AlertDialogFooter [#alertdialogtitle-alertdialogdescription-alertdialogfooter]

`StyledProps` of the matching Base UI part; Footer is a `<div>`. Styles are Dialog's.

### AlertDialogTrigger, AlertDialogClose [#alertdialogtrigger-alertdialogclose]

A button that opens the alert dialog.
Renders a `<button>` element.

**Trigger Props:**

| Prop         | Type                                                                                              | Default | Description                                                                                                                                                                                            |
| :----------- | :------------------------------------------------------------------------------------------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| handle       | `AlertDialog.Handle<Payload>`                                                                     | -       | A handle to associate the trigger with an alert dialog.&#xA;Can be created with the AlertDialog.createHandle() method.                                                                                 |
| nativeButton | `boolean`                                                                                         | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).              |
| payload      | `Payload`                                                                                         | -       | A payload to pass to the dialog when it is opened.                                                                                                                                                     |
| id           | `string`                                                                                          | -       | ID of the trigger. In addition to being forwarded to the rendered element,&#xA;it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop). |
| className    | `string \| ((state: AlertDialog.Trigger.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                               |
| style        | `React.CSSProperties \| ((state: AlertDialog.Trigger.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                            |
| render       | `ReactElement \| ((props: HTMLProps, state: AlertDialog.Trigger.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.          |

**Trigger Data Attributes:**

| Attribute       | Type | Description                                          |
| :-------------- | :--- | :--------------------------------------------------- |
| data-popup-open | -    | Present when the corresponding alert dialog is open. |
| data-disabled   | -    | Present when the trigger is disabled.                |

A button that closes the dialog.
Renders a `<button>` element.

**Close Props:**

| Prop         | Type                                                                                            | Default | Description                                                                                                                                                                                   |
| :----------- | :---------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nativeButton | `boolean`                                                                                       | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).     |
| className    | `string \| ((state: AlertDialog.Close.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
| style        | `React.CSSProperties \| ((state: AlertDialog.Close.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
| render       | `ReactElement \| ((props: HTMLProps, state: AlertDialog.Close.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

**Close Data Attributes:**

| Attribute     | Type | Description                          |
| :------------ | :--- | :----------------------------------- |
| data-disabled | -    | Present when the button is disabled. |

## Accessibility [#accessibility]

* `role="alertdialog"`, `aria-modal="true"`, labelled by the title and described by the
  description.
* Outside press does not close. Escape closes by default in Base UI; pass an `onOpenChange` that
  ignores the `escape-key` reason if the surface must not be escapable.
* Focus moves into the popup on open and returns to the trigger on close.

## Styling [#styling]

Same tokens as [Dialog](/cloud/primitives/dialog#styling).