AlertDialog

Use AlertDialog for a decision that interrupts the current workflow, such as confirming deletion. It provides alertdialog semantics, focus management, and explicit confirmation or cancellation. This primitive is for standalone Twenty UI and host-owned interfaces. Front components must request a confirmation through the SDK host dialog API. Direct Dialog, AlertDialog, and native browser dialogs are prohibited inside the front component renderer.

Usage

Uncontrolled state

Use defaultOpen to set the initial visibility. The dialog owns subsequent changes from its trigger, close controls, and dismissal interactions.

import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

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

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root defaultOpen={false}>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);

defaultOpen defaults to false, so it can be omitted. This example uses a synchronous confirmation callback and closes after the action runs.

Anatomy

Keep related parts inside AlertDialog.Root, or connect detached triggers through a handle. Compose the portal, backdrop, viewport, and popup separately.

AlertDialog.Root
├── AlertDialog.Trigger
└── AlertDialog.Portal
    ├── AlertDialog.Backdrop
    └── AlertDialog.Viewport
        └── AlertDialog.Popup
            ├── AlertDialog.Header
            │   ├── AlertDialog.Title
            │   └── AlertDialog.Description
            ├── AlertDialog.Body
            └── AlertDialog.Footer
                ├── AlertDialog.Close
                └── Confirmation action

Part	Requirement	Purpose
`Root`	Required	Coordinates open state and modal behavior.
`Trigger`	Optional for a programmatically opened dialog	Opens the dialog and provides a return focus target.
`Portal`	Recommended	Moves the overlay to its container and controls mounting.
`Backdrop`	Optional	Visually separates the alert from the surrounding page.
`Viewport`	Recommended	Positions the popup and provides its scrollable surrounding area.
`Popup`	Required	Renders the alert content with focus management.
`Title`	Recommended	Supplies the visible alert name. An accessible name is always required.
`Description`	Recommended for a confirmation	Explains the decision and its consequences.
`Header`, `Body`, `Footer`	Optional layout parts	Arrange headings, additional content, and actions.
`Close`	Recommended for cancellation	Supplies an explicit close action.

Set container and keepMounted on Portal, backdrop attributes on Backdrop, layout attributes on Viewport, and size and focus props on Popup. Each element part accepts its own native attributes, handlers, ref, and render composition. Popup.ref points to the alert content element. Title and Description establish the accessible relationships; provide aria-label on Popup when omitting a title. The confirmation action is application content, not an exported part. Use Close with a synchronous handler or a Button with controlled open state for asynchronous confirmation.

Controlled state

Pass open and update it with onOpenChange to own the same dialog’s visibility in React state. The callback receives the requested boolean and upstream event details, including reason, event, and cancel(). Call eventDetails.cancel() to reject a requested change. onOpenChangeComplete runs after opening or closing transitions finish.

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

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

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

  return (
    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Trigger
        render={<Button variant="solid">Delete record</Button>}
      />
      <AlertDialog.Portal>
        <AlertDialog.Backdrop />
        <AlertDialog.Viewport>
          <AlertDialog.Popup>
            <AlertDialog.Header>
              <AlertDialog.Title>Delete this record?</AlertDialog.Title>
              <AlertDialog.Description>
                This record will be permanently deleted. This action cannot be
                undone.
              </AlertDialog.Description>
            </AlertDialog.Header>
            <AlertDialog.Footer>
              <AlertDialog.Close render={<Button>Cancel</Button>} />
              <AlertDialog.Close
                onClick={onDelete}
                render={<Button color="danger">Delete</Button>}
              />
            </AlertDialog.Footer>
          </AlertDialog.Popup>
        </AlertDialog.Viewport>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
};

For asynchronous confirmation, use a Button with your action handler instead of AlertDialog.Close. Keep open true while the action is pending, call setOpen(false) after it succeeds, and show an error inside the dialog if it fails.

Compose with buttons

