> ## 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

**selector** `string | HTMLElement` *required*

DOM selector or element where SuperDoc will mount.

```javascript theme={null}
selector: '#editor'
// or
selector: document.querySelector('.my-editor')
```

**document** `Document | string | File` *required*

Document to load.

Can be a `Document (Object)`, `string` or `File`

**Supported formats**

* `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

> [!NOTE]
>
> 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.

**documents** `Document[]`

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' }
]
```

**Supported formats**

* `File` - From file input (e.g., from `<input type="file">`)
* `string` (URL) - To fetch the document

**superdocId** `string`

Unique identifier for this SuperDoc instance
\[!NOTE] Auto-generated UUID if not provided

## User & permissions

**user** `Object`

Current user information

**User properties**

**name** `string` *required*

Display name

**email** `string` *required*

Email address

**image** `string`

Avatar URL

**users** `User[]` (default: \[])

All users with document access. Used for @mentions and collaboration.

**role** `string` (default: 'editor')

User permission level

**Available roles**

* `editor` - Full editing capabilities
* `viewer` - Read-only access
* `suggester` - Can only suggest changes

> [!WARNING]
>
> Role overrides documentMode when more restrictive

**documentMode** `string` (default: 'editing')

Initial document mode

**Document modes**

* `editing` - Normal editing
* `viewing` - Read-only display
* `suggesting` - Track changes enabled

> [!NOTE]
>
> See the [Track Changes module](https://docs.superdoc.dev/editor/built-in-ui/track-changes.md) for accept/reject commands, the Document API, and configuration. The [runnable example](https://go.superdoc.dev/track-changes) shows a complete workflow.

**comments** `Object`

Viewing-mode visibility controls for standard comments

**properties**

**comments.visible** `boolean` (default: false)

Show comment highlights and threads when `documentMode` is `viewing`

**trackChanges** `Object` *deprecated*

> [!WARNING]
>
> **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.

**properties**

**trackChanges.visible** `boolean` (default: false)

Show tracked-change markup and threads when `documentMode` is `viewing`.

**permissionResolver** `function`

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;
  },
});
```

> [!NOTE]
>
> Return `false` to block an action. Return `true` or `undefined` to fall back to the built-in permission matrix. See [Comments > Permission resolver](https://docs.superdoc.dev/editor/built-in-ui/comments.md#permission-resolver) for the full list of permission types.

## Modules

**modules** `Object`

Configure optional modules

### Collaboration module

**modules.collaboration** `Object`

Real-time collaboration settings

**properties**

**modules.collaboration.ydoc** `Y.Doc` *required*

Shared Yjs document instance for this collaborative session.

**modules.collaboration.provider** `Object` *required*

Yjs-compatible provider instance (for example LiveblocksYjsProvider or WebsocketProvider from y-websocket).

> [!NOTE]
>
> SuperDoc uses a provider-agnostic collaboration contract: `modules.collaboration = { ydoc, provider }`.
> Provider setup remains in your app code. See [Collaboration configuration](https://docs.superdoc.dev/editor/collaboration/configuration.md) and [Collaboration guides](https://docs.superdoc.dev/editor/collaboration/overview.md).

### Comments module

**modules.comments** `Object`

Comments system configuration

**properties**

**element** `string | HTMLElement`

DOM element for comments list

**displayMode** `'sidebar' | 'inline' | 'auto'` (default: 'sidebar')

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.

**compactBreakpointPx** `number`

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.

**compactMeasurementSelector** `string`

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.

**allowResolve** `boolean` (default: true)

Allow resolving comments

**useInternalExternalComments** `boolean`

Dual comment system

**permissionResolver** `function`

Comments-only override for the permission resolver

### Track changes module

**modules.trackChanges** `Object`

Track changes configuration. Supersedes the top-level `trackChanges` and `layoutEngineOptions.trackedChanges` keys, which remain supported as deprecated aliases.

**properties**

**modules.trackChanges.visible** `boolean` (default: false)

Show tracked-change markup and threads when `documentMode` is `viewing`.

**modules.trackChanges.mode** `'review' | 'original' | 'final' | 'off'`

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.

**modules.trackChanges.enabled** `boolean` (default: true)

Whether the layout engine treats tracked changes as active.

**modules.trackChanges.replacements** `'paired' | 'independent'` (default: 'paired')

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.

**modules.trackChanges.authorColors** `Object`

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.

**properties**

**modules.trackChanges.authorColors.enabled** `boolean` (default: true)

Set to `false` to use the default tracked-change colors.

**modules.trackChanges.authorColors.overrides** `Record\<string, string\>`

Exact color overrides keyed by author email or author name. Email matches first, then name.

**modules.trackChanges.authorColors.resolve** `(author) =\> string | undefined`

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

**modules.toolbar** `Object`

Toolbar configuration

**properties**

**selector** `string`

CSS selector for the toolbar container (e.g. `'#toolbar'`)

**groups** `string[]` (default: \['left', 'center', 'right'])

Layout groups

**icons** `Object`

Custom icon overrides

**texts** `Object`

Text label overrides

**fonts** `string[]`

Available font families. See [Toolbar fonts](https://docs.superdoc.dev/editor/built-in-ui/toolbar.md#font-configuration) for details.

> [!NOTE]
>
> Custom fonts from DOCX files will display in the toolbar but won't be selectable unless loaded in your app and added here.

**hideButtons** `boolean` (default: true)

Hide when inactive

**responsiveToContainer** `boolean` (default: false)

Container-based responsive sizing

### Surface defaults

**modules.surfaces** `Object`

Optional defaults and resolver for SuperDoc surfaces.

**properties**

**modules.surfaces.resolver** `function`

Resolve intent-based surface requests opened with `kind`

**modules.surfaces.dialog** `Object`

Default dialog options

**modules.surfaces.dialog.closeOnEscape** `boolean` (default: true)

Close dialogs on `Escape`

**modules.surfaces.dialog.closeOnBackdrop** `boolean` (default: true)

Close dialogs on backdrop click

**modules.surfaces.dialog.maxWidth** `string | number`

Default dialog max-width

**modules.surfaces.floating** `Object`

Default floating-surface options

**modules.surfaces.floating.placement** `'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'` (default: 'top-right')

Default floating placement

**modules.surfaces.floating.width** `string | number`

Default floating width

**modules.surfaces.floating.maxWidth** `string | number`

Default floating max-width

**modules.surfaces.floating.maxHeight** `string | number`

Default floating max-height

**modules.surfaces.floating.closeOnEscape** `boolean` (default: true)

Close floating surfaces on `Escape`

**modules.surfaces.floating.closeOnOutsidePointerDown** `boolean` (default: false)

Close floating surfaces when clicking outside

**modules.surfaces.floating.autoFocus** `boolean` (default: true)

Move focus into the first focusable child on open

**modules.surfaces.findReplace** `false | true | Object` (default: false)

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](https://docs.superdoc.dev/editor/superdoc/surfaces.md#built-in-find-and-replace).

**modules.surfaces.passwordPrompt** `false | true | Object` (default: true)

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](https://docs.superdoc.dev/editor/superdoc/surfaces.md#built-in-password-prompt).

> [!NOTE]
>
> 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](https://docs.superdoc.dev/editor/superdoc/surfaces.md) for the full API and examples.

**modules.slashMenu** `Object` *deprecated*

> [!WARNING]
>
> **Deprecated**: Use `modules.contextMenu` instead. See the [Context Menu module](https://docs.superdoc.dev/editor/built-in-ui/context-menu.md) for configuration options.

### Content controls module

**modules.contentControls** `Object`

Content-control rendering configuration.

**properties**

**modules.contentControls.chrome** `'default' | 'none'` (default: 'default')

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,
  }
});
```

