ui/components/dialog

Dialog

Native modal dialog with compound parts, configurable frame and corner treatments, and a header strip band carrying the title and its optional description.

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogDefault() {14   return (15     <Dialog>16       <DialogTrigger>Open Dialog</DialogTrigger>17       <DialogContent>18         <DialogHeader>19           <DialogTitle>Apply Patch</DialogTitle>20         </DialogHeader>21         <DialogBody>22           <p className="text-sm text-muted-foreground leading-relaxed">23             This will modify <span className="text-foreground font-bold">2 files</span> in{" "}24             <span className="text-foreground font-mono">src/auth/</span>.25             <br />26             Continue?27           </p>28         </DialogBody>29         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>30           <DialogClose bracket>Cancel</DialogClose>31           <DialogAction>Apply</DialogAction>32         </DialogFooter>33       </DialogContent>34     </Dialog>35   );36 }37

Installation

$pnpm exec dgadd add ui/dialog

[Installs to]src/components/ui/dialog[Item]ui/dialog

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogDefault() {14   return (15     <Dialog>16       <DialogTrigger>Open Dialog</DialogTrigger>17       <DialogContent>18         <DialogHeader>19           <DialogTitle>Apply Patch</DialogTitle>20         </DialogHeader>21         <DialogBody>22           <p className="text-sm text-muted-foreground leading-relaxed">23             This will modify <span className="text-foreground font-bold">2 files</span> in{" "}24             <span className="text-foreground font-mono">src/auth/</span>.25             <br />26             Continue?27           </p>28         </DialogBody>29         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>30           <DialogClose bracket>Cancel</DialogClose>31           <DialogAction>Apply</DialogAction>32         </DialogFooter>33       </DialogContent>34     </Dialog>35   );36 }37

Examples

Open State (inline, non-modal)

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogCloseIcon,7   DialogContent,8   DialogDescription,9   DialogFooter,10   DialogHeader,11   DialogTitle,12 } from "@/components/ui/dialog";13 14 // modal={false} renders the dialog chrome in the document flow — same frame,15 // corners, header strip, eyebrow, and footer as the modal, without the16 // backdrop, focus trap, or top layer. That keeps the open state reviewable on a17 // static page. Product code opens a modal from a Dialog.Trigger instead. An18 // inline dialog gets no automatic [x], so the first one composes DialogCloseIcon.19 export default function DialogInlineExample() {20   return (21     <div className="flex flex-col gap-10">22       <Dialog open>23         <DialogContent modal={false} size="sm" corners="standard">24           <DialogHeader>25             <DialogTitle meta="CONFIRM">Apply Patch</DialogTitle>26           </DialogHeader>27           <DialogBody>28             <p className="text-sm text-muted-foreground leading-relaxed">29               This will modify <span className="text-foreground font-bold">2 files</span> in{" "}30               <span className="text-foreground font-mono">src/auth/</span>.31             </p>32           </DialogBody>33           <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>34             <DialogClose bracket>Cancel</DialogClose>35             <DialogAction>Apply</DialogAction>36           </DialogFooter>37           <DialogCloseIcon />38         </DialogContent>39       </Dialog>40 41       <Dialog open>42         <DialogContent modal={false} size="sm" corners="bold">43           <DialogHeader>44             <DialogTitle meta="DESTRUCTIVE">Delete Repository</DialogTitle>45             <DialogDescription>This action is permanent and cannot be undone.</DialogDescription>46           </DialogHeader>47           <DialogBody>48             <p className="text-sm text-muted-foreground leading-relaxed">49               All files, commits, and branches in{" "}50               <span className="text-foreground font-mono">voitz/diffgazer</span> are removed.51             </p>52           </DialogBody>53           <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>54             <DialogClose bracket>Cancel</DialogClose>55             <DialogAction variant="destructive">Delete</DialogAction>56           </DialogFooter>57         </DialogContent>58       </Dialog>59     </div>60   );61 }62

Bracketed

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogBracketed() {14   return (15     <Dialog>16       <DialogTrigger>Open Dialog</DialogTrigger>17       <DialogContent frame="border" corners="standard">18         <DialogHeader>19           <DialogTitle meta="CONFIRM">Apply Patch</DialogTitle>20         </DialogHeader>21         <DialogBody>22           <p className="text-sm text-muted-foreground leading-relaxed">23             This will modify <span className="text-foreground font-bold">2 files</span> in{" "}24             <span className="text-foreground font-mono">src/auth/</span>.25             <br />26             Continue?27           </p>28         </DialogBody>29         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>30           <DialogClose bracket variant="ghost">31             Cancel32           </DialogClose>33           <DialogAction>Apply</DialogAction>34         </DialogFooter>35       </DialogContent>36     </Dialog>37   );38 }39

