Modal
A dialog overlay that focuses user attention on a specific task or information, blocking interaction with the rest of the page.
Basic Modal
Sizes
Composable API
Non-dismissible Modal
Props
| Name | Type | Default | Description |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen' | 'md' | Size of the modal |
title | string | - | Modal title (convenience API) |
description | string | - | Modal description (convenience API) |
dismissible | boolean | true | Whether modal shows close button |
closeOnBackdropClick | boolean | true | Whether clicking backdrop closes modal |
closeOnEscape | boolean | true | Whether pressing Escape closes modal |
open | boolean | - | Controlled open state |
onOpenChange | (open: boolean) => void | - | Open state change handler |
children* | ReactNode | - | Modal body content |
footer | ReactNode | - | Modal footer content (convenience API) |
Usage Guidelines
When to use
- •For critical information that requires immediate user attention and action
- •To confirm destructive actions before proceeding
- •To collect user input in a focused context
- •To display supplementary content without navigating away from the page
Best practices
- •Keep modal content concise and focused on a single task or message
- •Provide clear action buttons - users should know exactly what will happen
- •Use appropriate size - don't make modals larger than necessary
- •Allow dismissal via backdrop click and Escape key (unless critical)
- •Use non-dismissible modals sparingly, only for critical actions
Accessibility
- •ARIA role: dialog with proper aria-labelledby and aria-describedby
- •Focus trap: Focus is trapped within modal when open
- •Keyboard accessible: Escape to close, Tab to navigate
- •Focus management: Focus returns to trigger element on close
- •Portal rendering: Rendered at document body level for proper stacking
Do's and Don'ts
✓ Do
- •Use descriptive titles that clearly explain the modal's purpose
- •Provide clear action buttons with explicit labels
- •Allow users to dismiss the modal easily (unless critical)
- •Use appropriate modal size based on content
- •Use non-dismissible modals only for critical actions
Good: Clear title, description, and action buttons
✗ Don't
- •Don't use vague titles like "Attention" or "Notice"
- •Don't overload modals with too much content or multiple tasks
- •Don't nest modals (modal inside modal)
- •Don't use modals for complex workflows (use full pages instead)
- •Don't make non-critical modals non-dismissible
Bad: Vague title, oversized modal, non-dismissible for non-critical content
Related Components
Button
Used to trigger modal actions
Drawer
Slide-in panel alternative to modals
Alert Dialog
Simplified modal for confirmations