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

User & permissions

user · Object

Current user information

Show 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

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: '[e-mail]' },
  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 module

modules.toolbar · Object

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

modules.slashMenu · Object · deprecated

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

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

toolbar · string

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

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.

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.