Dialog

Prezentare generală

Utilizați Dialog pentru formulare, detalii și alte sarcini care se deschid deasupra paginii. Gestionează focalizarea, închiderea de la tastatură, clicurile în exterior și derularea. Utilizați AlertDialog când utilizatorul trebuie să răspundă explicit la o decizie. Acest API este destinat pentru Twenty UI independent și aplicația-gazdă Twenty. Componentele Front trebuie să utilizeze openCommandConfirmationModal din SDK în loc să redea direct Dialog sau AlertDialog. Dialogurile și ferestrele pop-up native ale browserului sunt, de asemenea, interzise în randatorul de componente Front.

Utilizare

Stare necontrolată

Root gestionează vizibilitatea în mod implicit. Setați defaultOpen pentru starea sa inițială. Declanșatoarele, controalele de închidere, Escape și clicurile în exterior actualizează acea stare.

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

Anatomie

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	Țintă nativă și ref
`Root`	Coordonează vizibilitatea și comportamentul modal. Nu redă niciun nod DOM și nu acceptă atribute native sau ref DOM.
`Declanșator`	Un buton în mod implicit. Deschide dialogul și furnizează o țintă de restabilire a focalizării.
`Portal`	Div-ul portalului. Gestionează containerul de destinație și dacă conținutul închis rămâne montat.
`Backdrop`	Div-ul de fundal de sub fereastra pop-up. Opțional; omiteți-l când nu este necesar un fundal vizibil.
`Viewport`	Div-ul de poziționare din jurul ferestrei pop-up.
`Popup`	Div-ul dialogului. Gestionează conținutul, dimensiunea, țintele de focalizare și semantica dialogului.
`Titlu`	Un `h2` în mod implicit. Furnizează numele accesibil. Furnizați `aria-label` pentru `Popup` când îl omiteți.
`Description`	Un paragraf în mod implicit. Asociază textul de suport cu dialogul.
`Header`, `Body`, `Footer`	Div-uri opționale care aranjează titlurile, conținutul și acțiunile.
`Închide`	Un buton în mod implicit. Furnizează o acțiune de închidere vizibilă, inclusiv pentru cititoarele de ecran tactile.

Asamblați explicit Portal, Backdrop, Viewport și Popup. Fiecare parte DOM acceptă propriile atribute native, handlere, className, style, ref și compunerea render. Un ref vizează elementul redat al acelei părți. Popup nu creează un portal, un fundal sau un viewport.

Stare controlată

Transmiteți open și onOpenChange când aplicația gestionează vizibilitatea. Callbackul primește starea solicitată și detaliile evenimentului Base UI, inclusiv reason, event, trigger și cancel(). Actualizați starea pentru a accepta o modificare sau apelați eventDetails.cancel() pentru a o respinge. onOpenChangeComplete se execută când se termină animația de deschidere sau închidere.

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

Pentru un formular asincron, mențineți dialogul deschis în timpul trimiterii. Închideți-l după reușită și afișați erorile în dialog.

Compoziție

Trigger și Close acceptă render pentru compunerea cu Button, după cum se arată mai sus. Învelișurile personalizate trebuie să redirecționeze props și refs furnizate. Părțile DOM păstrează numele claselor, stilurile și contractele callbackului render dependente de stare ale Base UI. Header, Body și Footer își păstrează aspectul stilizat și compunerea div nativă. Includeți un alt Dialog.Root într-un popup pentru a deschide un al doilea dialog. Închiderea dialogului imbricat readuce focalizarea la declanșatorul său din cel părinte. Pentru a deschide un dialog din declanșatoare aflate în afara Root, creați o singură dată un handle cu Dialog.createHandle\<TPayload>() și transmiteți-l la handle atât pentru Root, cât și pentru fiecare Trigger. Valorile payload ale declanșatorului sunt disponibile în funcția de randare a lui Root. Dialog.Handle și tipul public DialogHandle expun contractul handle instalat:

Membru	Scop
`open(triggerId)`	Deschide cu un declanșator corespunzător ca declanșator activ.
`open(null)`	Deschide fără a asocia un declanșator.
`openWithPayload(payload)`	Deschide cu o sarcină utilă tipizată și fără un declanșator asociat.
`close()`	Solicită închiderea.
`isOpen`	Indică dacă dialogul asociat este deschis.

Acțiunile imperative au efect numai cât timp Root-ul asociat este montat. actionsRef al Root-ului expune și close() și unmount() pentru controlul explicit al tranziției. Pentru a controla o animație externă de închidere, apelați eventDetails.preventUnmountOnClose() în onOpenChange, apoi apelați acțiunea unmount() când animația se termină. Title utilizează Heading și are implicit un h2 cu text mare, culoare primară a textului, aliniere centrată și spațierea 4 sub acesta. Utilizați level pentru a schimba nivelul titlului independent de size sau color pentru a-i schimba culoarea textului. className, style, refs și render native sunt redirecționate către titlu. Păstrați un element de titlu când utilizați render. Description este centrată precum Title; AlertDialog le menține pe ambele aliniate la stânga. Popup nu are spațiere interioară. Header, Body și Footer asigură spațierea interioară, astfel încât conținutul plasat direct în Popup se află lipit de marginile sale.

