Import

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

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.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>
);

isDismissable

Controls whether the alert dialog can be dismissed by clicking the overlay backdrop. Alert dialogs typically require explicit action, so this defaults to false. Set to true for less critical confirmations.

isKeyboardDismissDisabled

Controls whether the ESC key can dismiss the alert dialog. Alert dialogs typically require explicit action, so this defaults to true. When set to false, the ESC key will be enabled.

Close Methods

Using slot="close"

The simplest way to close a dialog. Add slot="close" to any Button component within the dialog. When clicked, it will automatically close the dialog.

Using Dialog render props

Access the close method from the Dialog's render props. This gives you full control over when and how to close the dialog, allowing you to add custom logic before closing.

Controlled State

With React.useState()

Control the alert 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

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.Backdrop className="bg-red-950/90">
        <AlertDialog.Container className="items-start pt-20">
          <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]">
            <AlertDialog.CloseTrigger />
            <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 slot="close" variant="tertiary">
                Cancel
              </Button>
              <Button slot="close" variant="danger">
                Delete
              </Button>
            </AlertDialog.Footer>
          </AlertDialog.Dialog>
        </AlertDialog.Container>
      </AlertDialog.Backdrop>
    </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.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 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)

AlertDialog

isDismissable

isKeyboardDismissDisabled

Using slot="close"

Using Dialog render props

With React.useState()

With useOverlayState()

Related Components

On this page

Related Components

isDismissable

isKeyboardDismissDisabled

Using slot="close"

Using Dialog render props

With React.useState()

With useOverlayState()