Dialog

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

export default function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Edit profile</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={(e) => {
              e.preventDefault();
              close();
            }}
          >
            <DialogHeader>
              <DialogTitle>Edit profile</DialogTitle>
              <DialogDescription>
                Update how your name appears to your team.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                defaultValue="Nischal Timalsina"
                autoFocus
              />
              <TextField label="Username" prefix="@" defaultValue="nischal" />
            </div>
            <DialogFooter>
              <DialogClose>Cancel</DialogClose>
              <Button type="submit">Save changes</Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/dialog

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

tsx

<DialogTrigger>
  <Button>Open</Button>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    {/* content */}
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <Button>Confirm</Button>
    </DialogFooter>
  </DialogContent>
</DialogTrigger>

DialogTrigger connects the first child (any pressable, usually a Button) to the DialogContent after it. No state or refs needed.

When to use

Dialog — a short, self-contained task that needs the user's full attention: a form, a confirmation, a detail view.
Sheet — longer or secondary content that slides in from an edge and can stay open while users reference the page.
Popover — lightweight, non-modal content anchored to a trigger.
Toast — feedback that doesn't need a response.

Avoid dialogs that open other dialogs; prefer a multi-step flow inside one dialog.

Anatomy

tsx

<DialogTrigger>
  <Button />                       {/* trigger */}
  <DialogContent>                  {/* overlay + modal + dialog */}
    <DialogIcon />                 {/* optional status icon (alert dialogs) */}
    <DialogHeader>
      <DialogTitle />              {/* accessible name */}
      <DialogDescription />
    </DialogHeader>
    <DialogBody />                 {/* optional scrollable region */}
    <DialogFooter>
      <DialogClose />              {/* button that closes the dialog */}
    </DialogFooter>
  </DialogContent>
</DialogTrigger>

Part	Renders	Notes
`DialogTrigger`	—	Manages open state and wires the trigger to the dialog.
`DialogContent`	`ModalOverlay` › `Modal` › `Dialog`	Backdrop, centered panel and the `role="dialog"` element. Adds a close icon by default.
`DialogHeader`	`<div>`	Stacks title and description; leaves room for the close icon.
`DialogTitle`	`Heading` (`slot="title"`)	Becomes the dialog's accessible name.
`DialogDescription`	`<p>`	Supporting text.
`DialogIcon`	`<div>`	Tinted circular icon for alert dialogs.
`DialogBody`	`<div>`	Optional. Takes the remaining height and scrolls when content overflows.
`DialogFooter`	`<div>`	Actions. Stacked (primary on top) on mobile, right-aligned on larger screens.
`DialogClose`	`Button slot="close"`	Any button with `slot="close"` closes the dialog. Defaults to `outline`.
`DialogCloseIcon`	`<button>`	The top-right ✕. Rendered automatically unless `showCloseButton={false}`.

Examples

Alert dialog

role="alertdialog" is for confirmations that need an explicit decision. It can't be dismissed by clicking outside and hides the close icon. DialogIcon adds a tinted status icon.

import { TriangleAlertIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogIcon,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export default function AlertDialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline" color="danger">
        Delete project
      </Button>
      <DialogContent role="alertdialog" size="sm">
        <div className="flex gap-4">
          <DialogIcon tone="danger">
            <TriangleAlertIcon />
          </DialogIcon>
          <div className="grid gap-1.5">
            <DialogTitle>Delete this project?</DialogTitle>
            <DialogDescription>
              All deployments and logs will be permanently removed. This
              can&apos;t be undone.
            </DialogDescription>
          </div>
        </div>
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <DialogClose variant="solid" color="danger">
            Delete
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Sizes

sm (384px), md (512px, default), lg (672px), xl (896px) set the maximum width. The dialog shrinks to fit smaller viewports.

import { Button } from "@/components/ui/button";
import {
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

const sizes = ["sm", "md", "lg", "xl"] as const;

export default function DialogSizes() {
  return (
    <div className="flex flex-wrap gap-2">
      {sizes.map((size) => (
        <DialogTrigger key={size}>
          <Button variant="outline" className="uppercase">
            {size}
          </Button>
          <DialogContent size={size}>
            <DialogHeader>
              <DialogTitle>Size {size}</DialogTitle>
              <DialogDescription>
                Dialogs grow to fit their content up to this maximum width.
              </DialogDescription>
            </DialogHeader>
          </DialogContent>
        </DialogTrigger>
      ))}
    </div>
  );
}

Full screen

size="full" fills the viewport with a 1rem margin — useful for editors, previews and complex forms on small screens. Give the main element flex-1 to fill the space between header and footer.

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

export default function DialogFullscreen() {
  return (
    <DialogTrigger>
      <Button variant="outline">Open editor</Button>
      <DialogContent size="full">
        <DialogHeader>
          <DialogTitle>Edit README.md</DialogTitle>
          <DialogDescription>
            Changes are saved when you press Save.
          </DialogDescription>
        </DialogHeader>
        <textarea
          aria-label="Content"
          defaultValue={
            "# Desyne\n\nAccessible components for your shadcn project."
          }
          className="min-h-0 w-full flex-1 resize-none rounded-lg border bg-muted/40 p-4 font-mono text-sm outline-none focus-visible:ring-[3px] focus-visible:ring-ring/20"
        />
        <DialogFooter>
          <DialogClose>Discard</DialogClose>
          <DialogClose variant="solid">Save</DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Scrollable content

Dialogs never grow taller than the viewport. Wrap long content in DialogBody and it scrolls while the header and footer stay put. Pass a max-h-* class to DialogContent for a shorter cap.

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

export default function DialogScrollable() {
  return (
    <DialogTrigger>
      <Button variant="outline">Terms of service</Button>
      <DialogContent className="max-h-[80vh]">
        <DialogHeader>
          <DialogTitle>Terms of service</DialogTitle>
          <DialogDescription>Last updated September 2026.</DialogDescription>
        </DialogHeader>
        <DialogBody className="space-y-3 text-muted-foreground leading-relaxed">
          {Array.from({ length: 12 }, (_, i) => i + 1).map((n) => (
            <p key={n}>
              {n}. The content scrolls inside the dialog while the header and
              footer stay put. Long legal text, changelogs and review screens
              work well this way.
            </p>
          ))}
        </DialogBody>
        <DialogFooter>
          <DialogClose>Decline</DialogClose>
          <DialogClose variant="solid">Accept</DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Forms

Wrap the content in a React Aria Form and use the render-function child, ({ close }) => …, to close the dialog after a successful submit.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

export default function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Edit profile</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={(e) => {
              e.preventDefault();
              close();
            }}
          >
            <DialogHeader>
              <DialogTitle>Edit profile</DialogTitle>
              <DialogDescription>
                Update how your name appears to your team.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                defaultValue="Nischal Timalsina"
                autoFocus
              />
              <TextField label="Username" prefix="@" defaultValue="nischal" />
            </div>
            <DialogFooter>
              <DialogClose>Cancel</DialogClose>
              <Button type="submit">Save changes</Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}

Validation and async submit

Field validation runs before onSubmit. Show isPending on the submit button while the request runs, then close and confirm with a toast.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Select, SelectItem } from "@/components/ui/select";
import { TextField } from "@/components/ui/text-field";
import { toast } from "@/components/ui/toast";

export default function DialogFormValidation() {
  const [pending, setPending] = useState(false);
  return (
    <DialogTrigger>
      <Button>New API key</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={async (e) => {
              e.preventDefault();
              setPending(true);
              await new Promise((r) => setTimeout(r, 1000));
              setPending(false);
              close();
              toast.success("API key created");
            }}
          >
            <DialogHeader>
              <DialogTitle>Create API key</DialogTitle>
              <DialogDescription>
                Keys are shown once. Store it somewhere safe.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                name="name"
                isRequired
                autoFocus
                placeholder="Production server"
                validate={(v) =>
                  v.length > 0 && v.length < 3
                    ? "Use at least 3 characters."
                    : null
                }
              />
              <Select
                label="Permissions"
                name="scope"
                isRequired
                placeholder="Choose access"
              >
                <SelectItem id="read">Read only</SelectItem>
                <SelectItem id="write">Read and write</SelectItem>
                <SelectItem id="admin">Full access</SelectItem>
              </Select>
            </div>
            <DialogFooter>
              <DialogClose isDisabled={pending}>Cancel</DialogClose>
              <Button type="submit" isPending={pending}>
                Create key
              </Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}

Render DialogContent without a trigger and control it with isOpen and onOpenChange. Use this to open a dialog from a menu item, a keyboard shortcut or after an async event. Focus returns to the element that was focused before opening.

import { MoreHorizontalIcon, PencilIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { MenuContent, MenuItem, MenuTrigger } from "@/components/ui/menu";
import { TextField } from "@/components/ui/text-field";

/** Open a dialog from a menu item: control it with `isOpen` instead of a trigger. */
export default function DialogControlled() {
  const [isOpen, setOpen] = useState(false);
  return (
    <>
      <MenuTrigger>
        <Button variant="outline" size="icon" aria-label="Actions">
          <MoreHorizontalIcon />
        </Button>
        <MenuContent>
          <MenuItem textValue="Rename" onAction={() => setOpen(true)}>
            <PencilIcon /> Rename…
          </MenuItem>
        </MenuContent>
      </MenuTrigger>

      <DialogContent isOpen={isOpen} onOpenChange={setOpen} size="sm">
        <DialogHeader>
          <DialogTitle>Rename file</DialogTitle>
          <DialogDescription>
            Enter a new name for “roadmap.pdf”.
          </DialogDescription>
        </DialogHeader>
        <TextField
          aria-label="File name"
          defaultValue="roadmap.pdf"
          autoFocus
        />
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <Button onPress={() => setOpen(false)}>Rename</Button>
        </DialogFooter>
      </DialogContent>
    </>
  );
}

Non-dismissable

isDismissable={false} ignores outside clicks, isKeyboardDismissDisabled ignores Esc, and showCloseButton={false} hides the ✕. Use sparingly — users should always have a visible way out.

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

export default function DialogNonDismissable() {
  return (
    <DialogTrigger>
      <Button variant="outline">Accept terms</Button>
      <DialogContent
        isDismissable={false}
        isKeyboardDismissDisabled
        showCloseButton={false}
      >
        <DialogHeader>
          <DialogTitle>Updated terms of service</DialogTitle>
          <DialogDescription>
            Clicking outside or pressing Esc won’t close this dialog. Choose an
            option to continue.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose>Decline</DialogClose>
          <DialogClose variant="solid">Accept</DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Recipes

Type to confirm

For irreversible, high-impact actions, require the user to type the resource name before the destructive button is enabled.

import { TriangleAlertIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogIcon,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

const NAME = "acme-web";

export default function DialogRecipeTypeToConfirm() {
  const [value, setValue] = useState("");
  return (
    <DialogTrigger onOpenChange={() => setValue("")}>
      <Button variant="soft" color="danger">
        Delete repository
      </Button>
      <DialogContent role="alertdialog" size="sm">
        <div className="flex gap-4">
          <DialogIcon tone="danger">
            <TriangleAlertIcon />
          </DialogIcon>
          <div className="grid gap-1.5">
            <DialogTitle>Delete {NAME}?</DialogTitle>
            <DialogDescription>
              This permanently deletes the repository, its issues and all
              deployments.
            </DialogDescription>
          </div>
        </div>
        <TextField
          label={
            <>
              Type <code className="rounded bg-muted px-1">{NAME}</code> to
              confirm
            </>
          }
          value={value}
          onChange={setValue}
          autoFocus
        />
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <DialogClose
            variant="solid"
            color="danger"
            isDisabled={value !== NAME}
          >
            Delete repository
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Invite members

A small form that builds a list, with per-row role Selects inside the dialog.

import { UserPlusIcon, XIcon } from "lucide-react";
import { useState } from "react";
import { Form } from "react-aria-components";
import { Avatar } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Select, SelectItem } from "@/components/ui/select";
import { TextField } from "@/components/ui/text-field";

type Invite = { email: string; role: string };

export default function DialogRecipeInvite() {
  const [email, setEmail] = useState("");
  const [invites, setInvites] = useState<Invite[]>([
    { email: "olivia@acme.dev", role: "admin" },
  ]);
  return (
    <DialogTrigger>
      <Button>
        <UserPlusIcon /> Invite members
      </Button>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Invite to Acme</DialogTitle>
          <DialogDescription>
            New members get access to every project in this workspace.
          </DialogDescription>
        </DialogHeader>
        <Form
          className="flex items-end gap-2"
          onSubmit={(e) => {
            e.preventDefault();
            if (!email) return;
            setInvites((i) => [...i, { email, role: "member" }]);
            setEmail("");
          }}
        >
          <TextField
            label="Email"
            type="email"
            value={email}
            onChange={setEmail}
            placeholder="name@company.com"
            className="flex-1"
          />
          <Button type="submit" variant="outline">
            Add
          </Button>
        </Form>
        <ul className="grid gap-3">
          {invites.map((inv) => (
            <li key={inv.email} className="flex items-center gap-3">
              <Avatar
                size="sm"
                colorful
                alt={inv.email}
                fallback={inv.email[0].toUpperCase()}
              />
              <span className="min-w-0 flex-1 truncate text-sm">
                {inv.email}
              </span>
              <Select
                aria-label={`Role for ${inv.email}`}
                size="sm"
                defaultSelectedKey={inv.role}
                className="w-28"
              >
                <SelectItem id="admin">Admin</SelectItem>
                <SelectItem id="member">Member</SelectItem>
                <SelectItem id="viewer">Viewer</SelectItem>
              </Select>
              <Button
                variant="ghost"
                size="icon-sm"
                aria-label={`Remove ${inv.email}`}
                onPress={() => setInvites((i) => i.filter((x) => x !== inv))}
              >
                <XIcon />
              </Button>
            </li>
          ))}
        </ul>
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <DialogClose variant="solid" isDisabled={invites.length === 0}>
            Send {invites.length} {invites.length === 1 ? "invite" : "invites"}
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </DialogTrigger>
  );
}

Multi-step wizard

Keep one dialog open and swap its body. A ProgressBar and "Step x of y" give orientation; Back and Continue replace a stack of nested dialogs.

import { useState } from "react";
import { Button } from "@/components/ui/button";
import {
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { ProgressBar } from "@/components/ui/progress-bar";
import { RadioCard, RadioGroup } from "@/components/ui/radio-group";
import { Switch } from "@/components/ui/switch";
import { TextField } from "@/components/ui/text-field";

const steps = ["Name", "Template", "Settings"];

export default function DialogRecipeWizard() {
  const [step, setStep] = useState(0);
  const last = step === steps.length - 1;
  return (
    <DialogTrigger onOpenChange={(open) => open && setStep(0)}>
      <Button variant="outline">New workspace</Button>
      <DialogContent>
        {({ close }) => (
          <>
            <DialogHeader>
              <DialogTitle>Create a workspace</DialogTitle>
              <DialogDescription>
                Step {step + 1} of {steps.length} · {steps[step]}
              </DialogDescription>
            </DialogHeader>
            <ProgressBar
              aria-label="Progress"
              value={((step + 1) / steps.length) * 100}
              showValue={false}
              size="sm"
            />
            <div className="min-h-40">
              {step === 0 && (
                <TextField
                  label="Workspace name"
                  defaultValue="Acme"
                  autoFocus
                />
              )}
              {step === 1 && (
                <RadioGroup aria-label="Template" defaultValue="blank">
                  <RadioCard
                    value="blank"
                    title="Blank"
                    description="Start from scratch."
                  />
                  <RadioCard
                    value="saas"
                    title="SaaS app"
                    description="Auth, billing and a dashboard."
                  />
                </RadioGroup>
              )}
              {step === 2 && (
                <div className="grid gap-4">
                  <Switch
                    labelPlacement="start"
                    defaultSelected
                    description="Members can invite others."
                  >
                    Open invites
                  </Switch>
                  <Switch
                    labelPlacement="start"
                    description="Require SSO for all members."
                  >
                    Enforce SSO
                  </Switch>
                </div>
              )}
            </div>
            <DialogFooter>
              <Button
                variant="ghost"
                isDisabled={step === 0}
                onPress={() => setStep((s) => s - 1)}
              >
                Back
              </Button>
              <Button onPress={() => (last ? close() : setStep((s) => s + 1))}>
                {last ? "Create workspace" : "Continue"}
              </Button>
            </DialogFooter>
          </>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}

Accessibility

Focus moves into the dialog on open (to the first focusable element, or one with autoFocus), stays trapped inside, and returns to the trigger on close.
Page scroll is locked while open, and content outside the dialog is hidden from screen readers with aria-hidden.
DialogTitle provides the accessible name. Without a visible title, pass aria-label to DialogContent.
role="alertdialog" tells screen readers the dialog needs an immediate response.
Put autoFocus on the least destructive action in alert dialogs, or on the first field in forms.
Nested overlays (selects, menus, popovers) inside a dialog work as expected; Esc closes the innermost one first.

Keyboard

Key	Action
`Tab` / `Shift`+`Tab`	Cycles focus within the dialog
`Esc`	Closes the dialog (unless `isKeyboardDismissDisabled` or `role="alertdialog"`)

Styling

Data attributes

Attribute	On	Present when
`data-entering`	overlay, content	Opening animation is running
`data-exiting`	overlay, content	Closing animation is running
`data-slot="dialog-overlay"`	backdrop	Always
`data-slot="dialog-content"`	panel	Always
`data-slot="dialog-body"`	body	When `DialogBody` is used

Enter and exit animations use tw-animate-css classes keyed off data-entering and data-exiting, so React Aria waits for them to finish before unmounting.

Customizing

className on DialogContent styles the panel (width, height, padding, radius).
The backdrop uses the exported overlayStyles string; reuse it for your own modal surfaces.
The panel is a flex column capped at the viewport height; the inner Dialog is flex flex-col gap-4 p-6 and scrolls as a fallback if you don't use DialogBody.
The inner Dialog padding is p-6. Override with [&>[role=dialog]]:p-0 on DialogContent for edge-to-edge content like images.

Type

DialogTitle

Accepts every prop of React Aria's Heading, including level to change the heading element.

DialogHeader / DialogBody / DialogFooter / DialogDescription

Accept every prop of <div> / <div> / <div> / <p>.

Sheet — a dialog that slides in from the edge.
Popover — non-modal content anchored to a trigger.
Command Palette — a searchable dialog of actions.
Toast — non-blocking feedback after the dialog closes.