Components
Alert Dialog
Confirmations for destructive or irreversible actions that require an explicit choice.
Alert Dialog interrupts the user only when a decision is required. Use it for destructive or
irreversible actions such as deleting data, discarding changes, resetting state, or signing out.
It is built on Base UI Alert Dialog and exported from @orkest/ui/client.
Dialog vs Alert Dialog#
| Behavior | Dialog | Alert Dialog |
|---|---|---|
| Overlay press closes | Yes by default | No |
| Escape closes | Yes by default | No |
| Focus management | Yes | Yes |
| Requires an explicit choice | No | Yes |
| Typical use | Edit, view, create | Delete, discard, reset |
Alert Dialog is intentionally stricter than Dialog. It does not render a built-in close icon, and the only ways out are the cancel and confirming actions.
Basic usage#
import {
AlertDialog,
AlertDialogAction,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogHeader,
AlertDialogOverlay,
AlertDialogPortal,
AlertDialogTitle,
AlertDialogTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<AlertDialog>
<AlertDialogTrigger variant="destructive">Delete project</AlertDialogTrigger>
<AlertDialogPortal>
<AlertDialogOverlay />
<AlertDialogContent>
<AlertDialogHeader>
<AlertDialogTitle>Delete project?</AlertDialogTitle>
<AlertDialogDescription>
This permanently deletes the project and its data. This action
cannot be undone.
</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
<AlertDialogCancel>Cancel</AlertDialogCancel>
<AlertDialogAction>Delete project</AlertDialogAction>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialogPortal>
</AlertDialog>
);
}AlertDialogCancel renders a secondary Button. AlertDialogAction renders a destructive Button.
Both are Base UI close buttons, so pressing either action closes the dialog.
Async actions#
For an action that must finish before closing, control the dialog and use a regular Button with a loading state. The dialog stays open until the request succeeds.
import { useState } from 'react';
import { Button } from '@orkest/ui';
import {
AlertDialog,
AlertDialogCancel,
AlertDialogContent,
AlertDialogDescription,
AlertDialogFooter,
AlertDialogHeader,
AlertDialogOverlay,
AlertDialogPortal,
AlertDialogTitle,
} from '@orkest/ui/client';
export function Example() {
const [open, setOpen] = useState(false);
const [loading, setLoading] = useState(false);
async function handleDelete() {
setLoading(true);
await new Promise((resolve) => setTimeout(resolve, 600));
setLoading(false);
setOpen(false);
}
return (
<>
<Button variant="destructive" onClick={() => setOpen(true)}>
Delete account
</Button>
<AlertDialog open={open} onOpenChange={setOpen}>
<AlertDialogPortal>
<AlertDialogOverlay />
<AlertDialogContent>
<AlertDialogHeader>
<AlertDialogTitle>Delete account?</AlertDialogTitle>
<AlertDialogDescription>
All projects and data will be removed. This action cannot be
undone.
</AlertDialogDescription>
</AlertDialogHeader>
<AlertDialogFooter>
<AlertDialogCancel disabled={loading}>Cancel</AlertDialogCancel>
<Button
variant="destructive"
loading={loading}
onClick={handleDelete}
>
Delete account
</Button>
</AlertDialogFooter>
</AlertDialogContent>
</AlertDialogPortal>
</AlertDialog>
</>
);
}Props#
AlertDialog#
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
| Controlled open state. | ||
defaultOpen | boolean | false |
| Initial open state for uncontrolled usage. | ||
onOpenChange | (open, eventDetails) => void | — |
| Called when the dialog requests an open state change. Escape key requests are canceled. | ||
onOpenChangeComplete | (open: boolean) => void | — |
| Called after the open or close animation completes. | ||
actionsRef | RefObject<{ close: () => void; unmount: () => void }> | — |
| Imperative close and unmount actions. | ||
triggerId / defaultTriggerId | string | — |
| Associates an external trigger with a controlled alert dialog. | ||
AlertDialogContent#
| Prop | Type | Default |
|---|---|---|
size | 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'sm' |
| Maximum width preset. Alert dialogs are compact by default. | ||
initialFocus | boolean | RefObject<HTMLElement> | function | — |
| Element focused when the dialog opens. Defaults to the first action. | ||
finalFocus | boolean | RefObject<HTMLElement> | function | — |
| Element focused when the dialog closes. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| Class names, data attributes, and refs are forwarded to the popup. | ||
AlertDialogTrigger, Cancel, and Action#
| Prop | Type | Default |
|---|---|---|
variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | Trigger / Cancel: 'secondary'; Action: 'destructive' |
| Visual Button variant used by the default button. | ||
size | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
| Button size. | ||
render | ReactElement | — |
| Replaces the default Button with a custom element or variant. | ||
native attributes | ButtonHTMLAttributes<HTMLButtonElement> | — |
| Disabled, loading, click handlers, and refs are forwarded. | ||
Layout parts#
| Prop | Type | Default |
|---|---|---|
AlertDialogHeader | DialogHeader props | — |
| Groups the title and description. | ||
AlertDialogTitle | DialogTitle props | — |
| Accessible confirmation title. | ||
AlertDialogDescription | DialogDescription props | — |
| Explains the consequence of the action. | ||
AlertDialogFooter | DialogFooter props | — |
| Action row for cancel and confirm. | ||
AlertDialogOverlay | DialogOverlay props | — |
| Backdrop rendered beneath the content. | ||
AlertDialogPortal | DialogPortal props | — |
| Supports a custom container and keepMounted. | ||
Accessibility#
- Always render
AlertDialogTitleandAlertDialogDescription. The description should state the consequence, not just repeat the title. - Focus moves into the dialog when it opens and returns to the trigger when it closes.
- Escape and overlay press do not close the dialog. This is enforced by the component.
- The cancel action receives initial focus by default, reducing the chance of accidental confirmation.
AlertDialogActioncloses the dialog immediately. For async work, use a controlled dialog and a regular Button with a loading state.- Do not use Alert Dialog for non-blocking messages. Use Dialog or inline feedback instead.