Skip to content
WunderUI

Dialog

Free

Focus attention on one short task, such as a form or a choice, and return to the page when it is done.

npx wunderui-cli add dialog

Playground

Escape, the close button or a click on the backdrop closes it.

Installation

bash
npx wunderui-cli add dialog

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogIcon,
  DialogOverlay,
  DialogPortal,
  DialogProgress,
  DialogSurface,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

Then use it:

tsx
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function InviteTeammate() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="plain" />}>Invite teammate</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Invite a teammate</DialogTitle>
          <DialogDescription>They get an email with a link to join WunderUI.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          <div className="flex flex-col gap-2">
            <Label htmlFor="invite-email">Email address</Label>
            <Input id="invite-email" type="email" placeholder="name@wunderui.com" />
          </div>
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="plain" />}>Cancel</DialogClose>
          <Button>Send invite</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Expected result: You see an Invite teammate button. It opens a window with a close button, an email field, and Cancel and Send invite buttons; Cancel, the close button or Escape closes it.

When to use

Use Dialog for

  • A short task that needs full attention and ends with a decision, such as renaming a project or inviting a member
  • A small form, a choice from a list or a read-only summary before a user carries on
  • A short flow of two to four steps, such as creating a workspace

Use something else for

  • Alert Dialog for confirming an action that deletes data or removes access
  • Sheet for a long form or a detail view that needs more room
  • Popover for small content anchored to a control, without blocking the page

A title is required. A description, an icon and the close button are optional, and without the close button the footer must offer a way out.

Switch to annual billing

A pair of Cancel and one primary action is the default. Other layouts are a single button, a split footer with an action at the left edge, and a stacked footer for narrow dialogs.

Edit details

Update the name that appears on invoices.

Content

The body takes text, a short form, a single choice from a list or a read-only summary. Long content scrolls inside the body while title and footer stay in place.

Upgrade to Scale

Unlimited projects and priority support.

Your workspace stores 8 GB today. Scale raises the limit to 1 TB.

Steps

A short flow of two to four steps shows its progress above the title, with Back at the left edge of the footer. Longer flows belong on a page.

Step 1 of 3Workspace
Create a workspace

Presentation

A modal dims the page and traps focus. A non-modal one has no backdrop, leaves the page usable and sits in a corner, for help and side tasks.

States and content state

What the dialog shows while a request runs or fails, and what the body shows while a list loads, is empty or cannot be loaded.

States

Invite a teammate

They get an email with a link to join WunderUI.

Content state

Add members

Choose from people in your organisation.

Keyboard interactions

The buttons are native buttons, so the browser provides focus and activation. While a modal dialog is open the page behind it is inert.

TaborShiftTab
Moves focus between the close button, the fields and the buttons. In a modal dialog focus stays inside, wrapping from the last element to the first.
EnterorSpace
Presses the focused button. In a text field, Enter submits only when the field sits in a form.
Escape
Closes the dialog. A click on the backdrop closes it too, unless is set.

Behavior and motion

What the dialog does with focus, state, content and motion.

Modal
While a modal dialog is open, the page behind it is inert and does not scroll. The window is a dialog named by its title and described by its description.
Focus
Focus moves to the first focusable element when the dialog opens, or to one you choose. When it closes, focus returns to the trigger, or to a place you set.
Closing
The close button, a Close wrapped footer button, Escape and a click on the backdrop all close it. You can ignore the backdrop, for example while a request runs.
Non-modal
A non-modal dialog has no backdrop and no focus trap, so the page stays usable. Anchor it to the bottom right for help and side tasks.
Appearance
The surface look is the default: a semibold title, a footer band and a shadow. The plain look is the earlier flat one with a lighter title, no band and no shadow.
Scrolling
Long content goes into a scrollable body that scrolls up to 296 px between two rules while title and footer stay in view. Give it an aria-label so it is announced as a region.
Small screens
Below the small breakpoint the dialog fills the width minus 16 px gutters and the size setting has no effect. The footer stacks with the main action on top.
Previews in these docs
The window is portalled to the end of the document and fixed to the screen. The previews here draw it inside the card with the same behaviour, so it does not cover the page.
Opening and closing
The window fades in and zooms from 92% while sliding up 8 px, and the backdrop fades. Closing is a step faster and zooms down to 96%.
Reduced motion
With reduced motion the zoom and slide are off and the window only fades, in and out.

