Modals

Source files: dialog.tsx, alert-dialog.tsx, draggable-dialog.tsx, sheet.tsx

This guide covers overlay patterns shared by all modal components: focus trapping, dismiss behavior, z-index layering, and animation. For inline alerts (non-modal), see Feedback.

Dialog

File: dialog.tsx Primitive: @radix-ui/react-dialog

General-purpose modal dialog with a close button. Dismisses on Escape key or backdrop click.

Sub-components

Sizes

Dismiss behavior

Animation

Accessibility

• aria-modal="true" (set by Radix primitive)
• aria-labelledby auto-linked to DialogTitle
• aria-describedby auto-linked to DialogDescription
• Focus trapped within dialog while open
• Focus returns to trigger on close

Token usage

• bg-background (content surface)
• bg-black/50 (overlay)
• ring-offset-background, ring (close button focus)
• bg-accent, text-muted-foreground (close button hover/open state)
• shadow-lg (shadow.lg)
• z-50 (zIndex.overlay)

Exports

• Dialog, DialogTrigger, DialogClose, DialogContent
• DialogHeader, DialogFooter, DialogTitle, DialogDescription
• DialogOverlay, DialogPortal

AlertDialog

File: alert-dialog.tsx Primitive: @radix-ui/react-alert-dialog

Modal confirmation dialog for destructive or irreversible actions. Unlike Dialog, it does not dismiss on backdrop click – forces an explicit user action.

Sub-components

Dismiss behavior

Animation

Same as Dialog: fade-in/out overlay, zoom-in/out-95 content.

Accessibility

• role="alertdialog" (set by Radix primitive)
• aria-modal="true"
• aria-labelledby auto-linked to AlertDialogTitle
• aria-describedby auto-linked to AlertDialogDescription
• Focus trapped – initial focus goes to Cancel button by default
• Focus returns to trigger on close

Token usage

• bg-background (content surface)
• bg-black/50 (overlay)
• shadow-lg (shadow.lg)
• z-50 (zIndex.overlay)
• Action button inherits primary, primary-foreground
• Cancel button inherits outline variant tokens (border, bg-background, shadow-xs)

Exports

• AlertDialog, AlertDialogTrigger, AlertDialogContent
• AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription
• AlertDialogAction, AlertDialogCancel
• AlertDialogOverlay, AlertDialogPortal

DraggableDialog

File: draggable-dialog.tsx Primitive: @radix-ui/react-dialog (uses forwardRef pattern)

Dialog that can be repositioned by dragging a handle element. Supports maximize/restore toggle.

Sub-components

Props (DraggableDialogContent)

Drag behavior

• Drag position stored in a ref (no re-renders during drag)
• Maximize toggles to 100vw-2rem x 100vh-2rem
• Stored position is restored on un-maximize
• Disables text selection and sets cursor: grabbing during drag

Dismiss behavior

Accessibility

• Same ARIA pattern as Dialog (aria-modal, aria-labelledby, aria-describedby)
• Focus trapped within dialog
• Drag handle uses cursor-grab / cursor-grabbing to communicate interaction affordance
• Title has select-none to prevent accidental text selection during drag

Token usage

• bg-background (content surface)
• bg-black/80 (overlay – intentionally darker to provide more contrast for draggable content)
• ring-offset-background, ring (close button focus)
• shadow-lg (shadow.lg)
• z-50 (zIndex.overlay)

Exports

• DraggableDialog, DraggableDialogTrigger, DraggableDialogClose, DraggableDialogContent
• DraggableDialogHeader, DraggableDialogFooter, DraggableDialogTitle, DraggableDialogDescription
• DraggableDialogOverlay, DraggableDialogPortal

Sheet

File: sheet.tsx Primitive: Radix Dialog (used as sheet)

Slide-in panel from any edge. Used for side panels, mobile navigation, and secondary workflows.

Sub-components

Props (SheetContent)

Dimensions by side

Animation

Slide direction matches the side prop: slide-in-from-right, slide-in-from-left, slide-in-from-top, slide-in-from-bottom.

Dismiss behavior

Hook: useSheet()

From SheetProvider: returns { state, open, setOpen }.

Accessibility

• aria-modal="true" (inherited from Radix Dialog)
• aria-labelledby auto-linked to SheetTitle
• aria-describedby auto-linked to SheetDescription
• Focus trapped within sheet while open
• Focus returns to trigger on close

Token usage

• bg-background (content surface)
• bg-black/50 (overlay)
• ring-offset-background, ring (close button focus)
• shadow-lg (shadow.lg)
• z-50 (zIndex.overlay)
• Slide animations use Tailwind animate-in / animate-out with slide-in-from-* / slide-out-to-*

Exports

• Sheet, SheetTrigger, SheetClose, SheetContent
• SheetHeader, SheetFooter, SheetTitle, SheetDescription

Shared overlay patterns

All modal components in this group share common overlay patterns:

z-index layering

All modals render at z-50 (zIndex.overlay). Both the overlay backdrop and the content itself use this layer to ensure they sit above all page content, sticky headers, and raised elements.

Shadow

All modal content surfaces use shadow-lg (shadow.lg) for high elevation, visually separating them from the page beneath the overlay.

Focus management

• Focus trap: Radix primitives automatically trap focus within the modal while open. Tab and Shift+Tab cycle through focusable elements without leaving the modal.
• Initial focus: First focusable element receives focus on open. AlertDialog focuses the Cancel button by default.
• Restore focus: Focus returns to the trigger element when the modal closes.

Portal rendering

All modals render via a portal (appended to document.body) to avoid z-index and overflow clipping issues from parent containers.