AlertDialog

Use AlertDialog for a decision that interrupts the current workflow, such as confirming deletion. It provides an accessible modal with a backdrop and focus management.

Confirmation

import { useState } from 'react';
import { AlertDialog } from 'twenty-ui/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => {
  const [open, setOpen] = useState(false);

  return (
    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Trigger>Delete record</AlertDialog.Trigger>
      <AlertDialog.Popup>
        <AlertDialog.Header>
          <AlertDialog.Title>Delete this record?</AlertDialog.Title>
          <AlertDialog.Description>
            This action cannot be undone.
          </AlertDialog.Description>
        </AlertDialog.Header>
        <AlertDialog.Footer>
          <AlertDialog.Close>Cancel</AlertDialog.Close>
          <button
            type="button"
            onClick={() => {
              onDelete();
              setOpen(false);
            }}
          >
            Delete
          </button>
        </AlertDialog.Footer>
      </AlertDialog.Popup>
    </AlertDialog.Root>
  );
};

Root owns open state. Run the confirmed action in its event handler and close the dialog when it completes. For asynchronous actions, keep it open while pending and show an error if the action fails.

Parts and sizing

Part	Purpose
`Root`	Coordinates open state and modal behavior.
`Trigger`	Opens the dialog.
`Popup`	Includes the portal, backdrop, viewport, and dialog content.
`Title`, `Description`	Name the dialog and explain the decision.
`Header`	Groups the title and description.
`Body`	Holds optional additional content.
`Footer`	Groups confirmation and cancellation actions.
`Close`	Closes the dialog without running the confirmation action.

Popup.size defaults to md; see the reference for supported sizes. Use container to override the theme’s portal container and keepMounted to retain mounted content when closed.

Focus and dismissal

The dialog traps focus while open. Escape can dismiss it; clicking the backdrop does not. Always provide a visible Cancel or Close action. Keep the initial focus on the least destructive action, and preserve a meaningful return focus target when the action removes its trigger. Use Popup.initialFocus and Popup.finalFocus to customize focus behavior.

Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.

AlertDialog.Root

RefObject<DialogRootActions | null>

A ref to imperative actions.

unmount: Manually unmounts the alert dialog. Call this after any externally controlled closing animation finishes.
close: Closes the alert dialog imperatively when called.

ReactNode | PayloadChildRenderFunction<Payload>

The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger.

boolean

default:"false"

Whether the dialog is initially open.To render a controlled dialog, use the open prop instead.

string | null

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.

AlertDialogHandle<Payload>

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.

((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void)

Event handler called when the alert dialog is opened or closed.

((open: boolean) => void)

Event handler called after any animations complete when the dialog is opened or closed.

boolean

Whether the dialog is currently open.

string | null

ID of the trigger that the dialog is associated with. This is useful in conjunction with the open prop to create a controlled dialog. There’s no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).

AlertDialog.Trigger

string | ((state: DialogTriggerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

AlertDialogHandle<Payload>

A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method.

string

ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot triggerId prop).

boolean

default:"true"

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 (for example, <div>).

Payload

A payload to pass to the dialog when it is opened.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>

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.

CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

CSS class applied to the element, or a function that returns a class based on the component’s state.

Element the dialog is portaled into. Defaults to the theme’s portal container.

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, null to fall back to the default behavior, or false/undefined to do nothing.

Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.

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, null to fall back to the default behavior, or false/undefined to do nothing.

Keeps the dialog mounted in the DOM while it is closed.

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.

Width of the dialog, or fullscreen to fill the viewport.

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Title

string | ((state: DialogTitleState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>

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.

CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Description

string | ((state: DialogDescriptionState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>

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.

CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Close

string | ((state: DialogCloseState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

default:"true"

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 (for example, <div>).

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>

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.

CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Header

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

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.

AlertDialog.Body

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

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.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

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.

Guides

Forms

Navigation

Surfaces

Feedback

Typography

Confirmation

Parts and sizing

Focus and dismissal

Props

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer

​Confirmation

​Parts and sizing

​Focus and dismissal

​Props

​AlertDialog.Root

​AlertDialog.Trigger

​AlertDialog.Popup

​AlertDialog.Title

​AlertDialog.Description

​AlertDialog.Close

​AlertDialog.Header

​AlertDialog.Body

​AlertDialog.Footer

Confirmation

Parts and sizing

Focus and dismissal

Props

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Popup

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer