Alert Dialog

A dialog that requires user response to proceed.

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

export default function ExampleAlertDialog() {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger data-color="red" className={styles.Button}>
        Discard draft
      </AlertDialog.Trigger>
      <AlertDialog.Portal>
        <AlertDialog.Backdrop className={styles.Backdrop} />
        <AlertDialog.Popup className={styles.Popup}>
          <AlertDialog.Title className={styles.Title}>
            Discard draft?
          </AlertDialog.Title>
          <AlertDialog.Description className={styles.Description}>
            You can't undo this action.
          </AlertDialog.Description>
          <div className={styles.Actions}>
            <AlertDialog.Close className={styles.Button}>Cancel</AlertDialog.Close>
            <AlertDialog.Close data-color="red" className={styles.Button}>
              Discard
            </AlertDialog.Close>
          </div>
        </AlertDialog.Popup>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

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

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

API reference

Root

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

defaultOpen

boolean

(default:

false

)

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

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

open

boolean

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

onOpenChange

function

Name: onOpenChange
Description: Event handler called when the dialog is opened or closed.
Type: ((open: boolean, event: Event | undefined, reason: AlertDialog.Root.OpenChangeReason | undefined) => void)

actionsRef

RefObject<AlertDialog.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: RefObject<AlertDialog.Root.Actions>

onOpenChangeComplete

function

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

children

ReactNode

Name: children
Type: ReactNode

Trigger

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

nativeButton

boolean

(default:

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
Default: true

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: AlertDialog.Trigger.State) => string)

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: AlertDialog.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>.

container

Union

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

children

ReactNode

Name: children
Type: ReactNode

keepMounted

boolean

(default:

false

)

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

Backdrop

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

forceRender

boolean

(default:

false

)

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

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: AlertDialog.Backdrop.State) => string)

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: AlertDialog.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 alert dialog contents. Renders a <div> element.

initialFocus

Union

Name: initialFocus
Description: Determines the element to focus when the dialog is opened. By default, the first focusable element is focused.
Type: | RefObject<HTMLElement | null> | ((interactionType: InteractionType) => RefObject<HTMLElement | null>)

finalFocus

RefObject<HTMLElement | null>

Name: finalFocus
Description: Determines the element to focus when the dialog is closed. By default, focus returns to the trigger.
Type: RefObject<HTMLElement | null>

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: AlertDialog.Popup.State) => string)

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: AlertDialog.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.

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: AlertDialog.Title.State) => string)

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: AlertDialog.Title.State) => ReactElement)

Description

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

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: AlertDialog.Description.State) => string)

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: AlertDialog.Description.State) => ReactElement)

Close

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

nativeButton

boolean

(default:

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
Default: true

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: AlertDialog.Close.State) => string)

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: AlertDialog.Close.State) => ReactElement)

data-disabled

Present when the button is disabled.

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

Examples

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.

Make sure to also use the dialog’s finalFocus prop to return focus back to the menu trigger.

Connecting a dialog to a menu

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

function ExampleMenu() {
  const menuTriggerRef = React.useRef<HTMLButtonElement>(null);
  const [dialogOpen, setDialogOpen] = React.useState(false);

  return (
    <React.Fragment>
      <Menu.Root>
        {/* Set the trigger ref */}
        <Menu.Trigger ref={menuTriggerRef}>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 */}
      <AlertDialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
        <AlertDialog.Portal>
          <AlertDialog.Backdrop />
          {/* Return focus to the menu trigger when the dialog is closed */}
          <AlertDialog.Popup finalFocus={menuTriggerRef}>
            {/* Rest of the dialog */}
          </AlertDialog.Popup>
        </AlertDialog.Portal>
      </AlertDialog.Root>
    </React.Fragment>
  );
}

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.

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.