SuperDoc uses an event system for lifecycle hooks and change notifications.
Event Methods
Subscribe to Events
// Regular subscription
superdoc . on ( 'ready' , handler );
// One-time listener
superdoc . once ( 'ready' , handler );
// Unsubscribe
superdoc . off ( 'ready' , handler );
Event Categories
Lifecycle Initialization and teardown
Collaboration Multi-user events
Lifecycle Events
ready
Fired when SuperDoc is fully initialized.
superdoc . on ( 'ready' , ({ superdoc }) => {
console . log ( 'SuperDoc ready' );
// Safe to use all features
});
editorCreate
When an editor is created.
superdoc . on ( 'editorCreate' , ({ editor }) => {
console . log ( 'Editor created' );
editor . focus ();
});
editorDestroy
When an editor is destroyed.
superdoc . on ( 'editorDestroy' , () => {
console . log ( 'Editor destroyed' );
cleanup ();
});
Content Events
editor-update
When editor content changes.
Editor with updated content
superdoc . on ( 'editor-update' , ({ editor }) => {
const content = editor . getJSON ();
autoSave ( content );
});
content-error
When content processing fails.
superdoc . on ( 'content-error' , ({ error , editor }) => {
console . error ( 'Content error:' , error );
handleError ( error );
});
fonts-resolved
When the document fonts are resolved.
resolvedFonts
{ documentFonts: string[], unsupportedFonts: string[] }
required
Object with document fonts and unsupported fonts
superdoc . on ( 'fonts-resolved' , ({ documentFonts , unsupportedFonts }) => {
if ( unsupportedFonts . length > 0 ) {
console . warn ( 'Some fonts in the document are not supported.' , unsupportedFonts . join ( ', ' ))
}
})
When comments are modified.
Event type: ‘add’, ‘update’, ‘deleted’, ‘resolved’
superdoc . on ( 'comments-update' , ({ type , data }) => {
console . log ( 'Comment event:' , type );
refreshCommentsList ();
});
Collaboration Events
collaboration-ready
When collaboration is initialized.
Editor with collaboration
superdoc . on ( 'collaboration-ready' , ({ editor }) => {
console . log ( 'Collaboration active' );
showOnlineUsers ();
});
awareness-update
When user presence changes.
superdoc . on ( 'awareness-update' , ({ context , states }) => {
const users = Array . from ( states . values ());
updateUserCursors ( users );
});
locked
When document lock state changes.
User who locked the document
superdoc . on ( 'locked' , ({ isLocked , lockedBy }) => {
if ( isLocked ) {
showLockBanner ( `Locked by ${ lockedBy . name } ` );
}
});
Configuration-Based Events
Events can also be configured during initialization
new SuperDoc ({
selector: '#editor' ,
document: 'document.docx' ,
// Event handlers in config
onReady : ({ superdoc }) => {
console . log ( 'Ready from config' );
},
onEditorUpdate : ({ editor }) => {
autoSave ( editor . getJSON ());
},
onFontsResolved : ({ documentFonts , unsupportedFonts }) => {
console . log ( `Found ${ documentFonts . length } in the document` )
}
});
Common Patterns
Auto-save with Debouncing
import { debounce } from 'lodash' ;
const save = debounce ( async ( content ) => {
await api . saveDocument ( content );
}, 1000 );
superdoc . on ( 'editor-update' , ({ editor }) => {
save ( editor . getJSON ());
});
Track Multiple Editors
const editors = new Map ();
superdoc . on ( 'editorCreate' , ({ editor }) => {
const id = editor . options . documentId ;
editors . set ( id , editor );
});
superdoc . on ( 'editorDestroy' , () => {
editors . clear ();
});
Clean Up Pattern
const handlers = {
ready : () => console . log ( 'Ready' ),
update : () => console . log ( 'Updated' )
};
// Subscribe
Object . entries ( handlers ). forEach (([ event , handler ]) => {
superdoc . on ( event , handler );
});
// Later: Unsubscribe all
Object . entries ( handlers ). forEach (([ event , handler ]) => {
superdoc . off ( event , handler );
});
Event Order
Understanding event order helps with initialization:
editorBeforeCreate - Setup phase
editorCreate - Editor ready
ready - All editors ready
collaboration-ready - If enabled
Runtime events
editorDestroy - Cleanup
Best practices:
Use once() for one-time setup
Debounce expensive handlers
Clean up with off() when done
Avoid heavy work in awareness-update
Batch updates in editor-update