Components
Dialog
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.
Usage
pnpm dlx shadcn@latest add @opsinjs/dialog
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Dialog } from "@/components/ui/dialog"<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
dialog · base base · style base-lyraOpen under the product themeConfirming something that cannot be undone
Destructive first, safest last, where initialFocus="safest" lands, so a stray
Return keeps the reading.
dialog-confirming-a-deletion · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Dialog } from "@/components/ui/dialog"
export default function DialogConfirmingADeletion() {
const [open, setOpen] = useState(false)
return (
<div className="flex w-full max-w-sm flex-col items-start gap-opsin-4">
<p className="m-0 text-opsin-body text-muted-foreground">
An example measurement, recorded by hand.
</p>
<Button variant="destructive" onClick={() => setOpen(true)}>
Delete this reading
</Button>
<Dialog
open={open}
onOpenChange={setOpen}
title="Delete this reading?"
description="It will be removed from your history and from any trends it appears in. There is no way to bring it back."
actions={
<>
<Button variant="destructive" onClick={() => setOpen(false)}>
Delete reading
</Button>
<Button variant="primary" onClick={() => setOpen(false)}>
Keep it
</Button>
</>
}
/>
</div>
)
}An answer is needed
severity="alert" sets role="alertdialog", removes the close control, and
refuses both the scrim and Escape.
dialog-an-answer-is-needed · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Dialog } from "@/components/ui/dialog"
export default function DialogAnAnswerIsNeeded() {
const [open, setOpen] = useState(false)
return (
<div className="flex w-full max-w-sm flex-col items-start gap-opsin-4">
<Button variant="secondary" onClick={() => setOpen(true)}>
Open the alert dialog
</Button>
<Dialog
open={open}
onOpenChange={setOpen}
severity="alert"
title="Which device should record your readings?"
description="Readings can be recorded on one device at a time, and this account is set up on two. Choose one before you carry on. The other will stop recording, and nothing already saved is affected."
actions={
<>
<Button variant="secondary" onClick={() => setOpen(false)}>
Use the other device
</Button>
<Button variant="primary" onClick={() => setOpen(false)}>
Use this device
</Button>
</>
}
/>
</div>
)
}When to use it
Use it when
- A decision the reader must make before anything else can proceed.
- Confirming an action that cannot be undone or that the reader may not have anticipated.
- A short blocking task, such as re-authenticating before revealing sensitive values.
Do not use it when
- The reader could carry on without answering, or you are announcing, not asking.Use
alert-bannerinstead. - A task the reader chose to start and can abandon.Use
sheetinstead. - Asking permission to collect or share health data.Use
consent-sheetinstead. - Confirming something that has already happened.Use
toastinstead. - Supporting detail attached to a control.Use
popoverinstead.
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, notinert, 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.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the next control inside the dialog | Trapped; initialFocus="safest" wraps the first Tab to the top. |
| Shift+Tab | Moves focus back to the previous control | Reverse order matches visual order. |
| Enter | Activates the focused action | With initialFocus="safest", the answer that changes nothing. |
| Space | Activates the focused action | Consumed by the button. The page behind is scroll-locked. |
| Escape | Closes an ordinary dialog and returns focus to whatever opened it | The scrim dismisses the same way; both refuse when severity is alert. |
| Escape | Does not close an alert dialog; moves focus to the dialog itself | Re-reads the named, described container. The reason is not spoken. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from DialogProps in registry/bases/base/dialog.tsx.
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.