When to use it

Use Dialog when the page needs to interrupt the visitor with a centered panel that demands attention. It is the right choice for confirmation prompts, edit forms, detail previews, and any action where you want the surrounding page dimmed and inaccessible until the visitor responds.

If the content should stay visible alongside the page (cart drawer, navigation menu, filter panel), use Sheet or Popover instead. Dialog is for full-interruption flows.

Slot strategy

Dialog is a portal-based composition with several pieces:

• Dialog is the root. It manages open/close state and accepts open and onOpenChange for controlled usage.
• DialogTrigger is the element that opens the dialog. Use asChild to render your own button instead of a wrapper span.
• DialogContent is the centered panel. It automatically wraps itself with a portal and overlay, so you do not need to add those manually.
• DialogHeader and DialogFooter are layout containers for the top and bottom of the panel.
• DialogTitle and DialogDescription provide accessible labeling. Radix requires a title for screen readers.
• DialogClose renders a close button. Use it inside the content when you need an explicit dismiss affordance beyond the overlay click.

Behavior and theming guidance

The overlay dims the background with a semi-transparent black layer. Both the overlay and content panel animate in with coordinated fade and zoom transitions.

The footer layout is responsive: on mobile, buttons stack vertically in reverse order (primary action on top). On desktop, they sit in a row with the primary action on the right. This means you should always place the cancel button before the confirm button in the JSX.

For controlled dialogs, manage state with open and onOpenChange. This is useful when the dialog needs to close after an async action completes, like a form submission or API call.