# Dialog ## Summary `Dialog` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for modal overlays with root, trigger, and content parts. `DialogClose` turns your own button into a close button; headings and layout are plain markup you compose yourself. `DialogContent` renders a native `` opened with `showModal()`, so the browser puts it in the top layer, makes the rest of the page inert, and draws the backdrop. It is the strongest general-purpose overlay in the family and should be chosen when modal interruption is intentional. ## Imports ```tsx import { Dialog, DialogTrigger, DialogContent, DialogClose, type DialogProps, } from '@vega-ui/react'; ``` ## Exported Types - `DialogProps` - `DialogTriggerProps` - `DialogContentProps` - `DialogCloseProps` ## Minimal Composition ```tsx import { useId, type CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Heading, Icon, IconButton, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const destructive = { '--button-background-color': 'var(--color-red-accent-500)', '--button-background-color-hover': 'var(--color-red-accent-600)', '--button-background-color-active': 'var(--color-red-accent-700)', } as CSSProperties; export default function MinimalComposition() { const titleId = useId(); return (
Leave Northwind Studio?
You will lose access to 14 projects until an admin invites you again.
); } ``` ## Required Parts - `Dialog`: root state and context provider - `DialogTrigger`: open action surface - `DialogContent`: modal content container ## Optional Parts - `DialogClose`: closes the dialog when clicked; wraps your own button with `asChild` ## Your Own Markup - a heading whose `id` is passed to `DialogContent` as `aria-labelledby` (or `aria-label` on `DialogContent`); the dialog must have a name - action buttons that answer the dialog (Cancel, Confirm) inside a `
` ## Composition Order Typical composition: 1. `Dialog` 2. `DialogTrigger` 3. `DialogContent` with your heading, an optional `DialogClose`, body, and a `` for action buttons ## Variants - Controlled open state versus trigger-driven usage - Minimal content-only dialog versus a dialog with a header row and close button - Fixed content dialog versus scrollable or fluid content dialog ## Migrating From 2.x `DialogHeader`, `DialogTitle`, and `DialogCloseButton` were removed: the library keeps only parts that carry behavior plain markup cannot express. `DialogClose` is the behavior-only replacement for the close button. - `DialogHeader` → your own layout element, for example a flex row - `DialogTitle` → a `Heading` with an `id`, referenced by `aria-labelledby` on `DialogContent` - `DialogCloseButton` → `DialogClose asChild` around your own button, for example an `IconButton` with an `aria-label` - `useDialogContext()` no longer returns `contentId` or `titleId`, and `DialogTrigger` no longer sets `aria-controls` ## Edge Cases - Nested overlays should be tested for focus restoration and stacking order. - Long content should be scrollable without hiding the primary actions. - The dialog must be named with `aria-labelledby` or `aria-label`. - Keep dismissal behavior explicit when the dialog contains forms or destructive actions. - If the content starts reading like a full-page workflow, a drawer, sheet, or routed screen may be clearer than a large dialog. ## Common Mistakes - Leaving `DialogContent` without `aria-labelledby` or `aria-label`. - Putting critical page content into a dialog without a usable mobile layout. - Failing to test dialog behavior inside other overlays. - Treating long dialog content as static without checking scroll and action visibility. ## Examples ### Basic #### Basic: confirm before deleting a file The Cancel and Delete buttons live in a ``, so either one closes the dialog and its `value` becomes the dialog's `returnValue`. The page reads it in `onClose`, after the close transition, and only then removes the file; `Escape` and the close button leave `returnValue` empty. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Heading, Icon, IconButton, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const destructive = { '--button-background-color': 'var(--color-red-accent-500)', '--button-background-color-hover': 'var(--color-red-accent-600)', '--button-background-color-active': 'var(--color-red-accent-700)', } as CSSProperties; export default function ConfirmAction() { const titleId = useId(); const descriptionId = useId(); const [deleted, setDeleted] = useState(false); return (
{deleted ? ( <> Q3 board deck.pdf moved to trash. ) : ( <>
Q3 board deck.pdf 4.2 MB · Edited yesterday
setDeleted(event.currentTarget.returnValue === 'delete')} >
Delete Q3 board deck.pdf?
The file stays in trash for 30 days. Shared links stop working right away. )}
); } ``` ### Controlled/Stateful #### Controlled/Stateful: one dialog for many rows Each row opens the same controlled dialog with its own invoice. The parent owns both `open` and the selected row, and the native `` returns focus to the button that opened it. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, Heading, Icon, IconButton, Text, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; const invoices = [ { number: 'INV-2041', customer: 'Acme Logistics', amount: '$12,480.00', due: 'Nov 14, 2026' }, { number: 'INV-2042', customer: 'Blue Harbor Cafe', amount: '$860.50', due: 'Nov 21, 2026' }, { number: 'INV-2043', customer: 'Kestrel Robotics', amount: '$4,125.00', due: 'Dec 1, 2026' }, ]; export default function ControlledOpenState() { const titleId = useId(); const [open, setOpen] = useState(false); const [selected, setSelected] = useState(invoices[0]); const openInvoice = (invoice: typeof invoices[number]) => { setSelected(invoice); setOpen(true); }; return (
    {invoices.map((invoice, index) => (
  • 0 ? '1px solid var(--separator-opaque)' : undefined, }} >
    {invoice.customer} {invoice.number} · {invoice.amount}
    • ))}
Dialog: {open ? `open, showing ${selected.number}` : 'closed'}
{selected.number}
Customer
{selected.customer}
Amount
{selected.amount}
Due
{selected.due}
); } ``` #### Controlled/Stateful: keep the dialog open while there are unsaved changes Every close request (`Escape`, the close button, Cancel) goes through `onChangeOpen(false)`. While the note has unsaved edits the parent answers the first request with a warning instead of closing; a second request discards the draft. ```tsx import { useId, useState, type CSSProperties } from 'react'; import { Button, Dialog, DialogClose, DialogContent, DialogTrigger, Heading, HelperText, Icon, IconButton, Label, Text, TextArea, } from '@vega-ui/react'; import { XIcon } from '@vega-ui/icons'; export default function UnsavedChangesGuard() { const titleId = useId(); const fieldId = useId(); const warningId = useId(); const [open, setOpen] = useState(false); const [saved, setSaved] = useState('Call back after the Friday standup.'); const [draft, setDraft] = useState(saved); const [confirming, setConfirming] = useState(false); const dirty = draft !== saved; const changeOpen = (next: boolean) => { if (next) { setDraft(saved); setConfirming(false); setOpen(true); return; } if (dirty && !confirming) { setConfirming(true); return; } setOpen(false); }; const save = () => { setSaved(draft); setOpen(false); }; return (
Note for Maria Chen {saved}
Note for Maria Chen