Alert Dialog

Import

import {AlertDialog} from "@heroui/react";

Usage

"use client";

import {AlertDialog, Button} from "@heroui/react";

export function Default() {

Anatomy

Import the AlertDialog component and access all parts using dot notation.

import {AlertDialog, Button} from "@heroui/react";

export default () => (
  <AlertDialog>
    <Button>Open Alert Dialog</Button>
    <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>
);

Statuses

"use client";

import {AlertDialog, Button} from "@heroui/react";

export function Statuses() {

Placements

"use client";

import {AlertDialog, Button} from "@heroui/react";

export function Placements() {

Backdrop Variants

"use client";

import {AlertDialog, Button} from "@heroui/react";

export function BackdropVariants() {

With React.useState()

Control the dialog using React's useState hook for simple state management. Perfect for basic use cases.

Status: closed

With useOverlayState()

Use the useOverlayState hook for a cleaner API with convenient methods like open(), close(), and toggle().

Status: closed

"use client";

import {AlertDialog, Button, useOverlayState} from "@heroui/react";
import {useState} from "react";

Alert dialogs require explicit user action by design—users must click an action button to close the dialog. By default, backdrop clicks and ESC key are both disabled to prevent accidental dismissal of critical confirmations.

Default (Requires Action)

With default settings, users cannot close the dialog by clicking outside or pressing ESC. They must choose an action button.

Allow Backdrop Clicks

Set isDismissable=true to let users click outside the dialog to close it. Useful for less critical confirmations.

Full Flexibility

Enable both isDismissable=true and isKeyboardDismissDisabled=false for maximum flexibility. Users can close via backdrop, Esc, or button.

"use client";

import {AlertDialog, Button, Kbd} from "@heroui/react";
import {Icon} from "@iconify/react";

Custom Icon

"use client";

import {AlertDialog, Button} from "@heroui/react";
import {Icon} from "@iconify/react";

Custom Backdrop

"use client";

import {AlertDialog, Button} from "@heroui/react";
import {Icon} from "@iconify/react";

Custom Trigger

Delete Item

Permanently remove this item

"use client";

import {AlertDialog, Button} from "@heroui/react";
import {Icon} from "@iconify/react";

With Close Button

"use client";

import {AlertDialog, Button} from "@heroui/react";
import {Icon} from "@iconify/react";

Custom Animations

"use client";

import {AlertDialog, Button} from "@heroui/react";
import {Icon} from "@iconify/react";

Related Components

Button

CloseButton

Styling

Passing Tailwind CSS classes

import {AlertDialog, Button} from "@heroui/react";

function CustomAlertDialog() {
  return (
    <AlertDialog>
      <Button variant="danger">Delete</Button>
      <AlertDialog.Container backdropClassName="bg-red-950/90" className="items-start pt-20">
        <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
          {({close}) => (
            <>
              <AlertDialog.Header>
                <AlertDialog.Icon status="danger" />
                <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading>
              </AlertDialog.Header>
              <AlertDialog.Body>
                <p>This alert dialog has custom styling applied via Tailwind classes</p>
              </AlertDialog.Body>
              <AlertDialog.Footer>
                <Button variant="tertiary" onPress={close}>
                  Cancel
                </Button>
                <Button variant="danger" onPress={close}>
                  Delete
                </Button>
              </AlertDialog.Footer>
            </>
          )}
        </AlertDialog.Dialog>
      </AlertDialog.Container>
    </AlertDialog>
  );
}

Customizing the component classes

To customize the AlertDialog component classes, you can use the @layer components directive.

Learn more.

@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;
  }
}

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-visible or [data-focus-visible="true"] - Applied to trigger, dialog, and close button
Hover: :hover or [data-hovered="true"] - Applied to close button on hover
Active: :active or [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.Container

Prop	Type	Default	Description
`placement`	`"auto" \| "center" \| "top" \| "bottom"`	`"auto"`	Dialog position on screen
`backdropVariant`	`"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
`backdropClassName`	`string \| (values) => string`	-	Backdrop CSS classes
`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
`asChild`	`boolean`	`false`	Render as child
`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 directly

Accessibility

Implements WAI-ARIA AlertDialog pattern:

Focus trap: Focus locked within alert dialog
Keyboard: ESC closes (when enabled), Tab cycles 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)

With React.useState()

With useOverlayState()

Dismiss Behavior

Default (Requires Action)

Allow Backdrop Clicks

Full Flexibility

Related Components

On this page

Related Components