Events

SuperDoc uses an event system for lifecycle hooks and change notifications.

Subscribing to events

Usage

superdoc.on('ready', handler);     // Subscribe
superdoc.once('ready', handler);   // One-time listener
superdoc.off('ready', handler);    // Unsubscribe

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

const handler = ({ superdoc }) => {
  console.log('Handler called');
};

superdoc.on('ready', handler);     // Subscribe
superdoc.once('ready', handler);   // One-time listener
superdoc.off('ready', handler);    // Unsubscribe

Lifecycle events

ready

Fired when SuperDoc is fully initialized.

Usage

superdoc.on('ready', ({ superdoc }) => {
  // Safe to use all features
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('ready', ({ superdoc }) => {
  // Safe to use all features
});

editorBeforeCreate

Fired before an editor is created. Use this to configure extensions or set up services.

Usage

superdoc.on('editorBeforeCreate', ({ editor }) => {
  // Configure before editor mounts
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('editorBeforeCreate', ({ editor }) => {
  // Configure before editor mounts
});

editorCreate

When an editor is created.

Usage

superdoc.on('editorCreate', ({ editor }) => {
  editor.focus();
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('editorCreate', ({ editor }) => {
  editor.focus();
});

editorDestroy

When an editor is destroyed.

Usage

superdoc.on('editorDestroy', () => {
  cleanup();
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('editorDestroy', () => {
  cleanup();
});

Content events

editor-update

When editor content changes.

Usage

superdoc.on('editor-update', ({ editor }) => {
  autoSave(editor.getJSON());
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('editor-update', ({ editor }) => {
  autoSave(editor.getJSON());
});

content-error

When content processing fails.

Usage

superdoc.on('content-error', ({ error, editor, documentId }) => {
  console.error('Content error:', error);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('content-error', ({ error, editor, documentId }) => {
  console.error('Content error:', error);
});

fonts-resolved

When document fonts are resolved.

Usage

superdoc.on('fonts-resolved', ({ documentFonts, unsupportedFonts }) => {
  if (unsupportedFonts.length > 0) {
    console.warn('Unsupported fonts:', unsupportedFonts.join(', '));
  }
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('fonts-resolved', ({ documentFonts, unsupportedFonts }) => {
  if (unsupportedFonts.length > 0) {
    console.warn('Unsupported fonts:', unsupportedFonts.join(', '));
  }
});

Comments events

comments-update

When comments are modified.

Usage

superdoc.on('comments-update', ({ type, data }) => {
  // type: 'add', 'update', 'deleted', 'resolved'
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('comments-update', ({ type, data }) => {
  // type: 'add', 'update', 'deleted', 'resolved'
});

Collaboration events

collaboration-ready

When collaboration is initialized.

Usage

superdoc.on('collaboration-ready', ({ editor }) => {
  showOnlineUsers();
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('collaboration-ready', ({ editor }) => {
  showOnlineUsers();
});

awareness-update

When user presence changes.

Usage

superdoc.on('awareness-update', ({ context, states }) => {
  const users = Array.from(states.values());
  updateUserCursors(users);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('awareness-update', ({ context, states }) => {
  const users = Array.from(states.values());
  updateUserCursors(users);
});

locked

When document lock state changes.

Usage

superdoc.on('locked', ({ isLocked, lockedBy }) => {
  if (isLocked) {
    showLockBanner(`Locked by ${lockedBy.name}`);
  }
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('locked', ({ isLocked, lockedBy }) => {
  if (isLocked) {
    showLockBanner(`Locked by ${lockedBy.name}`);
  }
});

Pagination events

pagination-update

Fired after each layout pass with the current page count. Use this to know when page data is available — activeEditor.currentTotalPages is only populated after the first layout completes, which happens after the ready event.

Usage

superdoc.on('pagination-update', ({ totalPages, superdoc }) => {
  console.log(`Document has ${totalPages} pages`);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  pagination: true,
});

superdoc.on('pagination-update', ({ totalPages, superdoc }) => {
  console.log(`Document has ${totalPages} pages`);
});

UI events

zoomChange

When the zoom level changes via setZoom().

Usage

superdoc.on('zoomChange', ({ zoom }) => {
  console.log(`Zoom: ${zoom}%`);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('zoomChange', ({ zoom }) => {
  console.log(`Zoom: ${zoom}%`);
});

sidebar-toggle

When the comments sidebar is toggled.

Usage

superdoc.on('sidebar-toggle', (isOpened) => {
  adjustLayout(isOpened);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('sidebar-toggle', (isOpened) => {
  adjustLayout(isOpened);
});

Error events

exception

When an error occurs during document processing or runtime.

Usage

superdoc.on('exception', ({ error, document, editor }) => {
  console.error('SuperDoc error:', error);
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
});

superdoc.on('exception', ({ error, document, editor }) => {
  console.error('SuperDoc error:', error);
});

Configuration-based events

Events can also be set during initialization:

new SuperDoc({
  selector: '#editor',
  document: 'document.docx',
  onReady: ({ superdoc }) => { },
  onEditorBeforeCreate: ({ editor }) => { },
  onEditorCreate: ({ editor }) => { },
  onEditorUpdate: ({ editor }) => { },
  onFontsResolved: ({ documentFonts, unsupportedFonts }) => { },
  onPaginationUpdate: ({ totalPages, superdoc }) => { },
  onSidebarToggle: (isOpened) => { },
  onException: ({ error }) => { },
});

Event order

1. editorBeforeCreate — Before editor mounts
2. editorCreate — Editor ready
3. ready — All editors ready
4. collaboration-ready — If collaboration enabled
5. pagination-update — After each layout pass (page count available)
6. Runtime events (editor-update, comments-update, sidebar-toggle, etc.)
7. editorDestroy — Cleanup