Dialog

Dialog opens a modal window for focused tasks like forms or detail views. For confirmations, use AlertDialog.

Code

<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>
    Edit account
  </DialogTrigger>

  <DialogContent className="tw:sm:max-w-106.25">
    <DialogHeader>
      <DialogTitle>Edit account</DialogTitle>

      <DialogDescription>
        Update the account details used by sales and operations teams.
      </DialogDescription>
    </DialogHeader>

    <form onSubmit={(event) => event.preventDefault()}>
      <div className="tw:grid tw:gap-4 tw:py-4">
        <div className="tw:grid tw:grid-cols-4 tw:items-center tw:gap-4">
          <Label htmlFor="account-name" className="tw:text-right">
            Account
          </Label>

          <Input
            className="tw:col-span-3"
            defaultValue="Green Valley Farm"
            id="account-name"
          />
        </div>

        <div className="tw:grid tw:grid-cols-4 tw:items-center tw:gap-4">
          <Label htmlFor="account-owner" className="tw:text-right">
            Owner
          </Label>

          <Input
            className="tw:col-span-3"
            defaultValue="Maria Larsen"
            id="account-owner"
          />
        </div>
      </div>

      <DialogFooter>
        <Button type="submit">Save account</Button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>

API

Dialog

Name	Type/Description
actionsRef	RefObject<DialogRootActions | null> | undefined A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called.
children	ReactNode | PayloadChildRenderFunction<unknown> The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger.
defaultOpen = false	boolean | undefined Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
defaultTriggerId	string | null | undefined ID of the trigger that the dialog is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
disablePointerDismissal = false	boolean | undefined Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
handle	DialogHandle<unknown> | undefined A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
modal = true	boolean | "trap-focus" | undefined Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true` or `'trap-focus'`, render `<Dialog.Close>` inside `<Dialog.Popup>` so touch screen readers can escape the popup.
onOpenChange	((open: boolean, eventDetails: DialogRootChangeEventDetails) => void) | undefined Event handler called when the dialog is opened or closed.
onOpenChangeComplete	((open: boolean) => void) | undefined Event handler called after any animations complete when the dialog is opened or closed.
open	boolean | undefined Whether the dialog is currently open.
triggerId	string | null | undefined ID of the trigger that the dialog is associated with. This is useful in conjunction with the `open` prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

DialogClose

Name	Type/Description
className	string | ((state: DialogCloseState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
nativeButton = true	boolean | undefined Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
ref	((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogContent

Name	Type/Description
className	string | ((state: DialogPopupState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
finalFocus	boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | undefined Determines the element to focus when the dialog is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
initialFocus	boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) | undefined Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPopupState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
showCloseButton = true	boolean | undefined
style	CSSProperties | ((state: DialogPopupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogDescription

Name	Type/Description
className	string | ((state: DialogDescriptionState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
ref	((instance: HTMLParagraphElement | null) => void) | RefObject<HTMLParagraphElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogFooter

Name	Type/Description
showCloseButton = false	boolean | undefined

DialogHeader

No documented props

DialogOverlay

Name	Type/Description
className	string | ((state: DialogBackdropState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
forceRender = false	boolean | undefined Whether the backdrop is forced to render even when nested.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogPortal

Name	Type/Description
className	string | ((state: DialogPortalState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
container	HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null | undefined A parent element to render the portal element into.
keepMounted = false	boolean | undefined Whether to keep the portal mounted in the DOM while the popup is hidden.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogTitle

Name	Type/Description
className	string | ((state: DialogTitleState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
ref	((instance: HTMLHeadingElement | null) => void) | RefObject<HTMLHeadingElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

DialogTrigger

Name	Type/Description
className	string | ((state: DialogTriggerState) => string | undefined) | undefined CSS class applied to the element, or a function that returns a class based on the component's state.
handle	DialogHandle<unknown> | undefined A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
id	string | undefined ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop).
nativeButton = true	boolean | undefined Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
payload	unknown A payload to pass to the dialog when it is opened.
ref	((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined
render	ReactElement<any, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState> | undefined Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.