Primitives

Dialog

A modal on the popover tokens: portal, scrim, centered popup, and a built-in close button

Import

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@nyte-ai/ui";
import { Dialog as DialogPrimitive } from "@nyte-ai/ui/dialog";

Implemented in packages/ui/src/components/ui/dialog.tsx, wrapping @nyte-ai/ui/dialog. Dialog is Dialog.Root re-exported. The wrapper does not export a styled Trigger or Close; use DialogPrimitive.Trigger and DialogPrimitive.Close with render={<Button … />}.

Usage

Every dialog must have a DialogTitle. It becomes the accessible name. If the title is visually redundant, hide it with your own visually-hidden style rather than omitting it.
Use DialogDescription for the one sentence that explains the consequence. Longer content goes in the body.
Confirmations that destroy something use Alert dialog, which does not dismiss on outside press.
showCloseButton is on by default. Turn it off only when the footer already has a Cancel and the dialog is small enough that the ✕ would crowd the title.

Anatomy

<Dialog>
  <DialogPrimitive.Trigger />
  <DialogContent>
    {/* Portal › Backdrop › Popup, plus Close */}
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    …
    <DialogFooter />
  </DialogContent>
</Dialog>

DialogContent renders Dialog.Portal › Dialog.Backdrop › Dialog.Popup and, when showCloseButton, a Dialog.Close rendered as <Button size="icon-sm" variant="ghost"> with aria-label="Close" in the top-right corner. DialogHeader reserves --nyte-control-height-sm of right padding so the title clears that button.

Example

<Dialog>
  <DialogPrimitive.Trigger render={<Button variant="outline" />}>
    Rename session
  </DialogPrimitive.Trigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Rename session</DialogTitle>
      <DialogDescription>The name shows in the sidebar and in the window title.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogPrimitive.Close render={<Button variant="ghost" />}>Cancel</DialogPrimitive.Close>
      <DialogPrimitive.Close render={<Button />}>Save</DialogPrimitive.Close>
    </DialogFooter>
  </DialogContent>
</Dialog>

Props

Dialog (Root)

Groups all parts of the dialog. Doesn't render its own HTML element.

Root Props:

Prop	Type	Default	Description
defaultOpen	`boolean`	`false`	Whether the dialog is initially open. To render a controlled dialog, use the `open` prop instead.
open	`boolean`	-	Whether the dialog is currently open.
onOpenChange	`((open: boolean, eventDetails: Dialog.Root.ChangeEventDetails) => void)`	-	Event handler called when the dialog is opened or closed.
actionsRef	`React.RefObject<Dialog.Root.Actions \| 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.
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.
disablePointerDismissal	`boolean`	`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.
handle	`Dialog.Handle<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.
modal	`boolean \| 'trap-focus'`	`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.
onOpenChangeComplete	`((open: boolean) => void)`	-	Event handler called after any animations complete when the dialog is opened or closed.
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).
children	`React.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.

DialogContent

DialogContentProps is StyledProps<Dialog.Popup.Props> plus:

Prop	Type	Default	Description
`showCloseButton`	`boolean`	`true`	Render the ✕ close button in the top-right corner.

The styling channels (className, style, xstyle) apply to the Popup. The Backdrop is not exposed; theme --nyte-color-scrim to change it.

A container for the dialog contents. Renders a <div> element.

Popup Props:

Prop	Type	Default	Description
initialFocus	`boolean \| React.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.
finalFocus	`boolean \| React.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.
className	`string \| ((state: Dialog.Popup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Popup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Popup.State) => ReactElement)`	-	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 Data Attributes:

Attribute	Type	Description
data-open	-	Present when the dialog is open.
data-closed	-	Present when the dialog is closed.
data-nested	-	Present when the dialog is nested within another dialog.
data-nested-dialog-open	-	Present when the dialog has other open dialogs nested within it.
data-starting-style	-	Present when the dialog begins animating in.
data-ending-style	-	Present when the dialog is animating out.

Popup CSS Variables:

Variable	Type	Description
`--nested-dialogs`	`number`	Indicates how many dialogs are nested within.

DialogTitle

A heading that labels the dialog. Renders an <h2> element.

Title Props:

Prop	Type	Default	Description
className	`string \| ((state: Dialog.Title.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Title.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Title.State) => ReactElement)`	-	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.

DialogDescription

A paragraph with additional information about the dialog. Renders a <p> element.

Description Props:

Prop	Type	Default	Description
className	`string \| ((state: Dialog.Description.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Description.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Description.State) => ReactElement)`	-	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.

DialogHeader, DialogFooter

Plain <div>s with StyledProps<React.ComponentProps<"div">>. Header is a column with --nyte-space-1 gap; footer is a right-aligned row with --nyte-space-2 gap.

Trigger and Close

From @nyte-ai/ui/dialog:

A button that opens the dialog. Renders a <button> element.

Trigger Props:

Prop	Type	Default	Description
handle	`Dialog.Handle<Payload>`	-	A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
nativeButton	`boolean`	`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	`Payload`	-	A payload to pass to the dialog when it is opened.
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 Dialog.Root `triggerId` prop).
className	`string \| ((state: Dialog.Trigger.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Trigger.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Trigger.State) => ReactElement)`	-	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 Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding dialog is open.
data-disabled	-	Present when the trigger is disabled.

A button that closes the dialog. Renders a <button> element.

Close Props:

Prop	Type	Default	Description
nativeButton	`boolean`	`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>`).
className	`string \| ((state: Dialog.Close.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Dialog.Close.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Dialog.Close.State) => ReactElement)`	-	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 Data Attributes:

Attribute	Type	Description
data-disabled	-	Present when the button is disabled.

Accessibility

Base UI's dialog behavior, unchanged by the wrapper:

The popup has role="dialog" and aria-modal="true", and is labelled by DialogTitle and described by DialogDescription automatically.
Focus moves into the popup on open (first tabbable element, or the popup itself when opened by touch) and returns to the trigger on close. Tab cycles inside the popup.
Escape closes. Outside press closes unless disablePointerDismissal is set on Root.
Content outside the dialog is inert while it is open, and background scroll is locked.

Styling

Token	Role
`--nyte-layer-dialog`	z-index of backdrop and popup (50)
`--nyte-color-scrim`	Backdrop
`--nyte-dialog-width`, `-max-width`, `-max-height`	Popup box
`--nyte-radius-dialog`, `--nyte-elevation-dialog`, `--nyte-color-popover`	Popup surface
`--nyte-space-4`	Popup padding and grid gap
`--nyte-font-size-title` / `--nyte-leading-title`	Title
`--nyte-color-muted-foreground`	Description
`--nyte-motion-normal`	Fade and 0.98 scale via `[data-starting-style]` / `[data-ending-style]`; `0s` under reduced motion

dialogStyles is exported so Alert dialog renders the same surface.