Dialog

A modal window that overlays the page for focused tasks and content.

Usage

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'

<Dialog>
  <DialogTrigger render={<Button variant="outline">Invite people</Button>} />
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Invite your team</DialogTitle>
      <DialogDescription>Send an invitation by email.</DialogDescription>
    </DialogHeader>
    <DialogBody>{/* form, content, … */}</DialogBody>
    <DialogFooter>
      <DialogClose render={<Button variant="outline">Cancel</Button>} />
      <DialogClose render={<Button>Send invites</Button>} />
    </DialogFooter>
  </DialogContent>
</Dialog>

Dialog is a compound component built on Base UI's Dialog. The root holds the open state; the parts compose the trigger and the portalled, centered popup. By default it's modal (focus trapped, page behind blocked) and dismissible (an outside click or Escape closes it), and it draws a close button in the corner:

DialogTrigger — the button that opens the dialog. Use render to project it onto your own Button (or any element).
DialogContent — the portalled, centered popup. It draws the card, backdrop, focus trap, and corner close button, and accepts the shared modal props below.
DialogHeader — groups the title and description with consistent spacing.
DialogTitle — an <h2> that labels the popup (aria-labelledby).
DialogDescription — a <p> that describes it (aria-describedby).
DialogBody — the main content region. It doesn't scroll on its own — for content taller than the viewport, wrap it in a ScrollArea.
DialogFooter — the actions; stacks on small screens and right-aligns in a row from sm up.
DialogClose — a button that dismisses the dialog; project it onto your own Button with render.

Use a Dialog for a focused task or piece of content that should interrupt the page — a form, a confirmation with detail, a media viewer. When the action is a high-stakes confirmation, reach for an Alert Dialog; when the overlay should slide in from an edge (or be swipeable on touch), use a Drawer; for a small, non-blocking panel anchored to a control, use a Popover.

Examples

Form dialog

The most common shape: a header, a body of Fields, and a footer of actions. Lay the form out in DialogBody and dismiss with DialogClose projected onto your buttons.

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Textarea } from '@appica/ui-react/textarea'

export default function DialogForm() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Edit profile</Button>} />
      <DialogContent className="sm:w-110">
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>
            Update how you appear across the workspace. Changes are visible to your team.
          </DialogDescription>
        </DialogHeader>
        <DialogBody className="flex flex-col gap-4">
          <Field>
            <FieldLabel>Display name</FieldLabel>
            <Input defaultValue="Sarah Jenkins" />
          </Field>
          <Field>
            <FieldLabel>Email</FieldLabel>
            <Input type="email" defaultValue="sarah@appica.dev" />
          </Field>
          <Field>
            <FieldLabel>Bio</FieldLabel>
            <Textarea rows={3} defaultValue="Product designer focused on design systems and accessibility." />
          </Field>
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button variant="soft">Cancel</Button>} />
          <DialogClose render={<Button>Save changes</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Sizing

DialogContent is w-150 (600px) by default. Override the width with a className — a responsive sm:w-100 / sm:w-200, a max-w-* cap, or a fixed w-*. Every dialog also carries max-w-full, so any width you set still shrinks to fit narrow screens. For height, the popup grows with its content up to the viewport; give it a fixed h-* only when you want a scrollable body that doesn't resize as content changes.

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'

const SIZES = [
  { label: 'Small', className: 'sm:w-100', width: '400px' },
  { label: 'Default', className: undefined, width: '600px' },
  { label: 'Large', className: 'sm:w-200', width: '800px' },
] as const

export default function DialogSizing() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      {SIZES.map(({ label, className, width }) => (
        <Dialog key={label}>
          <DialogTrigger render={<Button variant="outline">{label}</Button>} />
          <DialogContent className={className}>
            <DialogHeader>
              <DialogTitle>{label} dialog</DialogTitle>
              <DialogDescription>
                {className ? (
                  <>
                    Set on <code>DialogContent</code> with <code>className="{className}"</code> ({width}).
                  </>
                ) : (
                  <>The default width is {width}; no className needed.</>
                )}
              </DialogDescription>
            </DialogHeader>
            <DialogBody>
              <p>
                Widths are responsive — every dialog also carries <code>max-w-full</code>, so it shrinks to fit narrow
                screens instead of overflowing.
              </p>
            </DialogBody>
            <DialogFooter>
              <DialogClose render={<Button variant="outline">Close</Button>} />
            </DialogFooter>
          </DialogContent>
        </Dialog>
      ))}
    </div>
  )
}

