alert-dialog

A modal dialog temporarily interrupts the user's workflow with important content, requiring immediate attention and a response before allowing further interaction.

Philosophy

Alert dialogs are the nuclear option of UI interruption. Unlike regular dialogs, they can't be dismissed by clicking outside or pressing Escape - the user must explicitly choose an action. Reserve them for destructive operations where an accidental dismissal could mean data loss.

Installation

npx @gentleduck/cli add alert-dialog

npx @gentleduck/cli add alert-dialog

Usage

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@/components/ui/alert-dialog';

<AlertDialog>
  <AlertDialogTrigger>Open</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account and remove your data from our servers.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Examples

Active Trigger on Open

Style the trigger to appear active while the alert dialog is open using data-[state=open]:

Component Composition

Loading diagram...

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the alert dialog follows. It extends Dialog, so the portaled content gets the resolved dir and the footer actions mirror without any extra props.

<DirectionProvider dir="rtl">
  <AlertDialog>
    <AlertDialogTrigger>حذف الحساب</AlertDialogTrigger>
    <AlertDialogContent>
      <AlertDialogHeader>
        <AlertDialogTitle>هل أنت متأكد؟</AlertDialogTitle>
        <AlertDialogDescription>لا يمكن التراجع عن هذا الإجراء.</AlertDialogDescription>
      </AlertDialogHeader>
      <AlertDialogFooter>
        <AlertDialogCancel>إلغاء</AlertDialogCancel>
        <AlertDialogAction>متابعة</AlertDialogAction>
      </AlertDialogFooter>
    </AlertDialogContent>
  </AlertDialog>
</DirectionProvider>

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionAlertDialog and MotionAlertDialogContent for smooth enter/exit animations powered by motion. Uses a stiffer spring to convey urgency compared to the regular dialog.

Requires the motion package. Use MotionAlertDialog instead of AlertDialog and MotionAlertDialogContent instead of AlertDialogContent. All other sub-components (AlertDialogTrigger, AlertDialogAction, etc.) stay the same.

API Reference

AlertDialog

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`-`	Determines if the dialog should be open by default
`open`	`boolean`	`-`	Controls the visibility of the dialog
`onOpenChange`	`(open: boolean) => void`	`-`	Callback fired when the dialog opens or closes
`dir`	`'ltr' \| 'rtl'`	`-`	Optional override. Resolved by primitives `useDirection` (`dir` prop -> `DirectionProvider` -> `<html dir>`). Inherited from the Dialog primitive.
`children`	`React.ReactNode`	(required)	Child elements (typically Trigger and Content)
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Root>`	-	Additional props inherited from `AlertDialogPrimitive.Root`

AlertDialogTrigger

Prop	Type	Default	Description
`children`	`React.ReactNode`	`--`	Content of the trigger
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Trigger>`	-	Additional props inherited from `AlertDialogPrimitive.Trigger`. Always renders a native `button` element; there is no `asChild`/`Slot` support.

AlertDialogPortal

Prop	Type	Default	Description
`container`	`HTMLElement`	-	Optional portal container
`forceMount`	`true`	-	Forces mounted state for all portal children
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Portal>`	-	Additional props inherited from `AlertDialogPrimitive.Portal`

AlertDialogOverlay

Prop	Type	Default	Description
`className`	`string`	-	Additional class names to apply
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Overlay>`	-	Additional props inherited from `AlertDialogPrimitive.Overlay`

AlertDialogContent

Prop	Type	Default	Description
`className`	`string`	`-`	Additional class names to apply
`children`	`React.ReactNode`	`-`	Content displayed inside the dialog
`forceMount`	`boolean`	`false`	If `true`, forces the content to stay mounted in the DOM
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>`	-	Additional props inherited from `AlertDialogPrimitive.Content`

MotionAlertDialog

Same props as AlertDialog. Wraps with useMotionRoot for exit animation support. Requires the motion package.

MotionAlertDialogContent

Prop	Type	Default	Description
`open`	`boolean`	-	Required. Controlled open state for AnimatePresence enter/exit
`className`	`string`	`-`	Additional class names to apply
`children`	`React.ReactNode`	`-`	Content displayed inside the dialog

Requires motion package installed. Content uses a scaleIn entrance (fade, scale, and blur) with a spring transition (stiffness 400, damping 30) for a snappier feel that conveys urgency; the overlay fades in independently. Automatically respects prefers-reduced-motion.

AlertDialogHeader

Prop	Type	Default	Description
`className`	`string`	`--`	Additional class names to apply
`children`	`React.ReactNode`	`--`	Header content (typically Title and Description)
`...props`	`React.HTMLAttributes<HTMLDivElement>`	-	Additional props to spread to the header container

AlertDialogFooter

Prop	Type	Default	Description
`className`	`string`	`--`	Additional class names to apply
`children`	`React.ReactNode`	`--`	Footer content (typically Action and Cancel buttons)
`...props`	`React.HTMLAttributes<HTMLDivElement>`	-	Additional props to spread to the content div

AlertDialogTitle

Prop	Type	Default	Description
`className`	`string`	`--`	Additional class names to apply
`children`	`React.ReactNode`	`--`	Title text content
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>`	-	Additional props inherited from `AlertDialogPrimitive.Title`

AlertDialogDescription

Prop	Type	Default	Description
`className`	`string`	`--`	Additional class names to apply
`children`	`React.ReactNode`	`--`	Description text content
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Description>`	-	Additional props inherited from `AlertDialogPrimitive.Description`

AlertDialogAction

Prop	Type	Default	Description
`className`	`string`	-	Additional class names merged with default button styles
`children`	`React.ReactNode`	-	Action button content
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Action>`	-	Additional props inherited from `AlertDialogPrimitive.Action`

AlertDialogCancel

Prop	Type	Default	Description
`className`	`string`	-	Additional class names merged with outline button styles
`children`	`React.ReactNode`	-	Cancel button content
`...props`	`React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Cancel>`	-	Additional props inherited from `AlertDialogPrimitive.Cancel`