Dialog

Panoramica

Usa Dialog per moduli, dettagli e altre attività che si aprono sopra la pagina. Gestisce il focus, la chiusura tramite tastiera, i clic esterni e lo scorrimento. Usa AlertDialog quando l’utente deve rispondere esplicitamente a una decisione. Questa API è destinata a Twenty UI autonomo e all’applicazione host Twenty. I componenti front devono utilizzare openCommandConfirmationModal dell’SDK invece di eseguire direttamente il rendering di Dialog o AlertDialog. Anche le finestre di dialogo e i popover nativi del browser sono vietati nel renderer dei componenti front.

Utilizzo

Stato non controllato

Root gestisce la visibilità per impostazione predefinita. Imposta defaultOpen per il relativo stato iniziale. Trigger, controlli di chiusura, Escape e clic esterni aggiornano tale stato.

import { Button, Field, Input } from 'twenty-ui/primitives/input';
import { Dialog } from 'twenty-ui/primitives/surfaces';

export const AccountDialog = () => (
  <Dialog.Root defaultOpen={false}>
    <Dialog.Trigger render={<Button>Edit account</Button>} />
    <Dialog.Portal>
      <Dialog.Backdrop />
      <Dialog.Viewport>
        <Dialog.Popup>
          <Dialog.Header>
            <Dialog.Title>Edit account</Dialog.Title>
            <Dialog.Description>Update the account details.</Dialog.Description>
          </Dialog.Header>
          <Dialog.Body>
            <Field.Root name="company">
              <Field.Label>Company name</Field.Label>
              <Input defaultValue="Acme" />
            </Field.Root>
          </Dialog.Body>
          <Dialog.Footer>
            <Dialog.Close render={<Button variant="outline">Close</Button>} />
            <Dialog.Close render={<Button>Save</Button>} />
          </Dialog.Footer>
        </Dialog.Popup>
      </Dialog.Viewport>
    </Dialog.Portal>
  </Dialog.Root>
);

Anatomia

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

Parte	Target nativo e ref
`Root`	Coordina la visibilità e il comportamento modale. Non esegue il rendering di alcun nodo DOM e non accetta attributi nativi né ref DOM.
`Trigger`	Un pulsante per impostazione predefinita. Apre la finestra di dialogo e fornisce una destinazione per il ripristino dello stato attivo.
`Portal`	Il div del portale. Gestisce il contenitore di destinazione e se il contenuto chiuso rimane montato.
`Backdrop`	Il div dello sfondo sotto il popup. Facoltativo; ometterlo quando non è necessario alcuno sfondo visibile.
`Viewport`	Il div di posizionamento attorno al popup.
`Popup`	Il div della finestra di dialogo. Gestisce il contenuto, le dimensioni, le destinazioni dello stato attivo e la semantica della finestra di dialogo.
`Titolo`	Un `h2` per impostazione predefinita. Fornisce il nome accessibile. Fornisci `aria-label` in `Popup` quando lo ometti.
`Description`	Un paragrafo per impostazione predefinita. Associa il testo di supporto alla finestra di dialogo.
`Header`, `Body`, `Footer`	Div facoltativi che dispongono titoli, contenuto e azioni.
`Chiudi`	Un pulsante per impostazione predefinita. Fornisce un’azione di chiusura visibile, anche per i lettori di schermo touch.

Assembla esplicitamente Portal, Backdrop, Viewport e Popup. Ogni parte DOM accetta i propri attributi nativi, gestori, className, style, ref e composizione render. Una ref punta all’elemento di cui quella parte esegue il rendering. Popup non crea un portale, uno sfondo o una viewport.

Stato controllato

Passa open e onOpenChange quando l’applicazione gestisce la visibilità. Il callback riceve lo stato richiesto e i dettagli dell’evento Base UI, inclusi reason, event, trigger e cancel(). Aggiorna lo stato per accettare una modifica oppure chiama eventDetails.cancel() per rifiutarla. onOpenChangeComplete viene eseguito al termine dell’animazione di apertura o chiusura.

import { useState } from 'react';
import { Button, Field, Input } from 'twenty-ui/primitives/input';
import { Dialog } from 'twenty-ui/primitives/surfaces';

export const AccountDialog = () => {
  const [open, setOpen] = useState(false);

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger render={<Button>Edit account</Button>} />
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Viewport>
          <Dialog.Popup>
            <Dialog.Header>
              <Dialog.Title>Edit account</Dialog.Title>
              <Dialog.Description>
                Update the account details.
              </Dialog.Description>
            </Dialog.Header>
            <Dialog.Body>
              <Field.Root name="company">
                <Field.Label>Company name</Field.Label>
                <Input defaultValue="Acme" />
              </Field.Root>
            </Dialog.Body>
            <Dialog.Footer>
              <Dialog.Close render={<Button variant="outline">Close</Button>} />
              <Dialog.Close render={<Button>Save</Button>} />
            </Dialog.Footer>
          </Dialog.Popup>
        </Dialog.Viewport>
      </Dialog.Portal>
    </Dialog.Root>
  );
};