Scrollable content

For content taller than the viewport, give DialogContent a fixed height and let a ScrollArea own the overflow between a pinned header and footer. The header and footer stay put while the body scrolls.

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { ScrollArea } from '@appica/ui-react/scroll-area'

const SECTIONS = [
  {
    title: '1. Acceptance of terms',
    body: 'By accessing or using the service you agree to be bound by these terms. If you are entering into this agreement on behalf of a company, you represent that you have the authority to bind that entity.',
  },
  {
    title: '2. Accounts',
    body: 'You are responsible for safeguarding the credentials you use to access the service and for any activity under your account. Notify us immediately of any unauthorized use.',
  },
  {
    title: '3. Acceptable use',
    body: 'You agree not to misuse the service: no probing, scanning, or testing the vulnerability of any system, and no interfering with or disrupting the integrity or performance of the service.',
  },
  {
    title: '4. Content',
    body: 'You retain ownership of the content you submit. By submitting content you grant us a worldwide, non-exclusive license to host and display it solely to operate and improve the service.',
  },
  {
    title: '5. Subscriptions',
    body: 'Paid plans renew automatically at the end of each billing cycle unless cancelled beforehand. Fees are non-refundable except where required by law.',
  },
  {
    title: '6. Termination',
    body: 'We may suspend or terminate your access if you breach these terms. You may stop using the service at any time; certain provisions survive termination.',
  },
  {
    title: '7. Disclaimers',
    body: 'The service is provided "as is" without warranties of any kind, whether express or implied, including merchantability, fitness for a particular purpose, and non-infringement.',
  },
  {
    title: '8. Changes',
    body: 'We may revise these terms from time to time. Material changes will be communicated in advance, and continued use after they take effect constitutes acceptance.',
  },
]

export default function DialogScrollable() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Review terms</Button>} />
      <DialogContent className="h-138 sm:w-130">
        <DialogHeader>
          <DialogTitle>Terms of Service</DialogTitle>
          <DialogDescription>Last updated June 27, 2026</DialogDescription>
        </DialogHeader>
        <ScrollArea className="min-h-0 flex-1">
          <div className="flex flex-col gap-5 px-6 pb-2">
            {SECTIONS.map((section) => (
              <section key={section.title} className="flex flex-col gap-1.5">
                <h3 className="text-foreground-intense font-medium">{section.title}</h3>
                <p>{section.body}</p>
              </section>
            ))}
          </div>
        </ScrollArea>
        <DialogFooter>
          <DialogClose render={<Button variant="outline">Decline</Button>} />
          <DialogClose render={<Button>Accept</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Nested dialogs

A dialog can open another dialog. When the child opens, the parent retracts with the same animation as a close and the child takes its place as a fresh dialog — keeping its frosted frame over the original backdrop — so the two never have to line up in size. Closing the child brings the parent back. Each dialog keeps its own state; just nest the markup.

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Badge } from '@appica/ui-react/badge'
import type { ReactNode } from 'react'

function SettingRow({ label, value, action }: { label: string; value: ReactNode; action?: ReactNode }) {
  return (
    <div className="border-border-muted flex items-center justify-between gap-4 border-b py-3 last:border-b-0">
      <div className="flex min-w-0 flex-col">
        <span className="text-foreground-intense font-medium">{label}</span>
        <span className="truncate text-sm">{value}</span>
      </div>
      {action}
    </div>
  )
}

export default function DialogNested() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline">Account settings</Button>} />
      <DialogContent className="sm:w-110">
        <DialogHeader>
          <DialogTitle>Account & security</DialogTitle>
          <DialogDescription>Manage how you sign in and keep your account safe.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          <SettingRow label="Email" value="ada@appica.dev" />
          <SettingRow
            label="Password"
            value="Last changed 3 months ago"
            action={
              <Dialog>
                <DialogTrigger render={<Button variant="soft">Change</Button>} />
                <DialogContent className="sm:w-110">
                  <DialogHeader>
                    <DialogTitle>Change password</DialogTitle>
                    <DialogDescription>Use at least 8 characters, including a number.</DialogDescription>
                  </DialogHeader>
                  <DialogBody className="flex flex-col gap-4">
                    <Field>
                      <FieldLabel>Current password</FieldLabel>
                      <Input type="password" autoComplete="new-password" defaultValue="opensesame" />
                    </Field>
                    <Field>
                      <FieldLabel>New password</FieldLabel>
                      <Input type="password" autoComplete="new-password" defaultValue="correct-horse" />
                    </Field>
                  </DialogBody>
                  <DialogFooter>
                    <DialogClose render={<Button variant="soft">Cancel</Button>} />
                    <DialogClose render={<Button>Update password</Button>} />
                  </DialogFooter>
                </DialogContent>
              </Dialog>
            }
          />
          <SettingRow label="Two-factor auth" value={<Badge variant="success">Enabled</Badge>} />
          <SettingRow label="Active sessions" value="2 devices" />
        </DialogBody>
        <DialogFooter>
          <DialogClose render={<Button>Done</Button>} />
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

