> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/radix-ui/primitives/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialog

> A modal dialog that interrupts the user with important content and expects a response.

## Overview

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

## Features

* Focus is automatically trapped within the dialog
* Can be controlled or uncontrolled
* Manages screen reader announcements with Title and Description components
* Esc key closes the dialog
* Clicking outside the dialog closes it
* Scrolling is blocked on the body when the dialog is open
* Optional modal or non-modal mode

## Installation

```bash theme={null}
npm install @radix-ui/react-dialog
```

## Anatomy

Import all parts and piece them together.

```tsx theme={null}
import * as Dialog from '@radix-ui/react-dialog';

export default () => (
  <Dialog.Root>
    <Dialog.Trigger />
    <Dialog.Portal>
      <Dialog.Overlay />
      <Dialog.Content>
        <Dialog.Title />
        <Dialog.Description />
        <Dialog.Close />
      </Dialog.Content>
    </Dialog.Portal>
  </Dialog.Root>
);
```

## API Reference

### Root

Contains all the dialog component parts.

<ParamField path="open" type="boolean">
  The controlled open state of the dialog. Must be used in conjunction with `onOpenChange`.
</ParamField>

<ParamField path="defaultOpen" type="boolean">
  The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
</ParamField>

<ParamField path="onOpenChange" type="(open: boolean) => void">
  Event handler called when the open state of the dialog changes.
</ParamField>

<ParamField path="modal" type="boolean" default="true">
  The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers.
</ParamField>

### Trigger

The button that opens the dialog.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

<Note>
  Supports all standard HTML button attributes.
</Note>

### Portal

When used, portals your overlay and content parts into the `body`.

<ParamField path="container" type="HTMLElement" default="document.body">
  Specify a container element to portal the content into.
</ParamField>

<ParamField path="forceMount" type="boolean">
  Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
</ParamField>

### Overlay

A layer that covers the inert portion of the view when the dialog is open.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

<ParamField path="forceMount" type="boolean">
  Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
</ParamField>

### Content

Contains the content to be rendered in the open dialog.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

<ParamField path="forceMount" type="boolean">
  Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
</ParamField>

<ParamField path="onOpenAutoFocus" type="(event: Event) => void">
  Event handler called when focus moves into the component after opening. It can be prevented by calling `event.preventDefault`.
</ParamField>

<ParamField path="onCloseAutoFocus" type="(event: Event) => void">
  Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`.
</ParamField>

<ParamField path="onEscapeKeyDown" type="(event: KeyboardEvent) => void">
  Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`.
</ParamField>

<ParamField path="onPointerDownOutside" type="(event: PointerDownOutsideEvent) => void">
  Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
</ParamField>

<ParamField path="onInteractOutside" type="(event: PointerDownOutsideEvent | FocusOutsideEvent) => void">
  Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`.
</ParamField>

### Title

An accessible title to be announced when the dialog is opened.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

<Warning>
  This part is required for accessibility. If you want to hide it, wrap it inside `@radix-ui/react-visually-hidden`.
</Warning>

### Description

An optional accessible description to be announced when the dialog is opened.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

### Close

The button that closes the dialog.

<ParamField path="asChild" type="boolean" default="false">
  Change the default rendered element for the one passed as a child, merging their props and behavior.
</ParamField>

## Example

<CodeGroup>
  ```tsx Basic Usage theme={null}
  import * as Dialog from '@radix-ui/react-dialog';

  function DialogDemo() {
    return (
      <Dialog.Root>
        <Dialog.Trigger>Open Dialog</Dialog.Trigger>
        <Dialog.Portal>
          <Dialog.Overlay className="dialog-overlay" />
          <Dialog.Content className="dialog-content">
            <Dialog.Title>Edit Profile</Dialog.Title>
            <Dialog.Description>
              Make changes to your profile here. Click save when you're done.
            </Dialog.Description>
            <div>
              <label htmlFor="name">Name</label>
              <input id="name" defaultValue="John Doe" />
            </div>
            <Dialog.Close>Save changes</Dialog.Close>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    );
  }
  ```

  ```tsx Controlled theme={null}
  import { useState } from 'react';
  import * as Dialog from '@radix-ui/react-dialog';

  function ControlledDialog() {
    const [open, setOpen] = useState(false);

    return (
      <Dialog.Root open={open} onOpenChange={setOpen}>
        <Dialog.Trigger>Open</Dialog.Trigger>
        <Dialog.Portal>
          <Dialog.Overlay />
          <Dialog.Content>
            <Dialog.Title>Controlled Dialog</Dialog.Title>
            <Dialog.Description>
              This dialog's state is controlled externally.
            </Dialog.Description>
            <button onClick={() => setOpen(false)}>Close</button>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    );
  }
  ```

  ```tsx Non-Modal theme={null}
  import * as Dialog from '@radix-ui/react-dialog';

  function NonModalDialog() {
    return (
      <Dialog.Root modal={false}>
        <Dialog.Trigger>Open Non-Modal Dialog</Dialog.Trigger>
        <Dialog.Portal>
          <Dialog.Content>
            <Dialog.Title>Non-Modal Dialog</Dialog.Title>
            <Dialog.Description>
              You can still interact with content outside this dialog.
            </Dialog.Description>
            <Dialog.Close>Close</Dialog.Close>
          </Dialog.Content>
        </Dialog.Portal>
      </Dialog.Root>
    );
  }
  ```
</CodeGroup>

## Accessibility

Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal).

### Keyboard Interactions

* `Space` - Opens/closes the dialog
* `Enter` - Opens/closes the dialog
* `Tab` - Moves focus to the next focusable element
* `Shift + Tab` - Moves focus to the previous focusable element
* `Esc` - Closes the dialog and moves focus to trigger