> [!NOTE]
>
> Bring your own provider. SuperDoc handles the editor UI. Your app controls the spell-check engine or API. See [Spell check](https://docs.superdoc.dev/editor/spell-check/overview.md) and [Custom spell-check provider](https://docs.superdoc.dev/editor/spell-check/custom-provider.md).

> [!NOTE]
>
> 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'`.

> [!NOTE]
>
> Only spelling issues render in v1. Grammar and style issues can still be returned by your provider but are not shown yet.

**proofing** `Object`

Spell-check configuration

**properties**

**proofing.enabled** `boolean` (default: false)

Enable or disable proofing

**proofing.provider** `Object`

Provider instance with an `id` and `check()` function. When the provider returns `replacements`, SuperDoc shows them as direct context-menu actions.

**proofing.defaultLanguage** `string | null`

Fallback language for segments without a resolved language

**proofing.debounceMs** `number` (default: 500)

Debounce delay after edits before rechecking

**proofing.maxSuggestions** `number`

Maximum replacement suggestions shown per issue

**proofing.visibleFirst** `boolean` (default: true)

Prioritize checking visible pages first

**proofing.allowIgnoreWord** `boolean` (default: true)

Show `Ignore` in the context menu

**proofing.ignoredWords** `string[]`

Words to suppress from displayed proofing results. This is a SuperDoc-side suppression list, not a provider dictionary mutation.

**proofing.timeoutMs** `number` (default: 10000)

Provider timeout per request in milliseconds

**proofing.maxConcurrentRequests** `number` (default: 2)

Maximum number of provider requests in flight at the same time

**proofing.maxSegmentsPerBatch** `number` (default: 20)

Maximum number of segments included in a single provider request

**proofing.onProofingError** `function`

Called when the provider times out, returns invalid ranges, or fails

**proofing.onStatusChange** `function`

Called with `idle`, `checking`, `disabled`, or `degraded`

## Appearance

**title** `string` (default: 'SuperDoc')

Document title for exports and display

**colors** `string[]`

Colors for user awareness and highlighting
\[!NOTE] Built-in palette provided by default

**viewOptions** `Object`

Document view options for controlling layout

**properties**

**viewOptions.layout** `string` (default: 'print')

Document view layout mode

* `'print'` - Fixed page width, displays document as it prints (default)
* `'web'` - Content reflows to fit container width

> [!NOTE]
>
> 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' }
```

**contained** `boolean` (default: false)

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}
<!-- Parent must have a definite height -->
<div style="height: 500px;">
  <div id="editor"></div>
</div>

<script type="module">
  import { SuperDoc } from 'superdoc';
  import 'superdoc/style.css';

  new SuperDoc({
    selector: '#editor',
    document: yourFile,
    contained: true,
  });
</script>
```

**zoom** `Object`

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.

**properties**

**zoom.initial** `number` (default: 100)

Initial zoom level as a percentage. In `fit-width` mode, this is the paint zoom until the first fit computes.

**zoom.mode** `'manual' | 'fit-width'` (default: 'manual')

Starting zoom mode. `'manual'` holds the current value. `'fit-width'` keeps the document fitted to the container.

**zoom.fitWidth** `Object`

Bounds and padding for the applied fit-width zoom.

**properties**

**zoom.fitWidth.min** `number` (default: 10)

Lower bound for the applied zoom percentage.

**zoom.fitWidth.max** `number` (default: 100)

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.

**zoom.fitWidth.padding** `number` (default: 0)

Horizontal padding in pixels reserved inside the available width before computing the fit.

For custom behavior, listen to [`viewport-change`](https://docs.superdoc.dev/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})`);
  },
});
```

> [card] [Responsive zoom example](https://github.com/superdoc/docx-editor/tree/main/examples/editor/built-in-ui/responsive-zoom)
>
> Minimal React example for fit-width zoom with current zoom and viewport metrics.

**layoutMode** `string` *deprecated*

> [!WARNING]
>
> **Removed in v1.0**: Use `viewOptions.layout` instead. `'paginated'` → `'print'`, `'responsive'` → `'web'`.

**layoutMargins** `Object` *deprecated*

> [!WARNING]
>
> **Removed in v1.0**: Use CSS to control margins in web layout mode.

**rulers** `boolean` (default: false)

Show document rulers

**toolbar** `string`

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](https://docs.superdoc.dev/advanced/headless-toolbar) to build your own UI.

## Advanced options

**editorExtensions** `Extension[]` (default: \[])

Additional SuperDoc extensions

**handleImageUpload** `function`

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;
}
```

