Configuration

Configuration is passed when creating a SuperDoc instance. Only two fields are required.

Quick start

new SuperDoc({
  selector: "#editor", // Required: Where to render
  document: "contract.docx", // Required: What to load
});

Core parameters

string | HTMLElement

required

DOM selector or element where SuperDoc will mount.

selector: '#editor'
// or
selector: document.querySelector('.my-editor')

Document | string | File

required

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.

Document[]

Multiple documents to load (alternative to single document)

documents: [
  { id: 'doc-1', type: 'docx', data: fileObject },
  { id: 'doc-2', type: 'pdf', url: 'report.pdf' }
]

Show Supported formats

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

string

Unique identifier for this SuperDoc instance

Auto-generated UUID if not provided

User & permissions

Object

Current user information

Show User properties

string

required

Display name

string

required

Email address

string

Avatar URL

User[]

default:"[]"

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

string

default:"'editor'"

User permission level

Show Available roles

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

Role overrides documentMode when more restrictive

string

default:"'editing'"

Initial document mode

Show Document modes

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

See the Track Changes module for accept/reject commands, the Document API, and configuration. The runnable example shows a complete workflow.

Object

Viewing-mode visibility controls for standard comments

Hide properties

boolean

default:"false"

Show comment highlights and threads when documentMode is viewing

Object

deprecated

Deprecated: Use modules.trackChanges instead. This top-level key remains supported as an alias and will emit a one-time console warning.

Hide properties

boolean

default:"false"

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

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.

