> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AlertDialog

> Richiedi una conferma prima di un'azione che necessita di una decisione esplicita.

## 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](https://docs.twenty.com/it/developers/extend/apps/layout/front-components.md#host-communication-api). `Dialog`, `AlertDialog` e le finestre di dialogo native del browser dirette sono vietati all'interno del renderer del componente frontale.

**Light**

[Esempio di AlertDialog (light)](https://storybook.twenty.com/iframe.html?id=ui-surfaces-alertdialog--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Esempio di AlertDialog (dark)](https://storybook.twenty.com/iframe.html?id=ui-surfaces-alertdialog--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-surfaces-alertdialog--display)

## 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.

```tsx theme={null}
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.

```text theme={null}
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.

```tsx theme={null}
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.

```tsx theme={null}
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](https://docs.twenty.com/it/ui/primitives/overview#custom-components).

## 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

**Root.actionsRef** `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.

**Root.children** `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.

**Root.defaultOpen** `boolean` (default: false)

Whether the dialog is initially open.

To render a controlled dialog, use the `open` prop instead.

**Root.defaultTriggerId** `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.

**Root.handle** `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.

**Root.onOpenChange** `((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) =\> void)`

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

**Root.onOpenChangeComplete** `((open: boolean) =\> void)`

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

**Root.open** `boolean`

Whether the dialog is currently open.

**Root.triggerId** `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

**Trigger.className** `string | ((state: DialogTriggerState) =\> string | undefined)`

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

**Trigger.handle** `AlertDialogHandle\<Payload\>`

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

**Trigger.id** `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).

**Trigger.nativeButton** `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>`).

**Trigger.payload** `Payload`

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

**Trigger.render** `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.

**Trigger.style** `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

**Portal.className** `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.container** `HTMLElement | ShadowRoot | RefObject\<HTMLElement | ShadowRoot | null\> | null`

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.

**Portal.keepMounted** `boolean` (default: false)

Keeps content mounted while the alert is closed.

**Portal.render** `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.

**Portal.style** `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

**Backdrop.className** `string | ((state: DialogBackdropState) =\> string | undefined)`

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

**Backdrop.forceRender** `boolean` (default: false)

Whether the backdrop is forced to render even when nested.

**Backdrop.render** `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.

**Backdrop.style** `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

**Viewport.className** `string | ((state: DialogViewportState) =\> string | undefined)`

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

**Viewport.render** `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.

**Viewport.style** `CSSProperties | ((state: DialogViewportState) =\> CSSProperties | undefined)`

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

### AlertDialog.Popup

**Popup.className** `string | ((state: DialogPopupState) =\> string | undefined)`

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

**Popup.finalFocus** `boolean | RefObject\<HTMLElement | null\> | ((closeType: InteractionType) =\> boolean | void | HTMLElement | null)`

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.

**Popup.initialFocus** `boolean | RefObject\<HTMLElement | null\> | ((openType: InteractionType) =\> boolean | void | HTMLElement | null)`

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.

**Popup.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogPopupState\>`

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.

**Popup.size** `"fullscreen" | "lg" | "md" | "sm" | "xl"` (default: md)

Width of the alert, or `fullscreen` to fill the viewport.

**Popup.style** `CSSProperties | ((state: DialogPopupState) =\> CSSProperties | undefined)`

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

### AlertDialog.Title

**Title.className** `string | ((state: DialogTitleState) =\> string | undefined)`

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

**Title.render** `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.

**Title.style** `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

**Description.className** `string | ((state: DialogDescriptionState) =\> string | undefined)`

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

**Description.render** `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.

**Description.style** `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

**Close.className** `string | ((state: DialogCloseState) =\> string | undefined)`

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

**Close.nativeButton** `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>`).

**Close.render** `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.

**Close.style** `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

**Header.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.

### AlertDialog.Body

**Body.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.

### AlertDialog.Footer

**Footer.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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.