Dialog

A popup that opens on top of the entire page.

import { Dialog } from '@base-ui-components/react/dialog';
import styles from './index.module.css';

export default function ExampleDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className={styles.Button}>View notifications</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop className={styles.Backdrop} />
        <Dialog.Popup className={styles.Popup}>
          <Dialog.Title className={styles.Title}>Notifications</Dialog.Title>
          <Dialog.Description className={styles.Description}>
            You are all caught up. Good job!
          </Dialog.Description>
          <div className={styles.Actions}>
            <Dialog.Close className={styles.Button}>Close</Dialog.Close>
          </div>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

import { Dialog } from '@base-ui-components/react/dialog';

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title />
      <Dialog.Description />
      <Dialog.Close />
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

API reference

Root

Groups all parts of the dialog. Doesn’t render its own HTML element.

defaultOpen

boolean

false

Name: defaultOpen
Description: Whether the dialog is initially open.

To render a controlled dialog, use the open prop instead.
Type: boolean | undefined
Default: false

open

boolean

—

Name: open
Description: Whether the dialog is currently open.
Type: boolean | undefined

onOpenChange

function

—

Name: onOpenChange
Description: Event handler called when the dialog is opened or closed.
Type: | (( open: boolean, eventDetails: Dialog.Root.ChangeEventDetails, ) => void) | undefined

actionsRef

RefObject<Dialog.Root.Actions>

—

Name: actionsRef
Description: A ref to imperative actions.

unmount: When specified, the dialog will not be unmounted when closed. Instead, the unmount function must be called to unmount the dialog manually. Useful when the dialog's animation is controlled by an external library.
Type: React.RefObject<Dialog.Root.Actions> | undefined

defaultTriggerId

string | null

—

Name: defaultTriggerId
Description: 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.
Type: string | null | undefined

dismissible

boolean

true

Name: dismissible
Description: Determines whether the dialog should close on outside clicks.
Type: boolean | undefined
Default: true

handle

DialogHandle<Payload>

—

Name: handle
Description: A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state. Can be created with the Dialog.createHandle() method.
Type: {} | undefined

Name: modal
Description: 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.
Type: boolean | 'trap-focus' | undefined
Default: true

onOpenChangeComplete

function

—

Name: onOpenChangeComplete
Description: Event handler called after any animations complete when the dialog is opened or closed.
Type: ((open: boolean) => void) | undefined

triggerId

string | null

—

Name: triggerId
Description: ID of the trigger that the dialog is associated with. This is useful in conjuntion with the open prop to create a controlled dialog. There's no need to specify this prop when the popover is uncontrolled (i.e. when the open prop is not set).
Type: string | null | undefined

children

ReactNode | PayloadChildRenderFunction<Payload>

—

Name: children
Description: The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger.
Type: | React.ReactNode | ((arg: { payload: Payload | undefined }) => ReactNode)

Trigger

A button that opens the dialog. Renders a <button> element.

handle

DialogHandle<Payload>

—

Name: handle
Description: A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
Type: {} | undefined

nativeButton

boolean

true

Name: nativeButton
Description: 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 (e.g. <div>).
Type: boolean | undefined
Default: true

payload

Payload

—

Name: payload
Description: A payload to pass to the dialog when it is opened.
Type: Payload | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Dialog.Trigger.State, ) => CSSProperties | undefined) | undefined

id

string

—

Name: id
Description: ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialogs in controlled mode (with the Dialog.Root triggerId prop).
Type: string | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Trigger.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Trigger.State, ) => ReactElement)

data-popup-open

Present when the corresponding dialog is open.

data-disabled

Present when the trigger is disabled.

Attribute	Description
`data-popup-open`	Present when the corresponding dialog is open.
`data-disabled`	Present when the trigger is disabled.

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Dialog.Portal.State, ) => CSSProperties | undefined) | undefined

container

Union

—

Name: container
Description: A parent element to render the portal element into.
Type: | HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Portal.State) => string | undefined)

