Dialog
A modal surface for a short task that stops the page: a form, a choice, or a confirmation.
Hanoi
Installation
npx shadcn@latest add @flyingsalmon/dialogUsage
import { Button, ButtonVariant } from '@/components/ui/button'
import {
Dialog,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogTitle,
DialogTrigger,
} from '@/components/ui/dialog'
import { Input } from '@/components/ui/input'
export function DialogUsage() {
return (
<Dialog>
<DialogTrigger>
<Button>Plan a trip</Button>
</DialogTrigger>
<DialogContent>
<DialogTitle>Plan a trip</DialogTitle>
<DialogDescription>
Pick a destination and your dates.
</DialogDescription>
<DialogBody>
<Input label="Destination" />
</DialogBody>
<DialogFooter>
<DialogClose>
<Button variant={ButtonVariant.Outline}>Cancel</Button>
</DialogClose>
<Button>Plan trip</Button>
</DialogFooter>
</DialogContent>
</Dialog>
)
}Examples
Large size
DialogSize.Large fits a two-column form.
Brian Nguyen
Scrolling body
The body scrolls while the title and footer stay put, so Done never leaves reach.
Destructive confirm
dismissible={false} ignores a click outside, so the decision ends on a button or Escape. The trip disappearing is the confirmation.
Hanoi in spring
Waiting inside the dialog
pending holds every exit while the code is checked, because the answer decides what happens next. Try any code, then KYOTO-2026.
One dialog, many triggers
Leave out DialogTrigger and drive open from your own state, so a toolbar button and a menu item open the same dialog.
Error after closing
This demo's server always fails. The dialog closes on submit, the failure arrives as a notice, and the notice's link reopens the form with the place you typed.
Guidelines
When to use
- For a short form that creates or edits one thing: plan a trip, add a place, edit a traveller.
- To confirm an action that cannot be undone, such as deleting a trip.
When not to use
- Use Drawer for content that accompanies the page, such as filters or the detail of a row. A drawer sits at the edge and leaves the page in view; a dialog stops it.
- Use Notice to report a result. A dialog demands a decision; a result needs only to be seen.
- Use Stepper to mark the traveller’s place in a long task with several stages, which deserves a page of its own.
Do and don’t
- DoClose a form dialog on submit and show the result on the item that changed.The new trip appearing in the list is the clearest success there is, and nobody waits for the server with a modal in their face.
- DoIf the save fails after the dialog has closed, keep the error on screen as a notice that reopens the dialog with what the traveller typed.The dialog is gone, so the notice is the one home that stays until it is seen, and nothing typed is lost.
- Don’tMake the traveller wait inside a dialog for a plain save.A dialog waits on the server only when the next screen depends on the answer, such as checking an invite code. Then the confirm button shows its own loading, and Cancel waits disabled until the answer arrives.
- DoShow a field error under its field and keep the dialog open.The traveller is still looking at the form, so the error belongs under the field they need to fix.
- DoShow a blocker no field can fix, such as a trip that is already full, as an error alert above the footer with a link out, and keep the confirm button disabled.The traveller learns why they cannot go on where they are already looking, and the link is the way to fix it.
- DoEnd on one outline Cancel beside one filled button that names the action: "Delete trip", not "OK".One filled button marks the single way forward, and its label is the last thing read before the decision.
- Don’tOpen a dialog from a dialog. Confirm a step inside it with an inline alert that carries its own buttons.Two modals deep, the traveller loses track of which one they are answering. An inline confirmation stays inside the task they started.
Accessibility
| Key | Description |
|---|---|
| EnterSpace | On the trigger, opens the dialog and moves focus to its first control. |
| TabShift+Tab | Cycles through the controls inside the dialog. The close button comes last. |
| Escape | Closes the dialog and returns focus to the trigger. Does nothing while the dialog is pending. |
The dialog is labelled by its title and described by DialogDescription when there is one. Focus never lands on the close button on open. Everything outside an open dialog is hidden from assistive technology, and the page behind it does not scroll. A pending dialog sets aria-busy and disables its close button.
Only a real DialogTrigger gives its button aria-haspopup, aria-expanded, and aria-controls. A button that opens a trigger-less dialog through state is a plain button.
API
Dialog
The root. Holds the open state and the rules for leaving.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | – | The controlled open state. |
| defaultOpen | boolean | false | The initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | – | Called when the dialog opens or closes. |
| size | DialogSize | DialogSize.Default | Default for a confirmation or a short form; Large for a two-column form. |
| dismissible | boolean | true | false ignores a click outside. Escape and the close button still work. |
| pending | boolean | false | Blocks Escape, a click outside, and the close button, and sets aria-busy. Use it for an answer the next step depends on, such as checking an invite code. It leaves your footer alone: set loading on the confirm button and disable Cancel yourself. |
DialogTrigger
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactElement | Required | One element, usually a Button, that opens the dialog. |
DialogClose
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactElement | Required | One element, usually a Button, that closes it. |
DialogContent
The surface. Renders the scrim and the close button for you.
| Prop | Type | Default | Description |
|---|---|---|---|
| onOpenAutoFocus | (event: Event) => void | – | Runs as focus moves in. Prevent the default to place focus yourself. |
| onCloseAutoFocus | (event: Event) => void | – | Runs as focus returns. Prevent the default to send it elsewhere. |
DialogTitle is required in every dialog. DialogDescription, DialogBody, and DialogFooter are optional and take the props of the element they render, typed as DialogTitleProps, DialogDescriptionProps, DialogBodyProps, and DialogFooterProps. DialogBody is the only part that scrolls.