Configure document watermarks
Open a Word-style dialog from the toolbar or your application to inspect, add, replace, or remove text and picture watermarks.
The Watermark dialog lets people configure text or picture watermarks in the browser Editor. Add its button to the built-in
toolbar with ui.toolbar.includeItems: ['watermark']. The page icon sits with the document insertion controls and moves
into the toolbar's overflow menu when space is limited. It is optional and does not appear in the default toolbar.
Add a Watermark button
These standalone examples use public/sample.docx from the Quickstart. Replace src/main.ts
or src/App.tsx to enable the built-in Watermark button:
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
const superdoc = new SuperDoc({
selector: '#editor',
document: '/sample.docx',
ui: { toolbar: { container: '#toolbar', includeItems: ['watermark'] } },
});
window.addEventListener('beforeunload', () => superdoc.destroy());
For Vanilla, replace the contents of <body> in index.html with:
<div id="toolbar"></div>
<div id="editor" style="height: 70vh"></div>
<script type="module" src="/src/main.ts"></script>
For a custom application entry point, call superdoc.ui.watermark.open().
open() returns { ok, reason? } for opening the dialog. It does not report whether a watermark was applied.
Call superdoc.ui.watermark.close() to dismiss the dialog from application code. Calling close() again is safe.
Try the workflow
- Choose Watermark, then Text. Enter
DRAFTand change its transparency or orientation. - Inspect the preview. Choose Cancel and confirm that the document has not changed.
- Reopen, configure the text again, and choose Apply watermark. The dialog closes after a successful change.
- Reopen and choose Picture. Select a local PNG or JPEG, adjust the scale, and apply it.
- Reopen, select No watermark (or Remove selected for multiple copies), and choose Remove watermark. Use the Editor's Undo action to restore it.
The preview uses a sample page with the selected page geometry. It is not a screenshot of the document's body. Draft changes stay in the dialog until Apply. Closing after Apply has started does not cancel the pending operation.
Configure text and pictures
Text controls include the text, font, automatic or explicit point size, bold, italic, color, transparency, and horizontal or diagonal orientation. Presets change the text without replacing the other settings.
Picture controls include image replacement, Auto or 50%, 100%, 150%, 200%, and 500% scaling, aspect-ratio preservation, washout, and transparency. Washout lightens the picture's colors; transparency controls visibility. Settings edits retain an existing embedded picture without requiring another upload.
Imported custom placement and dimensions are retained. The dialog identifies custom settings rather than showing a preset that would misrepresent them. Choosing an orientation or scale deliberately replaces the corresponding custom setting.
Choose the scope
Use Apply to for the entire document or a section, and Page type for all applicable headers or a default, first, or even-page header. Review the impact sentence before applying. Section-scoped edits preserve the surrounding sections and other header content.
A document can store several watermarks, including copies in first and even-page headers that are not currently visible. The selection list identifies each watermark's locations. Select the watermarks to edit, or choose Add watermark; the dialog does not silently replace every stored watermark.
Handle document changes
If the document changes while the draft is open, Apply rejects the stale revision instead of overwriting newer content. The dialog keeps the draft visible. Review latest state reloads the current watermarks and replaces the draft, so copy any text you want to keep before reloading.
Read-only documents can be inspected where the runtime supports it. Mutation controls are disabled when edits are not allowed, including unsupported Suggesting operations. Application permissions still belong to your integration.
Applied watermarks become document content. Follow Load and save to persist the DOCX. Use the Document API watermark reference for programmatic browser or headless operations. The dialog itself is a browser Editor feature.