AlertDialog

Panoramica

Usa AlertDialog per una decisione che interrompe il flusso di lavoro corrente, ad esempio per confermare l’eliminazione. Fornisce semantica alertdialog, gestione del focus e conferma o annullamento espliciti. Questa primitiva è destinata a interfacce Twenty UI autonome e controllate dall’host. I componenti Front devono richiedere una conferma tramite l’API della finestra di dialogo host dell’SDK. Dialog, AlertDialog e le finestre di dialogo native del browser dirette sono vietati all’interno del renderer del componente frontale.

Utilizzo

Stato non controllato

Usa defaultOpen per impostare la visibilità iniziale. La finestra di dialogo gestisce le modifiche successive dal relativo trigger, dai controlli di chiusura e dalle interazioni di chiusura.

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 è impostato su false per impostazione predefinita, quindi può essere omesso. Questo esempio usa una callback di conferma sincrona e si chiude dopo l’esecuzione dell’azione.

Anatomia

Mantieni le parti correlate all’interno di AlertDialog.Root oppure collega i trigger separati tramite un handle. Componi separatamente il portale, lo sfondo, il viewport e il popup.

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

Parte	Requisito	Scopo
`Root`	Obbligatorio	Coordina lo stato di apertura e il comportamento modale.
`Trigger`	Facoltativo per una finestra di dialogo aperta programmaticamente	Apre la finestra di dialogo e fornisce una destinazione per la restituzione del focus.
`Portal`	Consigliato	Sposta l’overlay nel relativo contenitore e controlla il montaggio.
`Backdrop`	Facoltativo	Separa visivamente l’avviso dalla pagina circostante.
`Viewport`	Consigliato	Posiziona il popup e fornisce l’area circostante scorrevole.
`Popup`	Obbligatorio	Esegue il rendering del contenuto dell’avviso con la gestione del focus.
`Titolo`	Consigliato	Fornisce il nome visibile dell’avviso. Un nome accessibile è sempre obbligatorio.
`Description`	Consigliato per una conferma	Spiega la decisione e le sue conseguenze.
`Header`, `Body`, `Footer`	Parti facoltative del layout	Organizzano intestazioni, contenuti aggiuntivi e azioni.
`Chiudi`	Consigliato per l’annullamento	Fornisce un’azione di chiusura esplicita.

Imposta container e keepMounted su Portal, gli attributi dello sfondo su Backdrop, gli attributi di layout su Viewport e le prop size e focus su Popup. Ogni parte dell’elemento accetta i propri attributi nativi, gestori, ref e composizione render. Popup.ref punta all’elemento di contenuto dell’avviso. Title e Description stabiliscono le relazioni di accessibilità; fornisci aria-label su Popup quando ometti un titolo. L’azione di conferma è contenuto dell’applicazione, non una parte esportata. Usa Close con un gestore sincrono o un Button con stato di apertura controllato per la conferma asincrona.

Stato controllato

Passa open e aggiornalo con onOpenChange per gestire la visibilità della stessa finestra di dialogo nello stato di React. Il callback riceve il valore booleano richiesto e i dettagli dell’evento a monte, inclusi reason, event e cancel(). Chiama eventDetails.cancel() per rifiutare una modifica richiesta. onOpenChangeComplete viene eseguito dopo il completamento delle transizioni di apertura o chiusura.

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>
  );
};

Per la conferma asincrona, usa un Button con il gestore dell’azione invece di AlertDialog.Close. Mantieni open su true mentre l’azione è in corso, chiama setOpen(false) dopo che ha avuto esito positivo e mostra un errore nella finestra di dialogo se non riesce.

Componi con pulsanti

Usa render per applicare all’attivatore e ai controlli di chiusura lo stile dei pulsanti di Twenty UI. Le parti della finestra di dialogo forniscono ai pulsanti i rispettivi gestori di interazione e ref.

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>
);

Mantieni ogni azione come un singolo controllo interattivo. Se includi Button nel tuo componente, inoltra le props e il ref forniti.

Trigger separati e azioni imperative

Crea un handle una volta con AlertDialog.createHandle\<Payload>() e passalo a handle su Root e su ogni Trigger separato. Il payload tipizzato di un trigger è disponibile per la funzione di rendering figlia della root. Un handle supporta anche open(triggerId), openWithPayload(payload), close() e il getter isOpen mentre la relativa root è montata. Passa a open un ID trigger corrispondente, oppure null per aprire senza un trigger. Chiama i metodi imperativi dai gestori di eventi o dagli effetti. Root.actionsRef espone close() e unmount(). Per un’animazione di chiusura controllata esternamente, chiama eventDetails.preventUnmountOnClose() in onOpenChange, quindi chiama actionsRef.current?.unmount() dopo il completamento dell’animazione. Le normali parti con stile gestiscono le proprie transizioni senza queste azioni imperative.

Dimensionamento e portali

Popup.size accetta sm, md, lg, xl e fullscreen e il valore predefinito è md. Dimensione e aspetto appartengono alla superficie di AlertDialog e non devono corrispondere ai preset di Dialog. Portal.container usa per impostazione predefinita il contenitore del portale del tema più vicino. In assenza di uno, Base UI usa la destinazione del portale predefinita, normalmente document.body. Un elemento esplicito, una shadow root o un ref sostituisce tale destinazione. Un valore null esplicito rinvia il montaggio finché non è disponibile un contenitore. Base UI risolve un ref il cui current è null usando la propria destinazione predefinita; usa container={null} quando il montaggio deve attendere. Il contenuto inserito nel portale mantiene il contesto del tema. Portal e Viewport ereditano la direzione del testo fornita, a meno che tu non imposti esplicitamente dir. Imposta Portal.keepMounted per conservare il contenuto montato e lo stato del modulo durante la chiusura.

Stato attivo e chiusura

L’avviso intrappola il focus, blocca l’interazione esterna e blocca lo scorrimento della pagina mentre è aperto. Escape richiede la chiusura; fare clic all’esterno no. Per impedire la chiusura con Escape, annulla la modifica escape-key in onOpenChange. Fornisci sempre un’azione Annulla o Chiudi visibile. Per impostazione predefinita, il focus passa al primo controllo selezionabile tramite Tab oppure al popup per un’apertura tramite tocco. Metti per prima l’azione meno distruttiva oppure usa Popup.initialFocus per selezionarla. Il focus torna al trigger o all’elemento precedentemente focalizzato quando l’avviso si chiude. Usa Popup.finalFocus quando un’azione riuscita rimuove quella destinazione. Entrambe le prop di focus accettano un booleano, un ref di elemento o un callback di tipo di interazione secondo il contratto a monte.

Props

Il riferimento viene generato dai tipi di componente pubblici. Gli attributi nativi, inclusi i nomi accessibili e i gestori di eventi, sono accettati anche nelle parti che eseguono il rendering degli elementi.

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

predefinito:"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

predefinito:"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

predefinito:"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

predefinito:"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

predefinito:"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.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Stato non controllato

Anatomia

Stato controllato

Componi con pulsanti

Trigger separati e azioni imperative

Dimensionamento e portali

Stato attivo e chiusura

Props

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Portal

AlertDialog.Backdrop

AlertDialog.Viewport

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer

​Panoramica

​Utilizzo

​Stato non controllato

​Anatomia

​Stato controllato

​Componi con pulsanti

​Trigger separati e azioni imperative

​Dimensionamento e portali

​Stato attivo e chiusura

​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

Panoramica

Utilizzo

Stato non controllato

Anatomia

Stato controllato

Componi con pulsanti

Trigger separati e azioni imperative

Dimensionamento e portali

Stato attivo e chiusura

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