keepMounted

boolean

false

Name: keepMounted
Description: Whether to keep the portal mounted in the DOM while the popup is hidden.
Type: boolean | undefined
Default: false

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Portal.State, ) => ReactElement)

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

forceRender

boolean

false

Name: forceRender
Description: Whether the backdrop is forced to render even when nested.
Type: boolean | undefined
Default: false

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Dialog.Backdrop.State, ) => CSSProperties | undefined) | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Backdrop.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Backdrop.State, ) => ReactElement)

data-open

Present when the dialog is open.

data-closed

Present when the dialog is closed.

data-starting-style

Present when the dialog is animating in.

data-ending-style

Present when the dialog is animating out.

Attribute	Description
`data-open`	Present when the dialog is open.
`data-closed`	Present when the dialog is closed.
`data-starting-style`	Present when the dialog is animating in.
`data-ending-style`	Present when the dialog is animating out.

A container for the dialog contents. Renders a <div> element.

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | ((state: Dialog.Popup.State) => CSSProperties | undefined) | undefined

initialFocus

Union

—

Name: initialFocus
Description: Determines the element to focus when the dialog is opened.

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, or false/undefined to do nothing.
Type: | boolean | React.RefObject<HTMLElement | null> | (( openType: InteractionType, ) => boolean | void | HTMLElement | null) | undefined

finalFocus

Union

—

Name: finalFocus
Description: 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, or false/undefined to do nothing.
Type: | boolean | React.RefObject<HTMLElement | null> | (( closeType: InteractionType, ) => boolean | void | HTMLElement | null) | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Popup.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Popup.State, ) => ReactElement)

data-open

Present when the dialog is open.

data-closed

Present when the dialog is closed.

data-nested

Present when the dialog is nested within another dialog.

data-nested-dialog-open

Present when the dialog has other open dialogs nested within it.

data-starting-style

Present when the dialog is animating in.

data-ending-style

Present when the dialog is animating out.

Attribute	Description
`data-open`	Present when the dialog is open.
`data-closed`	Present when the dialog is closed.
`data-nested`	Present when the dialog is nested within another dialog.
`data-nested-dialog-open`	Present when the dialog has other open dialogs nested within it.
`data-starting-style`	Present when the dialog is animating in.
`data-ending-style`	Present when the dialog is animating out.

--nested-dialogs

Indicates how many dialogs are nested within.

CSS Variable	Description
`--nested-dialogs`	Indicates how many dialogs are nested within.

Title

A heading that labels the dialog. Renders an <h2> element.

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | ((state: Dialog.Title.State) => CSSProperties | undefined) | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Title.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Title.State, ) => ReactElement)

Description

A paragraph with additional information about the dialog. Renders a <p> element.

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Dialog.Description.State, ) => CSSProperties | undefined) | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Description.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Description.State, ) => ReactElement)

Close

A button that closes the dialog. Renders a <button> element.

nativeButton

boolean

true

Name: nativeButton
Description: 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 (e.g. <div>).
Type: boolean | undefined
Default: true

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | ((state: Dialog.Close.State) => CSSProperties | undefined) | undefined

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Dialog.Close.State) => string | undefined)

render

ReactElement | function

—

Name: render
Description: 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.
Type: | ReactElement | (( props: HTMLProps, state: Dialog.Close.State, ) => ReactElement)

data-disabled

Present when the button is disabled.

Attribute	Description
`data-disabled`	Present when the button is disabled.

Examples

State

By default, Dialog is an uncontrolled component that manages its own state.

Uncontrolled dialog

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Popup>
      <Dialog.Title>Example dialog</Dialog.Title>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

Use open and onOpenChange props if you need to access or control the state of the dialog. For example, you can control the dialog state in order to open it imperatively from another place in your app.

Controlled dialog

