Modal dialog for critical confirmations requiring user attention and explicit action
Usage
Anatomy
import {AlertDialog, Button} from "@heroui/react";
export default () => (
<AlertDialog>
<Button>Open Alert Dialog</Button>
<AlertDialog.Backdrop>
<AlertDialog.Container>
<AlertDialog.Dialog>
<AlertDialog.CloseTrigger /> {/* Optional: Close button */}
<AlertDialog.Header>
<AlertDialog.Icon /> {/* Optional: Status icon */}
<AlertDialog.Heading />
</AlertDialog.Header>
<AlertDialog.Body />
<AlertDialog.Footer />
</AlertDialog.Dialog>
</AlertDialog.Container>
</AlertDialog.Backdrop>
</AlertDialog>
);Examples
Statuses
Placements
Sizes
Controlled State
Custom Icon
Custom Trigger
Backdrop Variants
Custom Backdrop
Dismiss Behavior
Close Methods
Custom Animations
Custom Portal
Customization
Tailwind CSS
Global CSS
To customize the AlertDialog component classes, you can use the @layer components directive.
@layer components {
.alert-dialog__backdrop {
@apply bg-gradient-to-br from-black/60 to-black/80;
}
.alert-dialog__dialog {
@apply rounded-2xl border border-red-500/20 shadow-2xl;
}
.alert-dialog__header {
@apply gap-4;
}
.alert-dialog__icon {
@apply size-16;
}
.alert-dialog__close-trigger {
@apply rounded-full bg-white/10 hover:bg-white/20;
}
}Styling Reference
HeroUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.
CSS Classes
The AlertDialog component uses these CSS classes (View source styles):
Base Classes
.alert-dialog__trigger- Trigger element that opens the alert dialog.alert-dialog__backdrop- Overlay backdrop behind the dialog.alert-dialog__container- Positioning wrapper with placement support.alert-dialog__dialog- Dialog content container.alert-dialog__header- Header section for icon and title.alert-dialog__heading- Heading text styles.alert-dialog__body- Main content area.alert-dialog__footer- Footer section for actions.alert-dialog__icon- Icon container with status colors.alert-dialog__close-trigger- Close button element
Backdrop Variants
.alert-dialog__backdrop--opaque- Opaque colored backdrop (default).alert-dialog__backdrop--blur- Blurred backdrop with glass effect.alert-dialog__backdrop--transparent- Transparent backdrop (no overlay)
Status Variants (Icon)
.alert-dialog__icon--default- Default gray status.alert-dialog__icon--accent- Accent blue status.alert-dialog__icon--success- Success green status.alert-dialog__icon--warning- Warning orange status.alert-dialog__icon--danger- Danger red status
Interactive States
The component supports these interactive states:
- Focus:
:focus-visibleor[data-focus-visible="true"]- Applied to trigger, dialog, and close button - Hover:
:hoveror[data-hovered="true"]- Applied to close button on hover - Active:
:activeor[data-pressed="true"]- Applied to close button when pressed - Entering:
[data-entering]- Applied during dialog opening animation - Exiting:
[data-exiting]- Applied during dialog closing animation - Placement:
[data-placement="*"]- Applied based on dialog position (auto, top, center, bottom)
API Reference
AlertDialog
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Trigger and container elements |
AlertDialog.Trigger
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Custom trigger content |
className | string | - | CSS classes |
AlertDialog.Backdrop
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "opaque" | "blur" | "transparent" | "opaque" | Backdrop overlay style |
isDismissable | boolean | false | Close on backdrop click |
isKeyboardDismissDisabled | boolean | true | Disable ESC key to close |
isOpen | boolean | - | Controlled open state |
onOpenChange | (isOpen: boolean) => void | - | Open state change handler |
className | string | (values) => string | - | Backdrop CSS classes |
UNSTABLE_portalContainer | HTMLElement | - | Custom portal container |
AlertDialog.Container
| Prop | Type | Default | Description |
|---|---|---|---|
placement | "auto" | "center" | "top" | "bottom" | "auto" | Dialog position on screen |
size | "xs" | "sm" | "md" | "lg" | "cover" | "md" | Alert Dialog size variant |
className | string | (values) => string | - | Container CSS classes |
AlertDialog.Dialog
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | ({close}) => ReactNode | - | Content or render function |
className | string | - | CSS classes |
role | string | "alertdialog" | ARIA role |
aria-label | string | - | Accessibility label |
aria-labelledby | string | - | ID of label element |
aria-describedby | string | - | ID of description element |
AlertDialog.Header
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Header content (typically Icon and Heading) |
className | string | - | CSS classes |
AlertDialog.Heading
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Heading text |
className | string | - | CSS classes |
AlertDialog.Body
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Body content |
className | string | - | CSS classes |
AlertDialog.Footer
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Footer content (typically action buttons) |
className | string | - | CSS classes |
AlertDialog.Icon
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Custom icon element |
status | "default" | "accent" | "success" | "warning" | "danger" | "danger" | Status color variant |
className | string | - | CSS classes |
AlertDialog.CloseTrigger
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Custom close button |
className | string | (values) => string | - | CSS classes |
useOverlayState Hook
import {useOverlayState} from "@heroui/react";
const state = useOverlayState({
defaultOpen: false,
onOpenChange: (isOpen) => console.log(isOpen),
});
state.isOpen; // Current state
state.open(); // Open dialog
state.close(); // Close dialog
state.toggle(); // Toggle state
state.setOpen(); // Set state directlyAccessibility
Implements WAI-ARIA AlertDialog pattern:
- Focus trap: Focus locked within alert dialog
- Keyboard:
ESCcloses (when enabled),Tabcycles elements - Screen readers: Proper ARIA attributes with
role="alertdialog" - Scroll lock: Body scroll disabled when open
- Required action: Defaults to requiring explicit user action (no backdrop/ESC dismiss)



