---
title: "Alert dialog"
description: "A modal dialog that interrupts the user with important content and expects a response."
url: "https://susonwaiba.github.io/htmx-ui/docs/components/alert-dialog"
section: "Components"
---
# Alert dialog
A modal dialog that interrupts the user with important content and expects a response.
```html
```
## Markup
An alert dialog is a [dialog](https://susonwaiba.github.io/htmx-ui/docs/components/dialog) with `role="alertdialog"`: the same classes, the same behaviour, the same ways to open it. The role changes two things. Screen readers announce it as an alert, and a click outside doesn't close it, because the user has to answer. `Esc` still closes it, as a cancel.
- Give it a title and a description, linked with `aria-labelledby` and `aria-describedby`.
- Leave out the corner close button; the footer's buttons are the answers.
- Put `autofocus` on the least destructive button, usually Cancel, so `Enter` can't confirm by accident.
- Give each button a `data-dialog-close` value. It becomes the dialog's `returnValue`, which tells the `close` event which answer was given.
## Small
`.dialog-sm` makes it narrower, centres the text and sets the two buttons side by side at equal width.
```html
```
## Media
`.dialog-media`, first in the header, adds an icon or an image. In the default size it sits beside the title and description from the `sm` breakpoint, and above them on smaller screens.
```html
```
## Small with media
In a small alert dialog the media is centred above the title. It can hold an image as well as an icon.
```html
```
## Destructive
For an action that destroys something, make the confirming button `.btn-danger` and tint the media with `.dialog-media-danger`. Name the action on the button (“Delete chat”), not just “Continue”.
```html
```
## Confirming an htmx request
Put the request on the confirming button. `data-dialog-close` closes the dialog at once and htmx sends the request; the response goes to the button's `hx-target`.
```html
```
To act on the answer in your own script instead, listen for the dialog's `close` event and read `returnValue`:
```ts
const dialog = document.querySelector("#alert-basic")!;
dialog.addEventListener("close", () => {
if (dialog.returnValue === "continue") deleteAccount();
dialog.returnValue = ""; // reset for the next time it opens
});
```
## Macro
`dialog()` with `alert=true` writes an alert dialog: the role, no corner button, and the header with optional media.
```jinja
{% from "components/dialog/dialog.html" import dialog %}
{% call dialog("delete-project", "Delete project?", "All of its pages and files will be removed.",
alert=true, size="sm", media="trash", media_variant="danger") %}
{% endcall %}
```
## Reference
Alert dialogs use the [dialog classes](https://susonwaiba.github.io/htmx-ui/docs/components/dialog#reference). These are the parts specific to them:
| Class | Description |
| --- | --- |
| `role="alertdialog"` | On the .dialog: announced as an alert, and a click outside doesn't close it. |
| `.dialog-sm` | Narrow, centred text, buttons side by side at equal width. |
| `.dialog-media` | Icon or image first in the header: beside the title in the default size from sm, centred above it in .dialog-sm. |
| `.dialog-media-danger` | Danger-tinted media, for destructive actions. |
| `[data-dialog-close="value"]` | An answer button: closes the dialog and sets returnValue. |