Dialog
FreeFocus 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 dialogPlayground
Invite a teammate
They get an email with a link to join WunderUI.
Escape, the close button or a click on the backdrop closes it.
Installation
npx wunderui-cli add dialogWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Dialog,
DialogBody,
DialogClose,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogIcon,
DialogOverlay,
DialogPortal,
DialogProgress,
DialogSurface,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog"Then use it:
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
Header
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
Switch to annual billing
Switch to annual billing
You save 20 % and are charged $950 today.
Switch to annual billing
You save 20 % and are charged $950 today.
Switch to annual billing
You save 20 % and are charged $950 today.
Switch to annual billing
You save 20 % and are charged $950 today.
Your trial ends in 3 days
Add a payment method to keep your projects and members.
Your trial ends in 3 days
Add a payment method to keep your projects and members.
Footer
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.
Edit details
Update the name that appears on invoices.
Edit details
Update the name that appears on invoices.
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.
Create project
Assign task
Pick who is responsible for Update onboarding flow.
Plan details
- Plan
- Pro, annual
- Seats
- 12 of 15 used
- Next invoice
- Nov 30, 2026
- Amount
- $1,188.00
Data processing terms
We process data only for the services you subscribe to. You can ask for a copy or for deletion at any time by writing to info@wunderui.com.
Project files stay in the region you chose when you created the workspace. Backups are kept for 30 days and then removed.
Subprocessors are listed in your account settings. We tell you at least 30 days before a new one starts to handle your data.
If a request cannot be completed within one month, we tell you why and when you can expect the result.
Members who leave the workspace lose access immediately. Their work stays with the workspace unless an owner deletes it.
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.
Create a workspace
Create a workspace
Create a workspace
- Workspace
- WunderUI
- Invites
- 1 pending
- Plan
- Free
- Region
- Europe
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.
Invite a teammate
They get an email with a link to join WunderUI.
Keyboard shortcuts
Press ? to open this panel anywhere.
G then P opens projects. G then T opens 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.
Invite a teammate
They get an email with a link to join WunderUI.
Invite a teammate
They get an email with a link to join WunderUI.
We couldn’t send the invite. Check your connection and try again.
Content state
Add members
Choose from people in your organisation.
Add members
Choose from people in your organisation.
Nobody to add yet
Everyone in your organisation is already a member.
Add members
Choose from people in your organisation.
Couldn’t load members. Check your connection and try again.
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.
- TaborShift+Tab
- 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.
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.
- 1data-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.
- 2Optional
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.
- 3data-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.
- 4data-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.
- 5data-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.
- 6data-slot="dialog-description"Optional
One or two sentences on what the dialog is for, read out after the title.
- 7data-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.
- 8data-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.
- 9data-slot="dialog-close"Optional
Closes the dialog. Wrap the Cancel button in it, or turn on the footer's Close button.
- 10Optional
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| open | boolean | — | Whether the dialog is currently open. |
| defaultOpen | boolean | false | Whether 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. |
| modal | boolean | "trap-focus" | true | Determines 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… |
| disablePointerDismissal | boolean | false | Whether 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. |
| actionsRef | RefObject<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. |
| children | ReactNode | 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. |
| defaultTriggerId | string | 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. |
| handle | DialogHandle<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. |
| triggerId | string | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (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. |
| handle | DialogHandle<Payload> | — | A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method. |
| id | string | — | 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). |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
| payload | Payload | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| showCloseButton | boolean | true | Shows the close button in the top right corner. Turn it off only when the footer offers a clear way out. |
| showOverlay | boolean | true | Non-modal dialog: omit the backdrop. |
| placement | "center" | "bottom-right" | "center" | Figma dialog placement: center or bottom-right (help panels). |
| initialFocus | boolean | 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… |
| finalFocus | boolean | 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. - … |
| overlayClassName | string | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| step required | number | — | The current step, from 1. It is clamped to the range of . |
| steps required | number | — | The number of steps in the flow. Keep it between two and four. |
| label | ReactNode | — | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| scrollable | boolean | false | Figma Scrollable body: title and footer stay fixed, the body scrolls. With aria-label or aria-labelledby the scrolling body is announced as a region. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| layout | "inline" | "stacked" | — | Figma Footer Layout: one row, one column with the primary on top. |
| band | boolean | — | Figma "Band": paints the footer fill; omitted = band inside surface dialogs. |
| start | ReactNode | — | Figma Footer Layout "Split": action at the left edge (Back, Compare). |
| showCloseButton | boolean | false | Adds a plain Close button to the footer, after your own buttons. |
Closes the dialog. Wrap the Cancel button in it, or turn on the footer's Close button.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (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. |
| nativeButton | boolean | true | Whether 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| forceRender | boolean | false | Whether 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| container | HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null | — | A parent element to render the portal element into. |
| keepMounted | boolean | false | Whether 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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. |
| showCloseButton | boolean | true | |
| 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.
get_component("dialog")npx wunderui-cli add dialogThe full library index for assistants is at /llms.txt.