AlertDialog

Alert dialogs require an explicit response before a consequential action proceeds.

Overview and decision boundary

Use AlertDialog when a destructive or difficult-to-reverse action must pause for one explicit response.

Do not hide side effects, default focus to a destructive action, or put multi-step workflows in AlertDialog.

1import * as React from 'react';2import { AlertDialog, AlertDialogAction, AlertDialogBackdrop, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, Button } from '@nerio-ui/ui/client';34function DeleteProjectDialog() {5  const cancelRef = React.useRef<HTMLButtonElement>(null);67  return (8    <AlertDialog>9      <AlertDialogTrigger render={<Button variant="danger">Delete project</Button>} />10      <AlertDialogPortal>11        <AlertDialogBackdrop />12        <AlertDialogContent initialFocus={cancelRef}>13          <AlertDialogHeader>14            <AlertDialogTitle>Delete project?</AlertDialogTitle>15            <AlertDialogDescription>This permanently removes the project and cannot be undone.</AlertDialogDescription>16          </AlertDialogHeader>17          <AlertDialogFooter>18            <AlertDialogCancel ref={cancelRef} render={<Button variant="secondary">Cancel</Button>} />19            <AlertDialogAction render={<Button variant="danger" onClick={deleteProject}>Delete project</Button>} />20          </AlertDialogFooter>21        </AlertDialogContent>22      </AlertDialogPortal>23    </AlertDialog>24  );25}

Advanced destructive confirmation

Exact-name confirmation is optional consumer-owned product policy. Compose it inside AlertDialogBody when a high-risk action needs a stronger response than the primitive confirmation boundary.

1import * as React from 'react';2import { AlertDialog, AlertDialogAction, AlertDialogBackdrop, AlertDialogBody, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, Button, Field, Input } from '@nerio-ui/ui/client';34function DeleteProjectDialog() {5  const cancelRef = React.useRef<HTMLButtonElement>(null);6  const projectName = "Nerio";7  const [confirmation, setConfirmation] = React.useState("");8  const isConfirmed = confirmation === projectName;910  return (11    <AlertDialog onOpenChange={(open) => !open && setConfirmation("")}>12      <AlertDialogTrigger render={<Button variant="danger">Delete project</Button>} />13      <AlertDialogPortal>14        <AlertDialogBackdrop />15        <AlertDialogContent initialFocus={cancelRef}>16          <AlertDialogHeader>17            <AlertDialogTitle>Delete project?</AlertDialogTitle>18            <AlertDialogDescription>This permanently removes the project and cannot be undone.</AlertDialogDescription>19          </AlertDialogHeader>20          <AlertDialogBody>21            <Field label={`Type “${projectName}” to confirm`} description="The project name is case-sensitive.">22              <Input autoComplete="off" value={confirmation} onChange={(event) => setConfirmation(event.target.value)} />23            </Field>24          </AlertDialogBody>25          <AlertDialogFooter>26            <AlertDialogCancel ref={cancelRef} render={<Button variant="secondary">Cancel</Button>} />27            <AlertDialogAction disabled={!isConfirmed} render={<Button variant="danger" onClick={deleteProject}>Delete project</Button>} />28          </AlertDialogFooter>29        </AlertDialogContent>30      </AlertDialogPortal>31    </AlertDialog>32  );33}

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm exec nerio add alert-dialog23import * as React from 'react';4import { AlertDialog, AlertDialogAction, AlertDialogBackdrop, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, Button } from '@nerio-ui/ui/client';

Usage

1import * as React from 'react';2import { AlertDialog, AlertDialogAction, AlertDialogBackdrop, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, Button } from '@nerio-ui/ui/client';34function DeleteProjectDialog() {5  const cancelRef = React.useRef<HTMLButtonElement>(null);67  return (8    <AlertDialog>9      <AlertDialogTrigger render={<Button variant="danger">Delete project</Button>} />10      <AlertDialogPortal>11        <AlertDialogBackdrop />12        <AlertDialogContent initialFocus={cancelRef}>13          <AlertDialogHeader>14            <AlertDialogTitle>Delete project?</AlertDialogTitle>15            <AlertDialogDescription>This permanently removes the project and cannot be undone.</AlertDialogDescription>16          </AlertDialogHeader>17          <AlertDialogFooter>18            <AlertDialogCancel ref={cancelRef} render={<Button variant="secondary">Cancel</Button>} />19            <AlertDialogAction render={<Button variant="danger" onClick={deleteProject}>Delete project</Button>} />20          </AlertDialogFooter>21        </AlertDialogContent>22      </AlertDialogPortal>23    </AlertDialog>24  );25}

Variants

Variant	Purpose
`Confirmation`	One explicit cancel/action decision.

Anatomy

Slot	Purpose
`portal`	Container boundary for the portalled confirmation.
`trigger`	Control that requests the confirmation.
`backdrop`	Modal backdrop that does not dismiss on pointer press.
`content`	Viewport-bounded alertdialog surface with deliberate focus.
`header`	Groups the accessible name and concrete consequence.
`title`	Required accessible name phrased as the decision.
`description`	Explains the consequence without ambiguous language.
`body`	Optional supporting content; keep the decision concise.
`footer`	Action row with cancel before confirmation.
`cancel`	Safe response and recommended initial-focus target.
`action`	Explicit confirmation boundary that closes after the consumer handler runs.

States

State	Purpose
`Open`	Pointer dismissal is disabled and focus stays in the alertdialog.
`Cancelled`	The safe response closes and restores focus.
`Confirmed`	The consumer handler runs and the dialog closes.

Motion

overlay entry and exit
reduced-motion fade-only state change

Accessibility

Uses the Base UI Alert Dialog primitive with role=alertdialog, modal focus containment, Escape dismissal, scroll locking, and pointer dismissal disabled.
AlertDialogTitle provides the accessible name and AlertDialogDescription explains the consequence in concrete language.
Place AlertDialogCancel before AlertDialogAction and pass its ref to AlertDialogContent initialFocus for destructive or difficult-to-reverse actions.
AlertDialogCancel and AlertDialogAction are explicit close boundaries; mutation, async orchestration, permissions, routing, and confirmation copy remain consumer-owned.
Focus returns to the trigger after either response and every action keeps native Button keyboard semantics through render composition.

Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.

API

Prop	Purpose
`AlertDialog`	Controlled or uncontrolled Base UI Alert Dialog root.
`AlertDialogContent`	Accepts initialFocus, finalFocus, className, native popup props, and a forwarded ref.
`AlertDialogCancel`	Explicit safe close boundary and recommended initial-focus target.
`AlertDialogAction`	Explicit confirm close boundary; consumers attach mutation behavior to the rendered Button.

Implementation contract

Contract	Value
`Registry item`	alert-dialog installs 1 source file into the configured components directory.
`Base UI`	alert-dialog
`Registry dependencies`	dialog
`Package dependencies`	@base-ui/react, clsx, react, tailwind-merge, tailwindcss

Styling contract

Contract	Value
`Authoring`	`Complete, statically detectable Tailwind CSS v4 recipes own component visuals.`
`Values`	`Semantic and component --n-* variables remain the canonical customization layer.`
`Overrides`	`Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically.`
`Residual CSS`	`Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer.`

Design notes

AlertDialog is a response boundary, not an async mutation orchestrator.
Exact-name confirmation is optional consumer-owned policy composed inside AlertDialogBody.
A normal Dialog remains appropriate for reversible tasks and forms with their own completion model.

Do / do not

Name the action and consequence precisely, focus Cancel first, and keep one clear confirmation action.

Compose an exact entity-name confirmation when consumer product policy requires it.

Do not