AlertDialog

A dialog that interrupts with a question that must be answered, such as confirming a deletion, without a way to click it away.

An alert dialog asks a question the reader must answer before going on: delete this, discard those changes. Unlike a dialog, it does not close on a click outside, and it is announced as an alert. For the common case of confirming one action with a busy state, use the composed ConfirmActionDialog, which is built on it.

A destructive question and a small oneClient

The scheme exists.

Full source examples/ui/alert-dialog.tsx

// apps/docs/examples/ui/alert-dialog.tsx'use client';
import {useState} from 'react';import {Trash2Icon} from 'lucide-react';
import {  AlertDialog,  AlertDialogAction,  AlertDialogCancel,  AlertDialogContent,  AlertDialogDescription,  AlertDialogFooter,  AlertDialogHeader,  AlertDialogMedia,  AlertDialogTitle,  AlertDialogTrigger,} from '@workspace/active-ui/components/primitives/alert-dialog';import {Button} from '@workspace/active-ui/components/primitives/button';
/** * A question that must be answered before the reader goes on: delete a * scheme, or discard unsaved changes. The cancel button closes the dialog by * itself; the action is an ordinary button, so it does its work and closes * the dialog through the open state. */export default function AlertDialogExample() {  const [open, setOpen] = useState(false);  const [deleted, setDeleted] = useState(false);  return (    <div className="flex flex-col items-center gap-4">      <div className="flex flex-wrap justify-center gap-2">        <AlertDialog open={open} onOpenChange={setOpen}>          <AlertDialogTrigger            render={<Button variant="destructive" disabled={deleted} />}          >            Delete scheme          </AlertDialogTrigger>          <AlertDialogContent>            <AlertDialogHeader>              <AlertDialogMedia>                <Trash2Icon aria-hidden />              </AlertDialogMedia>              <AlertDialogTitle>Delete Pension scheme 2026?</AlertDialogTitle>              <AlertDialogDescription>                The scheme and its 214 participants are removed. This cannot be                undone.              </AlertDialogDescription>            </AlertDialogHeader>            <AlertDialogFooter>              <AlertDialogCancel>Keep the scheme</AlertDialogCancel>              <AlertDialogAction                variant="destructive"                onClick={() => {                  setDeleted(true);                  setOpen(false);                }}              >                Delete              </AlertDialogAction>            </AlertDialogFooter>          </AlertDialogContent>        </AlertDialog>
        <AlertDialog>          <AlertDialogTrigger render={<Button variant="outline" />}>            Leave the form          </AlertDialogTrigger>          <AlertDialogContent size="sm">            <AlertDialogHeader>              <AlertDialogTitle>Discard your changes?</AlertDialogTitle>              <AlertDialogDescription>                The changes you made to this form are not saved.              </AlertDialogDescription>            </AlertDialogHeader>            <AlertDialogFooter>              <AlertDialogCancel>Stay</AlertDialogCancel>              <AlertDialogCancel variant="default">Discard</AlertDialogCancel>            </AlertDialogFooter>          </AlertDialogContent>        </AlertDialog>      </div>      <p className="text-muted-foreground text-sm" aria-live="polite">        {deleted ? 'The scheme was deleted.' : 'The scheme exists.'}      </p>      {deleted ? (        <Button variant="ghost" size="sm" onClick={() => setDeleted(false)}>          Reset the example        </Button>      ) : null}    </div>  );}

Usage#

TSX

import {  AlertDialog,  AlertDialogAction,  AlertDialogCancel,  AlertDialogContent,  AlertDialogDescription,  AlertDialogFooter,  AlertDialogHeader,  AlertDialogTitle,  AlertDialogTrigger,} from '@workspace/active-ui/components/primitives/alert-dialog';
<AlertDialog open={open} onOpenChange={setOpen}>  <AlertDialogTrigger render={<Button variant="destructive" />}>    Delete  </AlertDialogTrigger>  <AlertDialogContent>    <AlertDialogHeader>      <AlertDialogTitle>Delete this scheme?</AlertDialogTitle>      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>    </AlertDialogHeader>    <AlertDialogFooter>      <AlertDialogCancel>Cancel</AlertDialogCancel>      <AlertDialogAction variant="destructive" onClick={remove}>        Delete      </AlertDialogAction>    </AlertDialogFooter>  </AlertDialogContent></AlertDialog>;

Anatomy#

