Dialog

Patterns

Confirm Action

When to use:

• a destructive or high-signal action needs confirmation

Composition notes:

• keep the content short
• use explicit primary and secondary actions
• keep the title consequence-oriented

Trade-offs:

• strong interruption improves safety
• overuse increases friction

import { useId, useState, type CSSProperties } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,
  IconButton,
  Text,
} from '@vega-ui/react';

Form In Modal

When to use:

• a small editing flow should stay on the current page

Composition notes:

• keep the form short
• ensure close and submit remain visible

Trade-offs:

• good for focused edits
• weak fit for long, multi-step forms

import { useId, useState, type CSSProperties, type FormEvent } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  HelperText,
  Icon,
  IconButton,
  Label,

Scrollable Modal Content

When to use:

• the content can grow beyond a comfortable modal height

Composition notes:

• give the body a max-height, overflow: auto and overscroll-behavior: contain
• keep the heading and actions outside the scrolling body

Trade-offs:

• preserves modal framing
• requires deliberate layout to avoid trapped content

import { useId, type CSSProperties } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,
  IconButton,
  Text,
} from '@vega-ui/react';

Nested Confirm Step

When to use:

• a parent modal flow still needs a smaller confirm step

Composition notes:

• treat nested dialogs as an edge case
• retest focus restoration and escape handling

Trade-offs:

• can preserve the parent workflow context
• raises overlay and accessibility complexity quickly

import { useId, useState, type CSSProperties } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Heading,
  Icon,
  IconButton,
  Text,
} from '@vega-ui/react';

Comparison

Quick Decision Rule

Choose Dialog when the user must complete or confirm a focused modal task before returning to the main page.

Dialog vs Drawer

Use Dialog when:

• the task is modal
• content should feel centered and bounded
• confirmation or interruption is part of the UX

Use Drawer when:

• the task feels like a side panel
• the layout benefits from edge-anchored content

Trade-off:

• Dialog is stronger and more interruptive
• Drawer is roomier for workflows and secondary editing

Dialog vs Sheet

Use Dialog when:

• the layout should feel like a centered modal surface
• desktop-style bounded focus is the primary mental model

Use Sheet when:

• the presentation should feel more mobile-like or sliding

Dialog vs Popover

Use Dialog when:

• the content is a modal task
• focus trapping and explicit dismissal matter

Use Popover when:

• the content is lightweight and non-modal

Dialog vs Tooltip

Use Dialog when:

• the content is interactive or task-oriented

Use Tooltip when:

• the content is informational only

Choose This Component When

• the user must finish or dismiss the flow explicitly
• the content contains form fields or confirm actions
• modal interruption is the intended UX
• stronger focus trapping is part of the product contract

Do Not Choose This Component When

• the content is lightweight and contextual
• the overlay should stay non-modal
• the main need is hint text rather than interaction

Troubleshooting

Focus Does Not Return To The Trigger

Symptom

Closing the dialog leaves focus in an unexpected place or appears to lose focus entirely.

Likely Cause

The real trigger flow was replaced with a custom wrapper or nested overlay composition.

How To Verify

• open the dialog from the keyboard
• close it with Escape or the close button
• verify where focus lands

Fix

• return to the standard DialogTrigger composition first
• retest the exact nested overlay stack

Nested Dialogs Feel Unstable

Symptom

Escape handling, stacking, or focus movement behaves inconsistently with multiple dialogs open.

Likely Cause

Nested dialogs were treated like isolated overlays instead of a stack-level integration case.

How To Verify

• open parent and nested dialogs
• close them in reverse order
• test focus restoration at each level

Fix

• keep the standard Dialog part structure intact
• retest nested overlays as one integration flow

Long Content Pushes Actions Off Screen

Symptom

Users cannot reach actions easily when the dialog body grows.

Likely Cause

The content container was not given a scroll strategy.

How To Verify

• populate the dialog with long content
• test smaller viewport heights

Fix

• make the inner content region scrollable
• keep the header and critical actions outside the scrolling body when possible

The Dialog Opens But Feels Unlabeled

Symptom

The dialog is visible, but users lack clear orientation.

Likely Cause

DialogContent has no aria-labelledby or aria-label, or the heading it points to is too vague.

How To Verify

• open the dialog without looking at the trigger
• check whether the modal purpose is still obvious

Fix

• add a specific heading with an id and pass it to DialogContent as aria-labelledby
• keep title wording task-oriented