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

selector

string | HTMLElement

required

DOM selector or element where SuperDoc will mount.

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

document

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.

documents

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

superdocId

string

Unique identifier for this SuperDoc instance

Auto-generated UUID if not provided

User & permissions

user

Object

Current user information

Show User properties

name

string

required

Display name

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

Show Available roles

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

Role overrides documentMode when more restrictive

documentMode

string

default:"'editing'"

Initial document mode

Show Document modes

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

See the Track Changes extension for accept/reject commands, and the runnable example for a complete workflow.

comments

Object

Viewing-mode visibility controls for standard comments

Hide properties

comments.visible

boolean

default:"false"

Show comment highlights and threads when documentMode is viewing

trackChanges

Object

Viewing-mode visibility controls for tracked changes

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

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 for the full list of permission types.

Modules

modules

Object

Configure optional modules

Collaboration module

modules.collaboration

Object

Real-time collaboration settings

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

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

modules.comments

Object

Comments system configuration

Hide properties

element

string | HTMLElement

DOM element for comments list

allowResolve

boolean

default:"true"

Allow resolving comments

useInternalExternalComments

boolean

Dual comment system

permissionResolver

function

Comments-only override for the permission resolver

Toolbar configuration

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

hideButtons

boolean

default:"true"

Hide when inactive

responsiveToContainer

boolean

default:"false"

Container-based responsive sizing

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

Appearance

title

string

default:"'SuperDoc'"

Document title for exports and display

colors

string[]

Colors for user awareness and highlighting

Built-in palette provided by default

viewOptions

Object

Document view options for controlling layout

Hide 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

Use 'web' for mobile devices and WCAG AA reflow compliance (Success Criterion 1.4.10). When set to 'web', the layout engine is automatically disabled.

viewOptions: { layout: 'web' }

layoutMode

string

deprecated

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

layoutMargins

Object

deprecated

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

rulers

boolean

default:"false"

Show document rulers

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

Advanced options

editorExtensions

Extension[]

default:"[]"

Additional SuperDoc extensions

handleImageUpload

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

telemetry

Object

deprecated

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.

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

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.

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

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

onEditorBeforeCreate

function

Called before an editor is created

onEditorCreate

function

Called when editor is created

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

onEditorUpdate

function

Called on content changes

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

onTrackedChangeBubbleAccept

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.

onTrackedChangeBubbleReject

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.

onSidebarToggle

function

Called when the comments sidebar is toggled

onException

function

Called when an error occurs

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

See Events for complete list.

Getting Started

Core

Document Engine

Modules

Extensions

Solutions

Guides

Resources

Quick start

Core parameters

User & permissions

Modules

Collaboration module

Comments module

Appearance

Advanced options

Event handlers

Getting Started

Core

Document Engine

Modules

Extensions

Solutions

Guides

Resources

​Quick start

​Core parameters

​User & permissions

​Modules

​Collaboration module

​Comments module

​Toolbar module

​Appearance

​Advanced options

​Event handlers

Quick start

Core parameters

User & permissions

Modules

Collaboration module

Comments module

Toolbar module

Appearance

Advanced options

Event handlers