Anatomy

The parts a dialog is made of, numbered in the figure. The figure shows the progress and the icon together, but most dialogs use one or neither.

Step 2 of 3Team
Create a workspace

Invite the people who work on it with you.

  • data-slot="dialog"

    Holds the open state and links the trigger to the window. Control it or leave it uncontrolled; it renders nothing itself.

  • data-slot="dialog-trigger"Optional

    The element that opens the dialog, usually a button. Focus returns to it when the dialog closes.

  • data-slot="dialog-content"

    The window, with its own portal and overlay. It keeps focus inside, comes in three widths (384, 512 and 720 px) and can be non-modal and anchored to a corner.

  • Optional

    The icon button in the top right corner, named Close for screen readers. It is on by default; turn it off only when the footer offers a clear way out.

  • data-slot="dialog-header"Optional

    Stacks the progress, icon, title and description at the top, and leaves room for the close button.

  • data-slot="dialog-progress"Optional

    The step indicator of a short multi-step dialog (two to four steps), with an optional label for the current step. It is exposed as a progress bar.

  • data-slot="dialog-icon"Optional

    A round 40 px icon above the title in a default, warning or destructive look. Pass a Lucide icon as its child.

  • data-slot="dialog-title"

    Names the dialog, and screen readers announce it when the dialog opens. A title is needed even when the design shows none.

  • data-slot="dialog-description"Optional

    One or two sentences on what the dialog is for, read out after the title.

  • data-slot="dialog-body"Optional

    The slot between header and footer for a form, a list or text. When scrollable, it scrolls between two rules while title and footer stay put, and keyboard users can focus it to scroll.

  • data-slot="dialog-footer"Optional

    The row of buttons, with the last one on the right and on top on a phone. It can paint a full-width band, stack the buttons, or put one action such as Back at the left edge.

  • data-slot="dialog-close"Optional

    Closes the dialog. Wrap the Cancel button in it, or turn on the footer's Close button.

  • Optional

    The primary Button, last in the footer. Name it after its result, such as Send invite, and show its pending state while the request runs.

  • data-slot="dialog-footer-start"Optional
  • data-slot="dialog-overlay"Optional

    The dimmed, lightly blurred backdrop. DialogContent already renders it, and a click on it closes the dialog.

  • data-slot="dialog-portal"Optional

    Moves the window to the end of the document. DialogContent already renders it, so you only need it for a custom window or container.

  • data-slot="dialog-surface"Optional

    The same window as a static panel without portal, overlay or focus trap, for previews and embedded layouts. Give it an aria-label.

Best practices

  • Do

    Always include a DialogTitle, even when the design shows none. Without it the dialog has no name for screen readers.

  • Do

    Put the main action last and name it after its result: Send invite, Create project, not OK. Keep Cancel neutral next to it.

  • Do

    On a failed submit keep the dialog open and the input, and put the message on the field or in an Alert at the top of the body.

  • Do

    While the request runs, show the pending state on the primary action and disable the others. Close the dialog only after the server confirms.

  • Do

    Put long content in a scrollable DialogBody so the title and footer stay in view.

  • Don’t

    Don't confirm a destructive action in a Dialog, since a click outside closes it. An Alert Dialog closes only through a button or Escape.

  • Don’t

    Don't use a dialog to report that something worked. A saved state is a toast, and a dialog that needs a click to dismiss only adds a step.

  • Don’t

    Don't discard unsaved input silently when the dialog closes. Ask with an Alert Dialog on top, where Keep editing returns to the form.

  • Don’t

    Don't nest dialogs or use one for a long flow. More than four steps belong on a page.

API reference

Dialog wraps the Base UI dialog and passes its props on. The root takes the open state, the other parts also take a class name, style and render prop, and the rest are plain divs.

Holds the open state and links the trigger to the window. Control it or leave it uncontrolled; it renders nothing itself.