Use render to give the trigger and close controls Twenty UI button styling. The dialog parts supply their interaction handlers and refs to the buttons.

import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

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

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);

Keep each action as a single interactive control. If you wrap Button in your own component, forward the supplied props and ref.

Detached triggers and imperative actions

Create a handle once with AlertDialog.createHandle<Payload>() and pass it to handle on Root and each detached Trigger. A trigger’s typed payload is available to the root’s child render function. A handle also supports open(triggerId), openWithPayload(payload), close(), and the isOpen getter while its root is mounted. Pass a matching trigger ID to open, or null to open without a trigger. Call imperative methods from event handlers or effects. Root.actionsRef exposes close() and unmount(). For an externally controlled closing animation, call eventDetails.preventUnmountOnClose() in onOpenChange, then call actionsRef.current?.unmount() after the animation finishes. The regular styled parts manage their own transitions without these imperative actions.

Sizing and portals

Popup.size accepts sm, md, lg, xl, and fullscreen, and defaults to md. Size and appearance belong to the AlertDialog surface and do not have to match Dialog presets. Portal.container defaults to the nearest theme’s portal container. Without one, Base UI uses its default portal destination, normally document.body. An explicit element, shadow root, or ref overrides that destination. An explicit null defers mounting until a container is available. Base UI resolves a ref whose current is null using its default destination; use container={null} when mounting must wait. Portaled content retains the theme context. Portal and Viewport inherit the provided text direction unless you set dir explicitly. Set Portal.keepMounted to retain mounted content and form state while closed.

Focus and dismissal

The alert traps focus, blocks outside interaction, and locks page scrolling while open. Escape requests closure; clicking outside does not. To prevent Escape dismissal, cancel the escape-key change in onOpenChange. Always provide a visible Cancel or Close action. By default, focus moves to the first tabbable control, or to the popup for a touch opening. Put the least destructive action first, or use Popup.initialFocus to select it. Focus returns to the trigger or previously focused element when the alert closes. Use Popup.finalFocus when a successful action removes that target. Both focus props accept a boolean, element ref, or interaction-type callback according to the upstream contract.

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: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the alert dialog completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
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.

AlertDialog.Portal

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

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

Portal destination. Omission uses the theme container or Base UI default; explicit null defers mounting. A ref with a null current value uses the Base UI default destination.

boolean

default:"false"

Keeps content mounted while the alert is closed.

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

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: DialogPortalState) => CSSProperties | undefined)

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

AlertDialog.Backdrop

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

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

boolean

default:"false"

Whether the backdrop is forced to render even when nested.

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

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: DialogBackdropState) => CSSProperties | undefined)

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

AlertDialog.Viewport

string | ((state: DialogViewportState) => 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, DialogViewportState>

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: DialogViewportState) => 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.

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.

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 alert, 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.

Overview

Apps

API

Self-Host

Contribute

UI Library

Usage

Uncontrolled state

Anatomy

Controlled state

Compose with buttons

Detached triggers and imperative actions

Sizing and portals

Focus and dismissal

Props

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Portal

AlertDialog.Backdrop

AlertDialog.Viewport

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer

​Usage

​Uncontrolled state

​Anatomy

​Controlled state

​Compose with buttons

​Detached triggers and imperative actions

​Sizing and portals

​Focus and dismissal

​Props

​AlertDialog.Root

​AlertDialog.Trigger

​AlertDialog.Portal

​AlertDialog.Backdrop

​AlertDialog.Viewport

​AlertDialog.Popup

​AlertDialog.Title

​AlertDialog.Description

​AlertDialog.Close

​AlertDialog.Header

​AlertDialog.Body

​AlertDialog.Footer

Usage

Uncontrolled state

Anatomy

Controlled state

Compose with buttons

Detached triggers and imperative actions

Sizing and portals

Focus and dismissal

Props

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Portal

AlertDialog.Backdrop

AlertDialog.Viewport

AlertDialog.Popup

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer