React AlertDialog component

Preview

<AlertDialog>
  <AlertDialog.Trigger render={<Button variant="soft" />}>Delete branch</AlertDialog.Trigger>
  <AlertDialog.Content>
    <AlertDialog.Header>
      <AlertDialog.Title>Delete the branch?</AlertDialog.Title>
      <AlertDialog.Description>Its 3 open findings close with it.</AlertDialog.Description>

Usage

Use when

Confirming a destructive or irreversible action
An authority action: activating workspace rules, granting an exception, a bypass
A choice that must be answered before work continues

Avoid when

A task with fields (use Dialog)
A notice the user does not answer (use Toast or Alert)
A reversible action (act, then offer undo in a Toast)

Implementation notes

Title asks the question; the description names the consequence
Two answers: AlertDialog.Cancel and one AlertDialog.Action whose label is the verb
Pass render={<Button />} to Cancel and Action; a destructive Action takes tone="danger"
Focus opens on Cancel; set initialFocus only when the safe answer lives elsewhere
An Action press in the first half second after opening is ignored, so the click or Return that opened the dialog cannot answer it

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Anatomy

Import AlertDialog once, then compose its parts with dot notation.

AlertDialog.Trigger
AlertDialog.Content
AlertDialog.Header
AlertDialog.Title
AlertDialog.Description
AlertDialog.Body
AlertDialog.Footer
AlertDialog.Cancel
AlertDialog.Action

A destructive confirmation.

<AlertDialog>
  <AlertDialog.Trigger render={<Button variant="soft" />}>Delete branch</AlertDialog.Trigger>
  <AlertDialog.Content>
    <AlertDialog.Header>
      <AlertDialog.Title>Delete the branch?</AlertDialog.Title>
      <AlertDialog.Description>Its 3 open findings close with it.</AlertDialog.Description>
    </AlertDialog.Header>
    <AlertDialog.Footer>
      <AlertDialog.Cancel render={<Button variant="ghost" />}>Cancel</AlertDialog.Cancel>
      <AlertDialog.Action render={<Button variant="solid" tone="danger" />}>Delete branch</AlertDialog.Action>
    </AlertDialog.Footer>
  </AlertDialog.Content>
</AlertDialog>

Examples

Authority action

A consequential, non-destructive decision with a body.

<AlertDialog>
  <AlertDialog.Trigger render={<Button variant="soft" />}>Activate workspace rules</AlertDialog.Trigger>
  <AlertDialog.Content width="md">
    <AlertDialog.Header>
      <AlertDialog.Title>Activate the workspace rules?</AlertDialog.Title>
    </AlertDialog.Header>

API reference

Component props
Prop	Type	Default	Description
`Body.children`Required	`React.ReactNode`	Not set	—
`children`Required	`React.ReactNode`	Not set	AlertDialog parts (AlertDialog.Trigger, AlertDialog.Content)
`Content.children`Required	`React.ReactNode`	Not set	—
`Content.finalFocus`	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void) \| undefined`	Not set	Where focus goes on close.
`Content.initialFocus`	`boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| HTMLElement \| null \| void) \| undefined`	Not set	Where focus goes on open. Defaults to `AlertDialog.Cancel` when there is one.
`Content.width`	`AlertDialogWidth \| undefinedsmmd`	Not set	Sheet width.
`defaultOpen`	`boolean \| undefined`	`false`	Default open state (uncontrolled)
`Description.children`Required	`React.ReactNode`	Not set	—
`Footer.children`Required	`React.ReactNode`	Not set	—
`Header.children`Required	`React.ReactNode`	Not set	—
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Called when the open state changes; Escape and Cancel close it
`open`	`boolean \| undefined`	Not set	Controlled open state
`Title.children`Required	`React.ReactNode`	Not set	—

Accessibility

role="alertdialog" labelled by AlertDialog.Title and described by AlertDialog.Description
Traps focus; focus opens on AlertDialog.Cancel and returns to the trigger
Escape closes; an outside press does not

DialogsiblingUse Dialog for a task with fields or a long read
ToastalternativeFor a reversible action, act and offer undo in a Toast

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.