Per un modulo asincrono, mantieni aperta la finestra di dialogo durante l’invio. Chiudila dopo l’operazione riuscita e mostra gli errori all’interno della finestra di dialogo.

Composizione

Trigger e Close accettano render per comporsi con Button, come mostrato sopra. I wrapper personalizzati devono inoltrare le props e i ref forniti. Le parti DOM mantengono i nomi delle classi, gli stili e i contratti callback render di Base UI che tengono conto dello stato. Header, Body e Footer mantengono il proprio layout con stile e la composizione div nativa. Annida un altro Dialog.Root all’interno di un popup per aprire una seconda finestra di dialogo. La chiusura della finestra di dialogo annidata restituisce il focus al relativo trigger nel componente padre. Per aprire una finestra di dialogo da trigger esterni a Root, crea una volta un handle con Dialog.createHandle\<TPayload>() e passalo a handle sia in Root sia in ogni Trigger. I valori di payload del trigger sono disponibili nella funzione di rendering di Root. Dialog.Handle e il tipo pubblico DialogHandle espongono il contratto dell’handle installato:

Membro	Scopo
`open(triggerId)`	Apre con un trigger corrispondente come trigger attivo.
`open(null)`	Apre senza associare un trigger.
`openWithPayload(payload)`	Apre con un payload tipizzato e senza trigger associato.
`close()`	Richiede la chiusura.
`isOpen`	Indica se la finestra di dialogo associata è aperta.

Le azioni imperative hanno effetto solo mentre il Root associato è montato. actionsRef di Root espone anche close() e unmount() per un controllo esplicito della transizione. Per controllare un’animazione di chiusura esterna, chiama eventDetails.preventUnmountOnClose() in onOpenChange, quindi chiama l’azione unmount() al termine dell’animazione. Title usa Heading e per impostazione predefinita è un h2 con testo grande, colore del testo primario, allineamento centrato e spacing-4 sotto di esso. Usa level per modificare il livello dell’intestazione indipendentemente da size, oppure color per modificarne il colore del testo. className, style, i ref e render nativi vengono inoltrati all’intestazione. Mantieni un elemento di intestazione quando usi render. Description è centrata come Title; AlertDialog mantiene entrambi allineati a sinistra. Popup non ha alcuna spaziatura interna. Header, Body e Footer forniscono il rientro, quindi il contenuto posizionato direttamente in Popup aderisce ai suoi bordi.

Focus, scorrimento e chiusura

Root.modal controlla il confine di interazione:

Valore	Focus	Scorrimento della pagina e interazione esterna
`true` (predefinito)	Bloccato all’interno della finestra di dialogo	Lo scorrimento della pagina e l’interazione esterna sono bloccati.
`"trap-focus"`	Intrappolato nella finestra di dialogo	Lo scorrimento della pagina e l’interazione esterna rimangono disponibili.
`falso`	Può uscire dalla finestra di dialogo	Lo scorrimento della pagina e l’interazione esterna rimangono disponibili.

Ometti Backdrop quando non è necessario alcuno sfondo visibile. Per una finestra di dialogo non modale la cui viewport deve lasciare passare gli eventi del puntatore alla pagina, utilizza \<Dialog.Viewport data-backdrop-hidden="true">; Popup rimane interattivo. La sola omissione dello sfondo visivo non modifica Root.modal. Imposta Popup.initialFocus o Popup.finalFocus su un ref o un callback per scegliere le destinazioni del focus; false disabilita quello spostamento automatico del focus. I callback dello stato attivo ricevono il tipo di interazione e mantengono il comportamento di restituzione booleano, elemento, null e undefined di Base UI. La chiusura normalmente ripristina lo stato attivo sul trigger o sull’elemento precedentemente attivo. Root.disablePointerDismissal impedisce ai clic esterni di richiedere la chiusura. Per impedire la chiusura con Escape, annulla la modifica escape-key in onOpenChange. Fornisci sempre un modo visibile per chiudere una finestra di dialogo modale.

Dimensioni e portali

Popup.size accetta sm, compact, md, lg, xl e fullscreen e per impostazione predefinita è md. Il contenuto lungo scorre all’interno del popup. La larghezza è limitata alla viewport. Imposta Portal.container per scegliere una destinazione:

Valore	Risoluzione
Omettere o `undefined`	Utilizza il contenitore del tema con ambito più vicino. In assenza di uno, Base UI utilizza il portale padre o il body del documento.
Elemento o `ShadowRoot`	Utilizza quella destinazione esplicita invece dell’ambito del tema.
Rif.	Base UI risolve il relativo elemento corrente. Una ref il cui valore corrente è null utilizza come fallback il portale padre o il body del documento.
`null`	Attende senza montare. Fornisci una destinazione in un rendering successivo per montare.

