# Confirmations

Before an action that cannot be taken back cheaply, the viewer asks: a small dialog in the viewer's language — the question as its title, one sentence under it, **Cancel** first and the action in the danger color. Each question has a switch, under one master switch; the words come from the string table; and [`callbacks.onConfirm`](https://kernstra.com/docs/web-sdk/config/callbacks/onconfirm) puts your own dialog in place of ours. `confirmations` takes the object, or a bare boolean for the master switch.

- Interface: `ConfirmationsConfig`
- Config path: `config.confirmations`

## Example

```ts
// Never ask:
new PDFViewer(container, doc, { confirmations: false });

// Ask about the rest:
new PDFViewer(container, doc, { confirmations: { deleteComment: false, deleteBookmark: false } });

// Asks nothing: the master switch wins.
new PDFViewer(container, doc, { confirmations: { enabled: false, deletePages: true } });
```

## Options (9)

### `enabled`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/enabled

The master switch: `false` asks nothing, whatever the other switches say.

### `deleteTextBlock`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/deletetextblock

"Delete this text?" — asked before Edit Text's Delete removes a block. The deletion joins the session's one undo step.

### `deletePages`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/deletepages

"Delete this page?" — asked before Manage Pages' Delete (and its Delete / Backspace keys) or a thumbnail's Delete page; counts the pages.

### `discardPageEdits`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/discardpageedits

"Discard page changes?" — asked when Manage Pages is left with its changes unapplied, by Cancel, its close button, Escape or a click beside it.

### `deleteComment`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/deletecomment

"Delete this comment?" — asked before the Comments panel deletes a comment (its replies go with it, counted); a reply is asked about as "Delete this reply?".

### `deleteBookmark`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/deletebookmark

"Delete bookmark?" — asked before the outline deletes a bookmark; names it and counts the bookmarks inside it.

### `deleteAnnotation`

- Type: `boolean`
- Default: `false`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/deleteannotation

"Delete this annotation?" — asked before the handle's Delete button, or Delete / Backspace, removes a selected annotation, drawing, text box, image, stamp or placed signature. **Off by default**, on purpose: the deletion can be undone, so the SDK removes it, says so in a toast and offers **Undo** — a question before every highlight teaches people to click through questions. Turn it on for a product whose users would rather be asked.

### `removeAttachment`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/removeattachment

"Remove attachment?" — asked before the Attachments panel removes a file; names it.

### `replaceSignature`

- Type: `boolean`
- Default: `true`
- Page: https://kernstra.com/docs/web-sdk/config/confirmations/replacesignature

"Replace signature?" — asked when a form field signed earlier in this session is clicked again.

## The questions

| Question | Asked before | Default |
| --- | --- | --- |
| "Delete this text?" | Edit Text's Delete removes a block — the deletion joins the session's one undo step | on |
| "Delete this page?" | Manage Pages' Delete / Delete key / Backspace, a thumbnail's Delete page; counts the pages | on |
| "Discard page changes?" | Manage Pages is left with its changes unapplied, by Cancel, the close button, Escape or a click beside it | on |
| "Delete this comment?" | The Comments panel deletes a comment (and its replies, counted); a reply is asked about as "Delete this reply?" | on |
| "Delete bookmark?" | The outline deletes a bookmark; names it and counts the bookmarks inside it | on |
| "Delete this annotation?" | The handle's Delete button, or Delete / Backspace, on a selected annotation, drawing, text box, image, stamp or placed signature | **off** |
| "Remove attachment?" | The Attachments panel removes a file; names it | on |
| "Replace signature?" | A form field signed earlier in this session is clicked again | on |

## Notes

Actions that are not in the table — Erase, Black out, a drawing committed empty, a note left blank — are not asked about: each is undone with Ctrl / ⌘ + Z, and Erase previews what it will take before the stroke lands.

**Your own dialog.** [`callbacks.onConfirm(request)`](https://kernstra.com/docs/web-sdk/config/callbacks/onconfirm) replaces ours wherever it would open, with the same words. `request` is a `ConfirmRequest`: `action` (the key in the table above), `title`, `message`, `confirmLabel` and `cancelLabel` in the viewer's language, plus `count` (pages, replies, nested bookmarks) and `name` (a bookmark, an attachment) where the action has one. Resolve `true` to go ahead, `false` to leave things as they are; a plain boolean works too. A rejection is a `false` (logged with `console.warn`). An action switched off in `confirmations` asks nothing and never reaches `onConfirm`. A question still unanswered when the next one is asked is answered `false` for you — a promise your dialog never settles cannot stop every later question — and an answer that arrives after the viewer was destroyed is dropped.

**The words are partly the document's.** `name`, and so `message`, carry text from the file — a bookmark's title, an attachment's file name — written by whoever made it. Render them as text (a text node; never `innerHTML` or a dialog library's `html:` option), as the SDK's own dialog does. The SDK removes control and bidirectional characters and cuts a long name; it does not escape markup, because text never needs it.

**Our dialog, your look.** It is the shared dialog — `.ks-dialog` inside `.ks-dialog-backdrop` (plus `ks-dialog-backdrop--question`, which lifts it above a modal it may be asked over), portalled to `document.body` with `.ks-portal` — with `ks-confirm` on it and `data-ks-confirm="<action>"`, so one question can be styled without the others; the text is `.ks-confirm-text`, the buttons `.ks-dialog-btn` and `.ks-dialog-btn--danger`. Colors, radius, shadow and width come from the dialog tokens (`--ks-dialog-bg`, `--ks-dialog-border`, `--ks-dialog-radius`, `--ks-dialog-shadow`, and `--ks-dialog-sm-width` — a question is the small dialog) over the semantic ones (`--ks-danger` for the button) — see [Theme tokens](https://kernstra.com/docs/web-sdk/guides/theme-tokens). For example `.ks-dialog[data-ks-confirm='deletePages'] { --ks-dialog-radius: 4px; }`.

**The words.** Every word is a `confirm.*` key in [`locale.strings`](https://kernstra.com/docs/web-sdk/config/locale/strings) / `locale.translations`, with `{n, plural, …}` for the counts and `{name}` for the name; the buttons are `common.cancel`, `common.delete`, `common.remove`, `confirm.discard` and `confirm.replace`.


Web page: https://kernstra.com/docs/web-sdk/config/confirmations