Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
dialog · base base · style base-lyraOpen under the product theme

Confirming something that cannot be undone

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

Theme
Density
Text
Status
Accent theme
Accent
dialog-confirming-a-deletion · base base · style base-lyraOpen under the product theme
dialog-confirming-a-deletion.tsx
"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.

Theme
Density
Text
Status
Accent theme
Accent
dialog-an-answer-is-needed · base base · style base-lyraOpen under the product theme
dialog-an-answer-is-needed.tsx
"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-banner instead.
  • A task the reader chose to start and can abandon.Use sheet instead.
  • Asking permission to collect or share health data.Use consent-sheet instead.
  • Confirming something that has already happened.Use toast instead.
  • Supporting detail attached to a control.Use popover instead.

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.

KeyActionNotes
TabMoves focus to the next control inside the dialogTrapped; initialFocus="safest" wraps the first Tab to the top.
Shift+TabMoves focus back to the previous controlReverse order matches visual order.
EnterActivates the focused actionWith initialFocus="safest", the answer that changes nothing.
SpaceActivates the focused actionConsumed by the button. The page behind is scroll-locked.
EscapeCloses an ordinary dialog and returns focus to whatever opened itThe scrim dismisses the same way; both refuse when severity is alert.
EscapeDoes not close an alert dialog; moves focus to the dialog itselfRe-reads the named, described container. The reason is not spoken.
Contrast: 52 measured token pairs, 16 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor
body text on the canvas materiallight104.717.96:1Pass
body text on the canvas materialdark-100.518.00:1Pass
body text on the inset materiallight98.116.32:1Pass
body text on the inset materialdark-100.117.18:1Pass
body text on the card materiallight104.717.96:1Pass
body text on the card materialdark-99.616.32:1Pass
body text on the raised materiallight104.717.96:1Pass
body text on the raised materialdark-97.513.77:1Pass
body text on the sheet material over the darkest backdroplight99.916.76:1Pass
body text on the sheet material over the darkest backdropdark-99.716.47:1Pass
body text on the sheet material over the lightest backdroplight104.717.96:1Pass
body text on the sheet material over the lightest backdropdark-80.86.07:1Pass
body text on the overlay material over the darkest backdroplight85.913.48:1Pass
body text on the overlay material over the darkest backdropdark-99.916.77:1Pass
body text on the overlay material over the lightest backdroplight104.717.96:1Pass
body text on the overlay material over the lightest backdropdark-54.22.69:1Below 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.