Skip to content
flyingsalmon

Dialog

A modal surface for a short task that stops the page: a form, a choice, or a confirmation.

Hanoi

Mar 3, 2026 to Mar 9, 2026

Installation

npx shadcn@latest add @flyingsalmon/dialog

Usage

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

brian@example.com

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

12 places, 3 travellers

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

  • Do
    Close 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.
  • Do
    If 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’t
    Make 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.
  • Do
    Show 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.
  • Do
    Show 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.
  • Do
    End 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’t
    Open 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

KeyDescription
EnterSpaceOn the trigger, opens the dialog and moves focus to its first control.
TabShift+TabCycles through the controls inside the dialog. The close button comes last.
EscapeCloses 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.

PropTypeDefaultDescription
openboolean–The controlled open state.
defaultOpenbooleanfalseThe initial open state when uncontrolled.
onOpenChange(open: boolean) => void–Called when the dialog opens or closes.
sizeDialogSizeDialogSize.DefaultDefault for a confirmation or a short form; Large for a two-column form.
dismissiblebooleantruefalse ignores a click outside. Escape and the close button still work.
pendingbooleanfalseBlocks 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

PropTypeDefaultDescription
childrenReactElementRequiredOne element, usually a Button, that opens the dialog.

DialogClose

PropTypeDefaultDescription
childrenReactElementRequiredOne element, usually a Button, that closes it.

DialogContent

The surface. Renders the scrim and the close button for you.

PropTypeDefaultDescription
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.

  • Drawer

    The edge panel for content that accompanies the page.
  • Notice

    Carries a result once the dialog has closed.
  • Form

    Field layout, the actions row, and validation.
  • Dropdown menu

    A second way to open the same dialog.