Controlled

Drive the open state yourself with open + onOpenChange (or stay uncontrolled with defaultOpen). Owning the state is what makes a multi-step flow work — this create-project wizard tracks the current step, gates Next until the name is filled, resets itself when the dialog closes (via onOpenChange), and closes programmatically from Create rather than a DialogClose. The result is handed back to the page, which swaps the trigger for a project card; delete it to start over.

'use client'

import * as React from 'react'
import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogBody,
  DialogFooter,
  DialogClose,
} from '@appica/ui-react/dialog'
import { Button } from '@appica/ui-react/button'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Textarea } from '@appica/ui-react/textarea'
import { Thumbnail } from '@appica/ui-react/thumbnail'
import { Folder, Trash } from '@appica/icons-react'

interface Project {
  name: string
  description: string
}

export default function DialogControlled() {
  const [open, setOpen] = React.useState(false)
  const [step, setStep] = React.useState(0)
  const [name, setName] = React.useState('')
  const [description, setDescription] = React.useState('')
  const [project, setProject] = React.useState<Project | null>(null)

  function handleOpenChange(next: boolean) {
    setOpen(next)
    if (!next) {
      setStep(0)
      setName('')
      setDescription('')
    }
  }

  if (project) {
    return (
      <div className="border-border bg-background flex w-full max-w-80 items-center gap-3 rounded-xl border p-3">
        <Thumbnail variant="icon-soft" size="sm">
          <Folder />
        </Thumbnail>
        <div className="flex min-w-0 flex-col">
          <span className="text-foreground-intense -mb-0.5 truncate font-medium">{project.name}</span>
          <span className="text-foreground-muted truncate text-sm">{project.description || 'No description'}</span>
        </div>
        <Button
          variant="outline"
          size="icon-sm"
          className="ms-auto shrink-0"
          aria-label={`Delete ${project.name}`}
          onClick={() => setProject(null)}
        >
          <Trash />
        </Button>
      </div>
    )
  }

  return (
    <Dialog open={open} onOpenChange={handleOpenChange}>
      <DialogTrigger render={<Button variant="outline">Create project</Button>} />
      <DialogContent className="sm:w-105">
        <DialogHeader>
          <DialogTitle>{step === 0 ? 'Name your project' : 'Add a description'}</DialogTitle>
          <DialogDescription>Step {step + 1} of 2 — you can change this later.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          {step === 0 ? (
            <Field>
              <FieldLabel>Project name</FieldLabel>
              <Input autoFocus value={name} onChange={(e) => setName(e.target.value)} placeholder="Orbit" />
            </Field>
          ) : (
            <Field>
              <FieldLabel>Description</FieldLabel>
              <Textarea
                autoFocus
                rows={3}
                value={description}
                onChange={(e) => setDescription(e.target.value)}
                placeholder="What is this project about?"
              />
            </Field>
          )}
        </DialogBody>
        <DialogFooter>
          {step === 0 ? (
            <>
              <DialogClose render={<Button variant="soft">Cancel</Button>} />
              <Button disabled={!name.trim()} onClick={() => setStep(1)}>
                Next
              </Button>
            </>
          ) : (
            <>
              <Button variant="soft" onClick={() => setStep(0)}>
                Back
              </Button>
              <Button
                onClick={() => {
                  setProject({ name: name.trim(), description: description.trim() })
                  handleOpenChange(false)
                }}
              >
                Create project
              </Button>
            </>
          )}
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The header, body, and footer flip to read right-to-left, the footer's actions mirror to the leading edge, and the corner close button moves to the opposite corner. The popup portals to <body>, so it follows the document direction — when you scope RTL to a subtree of an LTR page, set dir="rtl" on DialogContent so the popup mirrors too. For setup details and caveats, see the RTL guide.

API reference

Dialog wraps Base UI's Dialog. Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

Dialog

The root. Holds the open state; renders no DOM of its own.

Prop	Type	Default	Description
`open`	`boolean`	—	Controlled open state. Pair with `onOpenChange`.
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state.
`onOpenChange`	`(open, eventDetails) => void`	—	Fires when the dialog opens or closes.
`modal`	`boolean \| 'trap-focus'`	`true`	Trap focus and block scroll/interaction with the page behind.
`disablePointerDismissal`	`boolean`	`false`	Keep the dialog open when the backdrop is clicked.
`onOpenChangeComplete`	`(open) => void`	—	Fires after the open/close transition finishes.
`actionsRef`	`RefObject`	—	Imperative handle to `close()` / `unmount()` the popup.

DialogTrigger

The button that opens the dialog. Forwards Base UI's Dialog.Trigger; use render to project it onto your own element.

Prop	Type	Default	Description
`render`	`ReactElement \| (props, state) => ReactElement`	—	Render the trigger as your own element (a `Button`).
`nativeButton`	`boolean`	`true`	Whether the rendered element is a native `<button>`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogContent

The portalled, centered popup. Draws the card, backdrop, focus trap, and corner close button, and maps the underlying Base UI Portal / Backdrop / Viewport so you don't have to reach into them. Shared with Alert Dialog and Drawer through the modal props. Defaults to a w-150 (600px) width — override with a className.

Prop	Type	Default	Description
`closeButton`	`boolean`	`true`	Render the × button in the corner.
`closeLabel`	`string`	`'Close'`	Accessible label for the close button.
`backdrop`	`boolean`	`true`	Render the dimmed, blurred backdrop behind the popup.
`initialFocus`	`RefObject`	—	Element to focus when the dialog opens.
`finalFocus`	`RefObject`	—	Element to focus when it closes (defaults to the trigger).
`container`	`HTMLElement \| ref \| null`	—	Portal target — render the popup into a different node.
`keepMounted`	`boolean`	`false`	Keep the popup mounted in the DOM while closed.
`backdropProps`	`object`	—	Escape hatch for the backdrop element (`className`, `style`, …).
`viewportProps`	`object`	—	Escape hatch for the viewport element that centers the popup.
`portalProps`	`object`	—	Escape hatch for the portal element.
`className`	`string`	—	Extra classes on the popup card (e.g. a wider `sm:w-` or a fixed `h-`).

DialogHeader

A layout wrapper that groups the title and description with consistent padding and spacing.

Prop	Type	Default	Description
`children`	`ReactNode`	—	Typically the title and description.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogTitle

An <h2> that labels the popup. Rendering one sets the popup's aria-labelledby.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The title text.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogDescription

A <p> that describes the popup. Rendering one sets the popup's aria-describedby.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The description text.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogBody

The main content region between the header and footer. Flexes to fill the available height; it doesn't scroll on its own — wrap it in a ScrollArea for content taller than the viewport.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The body content.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogFooter

A layout wrapper for the actions. Stacks them vertically on small screens and lays them out in a right-aligned row from sm up.

Prop	Type	Default	Description
`children`	`ReactNode`	—	The action buttons.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

DialogClose

A button that closes the dialog. Forwards Base UI's Dialog.Close; project it onto your own element with render.

Prop	Type	Default	Description
`render`	`ReactElement \| (props, state) => ReactElement`	—	Render the close control as your own element.
`nativeButton`	`boolean`	`true`	Whether the rendered element is a native `<button>`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

The popup has role="dialog" with aria-modal, and aria-labelledby / aria-describedby wired automatically from DialogTitle and DialogDescription — always render a title.
Opening traps focus inside the popup; Escape and an outside click close it (set disablePointerDismissal to keep it open on a backdrop click), and focus returns to the trigger.
With modal (the default), scroll and interaction with the rest of the page are blocked while the dialog is open. Set modal={false} for a non-blocking dialog that leaves the page interactive.
The corner close button carries an accessible label (closeLabel, default "Close"); set it when your dialog needs more specific wording.
Popup enter/exit transitions are skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Dialog

Usage

Examples

Form dialog

Sizing

Scrollable content

Nested dialogs

Controlled

RTL

API reference

Dialog

DialogTrigger

DialogContent

DialogHeader

DialogTitle

DialogDescription

DialogBody

DialogFooter

DialogClose

Accessibility