Corner Marks

Preview

tsx

1 import { InlineCode } from "@/components/ui/code-block";2 import {3   Dialog,4   DialogAction,5   DialogBody,6   DialogClose,7   DialogContent,8   DialogFooter,9   DialogHeader,10   DialogTitle,11   DialogTrigger,12 } from "@/components/ui/dialog";13 14 export default function DialogCorners() {15   return (16     <div className="flex flex-wrap gap-3">17       {(["subtle", "standard", "bold", "outset"] as const).map((corners) => (18         <Dialog key={corners}>19           <DialogTrigger>{corners.toUpperCase()}</DialogTrigger>20           <DialogContent frame="none" corners={corners}>21             <DialogHeader>22               <DialogTitle meta="CONFIRM">Apply Patch</DialogTitle>23             </DialogHeader>24             <DialogBody>25               <p className="text-sm text-muted-foreground leading-relaxed">26                 Corner marks: <InlineCode>{corners}</InlineCode>. This will modify{" "}27                 <span className="text-foreground font-bold">2 files</span> in{" "}28                 <span className="text-foreground font-mono">src/auth/</span>.29               </p>30             </DialogBody>31             <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>32               <DialogClose bracket>Cancel</DialogClose>33               <DialogAction>Apply</DialogAction>34             </DialogFooter>35           </DialogContent>36         </Dialog>37       ))}38     </div>39   );40 }41

With Description

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogDescription,8   DialogFooter,9   DialogHeader,10   DialogTitle,11   DialogTrigger,12 } from "@/components/ui/dialog";13 14 export default function DialogDescriptionExample() {15   return (16     <Dialog>17       <DialogTrigger>Reset Config</DialogTrigger>18       <DialogContent>19         <DialogHeader>20           <DialogTitle>Reset Configuration</DialogTitle>21           <DialogDescription>22             This will restore all settings to their default values.23           </DialogDescription>24         </DialogHeader>25         <DialogBody>26           <p className="text-sm text-muted-foreground leading-relaxed">27             Your current config in{" "}28             <span className="text-foreground font-mono">.diffgazer/config.json</span> will be29             overwritten. A backup will be saved as{" "}30             <span className="text-foreground font-mono">config.json.bak</span>.31           </p>32         </DialogBody>33         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>34           <DialogClose bracket>Cancel</DialogClose>35           <DialogAction>Reset</DialogAction>36         </DialogFooter>37       </DialogContent>38     </Dialog>39   );40 }41

Alert Dialog

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogDescription,8   DialogFooter,9   DialogHeader,10   DialogTitle,11   DialogTrigger,12 } from "@/components/ui/dialog";13 14 export default function DialogAlertExample() {15   return (16     <Dialog>17       <DialogTrigger>Delete Repository</DialogTrigger>18       <DialogContent role="alertdialog" closeOnBackdropClick={false}>19         <DialogHeader>20           <DialogTitle>Delete Repository</DialogTitle>21           <DialogDescription>This action is permanent and cannot be undone.</DialogDescription>22         </DialogHeader>23         <DialogBody>24           <p className="text-sm text-muted-foreground leading-relaxed">25             All files, commits, and branches in{" "}26             <span className="text-foreground font-mono">voitz/diffgazer</span> will be permanently27             deleted. This includes all issues, pull requests, and CI/CD pipelines.28           </p>29         </DialogBody>30         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>31           <DialogClose bracket variant="ghost" autoFocus>32             Cancel33           </DialogClose>34           <DialogAction variant="destructive" bracket>35             Delete36           </DialogAction>37         </DialogFooter>38       </DialogContent>39     </Dialog>40   );41 }42

With Form

Preview

tsx

