> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-sd-2792-selection-active-ids.mintlify.site/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](/modules/track-changes) for accept/reject commands, the Document API, and configuration. The [runnable example](https://github.com/superdoc-dev/superdoc/tree/main/examples/features/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](/modules/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](/modules/collaboration/configuration) and [Collaboration guides](/modules/collaboration/overview).
### Comments module
Comments system configuration
DOM element for comments list
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.
```javascript theme={null}
new SuperDoc({
selector: '#editor',
document: 'contract.docx',
documentMode: 'viewing',
modules: {
trackChanges: { visible: true, mode: 'review' },
},
});
```
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](/modules/toolbar/built-in#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](/core/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](/core/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](/core/superdoc/surfaces) for the full API and examples.
**Deprecated** — Use `modules.contextMenu` instead. See the [Context Menu module](/modules/context-menu) for configuration options.
## Proofing
Provider-based spell check and proofing for the layout-engine editor surface.
```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, while your app controls the proofing engine or API. See [Proofing](/guides/general/proofing) and [Custom proofing provider](/guides/general/custom-proofing-provider).
Proofing is available 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'`.
In the current UI, only spelling issues are rendered. Grammar and style issues can still be returned by your provider, but they are not shown yet.
Proofing 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}
```
**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](/modules/toolbar/headless) 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());
}
```
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](/core/superdoc/events) for complete list.