The Dialog component creates modal dialogs that overlay the main content. Built on Radix UI primitives, it provides accessible modal functionality with customizable content, headers, footers, and actions.
Basic Usage
Confirmation Dialog
Properties
Dialog
| Property | Type | Description |
|---|
open | boolean | The controlled open state of the dialog. |
defaultOpen | boolean | The open state of the dialog when it is initially rendered. |
onOpenChange | (open: boolean) => void | Event handler called when the open state changes. |
modal | boolean | The modality of the dialog. Default: true. |
DialogTrigger
| Property | Type | Description |
|---|
asChild | boolean | Change the default rendered element for the one passed as a child. |
children | React.ReactNode | The element that will trigger the dialog. |
DialogContent
| Property | Type | Description |
|---|
showCloseButton | boolean | Whether to show the close button. Default: true. |
className | string | Additional CSS classes for custom styling. |
children | React.ReactNode | The content of the dialog. |
| Property | Type | Description |
|---|
className | string | Additional CSS classes for custom styling. |
children | React.ReactNode | The header content (typically title and description). |
DialogTitle
| Property | Type | Description |
|---|
className | string | Additional CSS classes for custom styling. |
children | React.ReactNode | The title text. |
DialogDescription
| Property | Type | Description |
|---|
className | string | Additional CSS classes for custom styling. |
children | React.ReactNode | The description text. |
| Property | Type | Description |
|---|
className | string | Additional CSS classes for custom styling. |
children | React.ReactNode | The footer content (typically action buttons). |
DialogClose
| Property | Type | Description |
|---|
asChild | boolean | Change the default rendered element for the one passed as a child. |
children | React.ReactNode | The element that will close the dialog when clicked. |
Accessibility
The Dialog component includes comprehensive accessibility features:
- Focus Management - Focus is trapped within the dialog when open
- Keyboard Navigation - Escape key closes the dialog
- Screen Reader Support - Proper ARIA attributes and roles
- Focus Restoration - Focus returns to trigger element when closed
- Backdrop Interaction - Clicking outside closes the dialog (when modal)
Common Use Cases
The Dialog component is perfect for:
- Forms and Settings - Account settings, preferences, configuration
- Confirmations - Delete confirmations, important actions
- Information Display - Terms of service, help content, details
- Data Entry - Creating new items, editing existing content
- Alerts and Notices - Important announcements, warnings
- Media Viewers - Image galleries, video players
Best Practices
- Clear Purpose - Use dialogs for focused tasks that require user attention
- Appropriate Size - Keep content concise and dialog size reasonable
- Action Clarity - Make primary and secondary actions clearly distinguishable
- Escape Routes - Always provide a way to close or cancel the dialog
- Mobile Friendly - Ensure dialogs work well on smaller screens
- Loading States - Show loading indicators for async operations
- Error Handling - Display validation errors clearly within the dialog