const [open, setOpen] = React.useState(false);
return (
  <Dialog.Root open={open} onOpenChange={setOpen}>
    <Dialog.Trigger>Open</Dialog.Trigger>
    <Dialog.Portal>
      <Dialog.Popup>
        <form
          // Close the dialog once the form data is submitted
          onSubmit={async () => {
            await submitData();
            setOpen(false);
          }}
        >
          ...
        </form>
      </Dialog.Popup>
    </Dialog.Portal>
  </Dialog.Root>
);

It’s also common to use onOpenChange if your app needs to do something when the dialog is closed or opened. This is recommended over React.useEffect when reacting to state changes.

Running code when dialog state changes

<Dialog.Root
  open={open}
  onOpenChange={(open) => {
    // Do stuff when the dialog is closed
    if (!open) {
      doStuff();
    }
    // Set the new state
    setOpen(open);
  }}
>

In order to open a dialog using a menu, control the dialog state and open it imperatively using the onClick handler on the menu item.

Connecting a dialog to a menu

import * as React from 'react';
import { Dialog } from '@base-ui-components/react/dialog';
import { Menu } from '@base-ui-components/react/menu';

function ExampleMenu() {
  const [dialogOpen, setDialogOpen] = React.useState(false);

  return (
    <React.Fragment>
      <Menu.Root>
        <Menu.Trigger>Open menu</Menu.Trigger>
        <Menu.Portal>
          <Menu.Positioner>
            <Menu.Popup>
              {/* Open the dialog when the menu item is clicked */}
              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
            </Menu.Popup>
          </Menu.Positioner>
        </Menu.Portal>
      </Menu.Root>

      {/* Control the dialog state */}
      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
        <Dialog.Portal>
          <Dialog.Backdrop />
          <Dialog.Popup>
            {/* Rest of the dialog */}
          </Dialog.Popup>
        </Dialog.Portal>
      </Dialog.Root>
    </React.Fragment>
  );
}

Nested dialogs

You can nest dialogs within one another normally.

Use the [data-nested-dialog-open] selector and the var(--nested-dialogs) CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won’t be rendered so that you can present the parent dialog in a clean way behind the one on top of it.

Close confirmation

This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

To implement this, both dialogs should be controlled. The confirmation dialog may be opened when onOpenChange callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.

Detached triggers

A dialog can be controlled by a trigger located either inside or outside the <Dialog.Root> component. For simple, one-off interactions, place the <Dialog.Trigger> inside <Dialog.Root>, as shown in the example at the top of this page.

However, if defining the dialog’s content next to its trigger is not practical, you can use a detached trigger. This involves placing the <Dialog.Trigger> outside of <Dialog.Root> and linking them with a handle created by the Dialog.createHandle() function.

Detached triggers

const demoDialog = Dialog.createHandle();

<Dialog.Trigger handle={demoDialog}>Open</Dialog.Trigger>

<Dialog.Root handle={demoDialog}>
  ...
</Dialog.Root>

import * as React from 'react';
import { Dialog } from '@base-ui-components/react/dialog';
import styles from '../../index.module.css';

const demoDialog = Dialog.createHandle();

export default function DialogDetachedTriggersSimpleDemo() {
  return (
    <React.Fragment>
      <Dialog.Trigger className={styles.Button} handle={demoDialog}>
        View notifications
      </Dialog.Trigger>

      <Dialog.Root handle={demoDialog}>
        <Dialog.Portal>
          <Dialog.Backdrop className={styles.Backdrop} />
          <Dialog.Popup className={styles.Popup}>
            <Dialog.Title className={styles.Title}>Notifications</Dialog.Title>
            <Dialog.Description className={styles.Description}>
              You are all caught up. Good job!
            </Dialog.Description>
            <div className={styles.Actions}>
              <Dialog.Close className={styles.Button}>Close</Dialog.Close>
            </div>
          </Dialog.Popup>
        </Dialog.Portal>
      </Dialog.Root>
    </React.Fragment>
  );
}

Multiple triggers

