Skip to content

Dialog

The one modal surface under every overlay, such as a dialog, side sheet, bottom sheet or palette.

Anatomy

<dialog class="cap-dialog" data-cap="dialog" data-placement="center" data-size="md"
        id="rename" aria-labelledby="rename-title" aria-describedby="rename-desc">
  <div class="cap-dialog-header">
    <h2 class="cap-dialog-title" id="rename-title">Rename the site</h2>
    <p class="cap-dialog-description" id="rename-desc">Visitors keep the old address.</p>
  </div>
  <div class="cap-dialog-body">…</div>
  <div class="cap-dialog-footer">
    <button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
    <button type="button" class="cap-btn" data-variant="primary">Save name</button>
  </div>
  <button type="button" class="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only
          data-cap-part="close" aria-label="Close">…</button>
</dialog>
<button type="button" class="cap-btn" commandfor="rename" command="show-modal" data-cap-dialog-open="rename">Rename…</button>
<p><a class="cap-btn" href="#rename" data-cap-dialog-open="rename">Rename the site…</a></p>
<dialog class="cap-dialog" data-cap="dialog" data-cap-inline open data-placement="center" data-size="md" id="rename" aria-labelledby="rename-title">
  <form method="post" action="/admin/sites/example/rename">
    <div class="cap-dialog-header"><h2 class="cap-dialog-title" id="rename-title">Rename the site</h2></div>
    <div class="cap-dialog-body"><label for="name">Site name</label><input class="cap-input" id="name" name="name" /></div>
    <div class="cap-dialog-footer">
      <a class="cap-btn" href="/admin/sites/example" data-cap-part="cancel">Cancel</a>
      <button type="submit" class="cap-btn" data-variant="primary">Save name</button>
    </div>
  </form>
</dialog>
import { enhance, openDialog, closeDialog, setDialogBusy } from "capsomer/behavior/dialog";
enhance(); // every [data-cap="dialog"] and every [data-cap-dialog-open] trigger
openDialog(dialogEl, buttonEl, { history: true, focus: fieldEl, returnTo: mainEl });
setDialogBusy(dialogEl, true); // hold Esc, Close, Cancel and the backdrop
closeDialog(dialogEl);
import { Dialog, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, DialogClose, useDialog } from "capsomer/react/dialog";

const d = useDialog();
<button onClick={d.show}>Rename…</button>
<Dialog {...d.props} size="md">
  <DialogHeader><DialogTitle>Rename the site</DialogTitle><DialogDescription>Visitors keep the old address.</DialogDescription></DialogHeader>
  <DialogBody>…</DialogBody>
  <DialogFooter><DialogClose part="cancel">Cancel</DialogClose><button className="cap-btn" data-variant="primary">Save name</button></DialogFooter>
</Dialog>
ClassIs
.cap-dialogthe root
.cap-dialog-bodya part
.cap-dialog-closea part
.cap-dialog-descriptiona part
.cap-dialog-footera part
.cap-dialog-headera part
.cap-dialog-mediaa part
.cap-dialog-titlea part

Data attributes

AttributeValues
data-alignbetween start
data-cap-draggingpresent or absent
data-cap-inlinepresent or absent
data-cap-modal-lockpresent or absent
data-cap-wiredpresent or absent
data-dividerpresent or absent
data-flushpresent or absent
data-placementbottom left right top
data-sizelg sm
data-tonecrit warn
StateRead from
:focus-visiblethe platform
:hoverthe platform
:modalthe platform
[open]an attribute

Keyboard

KeyDoes
(on open)Focus is on the autofocus element, Cancel for an alert dialog, otherwise the first control
Tab, Shift TabMoves between the controls and stays inside the dialog; the page behind is inert
EscCloses the dialog and returns focus to the opener, unless it is busy
Enter or Space on Close or CancelCloses it
Arrow keys, Page Up, Page Down on a scrolling bodyScroll it
Back (browser), where data-cap-history is setCloses it

API

Dialog

PropTypeRequiredDoes
openbooleanYesControlled: true opens it (showModal), false closes it.
onOpenChange(open: boolean) => voidYesCalled once per close, by Esc, Close, Cancel, the backdrop or Back, with false.
placementDialogPlacement
sizeDialogSize
alertbooleanA question the person must answer: role="alertdialog", focus on Cancel, and a click outside does nothing. No Close button unless closeButton says so.
modalLockbooleanA click on the backdrop does nothing (Esc still closes).
destructivebooleanFocus goes to Cancel on open, as for an alert, without the alert role.
busybooleanBusy: aria-busy, and Esc, Close, Cancel and the backdrop refuse.
historybooleanPush "#dialog-<historyId>" so Back closes it.
historyIdstring
closeButtonbooleanThe corner Close button. Default: shown, except for an alert.
closeLabelstring
returnToHTMLElement | nullWhere focus goes when the opener has gone; the page's main region by default.
initialFocus{ current: HTMLElement | null }Where focus goes on open. Default: the [autofocus] control, else the first one.
describedbooleanServer-rendered markup cannot know a DialogDescription is inside; say so here to have aria-describedby in the HTML.
refRef<HTMLDialogElement>
aria-labelstringNames the dialog when there is no DialogTitle. With a DialogTitle, leave it out.
childrenReactNode

