Getting started

OverviewQuick startUsageAccessibilitySupport

Components

AccordionAlert DialogCheckboxCheckbox GroupCollapsibleDialogFieldFieldsetFormMenuNumber FieldPopoverPreview CardProgressRadio GroupScroll AreaSeparatorSliderSwitchTabsText InputTooltip

How-to guides

Next.js App Router

Alert Dialog

Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

Give FeedbackWAI-ARIABundle Size

Installation

Base UI components are all available as a single package.

npm install @base_ui/react

Once you have the package installed, import the component.

import { AlertDialog } from '@base_ui/react/AlertDialog';

Anatomy

Alert Dialogs are implemented using a collection of related components:

<AlertDialog.Root>
  <AlertDialog.Trigger />

  <AlertDialog.Backdrop />

  <AlertDialog.Popup>
    <AlertDialog.Title />
    <AlertDialog.Description />
    <AlertDialog.Close />
  </AlertDialog.Popup>
</AlertDialog.Root>

Alert dialogs vs. dialogs

The Alert Dialog is in many ways similar to the Dialog component. Alert dialogs should be used in cases where the normal user's workflow needs to be interrupted to get a response. Therefore alert dialogs are always modal and cannot be dismissed any other way than by pressing a button inside them.

Controlled vs. uncontrolled behavior

The simplest way to control the visibility of the alert dialog is to use the AlertDialog.Trigger and AlertDialog.Close components.

You can set the initial state with the defaultOpen prop.

<AlertDialog.Root>
  <AlertDialog.Trigger>Open</AlertDialog.Trigger>
  <AlertDialog.Popup>
    <AlertDialog.Title>Demo dialog</AlertDialog.Title>
    <AlertDialog.Close>Close</AlertDialog.Close>
  </AlertDialog.Popup>
</AlertDialog.Root>

Doing so ensures that the accessibity attributes are set correctly so that the trigger button is approriately announced by assistive technologies.

