Dialog
The blocking overlay for a decision or a short focused task: it dims the page, traps focus, and will not let the user move on until they answer.
import from ~/components/ui/dialog
Confirmation
destructive confirm
The title asks the question, the description names the consequence, and the confirm button repeats the verb.
Form
short form
A dialog holds a task short enough to finish in one sitting. Anything longer belongs on its own page.
Dismissal
Dismissed 0 times
Escape and the overlay
Every dismissal route runs through onOpenChange: the close button, the Escape key, and a click on the dimmed overlay. Open this one and try all three.
Rules
Do
Give every dialog a DialogTitle. It is the accessible name a screen reader announces.
Name the consequence in a destructive confirmation, and repeat the verb on the confirm button.
Leave Escape and the overlay click alone. A dialog must always have a way out.
Wrap the cancel action in DialogClose asChild so it closes without extra state.
Don't
Do not nest a dialog inside a dialog. Make the second step a page, or replace the content in place.
Do not use a dialog for feedback that does not block the user. That is a Toast.
Do not put a long, multi-step form in a dialog. Focus is trapped, so the user cannot go and look something up.
Do not pass color, border or shadow classes to DialogContent. The surface is fixed by the component.