> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
Configuration is passed when creating a SuperDoc instance. Only two fields are required.
## Quick start
```javascript theme={null}
new SuperDoc({
selector: "#editor", // Required: Where to render
document: "contract.docx", // Required: What to load
});
```
## Core parameters
DOM selector or element where SuperDoc will mount.
```javascript theme={null}
selector: '#editor'
// or
selector: document.querySelector('.my-editor')
```
Document to load.
Can be a `Document (Object)`, `string` or `File`
* `Document` Object
```json theme={null}
{
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.
Multiple documents to load (alternative to single `document`)
```javascript theme={null}
documents: [
{ id: 'doc-1', type: 'docx', data: fileObject },
{ id: 'doc-2', type: 'pdf', url: 'report.pdf' }
]
```
* `File` - From file input (e.g., from ``)
* `string` (URL) - To fetch the document
Unique identifier for this SuperDoc instance
Auto-generated UUID if not provided
## User & permissions
Current user information
Display name
Email address
Avatar URL
All users with document access. Used for @mentions and collaboration.
User permission level
* `editor` - Full editing capabilities
* `viewer` - Read-only access
* `suggester` - Can only suggest changes
Role overrides documentMode when more restrictive
Initial document mode
* `editing` - Normal editing
* `viewing` - Read-only display
* `suggesting` - Track changes enabled
See the [Track Changes module](/editor/built-in-ui/track-changes) for accept/reject commands, the Document API, and configuration. The [runnable example](https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/built-in-ui/track-changes) shows a complete workflow.
Viewing-mode visibility controls for standard comments
Show comment highlights and threads when `documentMode` is `viewing`
**Deprecated**: Use [`modules.trackChanges`](#track-changes-module) instead. This top-level key remains supported as an alias and will emit a one-time console warning.
Show tracked-change markup and threads when `documentMode` is `viewing`.
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.
```javascript theme={null}
const superdoc = new SuperDoc({
user: { name: 'Alex Editor', email: 'alex@example.com' },
permissionResolver: ({ permission, trackedChange, defaultDecision }) => {
if (permission === 'RESOLVE_OTHER' && trackedChange) {
return false; // Block accepting suggestions from other authors
}
return defaultDecision;
},
});
```
Return `false` to block an action. Return `true` or `undefined` to fall back to the built-in permission matrix. See [Comments > Permission resolver](/editor/built-in-ui/comments#permission-resolver) for the full list of permission types.
## Modules
Configure optional modules
### Collaboration module
Real-time collaboration settings
Shared Yjs document instance for this collaborative session.
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](/editor/collaboration/configuration) and [Collaboration guides](/editor/collaboration/overview).
### Comments module
Comments system configuration
DOM element for comments list
Comments/track-changes bubble display policy.
* `'sidebar'`: always use the right sidebar.
* `'inline'`: always use compact inline popover mode.
* `'auto'`: switch between sidebar and compact inline mode based on available container width.
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.
Allow resolving comments
Dual comment system
Comments-only override for the permission resolver
### Track changes module
Track changes configuration. Supersedes the top-level `trackChanges` and `layoutEngineOptions.trackedChanges` keys, which remain supported as deprecated aliases.
Show tracked-change markup and threads when `documentMode` is `viewing`.
Rendering mode for tracked changes.
* `'review'`: show insertions and deletions inline (default for editing/suggesting).
* `'original'`: show the document as it existed before tracked changes (default for viewing when `visible` is `false`).
* `'final'`: show the document with changes applied.
* `'off'`: disable tracked-change rendering.
Whether the layout engine treats tracked changes as active.
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.
Set to `false` to use the default tracked-change colors.
Exact color overrides keyed by author email or author name. Email matches first, then name.
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.
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
documentMode: 'viewing',
modules: {
trackChanges: { visible: true, mode: 'review' },
},
});
```
Assign per-author tracked-change colors without injecting CSS selectors:
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
modules: {
trackChanges: {
visible: true,
authorColors: {
overrides: {
'alice@example.com': '#1f6feb',
'Bob Reviewer': '#d1242f',
},
resolve: (author) => {
if (author.email?.endsWith('@outside-counsel.com')) return '#8250df';
return undefined; // SuperDoc assigns a stable fallback color
},
},
},
},
});
```
Opt into Microsoft Word / ECMA-376-style independent revisions, where each insertion and each deletion has its own id and resolves on its own:
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
modules: {
trackChanges: { replacements: 'independent' },
},
});
```
### Toolbar module
Toolbar configuration
CSS selector for the toolbar container (e.g. `'#toolbar'`)
Layout groups
Custom icon overrides
Text label overrides
Available font families. See [Toolbar fonts](/editor/built-in-ui/toolbar#font-configuration) for details.
Custom fonts from DOCX files will display in the toolbar but won't be selectable unless loaded in your app and added here.
Hide when inactive
Container-based responsive sizing
### Surface defaults
Optional defaults and resolver for SuperDoc surfaces.
Resolve intent-based surface requests opened with `kind`
Default dialog options
Close dialogs on `Escape`
Close dialogs on backdrop click
Default dialog max-width
Default floating-surface options
Default floating placement
Default floating width
Default floating max-width
Default floating max-height
Close floating surfaces on `Escape`
Close floating surfaces when clicking outside
Move focus into the first focusable child on open
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](/editor/superdoc/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](/editor/superdoc/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.
See [Surfaces](/editor/superdoc/surfaces) for the full API and examples.
**Deprecated**: Use `modules.contextMenu` instead. See the [Context Menu module](/editor/built-in-ui/context-menu) for configuration options.
### Content controls module
Content-control rendering configuration.
Built-in content-control chrome mode.
* `'default'`: Word-like built-in chrome (labels, borders, hover, selected outline)
* `'none'`: disables built-in chrome while keeping SDT data/geometry and `data-sdt-*` wrappers
Use this when you want to keep content controls in the document but disable SuperDoc’s built-in field visuals.
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
modules: {
contentControls: {
chrome: 'none',
},
},
});
```
## Spell check
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.
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
proofing: {
enabled: true,
provider,
defaultLanguage: 'en-US',
maxSuggestions: 3,
}
});
```
Bring your own provider. SuperDoc handles the editor UI. Your app controls the spell-check engine or API. See [Spell check](/editor/spell-check/overview) and [Custom spell-check provider](/editor/spell-check/custom-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.
Spell-check configuration
Enable or disable proofing
Provider instance with an `id` and `check()` function. When the provider returns `replacements`, SuperDoc shows them as direct context-menu actions.
Fallback language for segments without a resolved language
Debounce delay after edits before rechecking
Maximum replacement suggestions shown per issue
Prioritize checking visible pages first
Show `Ignore` in the context menu
Words to suppress from displayed proofing results. This is a SuperDoc-side suppression list, not a provider dictionary mutation.
Provider timeout per request in milliseconds
Maximum number of provider requests in flight at the same time
Maximum number of segments included in a single provider request
Called when the provider times out, returns invalid ranges, or fails
Called with `idle`, `checking`, `disabled`, or `degraded`
## Appearance
Document title for exports and display
Colors for user awareness and highlighting
Built-in palette provided by default
Document view options for controlling layout
Document view layout mode
* `'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'`.
```javascript theme={null}
viewOptions: { layout: 'web' }
```
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`).
```javascript Usage theme={null}
const superdoc = new SuperDoc({
selector: '#editor',
document: file,
contained: true,
});
```
```html Full Example theme={null}
```
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.
Initial zoom level as a percentage. In `fit-width` mode, this is the paint zoom until the first fit computes.
Starting zoom mode. `'manual'` holds the current value. `'fit-width'` keeps the document fitted to the container.
Bounds and padding for the applied fit-width zoom.
Lower bound for the applied zoom percentage.
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.
Horizontal padding in pixels reserved inside the available width before computing the fit.
For custom behavior, listen to [`viewport-change`](/editor/superdoc/events#viewport-change) and call `setZoom()` yourself.
```javascript Usage theme={null}
const superdoc = new SuperDoc({
selector: '#editor',
document: file,
zoom: {
mode: 'fit-width',
fitWidth: { min: 35, max: 100, padding: 24 },
},
});
```
```javascript Full Example theme={null}
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
const superdoc = new SuperDoc({
selector: '#editor',
document: yourFile,
zoom: {
initial: 100,
mode: 'fit-width',
fitWidth: { min: 35, max: 100, padding: 24 },
},
onZoomChange: ({ zoom, mode }) => {
console.log(`Zoom is now ${zoom}% (${mode})`);
},
});
```
Minimal React example for fit-width zoom with current zoom and viewport metrics.
**Removed in v1.0**: Use `viewOptions.layout` instead. `'paginated'` → `'print'`, `'responsive'` → `'web'`.**Removed in v1.0**: Use CSS to control margins in web layout mode.
Show document rulers
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](/advanced/headless-toolbar) to build your own UI.
## Advanced options
Additional SuperDoc extensions
Custom image upload handler
```javascript theme={null}
handleImageUpload: async (file) => {
const formData = new FormData();
formData.append('image', file);
const response = await fetch('/upload', {
method: 'POST',
body: formData
});
const { url } = await response.json();
return url;
}
```
**Deprecated since v1.8**: This option is no longer supported and will be ignored.
Override document content with a JSON schema. Used to load documents from a previously exported JSON representation instead of a DOCX file.
```javascript theme={null}
jsonOverride: { type: 'doc', content: [...] }
```
Font family used for all SuperDoc UI elements (toolbar, comments, etc.)
Prevent default DOCX styles from being applied
Disable custom context menus
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.
```javascript theme={null}
onUnsupportedContent: (items) => {
items.forEach(({ tagName, count }) => {
console.log(`Dropped ${count}x <${tagName}>`);
});
}
```
Log a `console.warn` listing HTML elements dropped during import. Ignored when `onUnsupportedContent` is provided.
Content Security Policy nonce
## Event handlers
All handlers are optional functions in the configuration:
Called when SuperDoc is ready
```javascript theme={null}
onReady: ({ superdoc }) => {
console.log('Ready');
}
```
Called before an editor is created
Called when editor is created
```javascript theme={null}
onEditorCreate: ({ editor }) => {
editor.focus();
}
```
Called on content changes
```javascript theme={null}
onEditorUpdate: ({ editor }) => {
autoSave(editor.getJSON());
}
```
Called when zoom changes from `setZoom()`, the toolbar zoom control, or `fit-width` mode.
```javascript theme={null}
onZoomChange: ({ zoom, mode }) => {
setZoomIndicator(zoom, mode);
}
```
Called when the fit-width calculation changes. Pixel-level width jitter is deduped. `getViewportMetrics()` always reads the latest measurements.
```javascript theme={null}
onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => {
updateFitIndicator({ availableWidth, documentWidth, fitZoom });
}
```
Custom handler for accepting tracked changes from comment bubbles. Replaces default accept behavior when provided.
```javascript theme={null}
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.
Custom handler for rejecting tracked changes from comment bubbles. Replaces default reject behavior when provided.
```javascript theme={null}
onTrackedChangeBubbleReject: (comment, editor) => {
// Custom logic before rejecting
editor.commands.rejectTrackedChangeById(comment.commentId);
logRejection(comment); // e.g., track rejections
}
```
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.
Called when the comments sidebar is toggled
Called when an error occurs
```javascript theme={null}
onException: ({ error }) => {
console.error('SuperDoc error:', error);
}
```
See [Events](/editor/superdoc/events) for complete list.