Skip to main content

​
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

npm install @radix-ui/react-dialog

​
Anatomy

Import all parts and piece them together. 
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.
​
open
boolean
The controlled open state of the dialog. Must be used in conjunction with onOpenChange.
​
defaultOpen
boolean
The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
​
onOpenChange
(open: boolean) => void
Event handler called when the open state of the dialog changes.
​
modal
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.

​
Trigger

The button that opens the dialog.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
Supports all standard HTML button attributes.

​
Portal

When used, portals your overlay and content parts into the body.
​
container
HTMLElement
default:"document.body"
Specify a container element to portal the content into.
​
forceMount
boolean
Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

​
Overlay

A layer that covers the inert portion of the view when the dialog is open.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
forceMount
boolean
Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

​
Content

Contains the content to be rendered in the open dialog.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
forceMount
boolean
Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
​
onOpenAutoFocus
(event: Event) => void
Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault.
​
onCloseAutoFocus
(event: Event) => void
Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.
​
onEscapeKeyDown
(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
​
onPointerDownOutside
(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.
​
onInteractOutside
(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.

​
Title

An accessible title to be announced when the dialog is opened.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
This part is required for accessibility. If you want to hide it, wrap it inside @radix-ui/react-visually-hidden.

​
Description

An optional accessible description to be announced when the dialog is opened.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.

​
Close

The button that closes the dialog.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.

​
Example

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>
  );
}

​
Accessibility

Adheres to the Dialog WAI-ARIA design pattern.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us