Dialog — Design System

Examples

Focused task

A named, described modal task returns focus to its trigger when closed.

Dialog preview with scrollable content and stable actions

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Form in a Dialog

Small forms keep their validation and business state in the feature.

Dialog containing a small form

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Delete confirmation

Destructive actions name the exact target and keep Cancel first.

Dialog confirmation for a destructive action

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Processing and error

In-flight and failure feedback stay explicit before the modal closes.

Dialog with simulated processing and error feedback

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Long content

DialogBody is the bounded scroll region; header and footer remain visible.

Dialog with long scrollable content

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

When to use

Use Dialog when the task needs attention before the person can continue. Use a page for a substantial workflow, and use Tooltip for short supplemental context.

Good fit

Reviewing changes, editing a small record, or confirming a consequential action.

Use a page instead

Do not put a multi-step workflow or a long required form into a small modal.

Usage

"use client";

import { Button } from "@phuctech/ui/components/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@phuctech/ui/components/dialog";

export function Example() {
  return (
    <Dialog>
      <DialogTrigger render={<Button>Review changes</Button>} />
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Review changes</DialogTitle>
          <DialogDescription>Confirm the update before it is applied.</DialogDescription>
        </DialogHeader>
        <DialogBody>Long content belongs in this scrollable region.</DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Cancel</Button>} />
          <Button>Apply changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Composition

Give the Dialog a trigger, title, and description. Put long content in DialogBody so the body scrolls while DialogHeader and DialogFooter remain visible. Use DialogClose for cancel or explicit close actions.

Use a real Button or IconButton as the trigger through render.
Keep the primary action in the footer and disable it while an operation is in flight.
Confirm destructive actions in a dedicated, clearly worded step.

API

Component API
Prop	Type	Default	Description	Constraints
`defaultOpen / open / onOpenChange`	`boolean / callback`	`false / —`	Uncontrolled or controlled visibility.	Do not mix controlled and uncontrolled models.
`modal`	`boolean \| "trap-focus"`	`true`	Controls focus trapping, scroll lock, and outside interaction.	Keep the default for modal tasks.
`DialogContent`	`Popup props`	`—`	Portaled, bounded popup with backdrop and focus behavior.	Use the provided max-height and overflow contract.
`DialogBody`	`HTMLDivElement props`	`—`	The growable scroll region for long content.	Use for content that can exceed the viewport.
`DialogClose`	`Close props`	`—`	Closes the dialog and returns focus to the trigger.	Keep a visible cancel/close action for touch and screen readers.

Tokens

Component tokens
Token	Role	Effective value	Usage
`--elevation-lg`	Modal depth	`shared large shadow`	Separates the popup from the page surface.
`--radius-xl`	Popup geometry	`shared large radius`	Keeps the modal surface aligned with Card.
`--motion-duration-fast`	Open/close timing	`120ms`	Dialog transitions are brief and respect reduced motion.

Accessibility

Every dialog needs a title; add a description when the task needs context.
Verify focus enters the popup, stays inside while modal, closes with Escape, and returns to the trigger.
Keep the growing body scrollable; do not clip long content behind the footer.

Do and don’t

Use a specific title, stable actions, and a body region that can scroll on a small viewport.

Don’t

Open a dialog for passive information, hide the only close action, or nest unrelated dialogs.

Button supplies dialog triggers and actions.
Tooltip is the lighter alternative for brief context.
Elevation documents portal and surface hierarchy.