Dialog

Usage examples

import { useState } from 'react';
import { Button, Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger, Field, FieldLabel, Input } from '@rookcom/monarch-react';

function RenameDialog() {
  const [open, setOpen] = useState(false);
  const [saving, setSaving] = useState(false);
  const save = () => {
    setSaving(true);
    window.setTimeout(() => {
      setSaving(false);
      setOpen(false);
    }, 1200);
  };
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger asChild>
        <Button>Rename board</Button>
      </DialogTrigger>
      <DialogContent
        busy={saving}
        closeOnOutsideClick={false}
        fullScreenOnPhone
        footer={
          <>
            <DialogClose asChild>
              <Button disabled={saving}>Cancel</Button>
            </DialogClose>
            <Button variant="primary" loading={saving} onClick={save}>
              Save
            </Button>
          </>
        }
      >
        <DialogHeader>
          <DialogTitle>Rename board</DialogTitle>
          <DialogDescription>Everyone with access sees the new name.</DialogDescription>
        </DialogHeader>
        <DialogBody>
          <Field>
            <FieldLabel>Board name</FieldLabel>
            <Input defaultValue="Q3 launch" />
          </Field>
        </DialogBody>
      </DialogContent>
    </Dialog>
  );
}

<RenameDialog />

Purpose

A modal window for a focused task or decision that must be finished or dismissed before returning to the page.

Design principles

• Every dialog has a DialogTitle (visually hidden if necessary) so it has an accessible name.
• Header, body and footer are separate parts so long content scrolls while actions stay visible.
• Dismissal is predictable: Escape and the close button always work unless an action is running (busy); outside clicks can be turned off for forms with typed values.
• One Escape press closes one layer: a control whose own popup is open keeps the press (escapeGuard).

API reference

import { Dialog, DialogBody, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@rookcom/monarch-react';

Dialog, DialogTrigger and DialogClose are the Radix Dialog Root, Trigger and Close.

DialogContent renders in a portal with the overlay and an optional built-in close button.

footer is shorthand for a trailing <DialogFooter>; the parts still work on their own.

Generated from the TypeScript declarations of packages/react/src/components/overlays/dialog.

Properties

Variants

States

Interaction behaviour

• Opening moves focus into the dialog; Tab and Shift+Tab stay inside it.
• Escape, the built-in close button or any DialogClose closes it, and focus returns to the trigger.
• A click on the overlay closes it, unless closeOnOutsideClick={false}.
• While busy, nothing closes it; disable your own Cancel button as well.
• Escape is ignored while focus is on a combobox or menu button whose popup is open (escapeGuard, on by default); Radix popups inside the dialog are already stacked layers.
• Controlled with open + onOpenChange, or uncontrolled.

Keyboard support

Accessibility

Role

dialog

Accessible name

DialogTitle; DialogDescription becomes the accessible description.

• The built-in close button is named by closeLabel (default "Close").
• Content outside the dialog is hidden from assistive technology while open (Radix).
• While busy, the content has aria-busy="true" and the close button is disabled.
• For confirmations of destructive actions use ConfirmDialog, which sets role="alertdialog".

Responsive behaviour

• Width is min(size, 100vw - 2rem) and height at most 100dvh - 2rem, so the dialog fits small screens.
• With fullScreenOnPhone, below 640px it fills the screen and pads for notches and home bars (env(safe-area-inset-*)).
• The body scrolls; header and footer stay put.

Theme support

• Raised surface, border and shadow tokens; light, dark and more-contrast themes apply automatically.
• The entrance animation uses duration tokens, which are 0ms under prefers-reduced-motion.

Do and don't

Related components

• ConfirmDialog: Ready-made confirmation built on Dialog.
• Sheet: Side or bottom panel for longer tasks.
• ResponsiveDialog: This dialog on wide screens, a bottom sheet on phones.
• Popover: Non-modal floating content.

Dependencies

Dismissal rules are shared with Sheet through src/internal/dismiss.ts.

Testing coverage

• Opens, traps focus, closes on Escape and restores focus to the trigger.
• Has an accessible name and description; built-in close button is present.
• closeLabel={null} removes the close button.
• No axe violations in the open dialog (jsdom).
• footer renders a DialogFooter after the children.
• busy blocks Escape, outside clicks and the close button, and sets aria-busy.
• closeOnOutsideClick={false} keeps it open on an overlay click; Escape still closes.
• Uncontrolled dialogs close on an overlay click by default.
• Escape guard: Escape on an expanded combobox does not close it; escapeGuard={false} lets it through.
• A consumer onEscapeKeyDown still runs and its preventDefault is honoured.
• size and fullScreenOnPhone are exposed as data attributes.
• Renders on the server (closed).

Tests: packages/react/src/components/overlays/dialog