Dialog

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add dialog

Usage#

import {
  Dialog, DialogTrigger, DialogContent, DialogIcon, DialogHeader,
  DialogFooter, DialogTitle, DialogDescription, DialogClose,
} from "@/components/ui/dialog"
import { UserCircle } from "koala-icons"
import { Button } from "@/components/ui/button"

export function Example() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogIcon><UserCircle /></DialogIcon>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>
            Visible to everyone in your workspace.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="ghost">Cancel</Button>
          </DialogClose>
          <Button>Save changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Anatomy#

import {
  Dialog, DialogTrigger, DialogContent, DialogIcon, DialogHeader, DialogTitle,
  DialogDescription, DialogStepper, DialogBody, DialogFooter, DialogClose,
} from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogIcon />
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogStepper />
    <DialogBody />
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogContent>
</Dialog>

Confirmation#

A destructive confirmation: no header close button (showClose={false}) forces an explicit choice, and the leading icon is tinted red.

Form#

Place labelled fields between DialogHeader and DialogFooter. Land focus on the first field with onOpenAutoFocus; inline validation appears below each field on submit.

Compact density#

Dialogs are compact unless a DensityProvider or density="comfortable" opens them up (20px padding instead of 16px, wider gaps, a larger icon). The content re-provides its density to the header, body and footer so every part stays in sync. Best driven once via DensityProvider; see Density.

Scrollable body#

For tall content (terms, changelogs, long forms) put the middle in a DialogBody. The dialog then caps itself to the viewport and only the body scrolls, its edges fading into the dialog while the header and footer stay pinned. It runs edge to edge, so the fade and the scrollbar use the full width. When it holds only text, give it tabIndex={0} so a keyboard user can scroll it.

Mobile#

Below the sm breakpoint a dialog docks to the bottom edge as a sheet: within thumb reach, with square bottom corners, rising on the drawer curve and keeping the home indicator’s safe area clear. This frame opens at phone width; switch it to Tablet or Desktop to watch the same dialog float back to the center. Pass mobile="center" to keep a dialog floating at every width. There is no grab handle, since a handle promises a drag: reach for Drawer when you want swipe to dismiss.

Nested dialogs#

Open a dialog from inside another and the one underneath steps back: it scales to 90% and lifts slightly, and a lighter second scrim keeps the page from going black. The component tracks the open dialogs itself, so there is nothing to wire, and closing the top dialog brings the other forward in step with its exit. It tracks two levels, which is also the most a flow should ask for.

Share#

A leading DialogIcon above composed Input parts: a read-only link with a copy button, and an email field paired with a send action.

Feedback#

A rating prompt: a single-select ToggleGroup for the score and a Textarea with a live character count. The primary action stays disabled until a score is picked, and the split footer carries a help link on the left.

Two-factor (2FA)#

A verification flow: a live QR Code on a nested surface (so it takes a concentric radius one step inside the dialog) above an OTP Input. Verify enables only once all six digits are in.

Selectable cards#

A single choice rendered as cards rather than bare dots: wrap each option in a <label> around a RadioGroup item and let CSS :has([data-state=checked]) light the selected card. The whole card is the hit target.

Announcement#

A leading DialogIcon, a hero media band, and a split footer: a helper on the left with actions on the right via className="sm:justify-between" (the footer's top divider is on by default).

Multi-step (wizard)#

For create flows that span several screens, put a vertical Stepper in a left rail and swap the active step's form on the right. The Stepper owns no state: drive its value from your own step state. Wrap the body in a Stagger keyed by step so each screen cascades in, and give it a min-h so the dialog holds its height between steps.

Upgrade / Subscribe#

An in-app upsell: a two-column dialog pairing edge-to-edge cover art with a benefits list and a single brand CTA. It composes the same dialogVariants recipe, cancelling the content padding and gap (p-0 gap-0) and splitting into two columns; use size="xl". Drag the frame narrow to watch the columns stack.

Sizes#

size on DialogContent caps the max width; the dialog still shrinks to fit narrow viewports, so it is a ceiling, not a fixed width. The default md (30rem) is the width nearly every dialog should use; reach for the others only when one genuinely needs less or more:

• sm: max-w-sm (384px). Confirmations and short prompts.
• md: max-w-[30rem] (480px). The default; most forms and messages.
• lg: max-w-2xl (672px). Denser forms with side-by-side fields.
• xl: max-w-4xl (896px). Rich content: tables, multi-column layouts.
• media: a 16:9 frame as wide as the viewport allows while it still fits the height. A video lightbox: no padding, no header or footer, the embedded player fills it, and the close button turns light over the footage. Pair it with mobile="center" (a video is not a sheet) and give it a visually hidden DialogTitle.

The previews below are the real DialogContent rendered inline so you can compare the widths directly:

PreviewCode

size="media"16:9, as wide as the viewport allowsA video lightbox.

Unsaved changes#

Behavior that needs a real trigger, so this one stays interactive. Use a controlled open / onOpenChange pair and intercept onInteractOutside + onEscapeKeyDown to guard against accidental data loss. When the form is dirty, every close attempt (the ✕, the scrim, Escape, or Cancel) opens a nested confirmation dialog instead.

Accessibility#

Radix traps focus inside the dialog, closes it on Escape and hides the page from screen readers while it is open. On close, focus goes back to the DialogTrigger. A dialog opened by state has no trigger (a keyboard shortcut, a row action, a command), so DialogContent remembers the element that had focus when it opened and returns focus there instead, as long as that element is still on the page. Without this, focus would fall back to the top of the document. Drawer, CommandDialog, Lightbox and FilePreviewDialog do the same.

A dialog opened from a menu item goes back to the button that opened the menu, since the item closes with the menu. From a submenu, that is the button of the top menu. A ContextMenu has no button, so focus goes back to whatever had it before the menu opened.

To send focus somewhere else, pass onCloseAutoFocus, call event.preventDefault() and focus your own element. The dialog then leaves focus alone.

API reference#

FAQ#