1 "use client";2 3 import { type FormEvent, useState, useTransition } from "react";4 import {5   Dialog,6   DialogAction,7   DialogBody,8   DialogClose,9   DialogContent,10   DialogFooter,11   DialogHeader,12   DialogTitle,13   DialogTrigger,14 } from "@/components/ui/dialog";15 import { Input } from "@/components/ui/input";16 import { Label } from "@/components/ui/label";17 18 const CREATE_DELAY_MS = 1000;19 20 function wait(ms: number) {21   return new Promise<void>((resolve) => window.setTimeout(resolve, ms));22 }23 24 export default function DialogForm() {25   const [open, setOpen] = useState(false);26   const [name, setName] = useState("");27   const [submitting, startCreate] = useTransition();28 29   const handleOpenChange = (nextOpen: boolean) => {30     if (submitting && !nextOpen) return;31     setOpen(nextOpen);32     if (!nextOpen) setName("");33   };34 35   const submit = () => {36     if (!name.trim() || submitting) return;37 38     startCreate(async () => {39       await wait(CREATE_DELAY_MS);40       setName("");41       setOpen(false);42     });43   };44 45   const handleSubmit = (event: FormEvent<HTMLFormElement>) => {46     event.preventDefault();47     submit();48   };49 50   return (51     <Dialog open={open} onOpenChange={handleOpenChange}>52       <DialogTrigger>New Project</DialogTrigger>53       <DialogContent54         closeOnBackdropClick={!submitting}55         onEscapeKeyDown={(e) => {56           if (submitting) e.preventDefault();57         }}58       >59         <DialogHeader>60           <DialogTitle>Create Project</DialogTitle>61         </DialogHeader>62         <form onSubmit={handleSubmit}>63           <DialogBody>64             <Label label="Project Name">65               <Input66                 autoFocus67                 value={name}68                 onChange={(e) => setName(e.target.value)}69                 placeholder="my-project"70               />71             </Label>72           </DialogBody>73           <DialogFooter74             hints={[75               { key: "Esc", label: "Close" },76               { key: "Enter", label: "Submit" },77             ]}78           >79             <DialogClose bracket disabled={submitting}>80               Cancel81             </DialogClose>82             <DialogAction83               disabled={!name.trim() || submitting}84               loading={submitting}85               onClick={(event) => {86                 event.preventDefault();87                 submit();88               }}89             >90               {submitting ? "Creating..." : "Create"}91             </DialogAction>92           </DialogFooter>93         </form>94       </DialogContent>95     </Dialog>96   );97 }98

Sizes

Preview

tsx

