# Dialog Root Component

The root Dialog component provides context and state management for the entire dialog system. It manages the open/closed state, coordinates between trigger and content components, and provides accessibility context.

## Capabilities

### Dialog Root

Root component that establishes dialog context and manages state for all child components.

```typescript { .api }
/**
 * Root dialog component that provides context and state management
 * @param props - Dialog configuration and children
 * @returns Dialog context provider with state management
 */
interface DialogProps {
  /** Child components that make up the dialog */
  children?: React.ReactNode;
  /** Controlled open state of the dialog */
  open?: boolean;
  /** Default open state for uncontrolled usage */
  defaultOpen?: boolean;
  /** Callback fired when the open state changes */
  onOpenChange?(open: boolean): void;
  /** Whether the dialog should be modal (default: true) */
  modal?: boolean;
}

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

**Usage Examples:**

```typescript
import { Dialog, DialogTrigger, DialogContent } from "@radix-ui/react-dialog";

// Basic uncontrolled dialog
function BasicDialog() {
  return (
    <Dialog>
      <DialogTrigger>Open</DialogTrigger>
      <DialogContent>
        Dialog content here
      </DialogContent>
    </Dialog>
  );
}

// Controlled dialog with state
function ControlledDialog() {
  const [open, setOpen] = React.useState(false);
  
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger>Open</DialogTrigger>
      <DialogContent>
        <p>This dialog is controlled by external state</p>
        <button onClick={() => setOpen(false)}>Close</button>
      </DialogContent>
    </Dialog>
  );
}

// Non-modal dialog
function NonModalDialog() {
  return (
    <Dialog modal={false}>
      <DialogTrigger>Open Non-Modal</DialogTrigger>
      <DialogContent>
        This dialog doesn't block interaction with background content
      </DialogContent>
    </Dialog>
  );
}

// Dialog with default open state
function DefaultOpenDialog() {
  return (
    <Dialog defaultOpen>
      <DialogTrigger>Already Open</DialogTrigger>
      <DialogContent>
        This dialog starts open by default
      </DialogContent>
    </Dialog>
  );
}
```

### State Management

The Dialog component provides both controlled and uncontrolled state patterns:

#### Controlled Usage

When both `open` and `onOpenChange` are provided, the dialog operates in controlled mode where you manage the state externally:

```typescript
const [isOpen, setIsOpen] = React.useState(false);

<Dialog open={isOpen} onOpenChange={setIsOpen}>
  {/* Dialog components */}
</Dialog>
```

#### Uncontrolled Usage

When neither `open` nor `onOpenChange` are provided, the dialog manages its own internal state:

```typescript
<Dialog>
  {/* Dialog components */}
</Dialog>
```

#### Default Open State

You can set an initial open state for uncontrolled dialogs:

```typescript
<Dialog defaultOpen={true}>
  {/* Dialog starts open */}
</Dialog>
```

### Modal vs Non-Modal

The `modal` prop controls whether the dialog blocks interaction with background content:

#### Modal Dialog (Default)

```typescript
<Dialog modal={true}> {/* or just <Dialog> */}
  {/* Background is blocked, focus is trapped */}
</Dialog>
```

Modal dialogs provide:
- Background content is blocked from interaction
- Focus is trapped within the dialog
- Overlay is rendered by default
- Scroll is locked on the body
- ESC key closes the dialog
- Click outside closes the dialog

#### Non-Modal Dialog

```typescript
<Dialog modal={false}>
  {/* Background remains interactive */}
</Dialog>
```

Non-modal dialogs provide:
- Background content remains interactive
- Focus can move outside the dialog
- No overlay is rendered by default
- No scroll locking
- More flexible interaction patterns

## Context and Internal Architecture

The Dialog component establishes several internal contexts:

- **Dialog Context**: Provides state and refs to all child components
- **Portal Context**: Manages force mounting for animations
- **Warning Context**: Development-time accessibility warnings

These contexts are automatically consumed by child components like DialogTrigger, DialogContent, etc.