const superdoc = new SuperDoc({
  user: { name: 'Alex Editor', email: '[email protected]' },
  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 for the full list of permission types.

Modules

Object

Configure optional modules

Collaboration module

Object

Real-time collaboration settings

Hide properties

Y.Doc

required

Shared Yjs document instance for this collaborative session.

Object

required

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.

Comments module

Object

Comments system configuration

Hide properties

string | HTMLElement

DOM element for comments list

'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.

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.

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.

boolean

default:"true"

Allow resolving comments

boolean

Dual comment system

function

Comments-only override for the permission resolver

Track changes module

Object

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

Hide properties

boolean

default:"false"

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

'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.

boolean

default:"true"

Whether the layout engine treats tracked changes as active.

'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.

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.

Show properties

boolean

default:"true"

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

Record<string, string>

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

(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.

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:

new SuperDoc({
  selector: '#editor',
  document: 'contract.docx',
  modules: {
    trackChanges: {
      visible: true,
      authorColors: {
        overrides: {
          '[email protected]': '#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:

new SuperDoc({
  selector: '#editor',
  document: 'contract.docx',
  modules: {
    trackChanges: { replacements: 'independent' },
  },
});

Toolbar configuration

Hide properties

string

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

string[]

default:"['left', 'center', 'right']"

Layout groups

Object

Custom icon overrides

Object

Text label overrides

string[]

Available font families. See Toolbar fonts 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.

boolean

default:"true"

Hide when inactive

boolean

default:"false"

Container-based responsive sizing

Surface defaults

Object

Optional defaults and resolver for SuperDoc surfaces.

Hide properties

function

Resolve intent-based surface requests opened with kind

Object

Default dialog options

boolean

default:"true"

Close dialogs on Escape

boolean

default:"true"

Close dialogs on backdrop click

string | number

Default dialog max-width

Object

Default floating-surface options

default:"'top-right'"

Default floating placement

string | number

Default floating width

string | number

Default floating max-width

string | number

Default floating max-height

boolean

default:"true"

Close floating surfaces on Escape

boolean

default:"false"

Close floating surfaces when clicking outside

boolean

default:"true"

Move focus into the first focusable child on open

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.

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.

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 for the full API and examples.

Deprecated: Use modules.contextMenu instead. See the Context Menu module for configuration options.

Content controls module

Object

Content-control rendering configuration.

Hide properties

'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.

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.

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

Object

Spell-check configuration

Hide properties

boolean

default:"false"

Enable or disable proofing

Object

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

string | null

Fallback language for segments without a resolved language

number

default:"500"

Debounce delay after edits before rechecking

number

Maximum replacement suggestions shown per issue

boolean

default:"true"

Prioritize checking visible pages first

boolean

default:"true"

Show Ignore in the context menu

string[]

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

number

default:"10000"

Provider timeout per request in milliseconds

number

default:"2"

Maximum number of provider requests in flight at the same time

number

default:"20"

Maximum number of segments included in a single provider request

function

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

function

Called with idle, checking, disabled, or degraded

Appearance

string

default:"'SuperDoc'"

Document title for exports and display

string[]

Colors for user awareness and highlighting

Built-in palette provided by default

Object

Document view options for controlling layout

Hide properties

string

default:"'print'"

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'.

viewOptions: { layout: 'web' }

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).

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  contained: true,
});

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

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.

Hide properties

number

default:"100"

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

'manual' | 'fit-width'

default:"'manual'"

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

Object

Bounds and padding for the applied fit-width zoom.

Show properties

number

default:"10"

Lower bound for the applied zoom percentage.

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.

number

default:"0"

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

For custom behavior, listen to viewport-change and call setZoom() yourself.

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  zoom: {
    mode: 'fit-width',
    fitWidth: { min: 35, max: 100, padding: 24 },
  },
});

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

Responsive zoom example

Minimal React example for fit-width zoom with current zoom and viewport metrics.

string

deprecated

Removed in v1.0: Use viewOptions.layout instead. 'paginated' → 'print', 'responsive' → 'web'.

Object

deprecated

Removed in v1.0: Use CSS to control margins in web layout mode.

boolean

default:"false"

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 to build your own UI.

Advanced options

Extension[]

default:"[]"

Additional SuperDoc extensions

function

Custom image upload handler

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

Object

deprecated

Deprecated since v1.8: This option is no longer supported and will be ignored.

Object

Override document content with a JSON schema. Used to load documents from a previously exported JSON representation instead of a DOCX file.

jsonOverride: { type: 'doc', content: [...] }

string

default:"'Arial, Helvetica, sans-serif'"

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

boolean

default:"false"

Prevent default DOCX styles from being applied

Disable custom context menus

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.

onUnsupportedContent: (items) => {
  items.forEach(({ tagName, count }) => {
    console.log(`Dropped ${count}x <${tagName}>`);
  });
}

boolean

default:"false"

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

string

Content Security Policy nonce

Event handlers

All handlers are optional functions in the configuration:

function

Called when SuperDoc is ready

onReady: ({ superdoc }) => {
  console.log('Ready');
}

function

Called before an editor is created

function

Called when editor is created

onEditorCreate: ({ editor }) => {
  editor.focus();
}

function

Called on content changes

onEditorUpdate: ({ editor }) => {
  autoSave(editor.getJSON());
}

function

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

onZoomChange: ({ zoom, mode }) => {
  setZoomIndicator(zoom, mode);
}

function

Called when the fit-width calculation changes. Pixel-level width jitter is deduped. getViewportMetrics() always reads the latest measurements.

onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => {
  updateFitIndicator({ availableWidth, documentWidth, fitZoom });
}

function

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.

function

Custom handler for rejecting tracked changes from comment bubbles. Replaces default reject behavior when provided.

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.

function

Called when the comments sidebar is toggled

function

Called when an error occurs

onException: ({ error }) => {
  console.error('SuperDoc error:', error);
}

See Events for complete list.

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Quick start

Core parameters

User & permissions

Modules

Collaboration module

Comments module

Track changes module

Surface defaults

Content controls module

Spell check

Appearance

Responsive zoom example

Advanced options

Event handlers

​Quick start

​Core parameters

​User & permissions

​Modules

​Collaboration module

​Comments module

​Track changes module

​Toolbar module

​Surface defaults

​Content controls module

​Spell check

​Appearance

Responsive zoom example

​Advanced options

​Event handlers

Quick start

Core parameters

User & permissions

Modules

Collaboration module

Comments module

Track changes module

Toolbar module

Surface defaults

Content controls module

Spell check

Appearance

Advanced options

Event handlers