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 javascript selector: '#editor' // or selector: document.querySelector('.my-editor')
document
Document | string | File
required
Document to load.Can be a Document (Object), string or File
{
id: 'doc-123', // string
type: 'docx', // string, can be 'docx' or 'pdf'
data: File // File or Blob
}
string - URL to fetchFile - From file input
Use documents array for multiple documents instead
Multiple documents to load (alternative to single document)documents: [
{ id: 'doc-1', type: 'docx', data: fileObject },
{ id: 'doc-2', type: 'pdf', url: 'report.pdf' }
]
File - From file input (e.g., from <input type="file">)string (URL) - To fetch the document
Unique identifier for this SuperDoc instance
Auto-generated UUID if not provided
User & Permissions
All users with document access. Used for @mentions and collaboration.
User permission level
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
editing - Normal editing - viewing - Read-only display - suggesting- Track changes enabled
Override permission checks for comments and tracked changesconst 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.
Modules
Configure optional modules
Collaboration Module
Real-time collaboration settings
providerType
string
default:"'hocuspocus'"
Provider implementation
Additional connection parameters
Comments system configuration
DOM element for comments list
Comments-only override for the permission resolver
Toolbar configuration
groups
string[]
default:"['left', 'center', 'right']"
Layout groups
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.
Container-based responsive sizing
Appearance
title
string
default:"'SuperDoc'"
Document title for exports and display
Colors for user awareness and highlighting
Built-in palette provided by default
Enable page-based layout
Consider using layoutMode for more control over document layout
layoutMode
string
default:"'paginated'"
Controls how the document is rendered
paginated - Fixed page width with page breaks (default)responsive - 100% width, text reflows to fit container
Use responsive for mobile devices and WCAG AA accessibility compliance. When set to responsive, pagination is automatically disabled.
Custom margins in pixels for responsive layout
Only applies when layoutMode is set to responsive
layoutMargins: { top: 10, bottom: 10, left: 10, right: 10 }
DOM element for toolbar
Alternative to modules.toolbar.selector
Advanced Options
Additional SuperDoc extensions
Learn how to create your own extensions
here. Custom image upload handlerhandleImageUpload: 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;
}
suppressDefaultDocxStyles
Prevent default DOCX styles from being applied
Disable custom context menus
Content Security Policy nonce
Event Handlers
All handlers are optional functions in the configuration:
Called when SuperDoc is readyonReady: ({ superdoc }) => {
console.log('Ready');
}
Called when editor is createdonEditorCreate: ({ editor }) => {
editor.focus();
}
Called on content changesonEditorUpdate: ({ editor }) => {
autoSave(editor.getJSON());
}
