Preview, then perform, for an action that cannot be undone.
<main class="specimen-page" id="main" tabindex="-1">
<h1>Agents</h1>
<p>Revoke opens the dialog. Cancel, Esc and Revoke agent all work here; the action waits until the page says so.</p>
<ul class="specimen-agents">
<li><span class="cap-mono">deploy-agent</span> <button type="button" class="cap-btn" data-variant="danger" data-specimen-action="revoke">Revoke deploy-agent…</button></li>
<li><span class="cap-mono">example.org</span> <button type="button" class="cap-btn" data-variant="danger" data-specimen-action="delete">Delete the example.org record…</button></li>
<li><span class="cap-mono">job_0cdf2803f0ba</span> <button type="button" class="cap-btn" data-variant="danger" data-specimen-action="fail">Mark job_0cdf2803f0ba failed…</button></li>
</ul>
<p role="status" data-specimen-part="said"></p>
</main>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/confirm-dialog.css";
import { enhance } from "capsomer/behavior/confirm-dialog";
enhance();import "capsomer/tokens.css";
import "capsomer/confirm-dialog.css";
import { ConfirmDialog, ConfirmPage, ConfirmModal } from "capsomer/react/confirm-dialog";Usage
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog"
id="revoke" aria-labelledby="revoke-title" aria-describedby="revoke-desc revoke-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg>…</svg></div>
<h2 class="cap-dialog-title" id="revoke-title">Revoke deploy-agent?</h2>
<p class="cap-dialog-description" id="revoke-desc">This cannot be undone. The agent stops working at once.</p>
</div>
<div class="cap-dialog-body">
<ul id="revoke-list"><li>Its key stops being accepted.</li><li>Its 1 claimed job goes back to the queue.</li></ul>
<!-- Only where the audit row carries a reason: -->
<div class="cap-confirm-reason">
<label for="revoke-reason">Reason (required)</label>
<textarea class="cap-input" id="revoke-reason" rows="3" aria-required="true" aria-describedby="revoke-reason-note" data-cap-part="reason"></textarea>
<p class="cap-confirm-note" id="revoke-reason-note" data-cap-part="reason-note">Recorded with the change.</p>
</div>
<!-- Only for what cannot be recovered: -->
<div class="cap-confirm-typed">
<label id="revoke-typed-label" for="revoke-typed">Type <b>revoke</b> to confirm</label>
<input class="cap-input" id="revoke-typed" autocomplete="off" spellcheck="false" data-cap-part="typed" data-cap-word="revoke">
</div>
</div>
<div class="cap-confirm-error" role="alert" id="revoke-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform">Revoke agent</button>
</div>
</dialog>
<button type="button" class="cap-btn" data-variant="danger" data-cap-confirm-open="revoke">Revoke deploy-agent…</button>import { confirm } from "capsomer/behavior/confirm-dialog";
const done = await confirm({
title: "Revoke deploy-agent?",
lead: "This cannot be undone.",
body: ["Its key stops being accepted.", "Its 1 claimed job goes back to the queue."],
action: "Revoke agent",
reason: {}, // only where the audit row carries a reason; perform gets it
typeToConfirm: "revoke", // only for what cannot be recovered
perform: (reason) => api.revoke("deploy-agent", reason), // reject with an Error whose message says what happened
});<form class="cap-confirm-page" data-cap="confirm-page" action="/admin/sites/example" method="post"
aria-labelledby="del-title" aria-describedby="del-desc del-list">
<input type="hidden" name="intent" value="delete" /><input type="hidden" name="site" value="example" />
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg>…</svg></div>
<h1 class="cap-dialog-title" id="del-title">Delete example.com?</h1>
<p class="cap-dialog-description" id="del-desc">This cannot be undone.</p>
</div>
<div class="cap-dialog-body">
<ul id="del-list"><li>Its 14 checks stop running.</li></ul>
<div class="cap-confirm-reason"><label for="del-reason">Reason (required)</label>
<textarea class="cap-input" id="del-reason" name="reason" rows="3" required></textarea></div>
<div class="cap-confirm-typed"><label for="del-typed">Type <b>delete</b> to confirm</label>
<input class="cap-input" id="del-typed" name="confirm" required pattern="[Dd][Ee][Ll][Ee][Tt][Ee]" title="Type delete" autocomplete="off" spellcheck="false" /></div>
</div>
<div class="cap-confirm-error" role="alert"><!-- empty, or what the server refused --></div>
<div class="cap-dialog-footer" data-align="between">
<a class="cap-btn" href="/admin/sites/example">Cancel</a>
<button type="submit" class="cap-btn" data-variant="danger">Delete site</button>
</div>
</form><ConfirmModal title="Delete this mention" lead="This removes the only copy of it." typeToConfirm="1" action_label="Delete permanently" cancelHref={cancelHref} onCancel={() => navigate(cancelHref)} renderForm={(p) => <Form {...p} />}>
<input type="hidden" name="intent" value="delete" />
</ConfirmModal><Form method="post" onSubmit={(e) => confirmSubmit(e, { title: `Remove ${sponsor.name}?`, action: "Remove sponsor" })}>Examples
Working: a form's own delete button
<main class="specimen-page" id="main" tabindex="-1">
<h1>Awards</h1>
<form data-specimen-part="form" method="post" action="#">
<span class="cap-mono">Spring award</span>
<button type="submit" name="intent" value="delete" class="cap-btn" data-variant="danger" data-specimen-part="delete">Remove the Spring award</button>
</form>
<p role="status" data-specimen-part="sent"></p>
</main>
Open, focus on Cancel
<main class="specimen-page" tabindex="-1">
<h1>Agents</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="open-title" aria-describedby="open-desc open-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="open-title">Revoke deploy-agent?</h2>
<p class="cap-dialog-description" id="open-desc">This cannot be undone. The agent stops working at once.</p>
</div>
<div class="cap-dialog-body">
<ul id="open-list">
<li>Its key stops being accepted.</li>
<li>Its 1 claimed job goes back to the queue.</li>
<li>An audit row records the revocation under your name.</li>
</ul>
</div>
<div class="cap-confirm-error" role="alert" id="open-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform">Revoke agent</button>
</div>
</dialog>
The confirm page: a form in the page, no script needed
<main class="specimen-page" id="main" tabindex="-1">
<form class="cap-confirm-page" data-cap="confirm-page" action="/admin/sites/example" method="post" aria-labelledby="pg-title" aria-describedby="pg-desc pg-list">
<input type="hidden" name="intent" value="delete" />
<input type="hidden" name="site" value="example" />
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z"/></svg></div>
<h1 class="cap-dialog-title" id="pg-title">Delete example.com?</h1>
<p class="cap-dialog-description" id="pg-desc">This cannot be undone. The site and its checks are removed.</p>
</div>
<div class="cap-dialog-body">
<ul id="pg-list">
<li>Its 14 checks stop running.</li>
<li>Its uptime history is deleted.</li>
<li>An audit row records the deletion under your name.</li>
</ul>
<div class="cap-confirm-reason">
<label for="pg-reason">Reason (required)</label>
<textarea class="cap-input" id="pg-reason" name="reason" rows="3" required aria-describedby="pg-reason-note"></textarea>
<p class="cap-confirm-note" id="pg-reason-note">Recorded with the change.</p>
</div>
<div class="cap-confirm-typed">
<label for="pg-typed">Type <b>delete</b> to confirm</label>
<input class="cap-input" id="pg-typed" name="confirm" required pattern="[Dd][Ee][Ll][Ee][Tt][Ee]" title="Type delete" autocomplete="off" spellcheck="false" />
</div>
</div>
<div class="cap-confirm-error" role="alert"></div>
<div class="cap-dialog-footer" data-align="between">
<a class="cap-btn" href="/admin/sites/example">Cancel</a>
<button type="submit" class="cap-btn" data-variant="danger">Delete site</button>
</div>
</form>
</main>
The confirm page, after the server refused: the typed word did not match
<main class="specimen-page" id="main" tabindex="-1">
<form class="cap-confirm-page" data-cap="confirm-page" action="/admin/sites/example" method="post" aria-labelledby="pe-title" aria-describedby="pe-desc pe-list">
<input type="hidden" name="intent" value="delete" />
<input type="hidden" name="site" value="example" />
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z"/></svg></div>
<h1 class="cap-dialog-title" id="pe-title">Delete example.com?</h1>
<p class="cap-dialog-description" id="pe-desc">This cannot be undone. The site and its checks are removed.</p>
</div>
<div class="cap-dialog-body">
<ul id="pe-list">
<li>Its 14 checks stop running.</li>
<li>Its uptime history is deleted.</li>
<li>An audit row records the deletion under your name.</li>
</ul>
<div class="cap-confirm-reason">
<label for="pe-reason">Reason (required)</label>
<textarea class="cap-input" id="pe-reason" name="reason" rows="3" required aria-describedby="pe-reason-note"></textarea>
<p class="cap-confirm-note" id="pe-reason-note">Recorded with the change.</p>
</div>
<div class="cap-confirm-typed">
<label for="pe-typed">Type <b>delete</b> to confirm</label>
<input class="cap-input" id="pe-typed" name="confirm" required pattern="[Dd][Ee][Ll][Ee][Tt][Ee]" title="Type delete" autocomplete="off" spellcheck="false" />
</div>
</div>
<div class="cap-confirm-error" role="alert"><b class="cap-confirm-error-lead">Not done. Nothing was changed.</b> The word did not match. Type delete exactly, then try again.</div>
<div class="cap-dialog-footer" data-align="between">
<a class="cap-btn" href="/admin/sites/example">Cancel</a>
<button type="submit" class="cap-btn" data-variant="danger">Delete site</button>
</div>
</form>
</main>
Comfortable density
<main class="specimen-page" tabindex="-1">
<h1>Agents</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-density="comfortable" data-specimen-open aria-labelledby="comf-title" aria-describedby="comf-desc comf-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="comf-title">Revoke deploy-agent?</h2>
<p class="cap-dialog-description" id="comf-desc">This cannot be undone. The agent stops working at once.</p>
</div>
<div class="cap-dialog-body">
<ul id="comf-list">
<li>Its key stops being accepted.</li>
<li>Its 1 claimed job goes back to the queue.</li>
<li>An audit row records the revocation under your name.</li>
</ul>
</div>
<div class="cap-confirm-error" role="alert" id="comf-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform">Revoke agent</button>
</div>
</dialog>
Busy: the action is running, Esc is held
<main class="specimen-page" tabindex="-1">
<h1>Agents</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="busy-title" aria-describedby="busy-desc busy-list" aria-busy="true">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="busy-title">Revoke deploy-agent?</h2>
<p class="cap-dialog-description" id="busy-desc">This cannot be undone. The agent stops working at once.</p>
</div>
<div class="cap-dialog-body">
<ul id="busy-list">
<li>Its key stops being accepted.</li>
<li>Its 1 claimed job goes back to the queue.</li>
<li>An audit row records the revocation under your name.</li>
</ul>
</div>
<div class="cap-confirm-error" role="alert" id="busy-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel" aria-disabled="true">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform" aria-busy="true" aria-disabled="true">Revoke agent</button>
</div>
</dialog>
Failed: the reason, with Try again
<main class="specimen-page" tabindex="-1">
<h1>Agents</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="error-title" aria-describedby="error-desc error-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="error-title">Revoke deploy-agent?</h2>
<p class="cap-dialog-description" id="error-desc">This cannot be undone. The agent stops working at once.</p>
</div>
<div class="cap-dialog-body">
<ul id="error-list">
<li>Its key stops being accepted.</li>
<li>Its 1 claimed job goes back to the queue.</li>
<li>An audit row records the revocation under your name.</li>
</ul>
</div>
<div class="cap-confirm-error" role="alert" id="error-error" data-cap-part="error"><p class="cap-confirm-error-lead"><svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4v5h1.6V4zM7.2 10.4V12h1.6v-1.6z" /></svg>Not done. Nothing was changed.</p><p>The server did not answer in 10 seconds. Check Activity, then try again.</p></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform" data-cap-label="Revoke agent">Try again</button>
</div>
</dialog>
Reason required, pressed while empty
<main class="specimen-page" tabindex="-1">
<h1>Queue</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="rm-title" aria-describedby="rm-desc rm-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="rm-title">Mark job failed: Rotate the watcher's Cloudflare token</h2>
<p class="cap-dialog-description" id="rm-desc">This ends the job. It cannot be resumed.</p>
</div>
<div class="cap-dialog-body">
<ul id="rm-list">
<li>The job's status becomes failed.</li>
<li>An audit row records the change and your reason.</li>
</ul>
<div class="cap-confirm-reason">
<label for="rm-reason">Reason (required)</label>
<textarea class="cap-input" id="rm-reason" rows="3" aria-required="true" aria-invalid="true" aria-describedby="rm-error rm-note" data-cap-part="reason"></textarea>
<p class="cap-confirm-note" id="rm-note" data-cap-part="reason-note">Recorded with the change.</p>
</div>
</div>
<div class="cap-confirm-error" role="alert" id="rm-error" data-cap-part="error"><p class="cap-confirm-error-lead"><svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4v5h1.6V4zM7.2 10.4V12h1.6v-1.6z" /></svg>A reason is required.</p><p>Type what you are doing and why, then try again. Nothing was changed.</p></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform">Mark failed</button>
</div>
</dialog>
Typed-word guard, not yet typed
<main class="specimen-page" tabindex="-1">
<h1>Sites</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="te-title" aria-describedby="te-desc te-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="te-title">Delete the example.org record?</h2>
<p class="cap-dialog-description" id="te-desc">This cannot be recovered. There is no backup of a site record.</p>
</div>
<div class="cap-dialog-body">
<ul id="te-list">
<li>Its 7 days of uptime history are deleted.</li>
<li>The watcher stops checking example.org on its next pass.</li>
<li>An audit row records the deletion under your name.</li>
</ul>
<div class="cap-confirm-typed">
<label id="te-typed-label" for="te-typed">Type <b>delete</b> to confirm</label>
<input class="cap-input" id="te-typed" type="text" autocomplete="off" autocapitalize="off" spellcheck="false" data-cap-part="typed" data-cap-word="delete" />
</div>
</div>
<div class="cap-confirm-error" role="alert" id="te-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform" aria-disabled="true" aria-describedby="te-typed-label">Delete record</button>
</div>
</dialog>
Typed-word guard, matched (case does not matter)
<main class="specimen-page" tabindex="-1">
<h1>Sites</h1>
<p>The page behind the dialog.</p>
</main>
<dialog class="cap-dialog" data-cap="confirm-dialog" data-placement="center" data-size="md" role="alertdialog" data-specimen-open aria-labelledby="tm-title" aria-describedby="tm-desc tm-list">
<div class="cap-dialog-header">
<div class="cap-dialog-media" data-tone="crit" aria-hidden="true"><svg viewBox="0 0 16 16" width="16" height="16" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.5l7 12.5H1zM7.2 6v4h1.6V6zM7.2 10.8v1.4h1.6v-1.4z" /></svg></div>
<h2 class="cap-dialog-title" id="tm-title">Delete the example.org record?</h2>
<p class="cap-dialog-description" id="tm-desc">This cannot be recovered. There is no backup of a site record.</p>
</div>
<div class="cap-dialog-body">
<ul id="tm-list">
<li>Its 7 days of uptime history are deleted.</li>
<li>The watcher stops checking example.org on its next pass.</li>
<li>An audit row records the deletion under your name.</li>
</ul>
<div class="cap-confirm-typed">
<label id="tm-typed-label" for="tm-typed">Type <b>delete</b> to confirm</label>
<input class="cap-input" id="tm-typed" type="text" autocomplete="off" autocapitalize="off" spellcheck="false" data-cap-part="typed" data-cap-word="delete" value="Delete" />
</div>
</div>
<div class="cap-confirm-error" role="alert" id="tm-error" data-cap-part="error"></div>
<div class="cap-dialog-footer" data-align="between">
<button type="button" class="cap-btn" data-cap-part="cancel">Cancel</button>
<button type="button" class="cap-btn" data-variant="danger" data-cap-part="perform">Delete record</button>
</div>
</dialog>
API reference
ConfirmDialog
| Prop | Type | Required | Does |
|---|---|---|---|
open | boolean | Yes | |
title | string | Yes | Names the action and the object: "Revoke deploy-agent?" |
lead | ReactNode | An optional first sentence: "This cannot be undone." | |
body | string[] | Yes | What will change, one line each. |
action | string | Yes | The perform button's label, named for the action: "Revoke agent". |
typeToConfirm | string | For what cannot be recovered: the short word to type ("revoke"). | |
reason | { label?: string; note?: string } | Asks for a reason, required, before the action. perform receives it. | |
perform | (reason: string) => Promise<void> | Yes | |
onClose | (performed: boolean) => void | Yes | Called once per close, with true when the action was performed. |
cancelLabel | string | ||
returnTo | HTMLElement | null | Where focus goes when the opener has gone; the page's main region by default. | |
media | boolean | The icon tile beside the title. Default: shown. |
ConfirmPage
| Prop | Type | Required | Does |
|---|---|---|---|
action | string | Where the form posts, and the fields it carries with it (the intent, the ids, a return address). Left out, it posts to the page it is on. | |
method | "post" | "get" | ||
hidden | Record<string, string | readonly string[]> | A list value is one hidden field per item, under one name (the ticked ids). | |
title | string | Yes | Names the action and the object: "Delete example.com?" |
lead | ReactNode | ||
body | string[] | What will change, one line each, from the server's own preview. | |
action_label | string | The perform button's label, named for the action: "Delete site". | |
cancelHref | string | Yes | Where Cancel goes: a link, so it works with no script. |
cancelLabel | string | ||
typeToConfirm | string | For what cannot be recovered: the short word to type. Checked by the browser (required and pattern) and again by the server. | |
reason | { label?: string; note?: string } | Asks for a reason, required, that the audit row carries. Posted as reason. | |
error | ReactNode | What the server found wrong the last time (the typed word did not match, no reason): shown in the alert box beside the buttons, so the page works with no script. | |
media | boolean | The icon tile beside the title. Default: shown. | |
headingLevel | "h1" | "h2" | h1 when the confirmation is the whole page, h2 when it sits under one. | |
children | ReactNode | More fields for the form, beside hidden: a list a server renders as its own inputs. | |
onCancel | () => void | Cancel without leaving the page (0.22.0): the link still goes to cancelHref with no script. | |
renderForm | (props: ConfirmFormProps) => ReactElement | The form element, for a router's own form (React Router's <Form>), so the post is a client navigation. It is given every prop the plain form would get. |
ConfirmModal
| Prop | Type | Required | Does |
|---|---|---|---|
hidden | Record<string, string | readonly string[]> | A list value is one hidden field per item, under one name (the ticked ids). | |
title | string | Yes | Names the action and the object: "Delete example.com?" |
children | ReactNode | More fields for the form, beside hidden: a list a server renders as its own inputs. | |
error | ReactNode | What the server found wrong the last time (the typed word did not match, no reason): shown in the alert box beside the buttons, so the page works with no script. | |
reason | { label?: string; note?: string } | Asks for a reason, required, that the audit row carries. Posted as reason. | |
action | string | Where the form posts, and the fields it carries with it (the intent, the ids, a return address). Left out, it posts to the page it is on. | |
method | "post" | "get" | ||
lead | ReactNode | ||
body | string[] | What will change, one line each, from the server's own preview. | |
action_label | string | The perform button's label, named for the action: "Delete site". | |
cancelHref | string | Yes | Where Cancel goes: a link, so it works with no script. |
cancelLabel | string | ||
typeToConfirm | string | For what cannot be recovered: the short word to type. Checked by the browser (required and pattern) and again by the server. | |
media | boolean | The icon tile beside the title. Default: shown. | |
onCancel | () => void | Cancel without leaving the page (0.22.0): the link still goes to cancelHref with no script. | |
renderForm | (props: ConfirmFormProps) => ReactElement | The form element, for a router's own form (React Router's <Form>), so the post is a client navigation. It is given every prop the plain form would get. |
Functions
| Function | Signature | Does |
|---|---|---|
useConfirmAction | <T>(): { subject: T | null; ask: (subject: T, opener?: EventTarget | null | undefined) => void; close: () => void; props: { returnTo: HTMLElement | null | undefined; onClose: (performed: boolean) => void; }; } | The state a page keeps for its confirm dialogs: what is being asked about and the control that asked, so focus goes back to it. ask(subject, event.currentTarget) opens; spread props into the ConfirmDialog whose open is your own test of subject. Carrel's editor, book file and project flags pages use it. |
useTwoStep | <I, P, R>({ preview, perform, onDone, onSignedOut, reachText, }: { preview: (input: I) => Promise<StepAnswer<P>>; perform: (preview: P) => Promise<StepAnswer<R>>; onDone: (result: R) => void; onSignedOut: () => void; reachText?: ((message: string) => string) | undefined; }): { ...; } | Preview, then perform: the preview writes nothing and answers what will change (and a token); perform carries it out. Every press ends in something the person can see: the preview, the result, a refusal in the server's words, or why it could not be sent. A perform refused because its preview expired drops the preview, so the next press previews again. Answers that arrive after the dialog has gone are ignored. |
wordPattern | (word: string): string | The typed-word guard as an HTML pattern, for the page form with no script: every letter is a class of both cases ("delete" gives [Dd][Ee][Ll][Ee][Tt][Ee]) and anything else is escaped, so the browser's own validation says what wordMatches says. The browser anchors the pattern to the whole value and does not trim, so the page's field allows no surrounding spaces; the server must still check the word, because markup is not a guard. |
reasonOf | (dialog: HTMLDialogElement): string | The reason is read from the field itself, not from a copy of its value, so text the browser filled in without an input event still counts. |
setBusy | (dialog: HTMLDialogElement, on: boolean): void | Busy: the shared dialog holds Esc, Close, Cancel and the backdrop; the perform button says so too, and the fields stop taking input. aria-disabled rather than disabled, so focus stays on the button that was pressed. |
showError | (dialog: HTMLDialogElement, message: string): void | Shows a failure inside the dialog, beside the action: what happened, then Try again. |
showReasonError | (dialog: HTMLDialogElement): void | The reason is empty: say so beside the field, mark the field invalid, and put focus in it. Nothing was tried, so the perform button keeps its name and no "Not done" is shown. |
clearError | (dialog: HTMLDialogElement): void | |
bindPerform | (dialog: HTMLDialogElement, perform: Perform): void | Binds what the perform button does for a dialog written in markup. |
openConfirm | (dialog: HTMLDialogElement, opener?: Element | null): void | Opens a confirm dialog, remembering the opener. Focus starts on Cancel. |
wasPerformed | (dialog: HTMLDialogElement): boolean | True when the last close of this dialog followed a successful perform. |
wire | (dialog: HTMLDialogElement, fallback?: HTMLElement | null | undefined): () => void | Wires one dialog: the shared dialog's rules (Cancel, the backdrop that does nothing, Esc held while busy, focus returned on close), then the perform button, the guard and the reason. Returns a function that unwires it. Idempotent for a dialog that is already wired. |
buildConfirm | (o: ConfirmOptions): HTMLDialogElement | Builds the dialog's markup, exactly the contract on the doc page: an alert dialog of the shared dialog, header (a crit icon tile, the title, the lead as its description), a body (what changes, the reason, the typed word), the error box, and the footer. |
confirm | (o: ConfirmOptions): Promise<boolean> | Builds a confirm dialog, opens it, and resolves true once the action has been performed, false when it was canceled. The dialog is removed when it closes. |
confirmSubmit | (e: { preventDefault(): void; currentTarget: Element; submitter?: HTMLElement | null | undefined; nativeEvent?: object | undefined; }, o: ConfirmSubmitOptions): void | The dialog in place of window.confirm on a form. Give it to a form's onSubmit or to a submit button's onClick: it holds the submit, asks, and sends the form again (with the same button) only once the action is chosen. Works with a router's Form, whose own submit runs after this handler. |
enhance | (root?: ParentNode): () => void | Attaches to every confirm dialog written in markup under root, and to every trigger [data-cap-confirm-open="<dialog id>"]. Returns a function that detaches them all. |
Parts and data attributes
| Class | Is |
|---|---|
.cap-confirm-error | its own class |
.cap-confirm-error-lead | its own class |
.cap-confirm-modal | its own class |
.cap-confirm-note | its own class |
.cap-confirm-reason | the root |
.cap-confirm-typed | its own class |
| Attribute | Values |
|---|---|
data-inline | present or absent |
| State | Read from |
|---|---|
:empty | the platform |
Accessibility
| Key | Does |
|---|---|
| (on open) | Focus is on Cancel |
| Tab, Shift Tab | Moves between the fields (when there are any), Cancel and the action; stays inside the dialog |
| Ctrl Enter, Cmd Enter in the reason field | Performs; with the reason empty, says a reason is required and keeps focus in the field |
| Enter or Space on Cancel | Closes; focus returns to the opener |
| Enter or Space on the action | Performs; the dialog shows busy until it ends |
| Enter in the typed-word field | Performs once the word matches |
| Esc | Closes, unless the action is running |
- A native
dialogopened withshowModal()withrole="alertdialog": the page behind is inert, and the dialog is named by its title (aria-labelledby) and described by its lead and its list of changes (aria-describedby). - The confirm page is a
formnamed by its title and described by its lead and its list of changes, so it is a namedformlandmark. It carries norole:groupis not an allowed role forform(ARIA in HTML; axearia-allowed-role). - The error is
role="alert", present and empty until it is needed, so it is announced when filled. - The guard's reason is the perform button's description, so a screen reader hears why it is off.
- An empty reason is
aria-invalid="true"and described by the error box; the border also turns critical, never alone. - Forced colors: the dialog and the error keep their borders.
- Focus is on Cancel on open, so Enter on arrival cannot do the damage.