AlertDialog: the open state; open and onOpenChange, or uncontrolled.
AlertDialogTrigger: the element that opens it; render uses your own button.
AlertDialogContent: the window with its backdrop. size: default, or sm for a short question with the buttons side by side.
AlertDialogHeader with AlertDialogTitle and AlertDialogDescription; AlertDialogMedia for an icon beside the title.
AlertDialogFooter with the answers:
- AlertDialogCancel closes the dialog (Base UI's close part, styled as an outline button, with variant and size);
- AlertDialogAction is a plain Button: it does not close the dialog. Do the work in its onClick and close through onOpenChange, or after the work finished, as in the example. That keeps a failed action from closing the question.

What your application provides#

The title, the description and the labels of both answers, worded as the outcome ("Delete", "Keep the scheme"), not "OK".
The open state when the action is more than a click, and the work the action starts.

Accessibility and keyboard#

The window is a role="alertdialog", named by its title and described by its description.
Opening moves the focus inside; Tab stays inside. Escape closes it like the cancel button.
A click on the backdrop does nothing: the question has to be answered.
On close, the focus returns to the trigger.

API#

AlertDialogContent#

Import from @workspace/active-ui/components/primitives/alert-dialog

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

finalFocusBase UI

Type: booleanRefObject<HTMLElement | null>(closeType) => …

Determines the element to focus when the dialog is closed.

false: Do not move focus.
true: Move focus based on the default behavior (trigger or previously focused element).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.

initialFocusBase UI

Type: booleanRefObject<HTMLElement | null>(openType) => …

Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.

false: Do not move focus.
true: Move focus based on the default behavior (first tabbable element or popup).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.

size

Type: "default""sm"
Default: 'default'

The width and layout: default, or sm for a short question with the answers side by side.

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

AlertDialogCancel#

Import from @workspace/active-ui/components/primitives/alert-dialog

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

nativeButtonBase UI

Type: boolean
Default: true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

size

Type: "default""icon""icon-lg""icon-sm""icon-xs""lg""sm""xs"null
Default: 'default'

The height and padding. xs, sm, default and lg for a button with text; icon-xs, icon-sm, icon and icon-lg for a square button with only an icon, which then needs an accessible name (aria-label).

variant

Type: "default""destructive""ghost""link""outline""secondary"null
Default: 'outline'

The visual weight of the button. default for the main action of a screen or form; outline and secondary for other actions; ghost for a quiet action in a toolbar or a list; destructive for an action that deletes or cannot be undone; link for an action that reads as a link. Every variant but link sinks 1px while pressed; a link-styled action keeps its text and icon in place (button-link-still).

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Other parts#

AlertDialog

All props come from the Base UI part this component is built on.

Props

open

Type: boolean

Whether the dialog is currently open.

defaultOpen

Type: boolean
Default: false

Whether the dialog is initially open.

To render a controlled dialog, use the open prop instead.

children

Type: PayloadChildRenderFunction<…>ReactNode

The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger.

defaultTriggerId

Type: string | null

ID of the trigger that the dialog is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open dialog.

handle

Type: AlertDialogHandle<unknown>

A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog's open state. Can be created with the AlertDialog.createHandle() method.

triggerId

Type: string | null

ID of the trigger that the dialog is associated with. This is useful in conjunction with the open prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).

actionsRef

Type: RefObject<…>

A ref to imperative actions.

unmount: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the alert dialog completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the alert dialog imperatively when called.

Events

Called by the component when something happens.

onOpenChange

Type: (open, eventDetails) => void

Event handler called when the alert dialog is opened or closed.

onOpenChangeComplete

Type: (open: boolean) => void

Event handler called after any animations complete when the dialog is opened or closed.

Takes only the props listed.

AlertDialogAction

Props marked Base UI are behaviour of the Base UI part this component is built on.

Props

focusableWhenDisabledBase UI

Type: boolean
Default: false

Whether the button should be focusable when disabled.

nativeButtonBase UI

Type: boolean
Default: true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

size

Type: "default""icon""icon-lg""icon-sm""icon-xs""lg""sm""xs"null

variant

Type: "default""destructive""ghost""link""outline""secondary"null

renderBase UI

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

AlertDialogOverlay

All props come from the Base UI part this component is built on.

Props

forceRender

Type: boolean
Default: false

Whether the backdrop is forced to render even when nested.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

AlertDialogPortal

All props come from the Base UI part this component is built on.

Props

container

Type: HTMLElementRefObject<…>ShadowRootnull

A parent element to render the portal element into.

keepMounted

Type: boolean
Default: false

Whether to keep the portal mounted in the DOM while the popup is hidden.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

AlertDialogTrigger

All props come from the Base UI part this component is built on.

Props

handle

Type: AlertDialogHandle<unknown>

A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method.

Type: string

ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot triggerId prop).

nativeButton

Type: boolean
Default: true

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

payload

Type: unknown

A payload to pass to the dialog when it is opened.

render

Type: ComponentRenderFn<…>ReactElement<…>

Allows you to replace the component's HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Other props, such as the standard attributes of the underlying element, className and ref, are passed through.

Parts that take only their element’s attributes

AlertDialogDescription: the attributes of its element, with className and ref, and Base UI's render to use your own element.
AlertDialogFooter: the attributes of a <div>, with className and ref.
AlertDialogHeader: the attributes of a <div>, with className and ref.
AlertDialogMedia: the attributes of a <div>, with className and ref.
AlertDialogTitle: the attributes of its element, with className and ref, and Base UI's render to use your own element.

Based on shadcn/ui

This page adapts the Alert Dialog documentation of shadcn/ui (MIT licence) to this package; see Third-party notices.