Dialog

A dialog pauses the page so someone can finish one task. When they finish or close it, they’re back where they started.

Press Esc to close and return to the trigger.

Fig. 1 Open the dialog. Press Esc or choose an action, and focus returns to the button that opened it.

When to use it

Use a dialog when a task needs someone’s full attention and has a clear end: renaming something, editing a few details, or filling in a short form. The page behind it dims and stops responding until the dialog closes.

If people need to see or use the page while they work, pick a different overlay. Start with one question: what should happen to the page behind it?

Popover

The page stays usable.

Press Esc or click outside to close.

Small changes next to their button.

DialogThis page

The page waits.

Press Esc to close and return to the trigger.

A focused task with a clear end.

Drawer

The page waits, from the edge.

Swipe toward the edge, click outside, or press Esc to close.

Choices on a phone, details beside a list.

Alert Dialog

The page needs an answer.

Clicking outside won’t close it. Choose Cancel or press Esc.

Actions that can’t be undone.

Fig. 2 Four overlays, four jobs. Open each one and notice what stays usable behind it and how it closes.

How it behaves

Base UI traps focus, locks background interaction, dismisses with Escape or an outside press, and restores focus to the trigger.

Always provide DialogTitle and DialogDescription. The close button has an accessible label.

Set showCloseButton={false} on DialogContent to supply your own close control. The preview puts a labeled ghost icon Button opposite the title.

Use render={<Button />} on triggers and close controls. Popups scroll within a constrained viewport on narrow screens.

DialogHeader and DialogFooter preserve the official composition API. DialogFooter accepts showCloseButton for a labeled closing action.

Build it

Add it with the shadcn CLI:

Terminal

A complete example. Change the values to fit your product:

dialog-example.tsx

The full source is yours to edit once installed:

dialog.tsx