Alert Dialog

In Nyte

import { AlertDialog } from "@nyte-ai/ui/alert-dialog";

@nyte-ai/ui/alert-dialog re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

• desktop/src/renderer/src/components/confirm-dialog.tsx

The rest of this page is Base UI's documentation for @base-ui/react/alert-dialog, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above.

Anatomy

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.

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.

The imperative methods on the handle, such as open() and openWithPayload(), require an <AlertDialog.Root> using the same handle to be mounted. Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.

const demoAlertDialog = AlertDialog.createHandle();

// @highlight
// @highlight-text "handle={demoAlertDialog}"
<AlertDialog.Trigger handle={demoAlertDialog}>Open</AlertDialog.Trigger>

// @highlight
// @highlight-text "handle={demoAlertDialog}"
<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:

// @highlight
const demoAlertDialog = AlertDialog.createHandle<{ message: string }>();

// @highlight
// @highlight-text "payload"
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 1' }}>
  Trigger 1
</AlertDialog.Trigger>

// @highlight
// @highlight-text "payload"
<AlertDialog.Trigger handle={demoAlertDialog} payload={{ message: 'Trigger 2' }}>
  Trigger 2
</AlertDialog.Trigger>

<AlertDialog.Root handle={demoAlertDialog}>
  {({ payload }) => ( // @highlight-text "payload"
    <AlertDialog.Portal>
      <AlertDialog.Popup>
        <AlertDialog.Title>Alert dialog</AlertDialog.Title>
        {payload !== undefined && ( // @highlight-text "payload"
          <AlertDialog.Description>
            Confirming {payload.message} {/* @highlight-text "payload" */}
          </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.

Root Props:

Root.Props

Re-export of Root props.

Root.State

type AlertDialogRootState = {};

Root.Actions

type AlertDialogRootActions = { unmount: () => void; close: () => void };

Root.ChangeEventReason

type AlertDialogRootChangeEventReason =
  | 'trigger-press'
  | 'outside-press'
  | 'escape-key'
  | 'close-press'
  | 'focus-out'
  | 'imperative-action'
  | 'none';

Root.ChangeEventDetails

type AlertDialogRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'focus-out'; event: KeyboardEvent | FocusEvent }
  | { reason: 'imperative-action'; event: Event }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  preventUnmountOnClose: preventUnmountOnClose;
};

Trigger

A button that opens the alert dialog. Renders a <button> element.

Trigger Props:

Trigger Data Attributes:

Trigger.Props

Re-export of Trigger props.

Trigger.State

type AlertDialogTriggerState = {
  /** Whether the trigger is currently disabled. */
  disabled: boolean;
  /** Whether the dialog is currently open and was opened by this trigger. */
  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.

Portal Props:

Portal.Props

Re-export of Portal props.

Portal.State

type AlertDialogPortalState = {};

Backdrop

An overlay displayed beneath the popup. Renders a <div> element.

Backdrop Props:

Backdrop Data Attributes:

Backdrop.Props

Re-export of Backdrop props.

Backdrop.State

type AlertDialogBackdropState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Popup

A container for the dialog contents. Renders a <div> element.

Popup Props:

Popup Data Attributes:

Popup CSS Variables:

Popup.Props

Re-export of Popup props.

Popup.State

type AlertDialogPopupState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within a parent dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};

Title

A heading that labels the dialog. Renders an <h2> element.

Title Props:

Title.Props

Re-export of Title props.

Title.State

type AlertDialogTitleState = {};

Description

A paragraph with additional information about the dialog. Renders a <p> element.

Description Props:

Description.Props

Re-export of Description props.

Description.State

type AlertDialogDescriptionState = {};

Close

A button that closes the dialog. Renders a <button> element.

Close Props:

Close Data Attributes:

Close.Props

Re-export of Close props.

Close.State

type AlertDialogCloseState = {
  /** Whether the button is currently disabled. */
  disabled: boolean;
};

Viewport

A positioning container for the dialog popup that can be made scrollable. Renders a <div> element.

Viewport Props:

Viewport Data Attributes:

Viewport.Props

Re-export of Viewport props.

Viewport.State

type AlertDialogViewportState = {
  /** Whether the dialog is currently open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the dialog is nested within another dialog. */
  nested: boolean;
  /** Whether the dialog has nested dialogs open. */
  nestedDialogOpen: boolean;
};

createHandle

Creates a new handle to connect an AlertDialog.Root with detached AlertDialog.Trigger components.

Return Value:

type ReturnValue = AlertDialog.Handle<Payload>;

Handle

Controls an Alert Dialog imperatively and associates detached AlertDialog.Trigger components with an AlertDialog.Root. Create one with AlertDialog.createHandle() and pass it to the handle prop of the root and of any triggers rendered outside of it.

The imperative methods take effect only while a root using this handle is mounted; calls made before a root attaches (or after it unmounts) are ignored.

Properties:

Methods:

function open(triggerId: string | null): void;

Opens the dialog, optionally associating it with a trigger.

This method should only be called in an event handler or an effect (not during rendering).

function openWithPayload(payload: Payload): void;

Opens the dialog with the given payload, without associating it with any trigger.

This method should only be called in an event handler or an effect (not during rendering).

function close(): void;

Closes the dialog.

This method should only be called in an event handler or an effect (not during rendering).

External Types

PayloadChildRenderFunction

type PayloadChildRenderFunction = (arg: { payload: unknown | undefined }) => ReactNode;

preventUnmountOnClose

type preventUnmountOnClose = () => void;

InteractionType

type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';

Export Groups

• AlertDialog.Root: AlertDialog.Root, AlertDialog.Root.State, AlertDialog.Root.Props, AlertDialog.Root.Actions, AlertDialog.Root.ChangeEventReason, AlertDialog.Root.ChangeEventDetails
• AlertDialog.Backdrop: AlertDialog.Backdrop, AlertDialog.Backdrop.Props, AlertDialog.Backdrop.State
• AlertDialog.Close: AlertDialog.Close, AlertDialog.Close.Props, AlertDialog.Close.State
• AlertDialog.Description: AlertDialog.Description, AlertDialog.Description.Props, AlertDialog.Description.State
• AlertDialog.Popup: AlertDialog.Popup, AlertDialog.Popup.Props, AlertDialog.Popup.State
• AlertDialog.Portal: AlertDialog.Portal, AlertDialog.Portal.State, AlertDialog.Portal.Props
• AlertDialog.Title: AlertDialog.Title, AlertDialog.Title.Props, AlertDialog.Title.State
• AlertDialog.Trigger: AlertDialog.Trigger, AlertDialog.Trigger.Props, AlertDialog.Trigger.State
• AlertDialog.Viewport: AlertDialog.Viewport, AlertDialog.Viewport.State, AlertDialog.Viewport.Props
• AlertDialog.Handle
• AlertDialog.createHandle
• Default: AlertDialogBackdropProps, AlertDialogBackdropState, AlertDialogCloseProps, AlertDialogCloseState, AlertDialogDescriptionProps, AlertDialogDescriptionState, AlertDialogPopupProps, AlertDialogPopupState, AlertDialogPortalProps, AlertDialogPortalState, AlertDialogTitleProps, AlertDialogTitleState, AlertDialogViewportProps, AlertDialogViewportState, AlertDialogRootState, AlertDialogRootProps, AlertDialogRootActions, AlertDialogRootChangeEventReason, AlertDialogRootChangeEventDetails, AlertDialogTriggerProps, AlertDialogTriggerState

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

• AlertDialog.Root.State: AlertDialogRootState
• AlertDialog.Root.Props: AlertDialogRootProps
• AlertDialog.Root.Actions: AlertDialogRootActions
• AlertDialog.Root.ChangeEventReason: AlertDialogRootChangeEventReason
• AlertDialog.Root.ChangeEventDetails: AlertDialogRootChangeEventDetails
• AlertDialog.Backdrop.Props: AlertDialogBackdropProps
• AlertDialog.Backdrop.State: AlertDialogBackdropState
• AlertDialog.Close.Props: AlertDialogCloseProps
• AlertDialog.Close.State: AlertDialogCloseState
• AlertDialog.Description.Props: AlertDialogDescriptionProps
• AlertDialog.Description.State: AlertDialogDescriptionState
• AlertDialog.Popup.Props: AlertDialogPopupProps
• AlertDialog.Popup.State: AlertDialogPopupState
• AlertDialog.Portal.State: AlertDialogPortalState
• AlertDialog.Portal.Props: AlertDialogPortalProps
• AlertDialog.Title.Props: AlertDialogTitleProps
• AlertDialog.Title.State: AlertDialogTitleState
• AlertDialog.Trigger.Props: AlertDialogTriggerProps
• AlertDialog.Trigger.State: AlertDialogTriggerState
• AlertDialog.Viewport.State: AlertDialogViewportState
• AlertDialog.Viewport.Props: AlertDialogViewportProps