Alert Dialog
A dialog that requires a user response to proceed.
View as MarkdownAnatomy
Import the component and assemble its parts:
import { AlertDialog } from '@base-ui/react/alert-dialog';
<AlertDialog.Root>
<AlertDialog.Trigger />
<AlertDialog.Portal>
<AlertDialog.Backdrop />
<AlertDialog.Viewport>
<AlertDialog.Popup>
<AlertDialog.Title />
<AlertDialog.Description />
<AlertDialog.Close />
</AlertDialog.Popup>
</AlertDialog.Viewport>
</AlertDialog.Portal>
</AlertDialog.Root>Examples
Open from a menu
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.
import * as React from 'react';
import { AlertDialog } from '@base-ui/react/alert-dialog';
import { Menu } from '@base-ui/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 */}
<AlertDialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
<AlertDialog.Portal>
<AlertDialog.Backdrop />
<AlertDialog.Popup>
{/* 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.
Detached triggers
An alert dialog can be controlled by a trigger located either inside or outside the <AlertDialog.Root> component.
For simple, one-off interactions, place the <AlertDialog.Trigger> inside <AlertDialog.Root>, as shown in the example at the top of this page.
However, if defining the alert dialog’s content next to its trigger is not practical, you can use a detached trigger.
This involves placing the <AlertDialog.Trigger> outside of <AlertDialog.Root> and linking them with a handle created by the AlertDialog.createHandle() function.
const demoAlertDialog = AlertDialog.createHandle();
<AlertDialog.Trigger handle={demoAlertDialog}>Open</AlertDialog.Trigger>
<AlertDialog.Root handle={demoAlertDialog}>
...
</AlertDialog.Root>Multiple triggers
A single alert 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 <AlertDialog.Trigger> components inside a single <AlertDialog.Root>.
<AlertDialog.Root>
<AlertDialog.Trigger>Trigger 1</AlertDialog.Trigger>
<AlertDialog.Trigger>Trigger 2</AlertDialog.Trigger>
...
</AlertDialog.Root>const demoAlertDialog = AlertDialog.createHandle();
<AlertDialog.Trigger handle={demoAlertDialog}>Trigger 1</AlertDialog.Trigger>
<AlertDialog.Trigger handle={demoAlertDialog}>Trigger 2</AlertDialog.Trigger>
<AlertDialog.Root handle={demoAlertDialog}>
...
</AlertDialog.Root>The alert dialog can render different content depending on which trigger opened it.
This is achieved by passing a payload to the <AlertDialog.Trigger> and using the function-as-a-child pattern in <AlertDialog.Root>.
The payload can be strongly typed by providing a type argument to the createHandle() function:
const demoAlertDialog = AlertDialog.createHandle<{ message: string }>();
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 1' }}>
Trigger 1
</AlertDialog.Trigger>
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 2' }}>
Trigger 2
</AlertDialog.Trigger>
<AlertDialog.Root handle={demoAlertDialog}>
{({ payload }) => (
<AlertDialog.Portal>
<AlertDialog.Popup>
<AlertDialog.Title>Alert dialog</AlertDialog.Title>
{payload !== undefined && (
<AlertDialog.Description>
Confirming {payload.message}
</AlertDialog.Description>
)}
</AlertDialog.Popup>
</AlertDialog.Portal>
)}
</AlertDialog.Root>Controlled mode with multiple triggers
You can control the alert dialog’s open state externally using the open and onOpenChange props on <AlertDialog.Root>.
This allows you to manage the alert 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 <AlertDialog.Root> and the id prop on each <AlertDialog.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.
API reference
Root
Groups all parts of the alert dialog. Doesn’t render its own HTML element.
defaultOpenbooleanfalse
boolean- Name
- Description
Whether the dialog is initially open.
To render a controlled dialog, use the
openprop instead.- Type
boolean | undefined- Default
false
openboolean—
boolean- Name
- Description
Whether the dialog is currently open.
- Type
boolean | undefined
onOpenChangefunction—
function- Name
- Description
Event handler called when the dialog is opened or closed.
- Type
| (( open: boolean, eventDetails: AlertDialog.Root.ChangeEventDetails, ) => void) | undefined
actionsRef| React.RefObject<AlertDialog.Root.Actions
| null>—
| React.RefObject<AlertDialog.Root.Actions
| null>- Name
- Description
A ref to imperative actions.
unmount: When specified, the dialog will not be unmounted when closed. Instead, theunmountfunction must be called to unmount the dialog manually. Useful when the dialog’s animation is controlled by an external library.close: Closes the dialog imperatively when called.
- Type
React.RefObject<AlertDialog.Root.Actions | null> | undefined
defaultTriggerIdstring | null—
string | null- Name
- Description
ID of the trigger that the dialog is associated with. This is useful in conjunction with the
defaultOpenprop to create an initially open dialog.- Type
string | null | undefined
handleAlertDialog.Handle<Payload>—
AlertDialog.Handle<Payload>- Name
- Description
A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog’s open state. Can be created with the AlertDialog.createHandle() method.
- Type
AlertDialog.Handle<Payload> | undefined
onOpenChangeCompletefunction—
function- Description
Event handler called after any animations complete when the dialog is opened or closed.
- Type
((open: boolean) => void) | undefined
triggerIdstring | null—
string | null- Name
- Description
ID of the trigger that the dialog is associated with. This is useful in conjunction with the
openprop to create a controlled dialog. There’s no need to specify this prop when the popover is uncontrolled (that is, when theopenprop is not set).- Type
string | null | undefined
children| React.ReactNode
| PayloadChildRenderFunction<Payload>—
| React.ReactNode
| PayloadChildRenderFunction<Payload>- Name
- Description
The content of the dialog. This can be a regular React node or a render function that receives the
payloadof the active trigger.- Type
React.ReactNode | ((arg: { payload: unknown | undefined }) => ReactNode)<Payload> | undefined
Additional Types
AlertDialog.Root.Props
Re-Export of Root props as AlertDialogRootProps
AlertDialog.Root.Actions
type AlertDialogRootActions = { unmount: () => void; close: () => void };AlertDialog.Root.ChangeEventReason
type AlertDialogRootChangeEventReason =
| 'trigger-press'
| 'outside-press'
| 'escape-key'
| 'close-press'
| 'focus-out'
| 'imperative-action'
| 'none';AlertDialog.Root.ChangeEventDetails
type AlertDialogRootChangeEventDetails =
| {
reason: 'trigger-press';
event:
| MouseEvent
| PointerEvent
| TouchEvent
| KeyboardEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'outside-press';
event: MouseEvent | PointerEvent | TouchEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'escape-key';
event: KeyboardEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'close-press';
event: MouseEvent | PointerEvent | KeyboardEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'focus-out';
event: KeyboardEvent | FocusEvent;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'imperative-action';
event: Event;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}
| {
reason: 'none';
event: Event;
cancel: () => void;
allowPropagation: () => void;
isCanceled: boolean;
isPropagationAllowed: boolean;
trigger: Element | undefined;
preventUnmountOnClose: () => void;
}Trigger
A button that opens the dialog.
Renders a <button> element.
handleAlertDialog.Handle<Payload>—
AlertDialog.Handle<Payload>- Name
- Description
A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
- Type
AlertDialog.Handle<Payload> | undefined
nativeButtonbooleantrue
boolean- Name
- Description
Whether the component renders a native
<button>element when replacing it via therenderprop. Set tofalseif the rendered element is not a button (for example,<div>).- Type
boolean | undefined- Default
true
payloadPayload—
Payload- Name
- Description
A payload to pass to the dialog when it is opened.
- Type
Payload | undefined
idstring—
string- Name
- 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 DialogRoot
triggerIdprop).- Type
string | undefined
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Trigger.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Trigger.State, ) => ReactElement) | undefined
data-popup-open
data-disabled
Additional Types
AlertDialog.Trigger.Props
Re-Export of Trigger props as AlertDialogTriggerProps
AlertDialog.Trigger.State
type AlertDialogTriggerState = { disabled: boolean; open: boolean };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.
containerUnion—
Union- Name
- Description
A parent element to render the portal element into.
- Type
| HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | undefined
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | (( state: AlertDialog.Portal.State, ) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Portal.State, ) => React.CSSProperties | undefined) | undefined
keepMountedbooleanfalse
boolean- Name
- Description
Whether to keep the portal mounted in the DOM while the popup is hidden.
- Type
boolean | undefined- Default
false
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Portal.State, ) => ReactElement) | undefined
Additional Types
AlertDialog.Portal.Props
Re-Export of Portal props as AlertDialogPortalProps
AlertDialog.Portal.State
type AlertDialogPortalState = {};Backdrop
An overlay displayed beneath the popup.
Renders a <div> element.
forceRenderbooleanfalse
boolean- Name
- Description
Whether the backdrop is forced to render even when nested.
- Type
boolean | undefined- Default
false
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Backdrop.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Backdrop.State, ) => ReactElement) | undefined
data-open
data-closed
data-starting-style
data-ending-style
Additional Types
AlertDialog.Backdrop.Props
Re-Export of Backdrop props as AlertDialogBackdropProps
AlertDialog.Backdrop.State
type AlertDialogBackdropState = { open: boolean; transitionStatus: TransitionStatus };Viewport
A positioning container for the dialog popup that can be made scrollable.
Renders a <div> element.
classNamestring | function—
string | function- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string | (( state: AlertDialog.Viewport.State, ) => string | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Viewport.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Viewport.State, ) => ReactElement) | undefined
data-open
data-closed
data-nested
data-nested-dialog-open
data-starting-style
data-ending-style
Additional Types
AlertDialog.Viewport.Props
Re-Export of Viewport props as AlertDialogViewportProps
AlertDialog.Viewport.State
type AlertDialogViewportState = {
open: boolean;
transitionStatus: TransitionStatus;
nested: boolean;
nestedDialogOpen: boolean;
};Popup
A container for the dialog contents.
Renders a <div> element.
initialFocusUnion—
Union- Name
- 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, orkeyboard). Return an element to focus,trueto use the default behavior, orfalse/undefinedto do nothing.
- Type
| boolean | React.RefObject<HTMLElement | null> | (( openType: 'mouse' | 'touch' | 'pen' | 'keyboard' | '', ) => boolean | void | HTMLElement | null) | undefined
finalFocusUnion—
Union- Name
- 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, orkeyboard). Return an element to focus,trueto use the default behavior, orfalse/undefinedto do nothing.
- Type
| boolean | React.RefObject<HTMLElement | null> | (( closeType: | 'mouse' | 'touch' | 'pen' | 'keyboard' | '', ) => boolean | void | HTMLElement | null) | undefined
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Popup.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Popup.State, ) => ReactElement) | undefined
data-open
data-closed
data-nested
data-nested-dialog-open
data-starting-style
data-ending-style
--nested-dialogs
Indicates how many dialogs are nested within.
Additional Types
AlertDialog.Popup.Props
Re-Export of Popup props as AlertDialogPopupProps
AlertDialog.Popup.State
type AlertDialogPopupState = {
open: boolean;
transitionStatus: TransitionStatus;
nested: boolean;
nestedDialogOpen: boolean;
};Title
A heading that labels the dialog.
Renders an <h2> element.
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Title.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Title.State, ) => ReactElement) | undefined
Additional Types
AlertDialog.Title.Props
Re-Export of Title props as AlertDialogTitleProps
AlertDialog.Title.State
type AlertDialogTitleState = {};Description
A paragraph with additional information about the dialog.
Renders a <p> element.
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Description.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Description.State, ) => ReactElement) | undefined
Additional Types
AlertDialog.Description.Props
Re-Export of Description props as AlertDialogDescriptionProps
AlertDialog.Description.State
type AlertDialogDescriptionState = {};Close
A button that closes the dialog.
Renders a <button> element.
nativeButtonbooleantrue
boolean- Name
- Description
Whether the component renders a native
<button>element when replacing it via therenderprop. Set tofalseif the rendered element is not a button (for example,<div>).- Type
boolean | undefined- Default
true
classNamestring | function—
string | function- Name
- 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 | undefined) | undefined
styleReact.CSSProperties | function—
React.CSSProperties | function- Name
- Type
| React.CSSProperties | (( state: AlertDialog.Close.State, ) => React.CSSProperties | undefined) | undefined
renderReactElement | function—
ReactElement | function- Name
- Description
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
Accepts a
ReactElementor a function that returns the element to render.- Type
| ReactElement | (( props: HTMLProps, state: AlertDialog.Close.State, ) => ReactElement) | undefined
data-disabled
Additional Types
AlertDialog.Close.Props
Re-Export of Close props as AlertDialogCloseProps
AlertDialog.Close.State
type AlertDialogCloseState = { disabled: boolean };createHandle
Return value
AlertDialog.Handle<Payload>Handle
A handle to control a Dialog imperatively and to associate detached triggers with it.
Constructor parameters
storeDialogStore<Payload>—
DialogStore<Payload>- Name
- Type
DialogStore<Payload> | undefined
Properties
isOpenbooleanreadonly
boolean- Name
- Description
Indicates whether the dialog is currently open.
- Type
boolean- Modifiers
readonly
Methods
open(triggerId)void
- Name
- Description
Opens the dialog and associates it with the trigger with the given id. The trigger, if provided, must be a Dialog.Trigger component with this handle passed as a prop.
This method should only be called in an event handler or an effect (not during rendering).
- Parameters
triggerId—string | nullID of the trigger to associate with the dialog. If null, the dialog will open without a trigger association.
- Returns
void
openWithPayload(payload)void
- Name
- Description
Opens the dialog and sets the payload. Does not associate the dialog with any trigger.
- Parameters
payload—PayloadPayload to set when opening the dialog.
- Returns
void
close()void
- Name
- Description
Closes the dialog.
- Returns
void