Dialog

A window that opens over the page and makes the content behind it inert.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { color, font, leading, radius, space, text } from "@/theme/tokens.stylex"

const styles = stylex.create({
  link: {
    overflow: "hidden",
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    paddingInline: space.s2_5,
    paddingBlock: space.s2,
    backgroundColor: `color-mix(in oklab, ${color.muted} 50%, transparent)`,
    fontFamily: font.mono,
    fontSize: text.xs,
    lineHeight: leading.xs,
    textOverflow: "ellipsis",
    whiteSpace: "nowrap",
  },
})

export default function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Invite people</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Invite to project</DialogTitle>
          <DialogDescription>
            Send this link to anyone who should join as a viewer.
          </DialogDescription>
        </DialogHeader>
        <div {...stylex.props(styles.link)}>https://example.com/invite/9f3a12</div>
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
          <Button>Copy link</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/dialog

Needs the arene setup first. Also adds Button.

Usage

import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>Invite people</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Invite to project</DialogTitle>
      <DialogDescription>Send this link to anyone who should join as a viewer.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
      <Button>Copy link</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Composition

Dialog
├── DialogTrigger
└── DialogContent          portal + overlay + viewport + popup
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    └── DialogFooter
        └── DialogClose

DialogContent renders the portal, the overlay, the viewport and the popup in one part. Pass props to the overlay and the viewport through overlayProps and viewportProps, or compose DialogPortal, DialogOverlay, DialogViewport yourself.

DialogFooter is drawn as a tray, and the content above it is drawn as a raised panel with rounded bottom corners and a hairline shadow. Keep the footer the last child of DialogContent. It extends to the popup's edges and draws the panel's bottom edge itself, so the panel needs no wrapper.

Custom close button

Use showCloseButton={false} to drop the corner button, then put your own controls in the footer.

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

export default function DialogCustomCloseDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Open</DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle>Leave without saving?</DialogTitle>
          <DialogDescription>Your changes to this draft will be lost.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose render={<Button variant="outline" />}>Keep editing</DialogClose>
          <DialogClose render={<Button variant="destructive" />}>Discard</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

No close button

Use showCloseButton={false} on DialogContent to hide the corner button. DialogFooter takes showCloseButton too, which appends a Close button to the row.

import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

export default function DialogNoCloseButtonDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Open</DialogTrigger>
      <DialogContent showCloseButton={false}>
        <DialogHeader>
          <DialogTitle>Session expired</DialogTitle>
          <DialogDescription>Sign in again to pick up where you left off.</DialogDescription>
        </DialogHeader>
        <DialogFooter showCloseButton />
      </DialogContent>
    </Dialog>
  )
}

Scrollable content

A dialog taller than the window scrolls in its viewport. Nothing is clipped, and you do not need to set a height.

import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { VStack } from "@/components/ui/stack"

const clauses = [
  "You may use the service for any lawful purpose, on any number of projects.",
  "Accounts are personal. Do not share credentials with anyone outside your team.",
  "We store usage data for ninety days, then delete it.",
  "Either party may end this agreement at any time, with no notice period.",
  "Fees already paid for the current billing period are not refunded.",
  "We may update these terms, and will announce any change two weeks ahead.",
  "The service is provided as is, without warranty of any kind.",
  "These terms are governed by the laws of the jurisdiction you signed up from.",
]

export default function DialogScrollableContentDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Read terms</DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Terms of service</DialogTitle>
          <DialogDescription>Last updated 14 September 2026.</DialogDescription>
        </DialogHeader>
        <VStack gap={3}>
          {clauses.map((clause, index) => (
            <p key={clause}>
              {index + 1}. {clause}
            </p>
          ))}
        </VStack>
        <DialogFooter showCloseButton />
      </DialogContent>
    </Dialog>
  )
}

To scroll the body instead, clamp maxHeight on the content through xstyle and give the body overflow-y: auto. The content is a grid. Set gridTemplateRows so the body is the row that shrinks to fit the clamp.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  content: { maxHeight: "min(80vh, 28rem)", gridTemplateRows: "auto 1fr auto" },
  body: {
    overflowY: "auto",
    marginInline: `calc(-1 * ${space.s5})`,
    paddingInline: space.s5,
  },
  row: {
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    paddingInline: space.s3,
    paddingBlock: space.s2,
  },
})

const items = [
  { title: "Update the Q4 revenue projection", owner: "Ada", due: "20 Feb" },
  { title: "Schedule the vendor review", owner: "Alan", due: "22 Feb" },
  { title: "Draft the headcount proposal", owner: "Emmy", due: "25 Feb" },
  { title: "Review the marketing allocation", owner: "Grace", due: "28 Feb" },
  { title: "Write the customer success playbook", owner: "Ada", due: "1 Mar" },
  { title: "Segment the NPS survey by account size", owner: "Grace", due: "3 Mar" },
  { title: "Kick off the retention task force", owner: "Alan", due: "5 Mar" },
  { title: "Finalise the Q4 content calendar", owner: "Emmy", due: "7 Mar" },
]

