Dialog Components Accessibility

[!CAUTION] BASED ON STANDARD RADIX/SHADCN PATTERNS — VERIFY AGAINST YOUR IMPLEMENTATION These accessibility patterns are derived from Radix UI primitive documentation and WAI-ARIA best practices. Your actual component implementations may differ. Test with a screen reader before relying on this guidance.

Applies To

• Dialog — general-purpose modal overlay (Radix Dialog primitive)
• AlertDialog — confirmation/destructive-action modal (Radix AlertDialog primitive)
• Sheet — side panel overlay (built on Radix Dialog primitive)
• Drawer — bottom/side drawer (built on Vaul, wraps Radix Dialog patterns)

Shared Modal Accessibility Fundamentals

All four overlay components share these core accessibility requirements:

Focus Management

Radix Dialog handles all three automatically. If you're wrapping Radix primitives (as shadcn/ui does), this behavior is inherited.

ARIA Attributes (All Overlays)

Keyboard Interactions (All Overlays)

Dialog

The standard modal dialog for forms, content, and general-purpose interactions.

Role & ARIA

<Dialog>
  <DialogTrigger asChild>
    <Button>Edit Profile</Button>
  </DialogTrigger>
  <DialogContent>
    {/* Radix renders: role="dialog" aria-modal="true" aria-labelledby aria-describedby */}
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>           {/* auto-linked via aria-labelledby */}
      <DialogDescription>                               {/* auto-linked via aria-describedby */}
        Make changes to your profile information.
      </DialogDescription>
    </DialogHeader>
    {/* ... content ... */}
    <DialogFooter>
      <Button type="submit">Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Radix Dialog automatically applies:

• role="dialog" on the content element
• aria-modal="true"
• aria-labelledby pointing to DialogTitle
• aria-describedby pointing to DialogDescription

Focus Behavior

Close Behavior

• Escape closes the dialog
• Click on overlay backdrop closes the dialog
• Close button (X) closes the dialog — this button must have aria-label="Close" (or visible "Close" text)

Screen Reader Announcements

AlertDialog

A modal for confirmation and destructive actions. More restrictive than Dialog — the user must make an explicit choice.

Role & ARIA

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete Account</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    {/* Radix renders: role="alertdialog" aria-modal="true" aria-labelledby aria-describedby */}
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Yes, delete account</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Key Differences from Dialog

Focus Behavior

Keyboard Interactions

Screen Reader Announcements

Sheet

A side panel overlay — structurally identical to Dialog in accessibility. Uses Radix Dialog internally.

Role & ARIA

Same as Dialog: role="dialog", aria-modal="true", aria-labelledby, aria-describedby.

<Sheet>
  <SheetTrigger asChild>
    <Button>Open Settings</Button>
  </SheetTrigger>
  <SheetContent side="right">
    {/* Radix renders dialog role and ARIA automatically */}
    <SheetHeader>
      <SheetTitle>Settings</SheetTitle>
      <SheetDescription>Adjust your preferences.</SheetDescription>
    </SheetHeader>
    {/* ... content ... */}
  </SheetContent>
</Sheet>

Focus Behavior

Identical to Dialog:

• Opens: Focus moves to first focusable element inside the sheet
• Trapped: Tab/Shift+Tab cannot leave the sheet
• Closes: Focus returns to SheetTrigger

Close Behavior

Same as Dialog:

• Escape closes the sheet
• Click on overlay backdrop closes the sheet
• Close button (X) needs aria-label="Close"

Animation and Reduced Motion

The sheet slides in from the side. Ensure:

• The slide animation respects prefers-reduced-motion: reduce — either disable animation or use a simple fade
• Animation does not delay focus movement — focus should land inside the sheet immediately, not after the transition completes

Drawer

A bottom or side drawer, typically used on mobile. Built with Vaul which wraps Radix Dialog patterns.

Role & ARIA

Same as Dialog: role="dialog", aria-modal="true", aria-labelledby, aria-describedby.

<Drawer>
  <DrawerTrigger asChild>
    <Button>Open Drawer</Button>
  </DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Move Goal</DrawerTitle>
      <DrawerDescription>Set your daily activity goal.</DrawerDescription>
    </DrawerHeader>
    {/* ... content ... */}
    <DrawerFooter>
      <Button>Submit</Button>
      <DrawerClose asChild>
        <Button variant="outline">Cancel</Button>
      </DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>

Focus Behavior

Identical to Dialog:

• Opens: Focus moves to first focusable element inside the drawer
• Trapped: Tab/Shift+Tab cannot leave
• Closes: Focus returns to DrawerTrigger

Drag-to-Close Gesture

Vaul supports drag-to-close (swipe down on mobile). This gesture must have a keyboard equivalent:

• Escape closes the drawer (inherits from Radix Dialog)
• A visible close/cancel button must be present for users who cannot perform drag gestures
• The drag handle (if visible) should be aria-hidden="true" — it's a visual affordance, not an interactive element for assistive technology

Animation and Reduced Motion

Same requirements as Sheet:

• Respect prefers-reduced-motion: reduce
• Don't delay focus movement behind animations

Stacked/Nested Overlays

When one overlay opens another (e.g., a Dialog opens an AlertDialog):

• The inner overlay traps focus — the outer overlay is effectively inert
• When the inner overlay closes, focus returns to the element in the outer overlay that triggered it
• When the outer overlay closes, focus returns to the original page trigger
• Screen readers should announce the new dialog role/title at each layer
• Avoid deeply nested overlays — more than 2 layers deep creates a confusing experience

Common Mistakes

Testing Checklist

Screen Reader Testing

• Dialog/AlertDialog role announced on open ("dialog" / "alertdialog")
• Title announced on open (via aria-labelledby)
• Description announced on open (via aria-describedby), if present
• Focus is inside the overlay — screen reader cannot read page content behind it
• Closing returns focus to trigger and trigger element is announced
• AlertDialog: Escape does NOT close it

Keyboard Testing

• Tab cycles through focusable elements inside the overlay only
• Shift+Tab cycles backwards through overlay content only
• Cannot Tab to elements outside the overlay (focus trap working)
• Escape closes Dialog, Sheet, Drawer
• Escape does NOT close AlertDialog
• Enter activates the focused button
• After close, focus returns to the trigger element

Visual Testing

• Focus ring visible on all interactive elements inside the overlay
• Background/backdrop visually obscures page content
• Sheet/Drawer animation respects prefers-reduced-motion
• Close button (X) has a visible focus indicator

References

• WAI-ARIA Dialog (Modal) Pattern
• WAI-ARIA AlertDialog Pattern
• Radix Dialog Primitive
• Radix AlertDialog Primitive
• Vaul Drawer

Last updated: February 9, 2026