A single dialog can be opened by multiple trigger elements. You can achieve this by using the same handle for several detached triggers, or by placing multiple <Dialog.Trigger> components inside a single <Dialog.Root>.

Multiple triggers within the Root part

<Dialog.Root>
  <Dialog.Trigger>Trigger 1</Dialog.Trigger>
  <Dialog.Trigger>Trigger 2</Dialog.Trigger>
  ...
</Dialog.Root>

multiple detached triggers

const demoDialog = Dialog.createHandle();

<Dialog.Trigger handle={demoDialog}>Trigger 1</Dialog.Trigger>
<Dialog.Trigger handle={demoDialog}>Trigger 2</Dialog.Trigger>
<Dialog.Root handle={demoDialog}>
  ...
</Dialog.Root>

The dialog can render different content depending on which trigger opened it. This is achieved by passing a payload to the <Dialog.Trigger> and using the function-as-a-child pattern in <Dialog.Root>.

The payload can be strongly typed by providing a type argument to the createHandle() function:

Detached triggers with payload

const demoDialog = Dialog.createHandle<{ text: string }>();

<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 1' }}>
  Trigger 1
</Dialog.Trigger>

<Dialog.Trigger handle={demoDialog} payload={{ text: 'Trigger 2' }}>
  Trigger 2
</Dialog.Trigger>

<Dialog.Root handle={demoDialog}>
  {({ payload }) => (
    <Dialog.Portal>
      <Dialog.Popup>
        <Dialog.Title>Dialog</Dialog.Title>
        {payload !== undefined && (
          <Dialog.Description>
            This has been opened by {payload.text}
          </Dialog.Description>
        )}
      </Dialog.Popup>
    </Dialog.Portal>
  )}
</Dialog.Root>

Controlled mode with multiple triggers

You can control the dialog’s open state externally using the open and onOpenChange props on <Dialog.Root>. This allows you to manage the dialog’s visibility based on your application’s state. When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <Dialog.Root> and the id prop on each <Dialog.Trigger>.

Note that there is no separate onTriggerIdChange prop. Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

import * as React from 'react';
import { Dialog } from '@base-ui-components/react/dialog';
import styles from '../../index.module.css';

const demoDialog = Dialog.createHandle<number>();

export default function DialogDetachedTriggersControlledDemo() {
  const [open, setOpen] = React.useState(false);
  const [triggerId, setTriggerId] = React.useState<string | null>(null);

  const handleOpenChange = (isOpen: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => {
    setOpen(isOpen);
    setTriggerId(eventDetails.trigger?.id ?? null);
  };

  return (
    <React.Fragment>
      <div className={styles.Container}>
        <Dialog.Trigger className={styles.Button} handle={demoDialog} id="trigger-1" payload={1}>
          Open 1
        </Dialog.Trigger>

        <Dialog.Trigger className={styles.Button} handle={demoDialog} id="trigger-2" payload={2}>
          Open 2
        </Dialog.Trigger>

        <Dialog.Trigger className={styles.Button} handle={demoDialog} id="trigger-3" payload={3}>
          Open 3
        </Dialog.Trigger>

        <button
          className={styles.Button}
          type="button"
          onClick={() => {
            setTriggerId('trigger-2');
            setOpen(true);
          }}
        >
          Open programmatically
        </button>
      </div>

      <Dialog.Root
        handle={demoDialog}
        open={open}
        onOpenChange={handleOpenChange}
        triggerId={triggerId}
      >
        {({ payload }) => (
          <Dialog.Portal>
            <Dialog.Backdrop className={styles.Backdrop} />
            <Dialog.Popup className={styles.Popup}>
              {payload !== undefined && (
                <Dialog.Title className={styles.Title}>Dialog {payload}</Dialog.Title>
              )}
              <div className={styles.Actions}>
                <Dialog.Close className={styles.Button}>Close</Dialog.Close>
              </div>
            </Dialog.Popup>
          </Dialog.Portal>
        )}
      </Dialog.Root>
    </React.Fragment>
  );
}