PropTypeDefaultDescription
openboolean—Whether the dialog is currently open.
defaultOpenbooleanfalseWhether the dialog is initially open. To render a controlled dialog, use the prop instead.
onOpenChange(open, eventDetails) => void—Event handler called when the dialog is opened or closed.
modalboolean | "trap-focus"trueDetermines if the dialog enters a modal state when open. - : user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - : user…
disablePointerDismissalbooleanfalseWhether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.
actionsRefRefObject<DialogRoot.Actions | null>—A ref to imperative actions. - : Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - : Closes the dialog imperatively when called.
childrenReactNode | PayloadChildRenderFunction<Payload>—The content of the dialog. This can be a regular React node or a render function that receives the of the active trigger.
defaultTriggerIdstring | null—ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create an initially open dialog.
handleDialogHandle<Payload>—A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method.
onOpenChangeComplete(open) => void—Event handler called after any animations complete when the dialog is opened or closed.
triggerIdstring | null—ID of the trigger that the dialog is associated with. This is useful in conjunction with the prop to create a controlled dialog. There's no need to specify this prop when the dialog is uncontrolled (that is, when the prop is…

The element that opens the dialog, usually a button. Focus returns to it when the dialog closes.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
handleDialogHandle<Payload>—A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method.
idstring—ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot prop).
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
payloadPayload—A payload to pass to the dialog when it is opened.

The window, with its own portal and overlay. It keeps focus inside, comes in three widths (384, 512 and 720 px) and can be non-modal and anchored to a corner.

PropTypeDefaultDescription
size"sm" | "md" | "lg""sm"Figma Dialog / Surface Size: Small 384, Medium 512, Large 720.
appearance"surface" | "plain""surface"Figma look (default) or the earlier plain look.
showCloseButtonbooleantrueShows the close button in the top right corner. Turn it off only when the footer offers a clear way out.
showOverlaybooleantrueNon-modal dialog: omit the backdrop.
placement"center" | "bottom-right""center"Figma dialog placement: center or bottom-right (help panels).
initialFocusboolean | RefObject<HTMLElement | null> | (openType) => unknown—Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual ke…
finalFocusboolean | RefObject<HTMLElement | null> | (closeType) => unknown—Determines the element to focus when the dialog is closed. - : Do not move focus. - : Move focus based on the default behavior (trigger or previously focused element). - : Move focus to the ref element. - …
overlayClassNamestring—Restyle the backdrop, e.g. a flat page colour for a screen that is only the modal.

Stacks the progress, icon, title and description at the top, and leaves room for the close button.

The step indicator of a short multi-step dialog (two to four steps), with an optional label for the current step. It is exposed as a progress bar.

PropTypeDefaultDescription
step requirednumber—The current step, from 1. It is clamped to the range of .
steps requirednumber—The number of steps in the flow. Keep it between two and four.
labelReactNode—A short name for the current step, shown at the right of the Step n of m line.

A round 40 px icon above the title in a default, warning or destructive look. Pass a Lucide icon as its child.

PropTypeDefaultDescription
variant"warning" | "default" | "destructive""default"The look of the round icon: (neutral), (yellow tint) or (red tint).

Names the dialog, and screen readers announce it when the dialog opens. A title is needed even when the design shows none.

One or two sentences on what the dialog is for, read out after the title.

The slot between header and footer for a form, a list or text. When scrollable, it scrolls between two rules while title and footer stay put, and keyboard users can focus it to scroll.

PropTypeDefaultDescription
scrollablebooleanfalseFigma Scrollable body: title and footer stay fixed, the body scrolls. With aria-label or aria-labelledby the scrolling body is announced as a region.

Closes the dialog. Wrap the Cancel button in it, or turn on the footer's Close button.

PropTypeDefaultDescription
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

The dimmed, lightly blurred backdrop. DialogContent already renders it, and a click on it closes the dialog.

PropTypeDefaultDescription
forceRenderbooleanfalseWhether the backdrop is forced to render even when nested.

Moves the window to the end of the document. DialogContent already renders it, so you only need it for a custom window or container.

PropTypeDefaultDescription
containerHTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null—A parent element to render the portal element into.
keepMountedbooleanfalseWhether to keep the portal mounted in the DOM while the popup is hidden.

The same window as a static panel without portal, overlay or focus trap, for previews and embedded layouts. Give it an aria-label.

PropTypeDefaultDescription
size"sm" | "md" | "lg""sm"Figma Dialog / Surface Size: Small 384, Medium 512, Large 720.
appearance"surface" | "plain""surface"Figma look (default) or the earlier plain look.
showCloseButtonbooleantrue
onClose() => void—Called when the corner close button is pressed (the static panel has no open state of its own).

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("dialog")
Installnpx wunderui-cli add dialog

The full library index for assistants is at /llms.txt.