Skip to content
Nexus Application Design nadesign

Dialog

<Dialog> is a centered modal panel for compact tasks — edit a property, create an entity, paste a token. Focus is trapped; the page beneath is dimmed and inert.

import from "@na/ui/components/dialog" ▶ Open in Storybook packages/ui/src/components/dialog.tsx

When to use

  • Compact create / edit forms (≤ 5 fields).
  • Tasks that fit on a single short panel and end with one decision (Save / Cancel).

Don’t use Dialog for: confirmations (AlertDialog or ConfirmDialog), long forms (use a real page), drawer-style filters or detail panels (use Sheet), or notifications (use Sonner).

Basic

<Dialog>
  <DialogTrigger asChild>
    <Button>Edit profile</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Update your display name and email.</DialogDescription>
    </DialogHeader>
    <div>{/* fields */}</div>
    <DialogFooter>
      <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
      <Button>Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

API

Dialog

Prop Type Default Description
open boolean — Controlled. Pair with onOpenChange.
defaultOpen boolean false Initial state.
onOpenChange (open: boolean) => void — Fires on open/close.
modal boolean true When false, the page beneath stays interactive.

Anatomy

Dialog (root) → DialogTrigger → DialogContent → DialogHeader → DialogTitle + DialogDescription → body → DialogFooter → DialogClose + Submit Button.

Design guidelines

✓ Do

  • Always include a DialogTitle. Untitled dialogs fail screen-reader announcement.
  • Place the destructive option on the LEFT (cancel/close) and the primary on the RIGHT.
  • Pair with form validation — surface FormError at the top of the body.

✗ Don't

  • Use Dialog for confirmations. AlertDialog or ConfirmDialog exist for that.
  • Open a Dialog from inside another Dialog. Stack horror.
  • Hide the close affordance. Esc + the X are both expected.

Accessibility

  • Composes Radix Dialog — focus trapped while open, returned to trigger on close, Esc closes.
  • DialogTitle is required for screen-reader announcement; pair with DialogDescription for the topic.
  • AlertDialog — Confirmations (no Esc-to-close).
  • ConfirmDialog — Async confirm with pending state.
  • Sheet — Edge-anchored drawer for filters / details.

▶ Open Dialog stories in Storybook