or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-radix-ui--react-alert-dialog

A React component for building accessible alert dialogs with focus management and ARIA compliance

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@radix-ui/react-alert-dialog@1.1.x

To install, run

npx @tessl/cli install tessl/npm-radix-ui--react-alert-dialog@1.1.0

index.mddocs/

Radix UI Alert Dialog

Radix UI Alert Dialog provides low-level, accessible React components for building alert dialogs. Alert dialogs are modal dialogs that demand user attention and action before continuing, with enhanced accessibility features including proper focus management, keyboard navigation, and screen reader support.

Package Information

  • Package Name: @radix-ui/react-alert-dialog
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @radix-ui/react-alert-dialog

Core Imports

import * as AlertDialog from "@radix-ui/react-alert-dialog";

Or import specific components:

import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogPortal,
  AlertDialogOverlay,
  AlertDialogContent,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogAction,
  AlertDialogCancel,
} from "@radix-ui/react-alert-dialog";

For CommonJS:

const AlertDialog = require("@radix-ui/react-alert-dialog");

Basic Usage

import * as AlertDialog from "@radix-ui/react-alert-dialog";

function MyAlertDialog() {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger asChild>
        <button>Delete item</button>
      </AlertDialog.Trigger>
      <AlertDialog.Portal>
        <AlertDialog.Overlay />
        <AlertDialog.Content>
          <AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
          <AlertDialog.Description>
            This action cannot be undone. This will permanently delete your item.
          </AlertDialog.Description>
          <div style={{ display: "flex", gap: 25, justifyContent: "flex-end" }}>
            <AlertDialog.Cancel asChild>
              <button>Cancel</button>
            </AlertDialog.Cancel>
            <AlertDialog.Action asChild>
              <button>Yes, delete item</button>
            </AlertDialog.Action>
          </div>
        </AlertDialog.Content>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
}

Architecture

Alert Dialog follows a compound component pattern where each part serves a specific role:

  • Root: Manages dialog state and provides context to child components
  • Trigger: Opens the dialog when activated
  • Portal: Renders dialog content in a separate DOM location (typically document.body)
  • Overlay: Background layer behind the dialog content
  • Content: Main dialog container with accessibility features
  • Title & Description: Accessible labeling required for screen readers
  • Action & Cancel: Interactive buttons that close the dialog

Key differences from regular dialogs:

  • Always modal (cannot be dismissed by clicking outside)
  • Prevents escape key dismissal
  • Auto-focuses the cancel button when opened
  • Requires explicit user action to dismiss

Capabilities

Root Component

The root container that manages dialog state and provides context to all child components.

interface AlertDialogProps {
  children?: React.ReactNode;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
}

const AlertDialog: React.FC<AlertDialogProps>;

Also available as:

const Root: React.FC<AlertDialogProps>;

Trigger Component

Button or element that opens the alert dialog when activated.

interface AlertDialogTriggerProps extends React.ComponentPropsWithoutRef<'button'> {
  asChild?: boolean;
}

const AlertDialogTrigger: React.ForwardRefExoticComponent<
  AlertDialogTriggerProps & React.RefAttributes<HTMLButtonElement>
>;

Also available as:

const Trigger: React.ForwardRefExoticComponent<
  AlertDialogTriggerProps & React.RefAttributes<HTMLButtonElement>
>;

Portal Component

Renders dialog content outside the normal DOM tree, typically in document.body.

interface AlertDialogPortalProps {
  children?: React.ReactNode;
  container?: HTMLElement;
  forceMount?: true;
}

const AlertDialogPortal: React.FC<AlertDialogPortalProps>;

Also available as:

const Portal: React.FC<AlertDialogPortalProps>;

Overlay Component

Background layer that appears behind the dialog content.

interface AlertDialogOverlayProps extends React.ComponentPropsWithoutRef<'div'> {
  asChild?: boolean;
  forceMount?: true;
}

const AlertDialogOverlay: React.ForwardRefExoticComponent<
  AlertDialogOverlayProps & React.RefAttributes<HTMLDivElement>
>;

Also available as:

const Overlay: React.ForwardRefExoticComponent<
  AlertDialogOverlayProps & React.RefAttributes<HTMLDivElement>
>;

Content Component

Main dialog container with built-in accessibility features and focus management.

interface AlertDialogContentProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onPointerDownOutside' | 'onInteractOutside'> {
  asChild?: boolean;
  forceMount?: true;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onOpenAutoFocus?: (event: Event) => void;
  onCloseAutoFocus?: (event: Event) => void;
}

const AlertDialogContent: React.ForwardRefExoticComponent<
  AlertDialogContentProps & React.RefAttributes<HTMLDivElement>