And every attribute of <element>.

DialogHeader

PropTypeRequiredDoes
dividerboolean

And every attribute of <element>.

DialogTitle

And every attribute of <element>.

DialogDescription

And every attribute of <element>.

DialogMedia

PropTypeRequiredDoes
tone"crit" | "warn"

And every attribute of <element>.

DialogBody

PropTypeRequiredDoes
flushboolean

And every attribute of <element>.

DialogFooter

PropTypeRequiredDoes
align"start" | "between"

And every attribute of <element>.

DialogClose

PropTypeRequiredDoes
part"close" | "cancel"
labelstring
childrenReactNode

And every attribute of <element>.

Functions

FunctionSignatureDoes
useDialog(initial?: boolean): { open: boolean; show: () => void; hide: () => void; toggle: () => void; props: { open: boolean; onOpenChange: (open: boolean) => void; }; }The state a trigger and a Dialog share: const d = useDialog(); <button onClick={d.show}> and <Dialog {...d.props}>. Focus goes back to the button that was focused when show ran.
rememberOpener(dialog: HTMLDialogElement, opener?: Element | null): voidRemembers what had focus before the dialog opened, to hand focus back on close.
returnFocus(dialog: HTMLDialogElement, fallback?: HTMLElement | null | undefined): voidHands focus back after a dialog closes. After the next frame, so whatever the action changed has rendered first (a revoked agent's row, and its button, may be gone). Only when focus is lost: if the browser already restored it, or a command opened another dialog, that focus stands.
isBackdropClick(dialog: HTMLDialogElement, e: MouseEvent): booleanTrue when a mouse event landed on the dialog's backdrop rather than its content.
errorText(e: unknown): stringThe text of a thrown value, for the error shown inside a dialog.
isBusy(dialog: HTMLDialogElement): booleanA dialog is busy while its action runs: aria-busy on the dialog. Esc, Close, Cancel and the backdrop all refuse until it is cleared.
setDialogBusy(dialog: HTMLDialogElement, on: boolean): voidSets or clears busy. The Close and Cancel parts say so with aria-disabled (not disabled, so focus stays where it was).
syncClosedBy(dialog: HTMLDialogElement): void
isLocked(dialog: HTMLDialogElement): booleanTrue when a click outside the dialog must not close it: it is locked, it is an alert dialog (one that asks a question the person must answer), or it is busy.
historyHash(dialog: HTMLDialogElement): stringThe address a history-entry dialog pushes: data-cap-history may name the prefix ("detail" gives #detail-<id>); the id is data-cap-history-id, data-cap-detail-id or the dialog's id.
focusInitial(dialog: HTMLDialogElement, target?: HTMLElement | null | undefined): voidPuts focus where a person starts: the given element, the [autofocus] one, Cancel when the dialog is an alert or marked destructive (Enter on arrival must not do the damage), else the first control that is not the Close button or the scrolling body, else Close, the body, the dialog itself.
syncScroll(dialog: HTMLDialogElement): voidA body that scrolls must be reachable by keyboard: it takes tabindex="0" while it overflows (and gives it back when it does not), so arrow keys scroll it.
wireDialog(dialog: HTMLDialogElement, opts?: DialogOptions): () => voidWires one dialog: a click on a Close or Cancel part, a click on the backdrop, Esc held while busy, and what happens on close (the address entry, focus back to the opener). Returns a function that unwires it. Idempotent for a dialog that is already wired.
openDialog(dialog: HTMLDialogElement, opener?: Element | null, opts?: DialogOptions): voidOpens a dialog from the control that asked for it, remembering that control. Focus is placed (see focusInitial); with history, "#<prefix>-<id>" is pushed so Back closes it.
closeDialog(dialog: HTMLDialogElement, returnValue?: string | undefined): void
enhance(root?: ParentNode): () => voidWires every dialog under root ([data-cap="dialog"]) and every trigger [data-cap-dialog-open="<dialog id>"]. A dialog with data-cap-open (or the specimens' data-specimen-open) opens now. A dialog with data-cap-inline and open is in the page until this runs, then closed (see the markup on the doc page). A trigger that is a link keeps its href for a new tab; a plain click opens the dialog. Returns a function that detaches them all.

CSS variables

VariableDefault
--cap-dialog-dir1
--cap-dialog-fromtranslateY(8px) scale(0.96)
--cap-dialog-gapmax(var(--space-5), env(safe-area-inset-top, 0px), env(safe-area-inset-bottom, 0px))
--cap-dialog-totranslateY(4px) scale(0.98)
--cap-dialog-topmax(var(--space-5), 10dvh)
--cap-dialog-w30rem
--cap-drag0