# Radix UI React Dialog

Radix UI React Dialog is a high-quality, accessible dialog component system for React applications. It provides modal overlays, popups, and dialog windows with proper accessibility features, focus management, keyboard navigation, and screen reader support as part of the Radix UI primitives collection.

## Package Information

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

## Core Imports

```typescript
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogTitle,
  DialogDescription,
  DialogClose,
  DialogOverlay,
  DialogPortal
} from "@radix-ui/react-dialog";
```

Alternative import pattern with short names:

```typescript
import {
  Root,
  Trigger,
  Content,
  Title,
  Description,
  Close,
  Overlay,
  Portal
} from "@radix-ui/react-dialog";
```

For CommonJS:

```javascript
const {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogTitle,
  DialogDescription,
  DialogClose
} = require("@radix-ui/react-dialog");
```

## Basic Usage

```typescript
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogTitle,
  DialogDescription,
  DialogClose,
  DialogOverlay,
  DialogPortal
} from "@radix-ui/react-dialog";

function MyDialog() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <button>Open Dialog</button>
      </DialogTrigger>
      <DialogPortal>
        <DialogOverlay className="dialog-overlay" />
        <DialogContent className="dialog-content">
          <DialogTitle>Are you sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone. This will permanently delete your account.
          </DialogDescription>
          <div className="dialog-actions">
            <DialogClose asChild>
              <button>Cancel</button>
            </DialogClose>
            <DialogClose asChild>
              <button className="destructive">Yes, delete account</button>
            </DialogClose>
          </div>
        </DialogContent>
      </DialogPortal>
    </Dialog>
  );
}
```

## Architecture

Radix UI React Dialog is built around a compound component pattern with several key components:

- **Root Component**: `Dialog` provides context and state management for the entire dialog system
- **Trigger System**: `DialogTrigger` handles opening the dialog with proper accessibility attributes
- **Portal Rendering**: `DialogPortal` renders content outside the normal DOM flow for proper layering
- **Overlay Management**: `DialogOverlay` provides modal background with scroll locking
- **Content Container**: `DialogContent` manages focus trapping, keyboard navigation, and dismissal
- **Accessibility Components**: `DialogTitle` and `DialogDescription` provide proper ARIA labeling
- **Close Controls**: `DialogClose` enables multiple ways to close the dialog
- **Context Scoping**: Advanced context management for nested or multiple dialog instances

## Capabilities

### Root Dialog Component

Core dialog root component that provides context and state management for all child components.

```typescript { .api }
interface DialogProps {
  children?: React.ReactNode;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?(open: boolean): void;
  modal?: boolean;
}

const Dialog: React.FC<DialogProps>;
```

[Dialog Root Component](./dialog-root.md)

### Dialog Triggers and Controls

Components for opening and closing dialogs with proper accessibility and focus management.

```typescript { .api }
interface DialogTriggerProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {}
interface DialogCloseProps extends React.ComponentPropsWithoutRef<typeof Primitive.button> {}

const DialogTrigger: React.ForwardRefExoticComponent<DialogTriggerProps>;
const DialogClose: React.ForwardRefExoticComponent<DialogCloseProps>;
```

[Triggers and Controls](./triggers-controls.md)

### Portal and Layout

Portal rendering and overlay components for proper dialog layering and modal behavior.

```typescript { .api }
interface DialogPortalProps {
  children?: React.ReactNode;
  container?: PortalProps['container'];
  forceMount?: true;
}

interface DialogOverlayProps extends React.ComponentPropsWithoutRef<typeof Primitive.div> {
  forceMount?: true;
}

const DialogPortal: React.FC<DialogPortalProps>;
const DialogOverlay: React.ForwardRefExoticComponent<DialogOverlayProps>;
```

[Portal and Layout](./portal-layout.md)

### Content and Accessibility

Main content container with focus management and accessibility components.

```typescript { .api }
interface DialogContentProps extends DialogContentTypeProps {
  forceMount?: true;
}

interface DialogTitleProps extends React.ComponentPropsWithoutRef<typeof Primitive.h2> {}
interface DialogDescriptionProps extends React.ComponentPropsWithoutRef<typeof Primitive.p> {}

const DialogContent: React.ForwardRefExoticComponent<DialogContentProps>;
const DialogTitle: React.ForwardRefExoticComponent<DialogTitleProps>;
const DialogDescription: React.ForwardRefExoticComponent<DialogDescriptionProps>;
```

[Content and Accessibility](./content-accessibility.md)

### Advanced Context Management

Utilities for advanced use cases like nested dialogs and custom context scoping.

```typescript { .api }
const createDialogScope: () => {
  Provider: React.Provider<any>;
  useScope: () => any;
};

const WarningProvider: React.Provider<any>;
```

[Advanced Context Management](./advanced-context.md)

## Alternative Export Names

All components are also available with shorter names for convenience:

```typescript { .api }
const Root: typeof Dialog;
const Trigger: typeof DialogTrigger;
const Portal: typeof DialogPortal;
const Overlay: typeof DialogOverlay;
const Content: typeof DialogContent;
const Title: typeof DialogTitle;
const Description: typeof DialogDescription;
const Close: typeof DialogClose;
```

## Element Types

Reference types for component elements:

```typescript { .api }
type DialogTriggerElement = React.ComponentRef<typeof Primitive.button>;
type DialogPortalElement = never; // Portal doesn't render a DOM element
type DialogOverlayElement = React.ComponentRef<typeof Primitive.div>;
type DialogContentElement = React.ComponentRef<typeof Primitive.div>;
type DialogTitleElement = React.ComponentRef<typeof Primitive.h2>;
type DialogDescriptionElement = React.ComponentRef<typeof Primitive.p>;
type DialogCloseElement = React.ComponentRef<typeof Primitive.button>;
```

## Key Features

- **Full Accessibility**: ARIA attributes, focus management, screen reader support
- **Keyboard Navigation**: ESC to close, Tab navigation, Enter/Space activation
- **Focus Management**: Focus trapping, auto-focus on open/close, focus restoration
- **Modal and Non-modal**: Supports both blocking overlays and non-blocking dialogs
- **Portal Rendering**: Content rendered outside normal DOM flow
- **Customizable**: All components accept standard HTML props for styling
- **Animation Support**: `forceMount` props for controlling mount/unmount timing
- **TypeScript**: Full type safety with comprehensive type definitions
- **Controlled/Uncontrolled**: Supports both usage patterns
- **Compound Components**: Composable API for maximum flexibility