Dialog React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Dialog from @/components/ui/dialog.

import { Pencil } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Dialog, DialogClose } from "@/components/ui/dialog"

export function EditListing({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <Dialog
      trigger={
        <Button variant="soft" leftIcon={<Pencil />}>
          Edit
        </Button>
      }
      title="Edit listing"
      description="Changes show up for buyers right away."
      icon={<Pencil />}
      closeLabel="Close dialog"
      shortcut="mod+e"
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Cancel</Button>
          </DialogClose>
          <Button loading={saving} loadingText="Saving" onClick={onSave}>
            Save
          </Button>
        </>
      }
    >
      <p className="text-sm text-muted-foreground">Title, price, city and description</p>
    </Dialog>
  )
}

Props

• defaultOpendefault false
  boolean

  Starts open (uncontrolled). Pass open and onOpenChange instead to control it.

• open
  boolean

  Controlled open state. The root keeps it across the 768px breakpoint, so resizing swaps the card for the sheet and keeps it open.

• onOpenChange
  (open: boolean) => void

  Called when it opens or closes: the trigger, Escape, an outside click, a drag on the sheet, a close button, the shortcut.

• titledefault ""
  ReactNode

  The title, also the dialog's accessible name. Always pass one: without it a visually hidden “Dialog” stands in so screen readers still get a name. The demo shows its sample while this is empty.

• descriptiondefault ""
  ReactNode

  A quieter line under the title, linked with aria-describedby. Without one the dialog opts out of the description (Radix's aria-describedby={undefined}).

• hideTitledefault false
  boolean

  Keeps the title for screen readers only, for dialogs whose content speaks for itself (a photo, a video).

• closeLabeldefault "Close"
  string

  aria-label of the × button, e.g. “Close dialog”. The demo spells it out under the page.

• trigger
  ReactNode

  The element that opens it, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-keyshortcuts when a shortcut is set. Leave it out and control open yourself.

• icon
  ReactNode

  An icon in a 40px tile before the title (above it when the header is centered), painted in the tone's soft color. It pops in on a bouncy spring as the card lands.

• children
  ReactNode

  The body. It scrolls on its own between the pinned header and footer (overscroll contained) and drives the hairlines. Forms inside get the first field focused on open.

• footer
  ReactNode

  The actions, primary last in the DOM: on the right in a row on desktop, on top when stacked. On the phone sheet they stack full width at 48px whatever size you passed. Wrap Cancel in DialogClose.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The icon tile's color: success for a confirmation, danger for a warning about data loss. Needs an icon.

• colordefault ""
  string

  Any CSS color for the icon tile. Replaces the tone; the icon is mixed toward the text color so it stays readable. Leave empty to use the tone.

• sizedefault "md"
  "sm" | "md" | "lg" | "xl" | "full"

  Max width 400 / 520 / 720 / 960px, always 16px clear of the screen edges. full fills the screen minus 16px on desktop (a lightbox, a long editor) and becomes a full-height sheet on phones.

• radiusdefault "lg"
  "none" | "sm" | "md" | "lg" | "full"

  Corners 0 / 12 / 16 / 24px (full stays 24px); the icon tile follows. Dialogs default to lg like every large surface. The phone sheet takes 0 / 16 / 24 / 28px.

• headerAligndefault "start"
  "start" | "center"

  start reads like a form: the icon beside the title. center reads like an announcement: the icon above a centered title, and the actions centered too.

• showClosedefault true
  boolean

  The round × in the top corner (ghost, 32px with a 44px hit area on touch). It closes even a dialog that is not dismissible.

• scrollBehaviordefault "inside"
  "inside" | "outside"

  inside: the card stops at 85% of the screen (720px at most), the header and footer stay and the body scrolls. outside: the card grows with its content and the dimmed page scrolls instead, for long reading. The phone sheet and size full always scroll inside.

• dismissibledefault true
  boolean

  false: outside clicks, Escape, the shortcut and the sheet drag do not close it; the card gives a small bump instead and the sheet loses its handle. The × and actions (DialogClose, or setting open) still close it, e.g. a consent that must be answered.

• responsivedefault true
  boolean

  Below 768px it opens as the drawer's bottom sheet: drag to dismiss, safe-area padding, a 92% height for size full. Off, it stays a centered card on phones too.

• shortcutdefault ""
  string

  A key combo in mod+k notation (⌘ on Apple devices, Ctrl elsewhere) that toggles the dialog from anywhere on the page; the trigger gets aria-keyshortcuts. Empty binds nothing.

• modaldefault true
  boolean

  false: no backdrop, no focus trap and no scroll lock; the page behind stays usable (Radix's modal), and on desktop a click on the page closes it. scrollBehavior outside needs the backdrop, so it scrolls inside then.

• onOpenAutoFocus
  (event: Event) => void

  Runs when it opens, before focus moves. Desktop focuses the first focusable element (put the close button last, as the dialog does); the phone sheet focuses itself so no keyboard pops up. Call event.preventDefault() and focus something yourself.

• onCloseAutoFocus
  (event: Event) => void

  Runs when it closes, before focus returns to the trigger. Prevent it to send focus elsewhere.

• container
  HTMLElement | null

  Portal target, document.body by default.

• classNames
  Partial<Record<"overlay" | "content" | "header" | "icon" | "title" | "description" | "body" | "footer" | "close", string>>

  Extra classes for the inner parts, in both modes: on phones they land on the sheet's parts, which carry the same data-slot="dialog-*" names (the backdrop and the handle keep drawer-overlay / drawer-handle).

• className
  string

  Extra classes for the card (dialog-content), merged last.

Parts

FAQ

Used in

More React overlay components