Focalizare, derulare și închidere

Root.modal controlează limita de interacțiune:

Valoare	Focalizare	Derularea paginii și interacțiunea din exterior
`true` (implicit)	Captiv în interiorul dialogului	Derularea paginii și interacțiunea din exterior sunt blocate.
`"trap-focus"`	Captată în dialog	Derularea paginii și interacțiunea în exterior rămân disponibile.
`fals`	Poate părăsi dialogul	Derularea paginii și interacțiunea din exterior rămân disponibile.

Omiteți Backdrop când nu este necesar un fundal vizibil. Pentru un dialog nemodal al cărui viewport trebuie să permită trecerea evenimentelor de indicator către pagină, utilizați \<Dialog.Viewport data-backdrop-hidden="true">; Popup rămâne interactiv. Omiterea numai a fundalului vizual nu modifică Root.modal. Setați Popup.initialFocus sau Popup.finalFocus la un ref sau callback pentru a alege țintele de focalizare; false dezactivează această mutare automată a focalizării. Callbackurile de focalizare primesc tipul de interacțiune și păstrează comportamentul de returnare Base UI pentru boolean, element, null și undefined. Închiderea restabilește în mod normal focalizarea la declanșator sau la elementul focalizat anterior. Root.disablePointerDismissal împiedică clicurile în exterior să solicite închiderea. Pentru a preveni închiderea cu Escape, anulați modificarea escape-key în onOpenChange. Furnizați întotdeauna o modalitate vizibilă de a închide un dialog modal.

Dimensiuni și portaluri

Popup.size acceptă sm, compact, md, lg, xl și fullscreen, iar valoarea implicită este md. Conținutul lung se derulează în popup. Lățimea este limitată la fereastra de vizualizare. Setați Portal.container pentru a alege o destinație:

Valoare	Rezoluție
Omis sau `undefined`	Utilizează cel mai apropiat container de temă cu domeniu de aplicare. În lipsa acestuia, Base UI utilizează portalul părinte sau corpul documentului.
Element sau `ShadowRoot`	Utilizează destinația explicită respectivă în locul domeniului temei.
Ref	Base UI rezolvă elementul său curent. Un ref a cărui valoare curentă este null revine la portalul părinte sau la corpul documentului.
`null`	Așteaptă fără montare. Furnizați o destinație într-o redare ulterioară pentru montare.

Portal.keepMounted păstrează conținutul și starea formularului când este închis. Viewport și Popup transferă direcția textului furnizată într-un container extern; propriile prop-uri explicite dir au prioritate. Fără un furnizor de direcție sau un dir explicit, acestea moștenesc direcția de la destinație. Consultați tematizarea și DirectionProvider. Personalizați Backdrop și Viewport prin propriile prop-uri. Atributele native, handlerele, ref-urile și render ale acestora se aplică acelor elemente independent de Popup. forceRender al Backdrop-ului menține vizibil fundalul unui dialog imbricat atunci când este necesar. Starea de deschidere și de tranziție Base UI rămâne disponibilă pentru stilurile dependente de stare și callbackurile de redare.

Migrare

Încapsulați conținutul existent Dialog.Popup în Dialog.Portal și Dialog.Viewport și adăugați un Dialog.Backdrop frate în Portal. Mutați container și keepMounted din Popup în Portal. Mutați fostele prop-uri backdrop în Backdrop; înlocuiți backdrop={false} prin omiterea Backdrop. Mutați viewportProps în Viewport, păstrând data-backdrop-hidden="true" când viewportul trebuie să permită trecerea evenimentelor de indicator externe. Păstrați size, initialFocus, finalFocus, atributele native ale ferestrei pop-up și ref-urile ferestrei pop-up în Popup. Prop-urile de asamblare Popup fuzionate sunt eliminate. Root, Trigger, Close, Title, Description, Header, Body, Footer și handle-urile existente își păstrează rolurile. Prop-urile părților publice, starea, acțiunile și tipurile de detalii ale evenimentelor sunt exportate din twenty-ui/primitives/surfaces.

Proprietăți

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

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

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

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

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

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

implicit:"primary"

Theme font color. Defaults to primary.

1 | 2 | 3 | 4 | 5 | 6

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

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

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

Dezvoltatori

Aplicații

API

Autogazda

Contribuie

Biblioteca UI

Prezentare generală

Utilizare

Stare necontrolată

Anatomie

Stare controlată

Compoziție

Focalizare, derulare și închidere

Dimensiuni și portaluri

Migrare

Proprietăți

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer

​Prezentare generală

​Utilizare

​Stare necontrolată

​Anatomie

​Stare controlată

​Compoziție

​Focalizare, derulare și închidere

​Dimensiuni și portaluri

​Migrare

​Proprietăți

​Dialog.Root

​Dialog.Trigger

​Dialog.Portal

​Dialog.Backdrop

​Dialog.Viewport

​Dialog.Popup

​Dialog.Title

​Dialog.Description

​Dialog.Close

​Dialog.Header

​Dialog.Body

​Dialog.Footer

Prezentare generală

Utilizare

Stare necontrolată

Anatomie

Stare controlată

Compoziție

Focalizare, derulare și închidere

Dimensiuni și portaluri

Migrare

Proprietăți

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Popup

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer