docs / core / dialog

Dialog

a window that stops the page until you answer it. for confirmations, short forms, and the last word before something destructive happens.

intensity · recedesrsc · client

provenance

authored in usva

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

confirmations and short forms that block the page until answereddestructive actions pass through it before anything is destroyednot for content that scrolls or pins to an edge. that is Drawernever stack two. a second dialog means the first asked too much

a11y

role="dialog" named by its Title, or aria-label without one · focus moves in on open, Escape closesjest-axe

dependencies

@base-ui/react · Card from the same package
live demo · try it out
customize
surfacehow content sits above the scrim
highlightwash, top edge, or glow ring
modalfocus trap, scroll lock, outside-pointer
titlenames the dialog for screen readers
descriptionthe body copy
confirmadd an accent button beside cancel
usagecopy
import { Dialog } from "@usva-ui/react/primitives/dialog";

<Dialog>
  <Dialog.Trigger>Open dialog</Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Confirm action</Dialog.Title>
    <Dialog.Description>This can't be undone. Are you sure you want to continue?</Dialog.Description>
    <div className="mt-4 flex justify-end gap-2">
      <Dialog.Close>Cancel</Dialog.Close>
      <button type="button">Confirm</button>
    </div>
  </Dialog.Content>
</Dialog>

props

proptypedefaultnotes
openboolean—controlled open state, on the root.
defaultOpenbooleanfalseinitial open state when uncontrolled.
onOpenChange(open, eventDetails) => void—fires when the open state changes.
modalboolean | "trap-focus"truefocus trap, scroll lock and outside-pointer behavior in one switch.
surface"elevated" | "flat" | "glass""elevated"how Dialog.Content sits above the scrim. shared with Card and Drawer.
highlight"none" | "wash" | "edge" | "ring""none"accent treatment on Dialog.Content: a radial wash, a top edge hairline, or a glow ring. the same vocabulary as Card.
backdropClassNamestring—extra classes on the scrim, on Dialog.Content.

get it

bun add @usva-ui/reactcopy
usagecopy
import { Dialog } from "@usva-ui/react/primitives/dialog";

<Dialog>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Confirm action</Dialog.Title>
    <Dialog.Description>This can't be undone.</Dialog.Description>
    <Dialog.Close>Cancel</Dialog.Close>
  </Dialog.Content>
</Dialog>