---
title: "Dialog"
description: "A window over the page that waits for an answer. It takes your keyboard and attention until you deal with it, and gives them back where it found them."
url: "https://opsinjs.pensievelabs.org/docs/components/dialog"
source: "https://opsinjs.pensievelabs.org/docs/components/dialog.md"
section: "Components"
status: "shipped"
kind: "component"
category: "surfaces"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["modal", "alert dialog", "popup", "confirm"]
governedBy: ["alerts", "consent-and-privacy", "high-stakes-moments"]
usedIn: ["alert-escalation", "consent-and-permissions"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="dialog"
  status="shipped"
  questions="[
  &#x22;`sheetBelow` is gone because a Sheet is dismissible, and whether an inset panel is the right phone answer stays open.&#x22;,
  &#x22;A refused Escape re-announces the question, never the reason, and nobody has put a screen reader on that announcement.&#x22;,
  &#x22;`actions` states a cap of two and cannot enforce it, because `ReactNode` does not say how many controls are inside.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="dialog" unbuilt="false" importPath="@/components/ui/dialog" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" registryDependencies="[&#x22;surface&#x22;, &#x22;button&#x22;]" />

```tsx
import { Dialog } from "@/components/ui/dialog"
```

```tsx
<Dialog
  open={open}
  onOpenChange={setOpen}
  title="Delete this reading?"
  description="It will be removed from your history and from any trends it appears in."
  actions={
    <>
      <Button variant="destructive" onClick={remove}>Delete reading</Button>
      <Button variant="primary" onClick={() => setOpen(false)}>Keep it</Button>
    </>
  }
/>
```

## Examples [#examples]

<ComponentPreview name="dialog" />

### Confirming something that cannot be undone [#confirming-something-that-cannot-be-undone]

Destructive first, safest last, where `initialFocus="safest"` lands, so a stray
Return keeps the reading.

<ComponentPreview name="dialog-confirming-a-deletion" kind="example" align="start" />

### An answer is needed [#an-answer-is-needed]

`severity="alert"` sets `role="alertdialog"`, removes the close control, and
refuses both the scrim and Escape.

<ComponentPreview name="dialog-an-answer-is-needed" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A decision the reader must make before anything else can proceed.&#x22;,
  &#x22;Confirming an action that cannot be undone or that the reader may not have anticipated.&#x22;,
  &#x22;A short blocking task, such as re-authenticating before revealing sensitive values.&#x22;,
]"
  avoid="[
  { case: &#x22;The reader could carry on without answering, or you are announcing, not asking.&#x22;, instead: &#x22;alert-banner&#x22; },
  { case: &#x22;A task the reader chose to start and can abandon.&#x22;, instead: &#x22;sheet&#x22; },
  { case: &#x22;Asking permission to collect or share health data.&#x22;, instead: &#x22;consent-sheet&#x22; },
  { case: &#x22;Confirming something that has already happened.&#x22;, instead: &#x22;toast&#x22; },
  { case: &#x22;Supporting detail attached to a control.&#x22;, instead: &#x22;popover&#x22; },
]"
/>

## Accessibility [#accessibility]

The rendered pass found no axe violation, undersized target or focus-visible miss, and
held at 320px, and the source had no critical, serious or moderate defect.

* `severity="alert"` swaps in Base UI's alert-dialog root, tying the role to the
  refusal to dismiss.
* It is named by its title and described by its description. A blank description
  renders nothing.
* Focus moves in on open, is trapped, and returns on close to whatever had it.
* The Close control sinks when pressed, so a tap on the way out shows it landed.
* The page behind is `aria-hidden`, not `inert`, so focus from behind can still
  reach it.

**Residual items.** `Dialog.Close` uses a raw `focus-visible` utility, not the
border-focus token, but renders a valid 2px offset ring, so 2.4.7 and 1.4.11 pass. It
matches the `sheet` close control by design.

<KeyboardTable
  name="dialog"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the next control inside the dialog&#x22;,
    notes: &#x22;Trapped; initialFocus=\&#x22;safest\&#x22; wraps the first Tab to the top.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back to the previous control&#x22;,
    notes: &#x22;Reverse order matches visual order.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Activates the focused action&#x22;,
    notes: &#x22;With initialFocus=\&#x22;safest\&#x22;, the answer that changes nothing.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Activates the focused action&#x22;,
    notes: &#x22;Consumed by the button. The page behind is scroll-locked.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Closes an ordinary dialog and returns focus to whatever opened it&#x22;,
    notes: &#x22;The scrim dismisses the same way; both refuse when severity is alert.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Does not close an alert dialog; moves focus to the dialog itself&#x22;,
    notes: &#x22;Re-reads the named, described container. The reason is not spoken.&#x22;,
  },
]"
/>

<ContrastReport component="dialog" />

## Props interface [#props-interface]

<PropsTable name="DialogProps" />

`actions` and `closeLabel` are not in the specification; `closeLabel` defaults to
*Close*, ignored on an alert dialog. `onOpenChange` does not fire when Escape is
refused. `sheetBelow` is not a prop: the dialog never becomes a Sheet.
