Skip to main content
SuperDoc uses an event system for lifecycle hooks and change notifications.

​
Event Methods

​
Subscribe to Events

​
event
string
required
Event name to listen for
​
handler
function
required
Callback function
// Regular subscription
superdoc.on('ready', handler);

// One-time listener
superdoc.once('ready', handler);

// Unsubscribe
superdoc.off('ready', handler);

​
Event Categories

Lifecycle

Initialization and teardown

Content

Document changes

Collaboration

Multi-user events

UI

Interface changes

​
Lifecycle Events

​
ready

Fired when SuperDoc is fully initialized.
​
superdoc
SuperDoc
required
SuperDoc instance
superdoc.on('ready', ({ superdoc }) => {
  console.log('SuperDoc ready');
  // Safe to use all features
});

​
editorCreate

When an editor is created.
​
editor
Editor
required
Created editor instance
superdoc.on('editorCreate', ({ editor }) => {
  console.log('Editor created');
  editor.focus();
});

​
editorDestroy

When an editor is destroyed.
No parameters passed
superdoc.on('editorDestroy', () => {
  console.log('Editor destroyed');
  cleanup();
});

​
Content Events

​
editor-update

When editor content changes.
​
editor
Editor
required
Editor with updated content
superdoc.on('editor-update', ({ editor }) => {
  const content = editor.getJSON();
  autoSave(content);
});

​
content-error

When content processing fails.
​
error
Error
required
Error details
​
editor
Editor
Related editor instance
​
documentId
string
Document identifier
​
file
File
Original file
superdoc.on('content-error', ({ error, editor }) => {
  console.error('Content error:', error);
  handleError(error);
});

​
fonts-resolved

When the document fonts are resolved.
Depending on the browser, the user might be prompted to grant access to their local system fonts.
​
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(', '))
  }
})

​
Comments Events

​
comments-update

When comments are modified.
​
type
string
required
Event type: ‘add’, ‘update’, ‘delete’, ‘resolve’
​
data
Object
Comment data
superdoc.on('comments-update', ({ type, data }) => {
  console.log('Comment event:', type);
  refreshCommentsList();
});

​
Collaboration Events

​
collaboration-ready

When collaboration is initialized.
​
editor
Editor
required
Editor with collaboration
superdoc.on('collaboration-ready', ({ editor }) => {
  console.log('Collaboration active');
  showOnlineUsers();
});

​
awareness-update

When user presence changes.
​
context
Object
required
Awareness context
​
states
Map
required
User states map
superdoc.on('awareness-update', ({ context, states }) => {
  const users = Array.from(states.values());
  updateUserCursors(users);
});

​
locked

When document lock state changes.
​
isLocked
boolean
required
Lock state
​
lockedBy
User
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:
  1. editorBeforeCreate - Setup phase
  2. editorCreate - Editor ready
  3. ready - All editors ready
  4. collaboration-ready - If enabled
  5. Runtime events
  6. editorDestroy - Cleanup

​
Performance Tips

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
⌘I