Portal.keepMounted conserva il contenuto e lo stato del modulo quando è chiuso. Viewport e Popup trasferiscono la direzione del testo fornita in un contenitore esterno; le relative props dir esplicite hanno la precedenza. Senza un provider di direzione o dir esplicito, ereditano dalla destinazione. Vedi tematizzazione e DirectionProvider. Personalizza Backdrop e Viewport tramite le rispettive props. I relativi attributi nativi, gestori, ref e render si applicano a tali elementi indipendentemente da Popup. forceRender di Backdrop mantiene visibile lo sfondo di una finestra di dialogo nidificata quando necessario. Lo stato di apertura e transizione di Base UI rimane disponibile per gli stili che tengono conto dello stato e i callback di rendering.

Migrazione

Racchiudi il contenuto Dialog.Popup esistente in Dialog.Portal e Dialog.Viewport, quindi aggiungi un elemento fratello Dialog.Backdrop all’interno di Portal. Sposta container e keepMounted da Popup a Portal. Sposta le precedenti props backdrop su Backdrop; sostituisci backdrop={false} omettendo Backdrop. Sposta viewportProps su Viewport, mantenendo data-backdrop-hidden="true" quando la viewport deve lasciare passare gli eventi del puntatore esterni. Mantieni size, initialFocus, finalFocus, gli attributi popup nativi e le ref popup su Popup. Le props dell’assemblaggio Popup combinato sono rimosse. Root, Trigger, Close, Title, Description, Header, Body, Footer e gli handle esistenti mantengono i propri ruoli. Le props delle parti pubbliche, lo stato, le azioni e i tipi dei dettagli degli eventi vengono esportati da twenty-ui/primitives/surfaces.

Props

Dialog.Root

RefObject<DialogRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the dialog after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the dialog completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the dialog imperatively when called.

ReactNode | PayloadChildRenderFunction<Payload>

Parts or a render function receiving the active trigger payload. Root renders no DOM node.

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.

boolean

predefinito:"false"

Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.

DialogHandle<Payload>

Connects detached triggers and imperative dialog actions.

Determines if the dialog enters a modal state when open.

true: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.
false: user interaction with the rest of the document is allowed.
'trap-focus': focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled.

When modal is true or 'trap-focus', render <Dialog.Close> inside <Dialog.Popup> so touch screen readers can escape the popup.

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

Receives the requested state and Base UI event details, including reason, event, trigger and cancel().

((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).

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

DialogHandle<Payload>

A handle to associate the trigger with a dialog. Can be created with the Dialog.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.

Ref to the trigger button, or the element supplied through 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.

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

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

Dialog.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. Omit to use the nearest theme scope, then the parent portal or document body. Explicit null defers mounting; an element, ShadowRoot or ref keeps Base UI resolution.

boolean

predefinito:"false"

Keeps the portal and its content mounted while closed.

Ref<HTMLDivElement>

Ref to the portal div, or the element supplied through render.

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

Composes the portal element. Native props and handlers target it.

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

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

Dialog.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"

Renders the backdrop even when this dialog is nested.

Ref<HTMLDivElement>

Ref to the backdrop div, or the element supplied through 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.

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

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

Dialog.Viewport

ReactNode

Popup and any other content within the positioning 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.

Ref<HTMLDivElement>

Ref to the viewport div, or the element supplied through 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.

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

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

Dialog content. Compose inside Viewport and Portal; Popup does not create those parts or a Backdrop.

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

Controls focus restoration on closing. Accepts a boolean, element ref or callback receiving the interaction type.

Controls focus on opening. Accepts a boolean, element ref or callback receiving the interaction type.

Ref to the popup div, or the element supplied through render.

Composes the popup element while retaining native props, handlers, dialog semantics and focus behavior.

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.

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

"primary" | "secondary" | "tertiary"

predefinito:"primary"

Theme font color. Defaults to primary.

1 | 2 | 3 | 4 | 5 | 6

predefinito:"2"

Semantic heading level, from h1 through h6. Does not change the visual size. Defaults to 2.

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.

"lg" | "md" | "sm" | "xl" | "xs" | "xxl"

predefinito:"lg"

Visual font size, independent of the heading level. Defaults to lg.

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

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

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

Ref<HTMLParagraphElement>

Ref to the description paragraph, or the element supplied through 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.

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

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

Dialog.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>).

Ref<HTMLButtonElement>

Ref to the close button, or the element supplied through 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.

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

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

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.

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

Composizione

Focus, scorrimento e chiusura

Dimensioni e portali

Migrazione

Props

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer

​Panoramica

​Utilizzo

​Stato non controllato

​Anatomia

​Stato controllato

​Composizione

​Focus, scorrimento e chiusura

​Dimensioni e portali

​Migrazione

​Props

​Dialog.Root

​Dialog.Trigger

​Dialog.Portal

​Dialog.Backdrop

​Dialog.Viewport

​Dialog.Popup

​Dialog.Title

​Dialog.Description

​Dialog.Close

​Dialog.Header

​Dialog.Body

​Dialog.Footer

Panoramica

Utilizzo

Stato non controllato

Anatomia

Stato controllato

Composizione

Focus, scorrimento e chiusura

Dimensioni e portali

Migrazione

Props

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Popup

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer