OverlaysReact
A dialog that requires a response to proceed.
Rendered by React 19.3.1
Loading React…Installation
npm i @hamur/reactNot on npm yet. The package goes out under the chosen name.
Anatomy
Import the component and assemble its parts:
<AlertDialog.Root>
<AlertDialog.Trigger />
<AlertDialog.Portal>
<AlertDialog.Backdrop />
<AlertDialog.Popup>
<AlertDialog.Title />
<AlertDialog.Description />
<AlertDialog.Close />
</AlertDialog.Popup>
</AlertDialog.Portal>
</AlertDialog.Root>
// Not in this example: AlertDialog.ViewportExamples
Detached Triggers Simple
A trigger outside Root opens it through a handle.
Detached Triggers Controlled
open with triggerId lets several triggers share one alert dialog.
Open From Menu
A menu item opens the alert dialog by setting open.
API reference
19 props across 9 parts, in React syntax. className, style, render are listed once, under Shared props.
BackdropAlertDialog.Backdrop
An overlay displayed beneath the popup. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
forceRenderWhether the backdrop is forced to render even when nested. | boolean | false |
| Data 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 begins animating in. |
data-ending-style | Present when the dialog is animating out. |
CloseAlertDialog.Close
A button that closes the dialog. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
| Data attribute | Description |
|---|---|
data-disabled | Present when the button is disabled. |
DescriptionAlertDialog.Description
A paragraph with additional information about the dialog. Renders a <p>.
PopupAlertDialog.Popup
A container for the dialog contents. Renders a <div>.
| Prop | Type | Default |
|---|---|---|
initialFocusDetermines the element to focus when the dialog is opened. | boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) | — |
finalFocusDetermines the element to focus when the dialog is closed. | boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null) | — |
| Data 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 begins animating in. |
data-ending-style | Present when the dialog is animating out. |
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. |
| CSS variable | Description |
|---|---|
--nested-dialogs | Indicates how many dialogs are nested within. |
PortalAlertDialog.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>.
| Prop | Type | Default |
|---|---|---|
containerA parent element to render the portal element into. | HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | — |
keepMountedWhether to keep the portal mounted in the DOM while the popup is hidden. | boolean | false |
RootAlertDialog.Root
Groups all parts of the alert dialog. Doesn’t render its own element.
| Prop | Type | Default |
|---|---|---|
defaultOpenWhether the dialog is initially open. | boolean | false |
openWhether the dialog is currently open. | boolean | — |
onOpenChangeEvent handler called when the alert dialog is opened or closed. | ((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void) | — |
actionsRefA ref to imperative actions. | React.RefObject<DialogRootActions | null> | — |
defaultTriggerIdID of the trigger that the dialog is associated with. | string | null | — |
handleA handle to associate the alert dialog with a trigger. | AlertDialogHandle<Payload> | — |
onOpenChangeCompleteEvent handler called after any animations complete when the dialog is opened or closed. | ((open: boolean) => void) | — |
triggerIdID of the trigger that the dialog is associated with. | string | null | — |
childrenThe content of the dialog. | React.ReactNode | PayloadChildRenderFunction<Payload> | — |
TitleAlertDialog.Title
A heading that labels the dialog. Renders a <h2>.
TriggerAlertDialog.Trigger
A button that opens the alert dialog. Renders a <button>.
| Prop | Type | Default |
|---|---|---|
handleA handle to associate the trigger with an alert dialog. | AlertDialogHandle<Payload> | — |
nativeButtonWhether the component renders a native <button> element when replacing it | boolean | true |
payloadA payload to pass to the dialog when it is opened. | Payload | — |
idID of the trigger. | string | — |
| Data attribute | Description |
|---|---|
data-disabled | Present when the trigger is disabled. |
data-popup-open | Present when the corresponding alert dialog is open. |
ViewportAlertDialog.Viewport
A positioning container for the dialog popup that can be made scrollable. Renders a <div>.
| Data 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 begins animating in. |
data-ending-style | Present when the dialog is animating out. |
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. |
Shared props
Every part that renders an element takes these.
| Prop | Type |
|---|---|
classNameCSS class applied to the element, or a function that
returns a class based on the component's state. | string | ((state: State) => string | undefined) |
styleStyle applied to the element, or a function that
returns a style object based on the component's state. | React.CSSProperties | ((state: State) => React.CSSProperties | undefined) |
renderAllows you to replace the component's HTML element
with a different tag, or compose it with another component. | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State> |
Keyboard and accessibility
Keyboard
| Keys | Does | Part |
|---|---|---|
| Escape | Closes the alert dialog and returns focus to the trigger that opened it | Popup |
Accessibility
| Part | Sets | So that |
|---|---|---|
| Trigger | aria-haspopup="dialog", aria-expanded, aria-controls | a screen reader says the button opens a dialog and whether it is open |
| Popup | role="alertdialog" | the popup is announced as an alert that needs an answer |
| Popup | aria-labelledby to Title, aria-describedby to Description | the question and its consequence are read when it opens |
| Popup | aria-hidden="true" on the rest of the page | a screen reader stays inside until the person answers |
| Backdrop | role="presentation" | the overlay is not read |
| Viewport | role="presentation" | the positioning container is not read |
Focus order
- Opening moves focus to the first focusable element in Popup, or to
initialFocus. Put the safe choice first. TabandShift+Tabstay inside the popup and wrap at either end.- Closing returns focus to the Trigger that opened it, or to
finalFocus.