Dialog

Present a focused task above the current page.

Use Dialog for forms, details, and other tasks that open above the page. It manages focus, keyboard dismissal, outside clicks, and scrolling. Use AlertDialog when the user must explicitly respond to a decision.

Anatomy

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

Part	Requirement	Purpose
Root	Required	Coordinates visibility and modal behavior.
Trigger	Optional	Opens the dialog and receives focus when it closes.
Popup	Required	Contains the dialog and includes its portal, backdrop, and viewport.
Title	Recommended	Provides the accessible name. Supply aria-label on Popup when omitting it.
Description	Optional	Associates supporting text with the dialog.
Header, Body, Footer	Optional	Arrange headings, content, and actions.
Close	Recommended	Provides a visible close action, including for touch screen readers.

Uncontrolled state

Root owns visibility by default. Set defaultOpen for its initial state. Triggers, close controls, Escape, and outside clicks update that state.

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

export const AccountDialog = () => (
  <Dialog.Root defaultOpen={false}>
    <Dialog.Trigger
      render={<Button>Account details</Button>}
    />
    <Dialog.Popup>
      <Dialog.Header>
        <Dialog.Title>Account details</Dialog.Title>
        <Dialog.Description>
          Review your account information.
        </Dialog.Description>
      </Dialog.Header>
      <Dialog.Body>Acme</Dialog.Body>
      <Dialog.Footer>
        <Dialog.Close render={<Button>Close</Button>} />
      </Dialog.Footer>
    </Dialog.Popup>
  </Dialog.Root>
);

Controlled state

Pass open and onOpenChange when the application owns visibility. The callback receives the requested state and event details. Update state to accept a change, or call eventDetails.cancel() to reject it.

import { useState } from 'react';
import { Button } 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>Account details</Button>}
      />
      <Dialog.Popup>
        <Dialog.Header>
          <Dialog.Title>Account details</Dialog.Title>
          <Dialog.Description>
            Review your account information.
          </Dialog.Description>
        </Dialog.Header>
        <Dialog.Body>Acme</Dialog.Body>
        <Dialog.Footer>
          <Dialog.Close render={<Button>Close</Button>} />
        </Dialog.Footer>
      </Dialog.Popup>
    </Dialog.Root>
  );
};

For an asynchronous form, keep the dialog open while submitting. Close it after success and display failures inside the dialog.

Composition

Trigger and Close accept render to compose with Button, as shown above. Custom wrappers must forward supplied props and refs. Layout parts also support render, native attributes, refs, styles, and class names. Popup, Title, and Description accept state-aware class names and styles.

Nest another Dialog.Root inside a popup to open a second dialog. Closing the nested dialog returns focus to its trigger in the parent.

To open one dialog from triggers outside Root, create a handle once with Dialog.createHandle() and pass it to handle on both Root and each Trigger. Trigger payload values are available in Root’s render function.

Title uses Heading and defaults to an h2 with large type, primary text color, centered alignment, and spacing-4 below it. Use level to change the heading level independently of size, or color to change its text color. Native className, style, refs, and render are forwarded to the heading. Keep a heading element when using render.

Focus, scrolling, and dismissal

Root.modal controls the interaction boundary:

Value	Focus	Page scrolling and outside interaction
true (default)	Trapped inside the dialog	Page scrolling and outside interaction are blocked.
"trap-focus"	Trapped inside the dialog	Page scrolling and outside interaction remain available.
false	Can leave the dialog	Page scrolling and outside interaction remain available.

Set Popup.backdrop={false} when outside content should remain visible and interactive. Set Popup.initialFocus or Popup.finalFocus to a ref or callback to choose focus targets; false disables that automatic focus move.

Root.disablePointerDismissal prevents outside clicks from requesting closure. To prevent Escape dismissal, cancel the escape-key change in onOpenChange. Always provide a visible way to close a modal dialog.

Sizes and portals

Popup.size accepts sm, md, lg, xl, and fullscreen, and defaults to md. Long content scrolls within the popup. Width is constrained to the viewport.

Portals use the nearest theme container by default and preserve text direction. Set container to an element or ref to choose another destination; null defers mounting until a destination is available. keepMounted retains content and form state while closed.

Use backdrop props to customize the backdrop, and viewportProps for native attributes, styles, or render composition on the surrounding viewport. These props let application layout containers host a dialog while keeping the popup’s semantics.

Props

Dialog.Root

Root.actionsRef · RefObject<DialogRootActions | null>

A ref to imperative actions.

• unmount: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes.
• close: Closes the 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.disablePointerDismissal · boolean · default: "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.

Root.handle · DialogHandle<Payload>

A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog’s open state. Can be created with the Dialog.createHandle() method.

Root.modal · boolean | "trap-focus" · default: "true"

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.

Root.onOpenChange · ((open: boolean, eventDetails: DialogRootChangeEventDetails) => void)

Event handler called when the 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).

Dialog.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 · DialogHandle<Payload>

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

Dialog.Popup

Popup.backdrop · boolean | DialogBackdropProps · default: "true"

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.container · HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null

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.keepMounted · boolean

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"

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.

Popup.viewportProps · DialogViewportProps

Dialog.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.color · "primary" | "secondary" | "tertiary" · default: "primary"

Theme font color. Defaults to primary.

Title.level · 1 | 2 | 3 | 4 | 5 | 6 · default: "2"

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

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.size · "lg" | "md" | "sm" | "xs" · default: "lg"

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

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.

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

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

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

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

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