Dialog

Content Structure

Always include a DialogTitle and DialogDescription for clarity and accessibility. Keep titles concise (2-5 words) and descriptions actionable. Place form fields in the body area between header and footer. Use DialogFooter for action buttons, with the primary action on the right.

Sizing & Layout

The default max-width is sm:max-w-lg (512px). Use sm:max-w-[425px] for compact form dialogs or sm:max-w-md for medium content. On mobile, dialogs expand to full width with a 1rem margin on each side. Avoid dialogs taller than 85vh; use scrollable content areas for long forms.

Responsive Behavior

Dialog footer buttons stack vertically in reverse order on mobile via flex-col-reverse, placing the primary action at the bottom for easier thumb reach. On larger screens, buttons align horizontally to the right. Consider replacing dialogs with full-page views on very small screens for complex forms.

Animation & Transitions

Dialogs use coordinated enter/exit animations: the overlay fades in/out while the content panel fades and scales from 95% to 100%. The 200ms duration keeps transitions snappy without feeling abrupt. The backdrop uses bg-black/50 to maintain readability while dimming background content.

Keyboard Navigation

• Tab — Move focus between focusable elements within the dialog
• Shift + Tab — Move focus backward; focus is trapped within the dialog
• Escape — Close the dialog and return focus to the trigger element
• Enter or Space — Activate the trigger button to open the dialog

Focus Management

When the dialog opens, focus moves to the first focusable element inside. Focus is trapped within the dialog while open, preventing interaction with background content. When the dialog closes, focus is restored to the trigger element that opened it. Use autoFocus on a specific input to direct initial focus to the most relevant field.

Screen Reader Support

• The dialog is announced with role="dialog" and aria-modal="true"
• DialogTitle provides the accessible name via aria-labelledby
• DialogDescription provides the accessible description via aria-describedby
• Background content is marked as inert, hidden from assistive technology
• The close button includes a sr-only "Close" label for screen readers

Modal vs Non-Modal

By default, dialogs are modal: they trap focus, show an overlay, and mark background content as inert. Set modal={false} for non-modal dialogs where users can still interact with background content. Non-modal dialogs do not trap focus or render an overlay, which is useful for persistent panels or chat widgets.

ARIA Attributes

{/* Dialog with descriptive title and description */}
<Dialog>
  <DialogTrigger asChild>
    <Button>Edit Profile</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      {/* DialogTitle maps to aria-labelledby */}
      <DialogTitle>Edit Profile</DialogTitle>
      {/* DialogDescription maps to aria-describedby */}
      <DialogDescription>
        Update your display name and username.
      </DialogDescription>
    </DialogHeader>
    {/* Form fields inside dialog */}
    <form>
      <Label htmlFor="name">Name</Label>
      <Input id="name" />
      <DialogFooter>
        <DialogClose asChild>
          <Button variant="outline">Cancel</Button>
        </DialogClose>
        <Button type="submit">Save</Button>
      </DialogFooter>
    </form>
  </DialogContent>
</Dialog>

{/* Non-modal dialog (no overlay, no focus trap) */}
<Dialog modal={false}>
  <DialogTrigger asChild>
    <Button variant="outline">Open Non-Modal</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Non-Modal Dialog</DialogTitle>
      <DialogDescription>
        Users can still interact with content behind this dialog.
      </DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>