>;

Also available as:

const Content: React.ForwardRefExoticComponent<
  AlertDialogContentProps & React.RefAttributes<HTMLDivElement>
>;

Key behaviors:

  • Sets role="alertdialog" for accessibility
  • Prevents pointer and interaction events outside the dialog (onPointerDownOutside and onInteractOutside are internally prevented)
  • Automatically focuses the cancel button when opened
  • Prevents dismissal via escape key or outside clicks

Title Component

Required accessible title for the alert dialog.

interface AlertDialogTitleProps extends React.ComponentPropsWithoutRef<'h2'> {
  asChild?: boolean;
}

const AlertDialogTitle: React.ForwardRefExoticComponent<
  AlertDialogTitleProps & React.RefAttributes<HTMLHeadingElement>
>;

Also available as:

const Title: React.ForwardRefExoticComponent<
  AlertDialogTitleProps & React.RefAttributes<HTMLHeadingElement>
>;

Description Component

Required accessible description for the alert dialog content.

interface AlertDialogDescriptionProps extends React.ComponentPropsWithoutRef<'p'> {
  asChild?: boolean;
}

const AlertDialogDescription: React.ForwardRefExoticComponent<
  AlertDialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>
>;

Also available as:

const Description: React.ForwardRefExoticComponent<
  AlertDialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>
>;

Note: The Description component is required for accessibility. In development mode, a console warning will be logged if the description is missing or not properly linked via aria-describedby. The warning provides detailed guidance on how to add proper descriptions for screen readers.

Action Component

Primary action button that closes the dialog and executes the main action.

interface AlertDialogActionProps extends React.ComponentPropsWithoutRef<'button'> {
  asChild?: boolean;
}

const AlertDialogAction: React.ForwardRefExoticComponent<
  AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>
>;

Also available as:

const Action: React.ForwardRefExoticComponent<
  AlertDialogActionProps & React.RefAttributes<HTMLButtonElement>
>;

Cancel Component

Cancel button that closes the dialog without executing the main action. Receives focus when the dialog opens.

interface AlertDialogCancelProps extends React.ComponentPropsWithoutRef<'button'> {
  asChild?: boolean;
}

const AlertDialogCancel: React.ForwardRefExoticComponent<
  AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>
>;

Also available as:

const Cancel: React.ForwardRefExoticComponent<
  AlertDialogCancelProps & React.RefAttributes<HTMLButtonElement>
>;

Key behavior: Automatically receives focus when the alert dialog opens.

Utility Functions

Advanced composition utility for creating scoped alert dialog contexts.

/**
 * Creates a scoped context for alert dialog components
 * Used for advanced composition scenarios with multiple dialog instances
 */
function createAlertDialogScope(): CreateScope;

interface CreateScope {
  scopeName: string;
  (): ScopeHook;
}

type ScopeHook = (scope: Scope) => { [__scopeProp: string]: Scope };
type Scope<C = any> = { [scopeName: string]: React.Context<C>[] } | undefined;

Common Props

asChild Prop

Many components support the asChild prop for composition:

// Default behavior - renders a button
<AlertDialog.Trigger>Open</AlertDialog.Trigger>

// With asChild - merges props with the child element
<AlertDialog.Trigger asChild>
  <MyCustomButton>Open</MyCustomButton>
</AlertDialog.Trigger>

forceMount Prop

Content and Overlay components support forceMount for animation libraries:

<AlertDialog.Overlay forceMount={shouldForceMount} />
<AlertDialog.Content forceMount={shouldForceMount}>
  {/* content */}
</AlertDialog.Content>

Event Handling

<AlertDialog.Root onOpenChange={(open) => console.log("Dialog is", open ? "open" : "closed")}>
  <AlertDialog.Content
    onOpenAutoFocus={(event) => {
      // Prevent default focus behavior if needed
      event.preventDefault();
    }}
    onCloseAutoFocus={(event) => {
      // Handle focus return when dialog closes
    }}
    onEscapeKeyDown={(event) => {
      // Escape key is prevented by default in alert dialogs
      // This handler won't typically fire unless custom behavior is needed
    }}
  >
    {/* content */}
  </AlertDialog.Content>
</AlertDialog.Root>

Accessibility Features

  • ARIA Compliance: Proper role="alertdialog" and ARIA labeling
  • Focus Management: Automatic focus on cancel button, proper focus return
  • Keyboard Navigation: Tab cycling within dialog, escape prevention
  • Screen Reader Support: Required title and description announcement
  • Non-dismissible: Cannot be closed by clicking outside or pressing escape
  • Development Warnings: Console warnings in development mode for missing required accessibility components (specifically the Description component)