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

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

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