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: 'docx', // string, can be 'docx' or 'pdf'
  data: File // File or Blob
}

• string - URL to fetch
• File - From file input

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

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.

Modules

modules · Object

Configure optional modules

Collaboration module

modules.collaboration · Object

Real-time collaboration settings

Hide properties

url · string · required

WebSocket server URL

providerType · string · default: "'hocuspocus'"

Provider implementation

token · string

Authentication token

params · Object

Additional connection parameters

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

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.

Web layout also forces disableContextMenu: true to prevent long-press context menus on mobile.

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

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

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.