1 import { InlineCode } from "@/components/ui/code-block";2 import {3   Dialog,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogSizes() {14   return (15     <div className="flex gap-3">16       {(["sm", "md", "lg", "full"] as const).map((size) => (17         <Dialog key={size}>18           <DialogTrigger>{size.toUpperCase()}</DialogTrigger>19           <DialogContent size={size}>20             <DialogHeader>21               <DialogTitle>Size: {size}</DialogTitle>22             </DialogHeader>23             <DialogBody>24               <p className="text-sm text-muted-foreground">25                 This dialog uses the <InlineCode>{size}</InlineCode> size variant.26               </p>27             </DialogBody>28             <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>29               <DialogClose bracket>Close</DialogClose>30             </DialogFooter>31           </DialogContent>32         </Dialog>33       ))}34     </div>35   );36 }37

Upload

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogUpload() {14   return (15     <Dialog>16       <DialogTrigger>Upload File</DialogTrigger>17       <DialogContent>18         <DialogHeader>19           <DialogTitle>Uploading File</DialogTitle>20         </DialogHeader>21         <DialogBody>22           <div className="space-y-3">23             <p className="text-sm text-muted-foreground">24               <span className="text-foreground font-mono">diffgazer-v1.4.2-linux-x64.tar.gz</span>25             </p>26             <div className="font-mono text-sm">27               <span className="text-success">[████████░░░░]</span>{" "}28               <span className="text-foreground">67%</span>29             </div>30             <div className="space-y-1 text-sm text-muted-foreground">31               <p>32                 <span className="text-success">[x]</span> Checksum verified33               </p>34               <p>35                 <span className="text-muted-foreground">[ ]</span> Signature verified36               </p>37             </div>38           </div>39         </DialogBody>40         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>41           <DialogClose bracket>Cancel</DialogClose>42           <DialogAction>Background</DialogAction>43         </DialogFooter>44       </DialogContent>45     </Dialog>46   );47 }48

Keyboard

Preview

tsx

1 "use client";2 3 import { useRef } from "react";4 import {5   Dialog,6   DialogAction,7   DialogBody,8   DialogClose,9   DialogContent,10   DialogDescription,11   DialogFooter,12   DialogHeader,13   DialogTitle,14   DialogTrigger,15 } from "@/components/ui/dialog";16 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item17 import { useNavigation } from "@/hooks/use-navigation";18 19 export default function DialogKeyboard() {20   const containerRef = useRef<HTMLDivElement>(null);21 22   const { onKeyDown } = useNavigation({23     containerRef,24     role: "button",25     orientation: "horizontal",26     moveFocus: true,27   });28 29   return (30     <Dialog>31       <DialogTrigger>Delete Branch</DialogTrigger>32       <DialogContent role="alertdialog" closeOnBackdropClick={false}>33         <DialogHeader>34           <DialogTitle>Delete Branch</DialogTitle>35           <DialogDescription>This action cannot be undone.</DialogDescription>36         </DialogHeader>37         <DialogBody>38           <p className="text-sm text-muted-foreground leading-relaxed">39             Are you sure you want to delete{" "}40             <span className="text-foreground font-mono">feature/auth-refactor</span>?41           </p>42         </DialogBody>43         <DialogFooter44           ref={containerRef}45           onKeyDown={onKeyDown}46           hints={[47             { key: "Esc", label: "Close" },48             { key: "←/→", label: "Navigate" },49             { key: "Enter", label: "Confirm" },50           ]}51         >52           <DialogClose data-value="cancel" bracket>53             Cancel54           </DialogClose>55           <DialogAction data-value="delete" variant="destructive">56             Delete57           </DialogAction>58         </DialogFooter>59       </DialogContent>60     </Dialog>61   );62 }63

Custom Trigger

Preview

tsx

1 "use client";2 3 import { Button } from "@/components/ui/button";4 import {5   Dialog,6   DialogAction,7   DialogBody,8   DialogClose,9   DialogContent,10   DialogFooter,11   DialogHeader,12   DialogTitle,13   DialogTrigger,14 } from "@/components/ui/dialog";15 16 export default function DialogCustomTrigger() {17   return (18     <Dialog>19       <DialogTrigger>20         {(triggerProps) => (21           <Button {...triggerProps} variant="ghost">22             Open Dialog23           </Button>24         )}25       </DialogTrigger>26       <DialogContent>27         <DialogHeader>28           <DialogTitle>Custom Trigger</DialogTitle>29         </DialogHeader>30         <DialogBody>31           <p className="text-sm text-muted-foreground leading-relaxed">32             This dialog was opened from a{" "}33             <span className="font-mono text-foreground">&lt;Button&gt;</span> using the render-prop34             pattern, avoiding{" "}35             <span className="font-mono text-foreground">&lt;button&gt;&lt;button&gt;</span> nesting.36           </p>37         </DialogBody>38         <DialogFooter>39           <DialogClose bracket>Close</DialogClose>40           <DialogAction>Confirm</DialogAction>41         </DialogFooter>42       </DialogContent>43     </Dialog>44   );45 }46

Close Icon

Preview

tsx

1 import { InlineCode } from "@/components/ui/code-block";2 import {3   Dialog,4   DialogBody,5   DialogContent,6   DialogHeader,7   DialogTitle,8   DialogTrigger,9 } from "@/components/ui/dialog";10 11 export default function DialogCloseIconExample() {12   return (13     <Dialog>14       <DialogTrigger>Open Dialog</DialogTrigger>15       <DialogContent>16         <DialogHeader>17           <DialogTitle>With close icon</DialogTitle>18         </DialogHeader>19         <DialogBody>20           <p className="text-sm leading-relaxed">21             Every modal dialog renders the top-right icon button by default. It closes the dialog,22             and Esc still closes too. Pass <InlineCode>closeIcon={"{false}"}</InlineCode> to opt23             out.24           </p>25         </DialogBody>26       </DialogContent>27     </Dialog>28   );29 }30

Nested Popover

Preview

tsx

1 import {2   Dialog,3   DialogBody,4   DialogClose,5   DialogContent,6   DialogDescription,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 import { Popover } from "@/components/ui/popover";13 14 export default function DialogPopoverExample() {15   return (16     <Dialog>17       <DialogTrigger>Open nested overlay</DialogTrigger>18       <DialogContent size="sm">19         <DialogHeader>20           <DialogTitle>Nested overlay</DialogTitle>21           <DialogDescription>Escape closes one overlay layer at a time.</DialogDescription>22         </DialogHeader>23         <DialogBody className="flex items-center gap-3">24           <Popover>25             <Popover.Trigger>Open popover</Popover.Trigger>26             <Popover.Content27               role="dialog"28               aria-label="Nested popover"29               autoFocus={false}30               className="p-3"31             >32               <button type="button" className="border border-border px-3 py-1 text-sm">33                 Popover action34               </button>35             </Popover.Content>36           </Popover>37           <button type="button" className="border border-border px-3 py-1 text-sm">38             Dialog sibling39           </button>40         </DialogBody>41         <DialogFooter>42           <DialogClose>Done</DialogClose>43         </DialogFooter>44       </DialogContent>45     </Dialog>46   );47 }48

API Reference

Dialog

Name	Type	Default	Description
open	boolean	—	Controlled open state. Pair with onOpenChange.
defaultOpen	boolean	false	Initial open state for uncontrolled usage.
onOpenChange	(open: boolean) => void	—	Called whenever open state changes (trigger click, Escape, backdrop click, programmatic close).

DialogContent

Name	Type	Default	Description
size	"sm" \| "md" \| "lg" \| "full"	"md"	Modal width preset.
frame	"border" \| "none"	"border"	Border frame style. "border" renders a 1px border around the dialog. "none" removes the border (pair with corners for a frameless viewfinder look).
corners	"none" \| "subtle" \| "standard" \| "bold" \| "outset"	"none"	Corner accent marks drawn at the dialog corners. "none" skips them. "subtle" uses border color and tighter 12px arms. "standard" uses foreground color 18px arms. "bold" uses foreground color 28px arms. "outset" is standard shifted 3px outside the dialog edge. Combine with frame="none" for a pure viewfinder look or frame="border" for a bracketed-frame look.
role	"dialog" \| "alertdialog"	"dialog"	Set role="alertdialog" for destructive confirmations. Per WAI-ARIA APG, alert dialogs should not close on outside interaction. Modal mode only — an inline dialog is a labelled region, not a dialog.
modal	boolean	true	Renders the dialog as a native modal in the browser top layer. Pass false to render the same frame, corners, and chrome in the document flow instead — no backdrop, focus trap, scroll lock, or focus restoration, and role="group" instead of a dialog role.
closeIcon	boolean	true	Renders the top-right [x] close control on a modal dialog. Pass false to opt out when the dialog owns its own dismissal affordance. Inline dialogs never render it — compose DialogCloseIcon explicitly there.
closeOnBackdropClick	boolean	true	When false, clicking the backdrop does not close the dialog (recommended for alertdialog).
initialFocus	RefObject<HTMLElement \| null>	—	Element ref to focus when the dialog opens. Use it for alertdialog flows where focus should start on the safest action, such as Cancel.
onEscapeKeyDown	(e: SyntheticEvent<HTMLDialogElement>) => void	—	Intercept Escape. Call e.preventDefault() to keep the dialog open during async operations.
onCancel	(e: SyntheticEvent<HTMLDialogElement>) => void	—	Native cancel handler. Defaults to closing the dialog.

DialogTitle

Name	Type	Default	Description
as	"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"	"h2"	Heading level for the title element.
meta	string	—	Optional eyebrow tag (e.g. "CONFIRM", "DESTRUCTIVE"). Sits at the title row inline end, except when a DialogCloseIcon is present — then the close button owns the top-right corner and the eyebrow moves next to the title text instead. Rendered as dialog content but outside the heading, so it is excluded from the dialog accessible name.

DialogTrigger

Name	Type	Default	Description
childrenrequired	ReactNode \| (renderProps: DialogTriggerRenderProps) => ReactNode	—	Trigger button or render function. The render form receives ref, className, aria-haspopup/expanded/controls, and onClick.

DialogAction

Name	Type	Default	Description
onClick	(e: MouseEvent<HTMLButtonElement>) => void	—	Primary action handler. Call e.preventDefault() to keep the dialog open (e.g. failed form validation).

DialogClose

Name	Type	Default	Description
onClick	(e: MouseEvent<HTMLButtonElement>) => void	—	Close handler. Call e.preventDefault() to keep the dialog open.
aria-label	string	—	Explicit accessible name. aria-labelledby wins when both attributes are set. With neither attribute, visible child text names the button; empty, decorative, or hidden content falls back to "Close dialog".
aria-labelledby	string	—	ID of the element that labels the close button. It takes precedence over aria-label and suppresses the automatic "Close dialog" fallback.

DialogCloseIcon

Name	Type	Default	Description
aria-label	string	"Close dialog"	Accessible name for the close button. Override for localization or alternative phrasing.

DialogFooter

Name	Type	Default	Description
hints	KeyboardHint[]	—	Inline keyboard shortcut hints rendered alongside the action buttons. Use the shorthand instead of composing DialogFooter.Hints when the hints belong with the footer actions.

Data attributes

Attribute	Applies to	Values	Description
data-state	DialogContent	"open" \| "closed"	Native dialog open state mirrored by the shared shell.
data-frame	DialogContent	"border" \| "none"	Border frame style.
data-corners	DialogContent	"none" \| "subtle" \| "standard" \| "bold" \| "outset"	Corner accent treatment.

Accessibility

Keyboard Navigation

Dialog uses the native <dialog> element for modal behavior. Escape closes the dialog and focus is automatically restored to the trigger. Tab cycles focus between focusable elements within the dialog (native inert background). Enter activates the focused button (DialogAction or DialogClose).

Key	Action
Escape	Closes the dialog unless onEscapeKeyDown prevents it.
Tab / Shift+Tab	Moves through focusable dialog content while the native modal keeps background inert.
Enter / Space	Activates the focused button, action, or close control.

Default with keyboard

Preview

tsx

1 import {2   Dialog,3   DialogAction,4   DialogBody,5   DialogClose,6   DialogContent,7   DialogFooter,8   DialogHeader,9   DialogTitle,10   DialogTrigger,11 } from "@/components/ui/dialog";12 13 export default function DialogDefault() {14   return (15     <Dialog>16       <DialogTrigger>Open Dialog</DialogTrigger>17       <DialogContent>18         <DialogHeader>19           <DialogTitle>Apply Patch</DialogTitle>20         </DialogHeader>21         <DialogBody>22           <p className="text-sm text-muted-foreground leading-relaxed">23             This will modify <span className="text-foreground font-bold">2 files</span> in{" "}24             <span className="text-foreground font-mono">src/auth/</span>.25             <br />26             Continue?27           </p>28         </DialogBody>29         <DialogFooter hints={[{ key: "Esc", label: "Close" }]}>30           <DialogClose bracket>Cancel</DialogClose>31           <DialogAction>Apply</DialogAction>32         </DialogFooter>33       </DialogContent>34     </Dialog>35   );36 }37

Keyboard hints

Preview

tsx

1 "use client";2 3 import { useRef } from "react";4 import {5   Dialog,6   DialogAction,7   DialogBody,8   DialogClose,9   DialogContent,10   DialogDescription,11   DialogFooter,12   DialogHeader,13   DialogTitle,14   DialogTrigger,15 } from "@/components/ui/dialog";16 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden use-navigation hook registry item17 import { useNavigation } from "@/hooks/use-navigation";18 19 export default function DialogKeyboard() {20   const containerRef = useRef<HTMLDivElement>(null);21 22   const { onKeyDown } = useNavigation({23     containerRef,24     role: "button",25     orientation: "horizontal",26     moveFocus: true,27   });28 29   return (30     <Dialog>31       <DialogTrigger>Delete Branch</DialogTrigger>32       <DialogContent role="alertdialog" closeOnBackdropClick={false}>33         <DialogHeader>34           <DialogTitle>Delete Branch</DialogTitle>35           <DialogDescription>This action cannot be undone.</DialogDescription>36         </DialogHeader>37         <DialogBody>38           <p className="text-sm text-muted-foreground leading-relaxed">39             Are you sure you want to delete{" "}40             <span className="text-foreground font-mono">feature/auth-refactor</span>?41           </p>42         </DialogBody>43         <DialogFooter44           ref={containerRef}45           onKeyDown={onKeyDown}46           hints={[47             { key: "Esc", label: "Close" },48             { key: "←/→", label: "Navigate" },49             { key: "Enter", label: "Confirm" },50           ]}51         >52           <DialogClose data-value="cancel" bracket>53             Cancel54           </DialogClose>55           <DialogAction data-value="delete" variant="destructive">56             Delete57           </DialogAction>58         </DialogFooter>59       </DialogContent>60     </Dialog>61   );62 }63

Notes

Requires @diffgazer/keys (package mode)

DialogContent's focus restore (returning focus to the trigger on close) imports from the required @diffgazer/keys peer. Package consumers need @diffgazer/keys installed alongside @diffgazer/ui. Diffgazer packages are not yet published to npm; until the first release, install both from locally packed tarballs. Importing @diffgazer/ui/components/dialog without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the focus-restore hook to local source.

Compound Architecture

Dialog is composed of Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter (with DialogFooter.Hints and DialogFooter.Actions sub-components), DialogClose, DialogAction, and DialogCloseIcon.

Header strip

DialogHeader is a single form: a 44px band one surface step above the body (--surface-2) closed by a bottom hairline, laying its children out in one row. A DialogTitle renders as the 14px/700 mono title in the accent tone (--info-text) and a DialogDescription beside it as the 12px muted subtitle. Pass className to override padding, background, or direction — the overrides merge via tailwind-merge.

Close control

A modal DialogContent renders the top-right [x] (DialogCloseIcon) by default, so every modal dialog carries a pointer dismissal affordance. Pass closeIcon={false} to opt out when the dialog owns its own dismissal control. Inline dialogs (modal={false}) never render it — compose DialogCloseIcon yourself there, last inside DialogContent so it stays the final tab stop.

Native Dialog

DialogContent uses the native <dialog> element with showModal(), which provides built-in focus management, inert background, top-layer rendering, and accessible modal semantics. Focus is restored to the trigger on close.

Scroll lock

Background scroll lock has exactly one owner, and it is not the stylesheet. showModal() does not lock background scroll, so DialogContent runs useScrollLock (reference counted, scrollbar-width compensated) while it is open and modal — that lock is also the one that handles custom scroll roots and stacked dialogs. The CSS-only body lock shared/dialog.css used to ship alongside it is gone: two locks compensated for the same scrollbar twice, and the page jumped on every open. Consumers driving a raw <dialog> off the stylesheet alone therefore get no automatic lock and own that themselves (useScrollLock drops in). Inline dialogs (modal={false}) never lock.

Alert Dialog

Set role="alertdialog" and closeOnBackdropClick={false} on DialogContent for destructive confirmations. Screen readers announce it as an alert requiring immediate attention. Per WAI-ARIA APG, alert dialogs should not close on outside interaction, and focus should start on the safest action (e.g., Cancel) using initialFocus.

Escape Interception

Pass onEscapeKeyDown to DialogContent to intercept cancelable Escape dismissal. Call e.preventDefault() to keep the dialog open during async operations or form validation; if the native dialog is force-closed without a cancelable cancel event while React open is still true, the shell reopens it.

Nested popovers

An open Popover inside Dialog owns the first Escape press, including when focus is on a dialog sibling. Escape closes only the popover; focus returns to its trigger only when focus was inside the popover or trigger.

Preventing Close on Action

DialogAction and DialogClose check e.defaultPrevented. Call e.preventDefault() in your onClick handler to keep the dialog open — useful for async validation where you want to close only on success.

Keyboard hints

Pass a hints array to DialogFooter (or compose DialogFooter.Hints) to render inline keyboard shortcut hints alongside the action buttons. Hints render through the shared OverlayHints primitive (registry/ui/shared/overlay-hints), so Dialog, CommandPalette, and any future keyboard surface spell their legend the same way. Dialog opts out of the primitive's aria-hidden default so the key names stay discoverable by assistive technology. At coarse pointer the legend collapses — a key hint is instructions a touch user cannot follow — so keep any touch-relevant action in the action row, not the hints.

Corner clearance

The corner brackets own the dialog corners, so the content insets around them. corners="bold" draws 28px arms and pushes the footer actions inward so a button corner never collides with the bottom brackets, and the DialogCloseIcon inset grows per corner variant. The close icon owns the top-right corner alone: when a DialogTitle also carries a meta eyebrow, the eyebrow drops out of the corner and sits beside the title text instead, and the title row reserves the button's slot so a long (truncating) title stays clear of it.

Inline (non-modal)

Pass modal={false} to DialogContent to render the same frame, corners, header strip, and footer in the document flow — no backdrop, focus trap, scroll lock, or focus restoration. Because nothing is modal about it, the inline shell exposes role="group" (still named by DialogTitle) rather than a dialog role, and the role prop is ignored. Use it to embed dialog chrome in a page, or to make the open state visible on a static page — see the Open State example. Inline content still honours open, so it unmounts when the consumer closes it. DialogContentProps is a discriminated union on modal, so each arm types it as a literal (modal?: true or modal: false) and a boolean variable satisfies neither: branch on the variable and render the arm you mean.

Surface and backdrop

DialogContent is the modal overlay tier: --surface-1 fill (one step off the page background) with a 1px --surface-1-highlight inner lip, 1px border under the default frame='border', rounded-sm corners, and --shadow-hard (a hard 4px offset with no blur) — the library's only sanctioned shadow, reserved for this tier. Anchored overlays such as Popover and Menu submenus share the fill and lip but drop the slab shadow. The backdrop dims with --scrim over a 2px blur; the dim carries the layer separation, not the blur.

Narrow-viewport geometry

Below 640px DialogContent insets 12px from each viewport edge (max-sm:mx-3 with a matching width and max-w-none) so both vertical hairlines, the offset shadow, and the corner brackets render whole instead of being clipped at the edge. It also pads its bottom by env(safe-area-inset-bottom) to keep the footer's action row clear of the home indicator — that requires viewport-fit=cover on the host page and resolves to 0 without it. The height cap stays max-h-[90dvh], and nothing changes at 640px and up.

Entrance motion

The overlay family runs one entrance vector: opacity plus a 4px translateY drop, never a scale — a scale-in reads as a rubbery soft-UI surface, and on a wide dialog it grows the drawn border across every open. The modal tier owns its entrance clock: --dialog-duration is 150ms, because a dialog takes over the viewport and reads as a deliberate open, while the anchored tier (Select, Popover, Tooltip) stays on the 60ms --ui-content-* tokens where anything slower feels laggy under the pointer. The exit stays on --ui-content-exit-duration, and --dialog-duration remains a working per-instance override. prefers-reduced-motion: reduce drops the animation entirely.

Extending DialogContent styles

dialogContentVariants is the CVA used by DialogContent. Re-export it to compose custom variants for product-specific dialog shells — e.g. extend the base classes with bg/border tokens, or add new size keys. The corners prop is a plain TypeScript type (DialogCorners) whose visual styling is driven by [data-corners] selectors in shared/dialog.css.

Scroll lock

Native <dialog>.showModal() does not lock background scroll, so Dialog.Content locks it in JavaScript: useScrollLock from @diffgazer/keys, pointed at the dialog's own ownerDocument.body and enabled while the dialog is open and modal.

The lock is reference counted, so a stack of dialogs takes one lock and the last one to close restores the body's original overflow and padding-right. Compensation is measured rather than reserved: the hook adds the scrollbar's width to padding-right for the life of the lock, so hiding the scrollbar does not shift the page sideways. Inline dialogs (modal={false}) never lock — nothing is modal about them.

Limits to be aware of:

Custom scroll roots. Dialog locks <body>. Apps that scroll on <html>, on a wrapping layout element, or inside a dedicated scroll container call useScrollLock({ target }) themselves for that element.
iOS Safari rubber-band. overflow: hidden on <body> does not prevent touch scrolling of the visual viewport. If preventing rubber-band is required, layer a touchmove handler on top.

Copy-mode installs pull keys/scroll-lock as a registry dependency of dialog, so the hook arrives with the component. A raw <dialog> driven off dialog.css alone gets no background lock and owns that itself.

Source

Install via CLI: pnpm exec dgadd add ui/dialog. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Dialog

Installation

Usage

Examples

Open State (inline, non-modal)

Bracketed

Corner Marks

With Description

Alert Dialog

With Form

Sizes

Upload

Keyboard

Custom Trigger

Close Icon

Nested Popover

API Reference

Dialog

DialogContent

DialogTitle

DialogTrigger

DialogAction

DialogClose

DialogCloseIcon

DialogFooter

Data attributes

Accessibility

Keyboard Navigation

Default with keyboard

Keyboard hints

Notes

Requires @diffgazer/keys (package mode)

Compound Architecture

Header strip

Close control

Native Dialog

Scroll lock

Alert Dialog

Escape Interception

Nested popovers

Preventing Close on Action

Keyboard hints

Corner clearance

Inline (non-modal)

Surface and backdrop

Narrow-viewport geometry

Entrance motion

Extending DialogContent styles

Scroll lock

Source

View component source (52 files)