Dialog
The <Dialog>
component is a versatile UI element used to display important content that requires user interaction, typically in a modal or popup window. It is designed to temporarily interrupt the user's workflow to present critical information, request confirmation, or facilitate a task without navigating away from the current page.
Key features of the <Dialog>
component include customizable content, support for multiple dialog sizes, focus trapping for accessibility, and optional overlay to dim the background. It can be used for alerts, forms, confirmations, or any interactive modal interface.
Anatomy
A dialog consists of an optional title, content, actions, an optional close button, and an underlay. The title provides context for the user, while the content holds the main message or interactive elements like forms. The actions section contains controls such as buttons for confirming or canceling. The underlay dims the background to focus attention on the dialog and prevent interaction with other elements on the page. The close button offers way to dismiss the dialog.

Appearance
The appearance of a component can be customized using the variant
and size
props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Property | Type | Description |
---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
A dialog is used to capture the user’s attention for tasks that require focus, such as confirming actions, filling out forms, or providing important information. Common use cases include confirmation prompts, data entry, and notifications.
When using a dialog, it’s important to ensure it doesn’t unnecessarily interrupt the user’s workflow and that it provides a clear way to close or complete the interaction. Dialogs should be concise, focused on a single task and while they are highly versatile, dialogs aren’t suitable for every situation. They can be intrusive and should be used sparingly.
Use a dialog when
- an immediate response is needed to continue a user-initiated process,
- to notify the user of urgent information related to their task, or
- to confirm a user decision.
Labeling
To correctly label a dialog, always include a title (<Dialog.Title>
) or an aria-label
so users understand its purpose. The title should be concise and descriptive, using a verb-noun combination (e.g., "Edit Profile" or "Confirm Purchase"). If no visible title is used, ensure that the dialog is properly labeled with an aria-label
for accessibility.
For short, straightforward messages, you can combine the title and the message to make things clearer and avoid repeating information in both the title and content. If you do this, there should be no additional text in the content of the dialog.
<Dialog aria-label="delete event">
<Dialog.Title>Are you sure you want to delete this event?</Dialog.Title>
<Dialog.Actions>
<Button variant="secondary" slot="close">
Cancel
</Button>
<Button variant="destructive">Delete</Button>
</Dialog.Actions>
</Dialog>
Content
Keep dialogs simple by limiting the number of interactions. Remove any content or elements that aren't essential to completing the task. For instance, if the dialog is for editing a user's profile information, only include the necessary fields like name and email, rather than unrelated options like notification settings.
It's also best to avoid multi-step processes or requiring users to navigate within the dialog, as this can complicate the experience. If a task is too complex, consider using a dedicated page instead.
Lastly, avoid asking users to make decisions that require information not accessible in the dialog, such as needing to check a different page or document to proceed—since this can frustrate users and disrupt their workflow.
Dismissal
When a dialog is open, users cannot interact with the rest of the page until the dialog is closed. To accommodate both mouse and keyboard users, the <Dialog>
provides multiple ways to close it:
- pressing the close button (
slot="close"
) inside<Dialog.Actions>
, - using the close button (indicated by an "x"),
- pressing the "Esc" key, or
- clicking on the underlay (the dimmed background).
To prevent the dialog from closing when the underlay is (accidentally) clicked, you can set the dismissable
prop on the <Dialog.Trigger>
component to false
. This disables closing the dialog by clicking on the background, ensuring that the dialog remains open until the user interacts with the provided buttons or other close mechanisms.
To conveniently create a close button for a dialog, set the slot
prop to "close"
on any <Button>
within <Dialog.Actions>
component. Pressing the button will then close the dialog.
Role
When a dialog requires the user's immediate attention, such as for an error or warning, set role="alertdialog"
. This role ensures that assistive technologies, like screen readers, treat the dialog as high-priority, immediately notifying users of its content.
It is essential for situations where the user must address an issue before continuing, such as critical system errors or warnings about destructive actions. Proper use of role="alertdialog"
improves accessibility and ensures important messages are not missed.
Controlled
You can programmatically open a dialog by using the open
and onOpenChange
props from the <Dialog.Trigger>
. This is particularly helpful when the action cannot be initiated by a simple <Button>
component, such as when selecting an option from a dropdown menu or a context menu that requires additional confirmation before proceeding.
For instance, selecting "Delete" from a menu might trigger a confirmation dialog to ensure the user fully understands the destructive nature of the action and its consequences. This extra step helps prevent accidental deletions by requiring explicit confirmation before proceeding.
Props
Dialog
Dialog.Trigger
children?
ReactNode;
value
ModalProps;
Dialog.Title
children?
ReactNode;
Dialog.Content
children?
ReactNode;
Dialog.Actions
children?
ReactNode;