export default function DialogStickyFooterDemo() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>Review action items</DialogTrigger>
      <DialogContent xstyle={styles.content}>
        <DialogHeader>
          <DialogTitle>Action items</DialogTitle>
          <DialogDescription>Eight items captured in this meeting.</DialogDescription>
        </DialogHeader>
        <VStack gap={2} xstyle={styles.body}>
          {items.map((item) => (
            <div key={item.title} {...stylex.props(styles.row)}>
              <p>{item.title}</p>
              <Text render={<p />} tone="muted">
                {item.owner} &middot; due {item.due}
              </Text>
            </div>
          ))}
        </VStack>
        <DialogFooter showCloseButton>
          <Button>Send reminders</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Imperative API

defineDialog builds a dialog with no trigger in the tree. Call open(payload) from any event handler; the payload is typed and is passed to the render function.

import { Button } from "@/components/ui/button"
import {
  defineDialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog"
import { VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"

type Release = { version: string; date: string; summary: string }

const releaseDialog = defineDialog<Release>((release) => (
  <DialogContent>
    <DialogHeader>
      <DialogTitle>arene {release.version}</DialogTitle>
      <DialogDescription>Released {release.date}.</DialogDescription>
    </DialogHeader>
    <p>{release.summary}</p>
    <DialogFooter>
      <Button variant="outline" onClick={() => releaseDialog.close()}>
        Close
      </Button>
    </DialogFooter>
  </DialogContent>
))

const releases: Release[] = [
  {
    version: "0.4.0",
    date: "14 September 2026",
    summary: "Dialog and alert dialog, both on the Base UI viewport.",
  },
  {
    version: "0.3.0",
    date: "2 September 2026",
    summary: "Button groups, and a dropdown menu that reverses mid-exit.",
  },
  {
    version: "0.2.0",
    date: "18 August 2026",
    summary: "The token layer moved to light-dark() pairs.",
  },
]

export default function DialogImperativeDemo() {
  return (
    <VStack gap={2} align="start">
      {releases.map((release) => (
        <Button key={release.version} variant="outline" onClick={() => releaseDialog.open(release)}>
          {release.version}
          <Text tone="muted">{release.date}</Text>
        </Button>
      ))}
      <releaseDialog.Root />
    </VStack>
  )
}

Define it at module scope

defineDialog<Payload>(render) returns { open, close, Root }. Keep it in a module so any caller can import it.

import { defineDialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"

export const renameDialog = defineDialog<{ id: string; name: string }>((project) => (
  <RenameDialogContent {...project} />
))

Put state in the body

The render function runs only while the dialog is on screen, so state declared inside it starts fresh on every open.

function RenameDialogContent({ id, name }: { id: string; name: string }) {
  const [value, setValue] = useState(name)

  return (
    <DialogContent>
      <DialogHeader>
        <DialogTitle>Rename {name}</DialogTitle>
      </DialogHeader>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <DialogFooter>
        <Button
          onClick={() => {
            renameProject(id, value)
            renameDialog.close()
          }}
        >
          Save
        </Button>
      </DialogFooter>
    </DialogContent>
  )
}

Mount the root once

export function AppDialogs() {
  return <renameDialog.Root />
}

Open it from anywhere

renameDialog.open({ id: project.id, name: project.name })

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Dialog part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className.

Dialog

PropTypeDefault
openboolean—
defaultOpenbooleanfalse
onOpenChange(open: boolean, details) => void—
modalboolean | "trap-focus"true
disablePointerDismissalbooleanfalse
handleDialogHandle—

Call details.cancel() inside onOpenChange to block a close. Use this to write an unsaved-changes guard.

DialogContent

PropTypeDefault
showCloseButtonbooleantrue
overlayPropsDialogOverlayProps—
viewportPropsDialogViewportProps—
initialFocusboolean | RefObject | (type) => …—
finalFocusboolean | RefObject | (type) => …—

DialogFooter

PropTypeDefault
showCloseButtonbooleanfalse

defineDialog

MemberType
open(payload)(payload: Payload) => void
close()() => void
Rootevery Dialog prop except open, defaultOpen, handle and children

Mount Root somewhere that stays mounted across navigation. It renders into <body> through a portal, so its place in the tree only decides when it mounts and unmounts.

Data attributes

AttributeOnEffect
data-slot="dialog-content"the popupPopup slot
data-slot="dialog-overlay"the scrimBackdrop surface
data-starting-style, data-ending-stylepopup and overlayBase UI writes them while the dialog animates
data-open, data-closedpopup and overlayBase UI writes them
data-nested, data-nested-dialog-openpopupSet when dialogs are stacked