Dialog

Dialog dims and blocks the window, moves focus into its surface, keeps Tab inside it, and returns focus to whatever opened it. Compose it from a trigger, a content surface and the header, description and footer parts.

InstallationCopy Anchor Link

nub add @gpuixui/components@workspace:*

UsageCopy Anchor Link

import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@gpuixui/components/dialog";
import { Button } from "@gpuixui/primitives";

<Dialog>
  <DialogTrigger>Delete workspace</DialogTrigger>
  <DialogContent label="Delete workspace">
    <DialogHeader>
      <DialogTitle>Delete this workspace?</DialogTitle>
      <DialogDescription>
        The workspace and its 42 files are removed for everyone.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <Button variant="destructive">Delete workspace</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>;

CompositionCopy Anchor Link

The parts validate their placement: a DialogTitle outside DialogHeader, or a DialogContent outside Dialog, fails with a message naming the family. Put DialogTrigger and DialogContent directly inside Dialog.

Controlled and uncontrolledCopy Anchor Link

// Uncontrolled: the dialog remembers.
<Dialog defaultOpen>…</Dialog>;

// Controlled: the app remembers, which async work needs.
<Dialog open={open} onOpenChange={setOpen}>…</Dialog>;

The controlled form is authoritative. onOpenChange still fires, but the dialog does not change its own state until the consumer re-renders with the new value. A dialog doing async work stays open while the work runs and closes only when it succeeds.

SizesCopy Anchor Link

DialogContent takes size, a width cap in pixels:

The surface never exceeds the window minus two spacing["3xl"], and its interior scrolls, so a long body cannot push the actions off screen.

DismissalCopy Anchor Link

dismissible (default true) controls both Escape and an outside press. A dialog doing uninterruptible work sets dismissible={false} and re-enables it when the work settles.

Open overlays share one dismiss stack: Escape and outside presses are consumed by the topmost layer only. A popover inside a dialog closes the popover first; one event cannot close both.

KeyboardCopy Anchor Link

API referenceCopy Anchor Link

DialogCopy Anchor Link

DialogContentCopy Anchor Link

DialogTrigger, DialogClose and DialogTitle take the GPUix host props where they render a host element plus, for the buttons, the button variant and size. Every part merges style last.

Accessibility and limitationsCopy Anchor Link

• role="dialog" with the required label as its accessible name.
• Focus enters the surface on open and returns to the opener on close.
• No aria-modal and no aria-labelledby in @gpuix/native@0.10.0. The dialog is named by label; its title is a separate heading, not the dialog's accessible name.
• The veil is an anchored layer at window coordinates. 0.10.0 ships no portal, and position: "absolute" resolves against the mount parent, so mount a dialog at or near the root of the tree.
• The top-right close control is a ✕ text glyph until an icon package lands.
• A dialog is not resizable, draggable or multi-window. One dialog per surface.

RelatedCopy Anchor Link

• Confirmation dialog — the safe default for destructive actions.
• Popover — a non-modal floating surface anchored to a trigger.
• Card — the in-flow surface, when nothing should be blocked.