Document to load.Can be a Document (Object), string or File
Show Supported formats
Document Object
{ id: 'doc-123', // string type: 'pdf', // string, can be 'docx' or 'pdf' data: File, // local File or Blob source // OR url: 'https://example.com/report.pdf' // remote URL source}
string - URL to fetch
File - From file input
For a Document object, use data for local files and url for remote files.
Provide one source field (data or url) per document object.
Use documents array for multiple documents instead.
Override permission checks for comments and tracked changes. By default, editors can resolve, edit, and delete any user’s comments and tracked changes. Use this to restrict actions.
Return false to block an action. Return true or undefined to fall back to the built-in permission matrix. See Comments > Permission resolver for the full list of permission types.
Yjs-compatible provider instance (for example LiveblocksYjsProvider or WebsocketProvider from y-websocket).
SuperDoc uses a provider-agnostic collaboration contract: modules.collaboration = { ydoc, provider }.
Provider setup remains in your app code. See Collaboration configuration and Collaboration guides.
Optional fixed compact-mode threshold override in pixels (used when displayMode: 'auto').
When set, compact mode is active when measured available width is below this value.
Optional CSS selector for the element used to measure available width in displayMode: 'auto'.
Use this when SuperDoc is embedded in custom flex/grid shells and the default fallback target is not representative.
Track changes configuration. Supersedes the top-level trackChanges and layoutEngineOptions.trackedChanges keys, which remain supported as deprecated aliases.
How a tracked replacement (adjacent insertion + deletion created by typing over selected text) surfaces in the UI and API.
'paired' (default, Google Docs model): the two halves share one id and resolve together with a single accept/reject click.
'independent' (Microsoft Word / ECMA-376 §17.13.5 model): each insertion and each deletion has its own id, is addressable on its own, and resolves independently.
Resolve one tracked-change highlight color per author. Use this when imported DOCX files contain reviewers your app does not know ahead of time, or when you want a stable author legend in a custom review UI.
Callback for authors not covered by overrides. Receives { name, email, image }. Return any CSS color string, or undefined to use SuperDoc’s deterministic fallback color.
Built-in find/replace popover for editor-backed documents. Disabled by default; set to true for the built-in UI, or pass an object to customize text, disable replace actions, provide a custom component or render function, or add a runtime resolver. See Surfaces: Built-in Find and Replace.
Built-in password prompt for encrypted DOCX files. Enabled by default when omitted; set to false to disable, true for defaults, or pass an object to customize text, provide a custom component or render function, or add a per-document resolver. See Surfaces: Built-in password prompt.
You only need modules.surfaces if you want shared defaults, a central resolver, or to enable/configure built-in surface behaviors like find/replace and the password prompt. Direct superdoc.openSurface(...) calls do not require any special setup.
Provider-based spell check for the layout-engine editor surface. The configuration key is proofing because the provider contract is designed to support spelling, grammar, and style. The current UI renders spelling only.
Bring your own provider. SuperDoc handles the editor UI. Your app controls the spell-check engine or API. See Spell check and Custom spell-check provider.
Spell check runs when the layout engine is active. In print layout this works out of the box. In web layout, keep the layout engine enabled with layoutEngineOptions.flowMode: 'semantic'.
Only spelling issues render in v1. Grammar and style issues can still be returned by your provider but are not shown yet.
'print' - Fixed page width, displays document as it prints (default)
'web' - Content reflows to fit container width
Use 'web' for mobile devices and WCAG AA reflow compliance (Success Criterion 1.4.10). If you also need layout-engine-powered features such as proofing in web layout, set layoutEngineOptions.flowMode: 'semantic'.
Enable contained mode for fixed-height container embedding. When true, SuperDoc fits within its parent’s height and scrolls internally instead of expanding to the document’s natural height. Works with DOCX, PDF, and HTML documents.Use this when embedding SuperDoc inside a panel, sidebar, or any container with a fixed height (e.g., height: 400px or flex: 1).
Zoom behavior for the document. Use mode: 'fit-width' to keep DOCX and PDF documents fitted to the available container width. Calling setZoom() switches back to manual zoom.
Upper bound for the applied zoom percentage. The default never enlarges the document past its natural size; raise it to let wide containers scale the page up.
CSS selector for the built-in toolbar container (e.g. '#toolbar'). Shorthand for modules.toolbar.selector.Omit this to skip the built-in toolbar: for example, when using the headless toolbar to build your own UI.
Callback invoked with HTML elements that were dropped during import because they have no schema representation. Receives an array of { tagName, outerHTML, count } items. When provided, console.warn is suppressed.
Custom handler for accepting tracked changes from comment bubbles. Replaces default accept behavior when provided.
onTrackedChangeBubbleAccept: (comment, editor) => { // Custom logic before accepting editor.commands.acceptTrackedChangeById(comment.commentId); saveDocument(); // e.g., trigger auto-save after accept}
Only fires from bubble buttons, not toolbar or context menu. The dialog cleanup (closing the bubble) happens automatically after your handler runs.
When using a custom handler, you are responsible for calling editor.commands.acceptTrackedChangeById() if you want the change accepted. The default behavior is fully replaced.
Only fires from bubble buttons, not toolbar or context menu. The dialog cleanup (closing the bubble) happens automatically after your handler runs.
When using a custom handler, you are responsible for calling editor.commands.rejectTrackedChangeById() if you want the change rejected. The default behavior is fully replaced.