If you need to control the visibility programmatically from the outside, use the value prop. You can still use the AlertDialog.Trigger and AlertDialog.Close components (though it's not necessary), but you need to make sure to create a handler for the onOpenChange event and update the state manually.

const [open, setOpen] = React.useState(false);

return (
  <AlertDialog.Root open={open} onOpenChange={setOpen}>
    <AlertDialog.Trigger>Open</AlertDialog.Trigger>
    <AlertDialog.Popup>
      <AlertDialog.Title>Demo dialog</AlertDialog.Title>
      <AlertDialog.Close>Close</AlertDialog.Close>
    </AlertDialog.Popup>
  </AlertDialog.Root>
);

Nested dialogs

An alert dialog can open another dialog (or alert dialog). At times, it may be useful to know how may open sub-dialogs a given alert dialog has. One example of this could be styling the bottom dialog in a way they appear below the top-most one.

The number of open child dialogs is present in the data-nested-dialogs attribute and in the --nested-dialogs CSS variable on the <AlertDialog.Popup> component.

NestedAlertDialogs.tsx

Note that when dialogs are nested, only the bottom-most backdrop is rendered.

Animation

The <AlertDialog.Popup> and <AlertDialog.Backdrop> components support transitions on entry and exit.

CSS animations and transitions are supported out of the box. If a component has a transition or animation applied to it when it closes, it will be unmounted only after the animation finishes.

As this detection of exit animations requires an extra render, you may opt out of it by setting the animated prop on Popup and Backdrop to false. We also recommend doing so in automated tests, to avoid asynchronous behavior and make testing easier.

Alternatively, you can use JavaScript-based animations with a library like framer-motion, React Spring, or similar. With this approach set the keepMounted to true and let the animation library control mounting and unmounting.

CSS transitions

Here is an example of how to apply a symmetric scale and fade transition with the default conditionally-rendered behavior:

<AlertDialog.Popup className="AlertDialogPopup">Alert</AlertDialog.Popup>
.AlertDialogPopup {
  transition-property: opacity, transform;
  transition-duration: 0.2s;
  /* Represents the final styles once exited */
  opacity: 0;
  transform: translate(-50%, -35%) scale(0.8);
}

/* Represents the final styles once entered */
.AlertDialogPopup[data-open] {
  opacity: 1;
  transform: translate(-50%, -50%) scale(1);
}

/* Represents the initial styles when entering */
.AlertDialogPopup[data-entering] {
  opacity: 0;
  transform: translate(-50%, -35%) scale(0.8);
}

Styles need to be applied in three states:

AlertDialogWithTransitions.tsx

In newer browsers, there is a feature called @starting-style which allows transitions to occur on open for conditionally-mounted components:

/* Base UI API - Polyfill */
.AlertDialogPopup[data-entering] {
  opacity: 0;
  transform: translate(-50%, -35%) scale(0.8);
}

/* Official Browser API - no Firefox support as of May 2024 */
@starting-style {
  .AlertDialogPopup[data-open] {
    opacity: 0;
    transform: translate(-50%, -35%) scale(0.8);
  }
}

CSS animations

CSS animations can also be used, requiring only two separate declarations:

@keyframes scale-in {
  from {
    opacity: 0;
    transform: translate(-50%, -35%) scale(0.8);
  }
}

@keyframes scale-out {
  to {
    opacity: 0;
    transform: translate(-50%, -35%) scale(0.8);
  }
}

.AlertDialogPopup {
  animation: scale-in 0.2s forwards;
}

.AlertDialogPopup[data-exiting] {
  animation: scale-out 0.2s forwards;
}

JavaScript animations

The keepMounted prop lets an external library control the mounting, for example framer-motion's AnimatePresence component.

function App() {
  const [open, setOpen] = useState(false);
  return (
    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Trigger>Trigger</AlertDialog.Trigger>
      <AnimatePresence>
        {open && (
          <AlertDialog.Popup
            keepMounted
            render={
              <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />
            }
          >
            Alert Dialog
          </AlertDialog.Popup>
        )}
      </AnimatePresence>
    </AlertDialog.Root>
  );
}

Animation states

Four states are available as data attributes to animate the dialog, which enables full control depending on whether the popup is being animated with CSS transitions or animations, JavaScript, or is using the keepMounted prop.

Composing a custom React component

Use the render prop to override the rendered element:

<AlertDialog.Popup render={<MyCustomDialog />} />
// or
<AlertDialog.Popup render={(props) => <MyCustomDialog {...props} />} />

Accessibility

Using the <AlertDialog.Trigger> sets the required accessibility attributes on the trigger button. If you prefer controlling the open state differently, you need to apply these attributes on your own:

const [open, setOpen] = React.useState(false);

return (
  <div>
    <button
      aria-haspopup="dialog"
      aria-controls="my-popup"
      type="button"
      onClick={() => setOpen(true)}
    >
      Open
    </button>

    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Popup id="my-popup">
        <AlertDialog.Title>Demo dialog</AlertDialog.Title>
        <AlertDialog.Close>Close</AlertDialog.Close>
      </AlertDialog.Popup>
    </AlertDialog.Root>
  </div>
);

API Reference

AlertDialogBackdrop

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
keepMountedboolfalseIf true, the backdrop element is kept in the DOM when closed.
renderunionA function to customize rendering of the component.

AlertDialogClose

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
renderunionA function to customize rendering of the component.

AlertDialogDescription

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
renderunionA function to customize rendering of the component.

AlertDialogPopup

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
containerunionThe container element to which the popup is appended to.
initialFocusunionDetermines an element to focus when the dialog is opened. It can be either a ref to the element or a function that returns such a ref. If not provided, the first focusable element is focused.
keepMountedboolfalseIf true, the dialog element is kept in the DOM when closed.
renderunionA function to customize rendering of the component.

AlertDialogRoot

PropTypeDefaultDescription
animatedbooltrueIf true, the dialog supports CSS-based animations and transitions. It is kept in the DOM until the animation completes.
defaultOpenboolDetermines whether the dialog is initally open. This is an uncontrolled equivalent of the open prop.
onOpenChangefuncCallback invoked when the dialog is being opened or closed.
openboolDetermines whether the dialog is open.

AlertDialogTitle

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
renderunionA function to customize rendering of the component.

AlertDialogTrigger

PropTypeDefaultDescription
classNameunionClass names applied to the element or a function that returns them based on the component's state.
renderunionA function to customize rendering of the component.
Edit this page on GitHub
Previous
Accordion
Next
Checkbox

Contents