**telemetry** `Object` *deprecated*

> [!WARNING]
>
> **Deprecated since v1.8**: This option is no longer supported and will be ignored.

**jsonOverride** `Object`

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: [...] }
```

**uiDisplayFallbackFont** `string` (default: 'Arial, Helvetica, sans-serif')

Font family used for all SuperDoc UI elements (toolbar, comments, etc.)

**suppressDefaultDocxStyles** `boolean` (default: false)

Prevent default DOCX styles from being applied

**disableContextMenu** `boolean` (default: false)

Disable custom context menus

**onUnsupportedContent** `function`

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}>`);
  });
}
```

**warnOnUnsupportedContent** `boolean` (default: false)

Log a `console.warn` listing HTML elements dropped during import. Ignored when `onUnsupportedContent` is provided.

**cspNonce** `string`

Content Security Policy nonce

## Event handlers

All handlers are optional functions in the configuration:

**onReady** `function`

Called when SuperDoc is ready

```javascript theme={null}
onReady: ({ superdoc }) => {
  console.log('Ready');
}
```

**onEditorBeforeCreate** `function`

Called before an editor is created

**onEditorCreate** `function`

Called when editor is created

```javascript theme={null}
onEditorCreate: ({ editor }) => {
  editor.focus();
}
```

**onEditorUpdate** `function`

Called on content changes

```javascript theme={null}
onEditorUpdate: ({ editor }) => {
  autoSave(editor.getJSON());
}
```

**onZoomChange** `function`

Called when zoom changes from `setZoom()`, the toolbar zoom control, or `fit-width` mode.

```javascript theme={null}
onZoomChange: ({ zoom, mode }) => {
  setZoomIndicator(zoom, mode);
}
```

**onViewportChange** `function`

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 });
}
```

**onTrackedChangeBubbleAccept** `function`

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
}
```

> [!NOTE]
>
> Only fires from bubble buttons, not toolbar or context menu. The dialog cleanup (closing the bubble) happens automatically after your handler runs.

> [!WARNING]
>
> 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.

**onTrackedChangeBubbleReject** `function`

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
}
```

> [!NOTE]
>
> Only fires from bubble buttons, not toolbar or context menu. The dialog cleanup (closing the bubble) happens automatically after your handler runs.

> [!WARNING]
>
> 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.

**onSidebarToggle** `function`

Called when the comments sidebar is toggled

**onException** `function`

Called when an error occurs

```javascript theme={null}
onException: ({ error }) => {
  console.error('SuperDoc error:', error);
}
```

See [Events](https://docs.superdoc.dev/editor/superdoc/events.md) for complete list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.