Alert dialog

Pro

A dialog that stops for a decision, in Candor's theme (Base UI's AlertDialog). It can't be dismissed by clicking outside, Escape answers Cancel, and focus starts on Cancel, so no key press by accident confirms the destructive action. The action's colour comes from the app (variant="destructive"); nothing is chosen for the person.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0 and 2.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/alert-dialog

Brings in: button, heading-scope, layer, locked, merge-refs, motion, tokens, utils · npm: @base-ui/react@^1.9.0, lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import { Button } from "@/components/candor/ui/button"
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/candor/ui/alert-dialog"
import { TooltipProvider } from "@/components/candor/ui/tooltip"

export default function Example() {
  return (
    <TooltipProvider>
      <AlertDialog>
        <AlertDialogTrigger render={<Button variant="outline">Delete project</Button>} />
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Delete the project “Atlas”?</AlertDialogTitle>
            <AlertDialogDescription>Its 4 environments and 18 members lose access straight away.</AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>Keep project</AlertDialogCancel>
            {/* Focus starts on Cancel. The action says what can't be undone, in the app's words. */}
            <AlertDialogAction variant="destructive" irreversible="The 312 runs and their logs are deleted for good. Members and settings can be restored from the audit log.">
              Delete project
            </AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </TooltipProvider>
  )
}

<AlertDialog>

No props.

Also takes the props of AlertDialogPrimitive.Root.Props.

<AlertDialogAction>

The button that takes the action and closes the dialog, with what can't be undone and why it's locked when it is.

Prop	Type	Default	Description
render	`React.ReactElement \| undefined`	—	Draws this element instead of Candor's button (a link, say); it closes the dialog when pressed.
variant	`ButtonVariant \| undefined`	"default"	The button's look. Defaults to the primary button; pass `destructive` for an action that removes or can't be undone.
locked	`string \| null \| undefined`	—	Why the action can't be taken yet. When set, the button stays focusable and marked `aria-disabled`, pressing it does nothing and keeps the dialog open, and the reason is shown on hover and focus and read to screen readers. `null` or left out: unlocked.
irreversible	`string \| undefined`	—	What can't be undone, in the app's words ("The 18,240 rows in this table are deleted for good."). Shown in the footer above the buttons and read with the action. Without it the dialog says nothing about reversibility, so pass it whenever the action is destructive and the app knows.

Also takes the props of Omit<Classed<AlertDialogPrimitive.Close.Props>, "render">.

<AlertDialogCancel>

The button that closes the dialog without acting, where focus starts.

Prop	Type	Default	Description
render	`React.ReactElement \| undefined`	—	Draws this element instead of Candor's outline button; it closes the dialog when pressed.

Also takes the props of Omit<Classed<AlertDialogPrimitive.Close.Props>, "render">.

<AlertDialogContent>

The alert dialog's window, with its backdrop; focus starts on Cancel and Tab stays inside it. Content inside sits under the title, an <h2>: it is in a HeadingScope of 2, so Candor items in it draw their headings from <h3>.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<P, "className" | "style">.

<AlertDialogDescription>

The sentence under the title that says what the action does, read with its name.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<P, "className" | "style">.

<AlertDialogFooter>

The row at the bottom of the alert dialog for Cancel and the action, and what can't be undone.

No props.

Also takes the props of React.ComponentProps<"div">.

<AlertDialogHeader>

The block at the top of the alert dialog for its title and description.

No props.

Also takes the props of React.ComponentProps<"div">.

<AlertDialogOverlay>

The backdrop that dims the page behind the alert dialog; a click on it doesn't close the dialog.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<P, "className" | "style">.

<AlertDialogPortal>

Puts the alert dialog's overlay and window at the end of the page, or in a Candor host inside another library's dialog.

No props.

Also takes the props of Omit<AlertDialogPrimitive.Portal.Props, "container">.

<AlertDialogTitle>

The alert dialog's heading, an <h2>: the decision it asks for, named to screen readers.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<P, "className" | "style">.

<AlertDialogTrigger>

The control that opens the alert dialog, which scales up from it; focus returns to it when the dialog closes.

Prop	Type	Default	Description
className	`string \| undefined`	—	Classes for the part, merged with Candor's.
style	`React.CSSProperties \| undefined`	—	Inline styles for the part, merged over its motion chain.

Also takes the props of Omit<P, "className" | "style">.

Motion

Moment	Family	What it does
open	overlay, scale	The dialog fades in over the overlay family's duration (200 ms in, 120 ms out by default) and scales up from 0.95 from where the trigger was pressed. Opened any other way (a shortcut, the app's own state) it opens from its centre.

Set with --cd-motion-alert-dialog-<moment>-* in your brand file; the families are in the design reference.