Events

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

Driving live React UI state? Prefer superdoc/ui subscriptions. useSuperDocSelection, useSuperDocComments, useSuperDocTrackChanges, useSuperDocDocument, and useSuperDocCommand give you typed, memoized, per-slice state with one re-render per change instead of a manual superdoc.on('editor-update', ...) loop. See Custom UI.The events on this page are for lifecycle (ready, editor-create), integration (error, comment-changed), analytics, and compatibility with code that doesn’t use the React surface.

Subscribing to events

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

/** @param {import('superdoc').SuperDocReadyPayload} payload */
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.

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.

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.

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.

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. Use this to refresh live UI state like word counts or auto-save.

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

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

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

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

Live counter example: Read editor.doc.info() inside the handler to build a live document-stats panel without polling.

superdoc.on('editor-update', ({ editor }) => {
  const { counts } = editor.doc.info();
  document.getElementById('stats').textContent =
    `${counts.words} words, ${counts.characters} characters, ` +
    `${counts.trackedChanges} tracked changes, ${counts.lists} lists`;
});

`content-error`

When content processing fails.

superdoc.on('content-error', ({ error, editor }) => {
  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 }) => {
  console.error('Content error:', error);
});

`fonts-resolved`

When document fonts are resolved.

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

Content controls (SDT fields)

`content-control:active-change`

Fires when selection enters a content control, switches between controls, or leaves all controls.

superdoc.on('content-control:active-change', ({ active, previous, activePath, source }) => {
  // source: 'keyboard' | 'pointer'
  // active / previous: SdtRef | null
  // activePath: SdtRef[] - full active stack, innermost first ([] when none)
});

SdtRef shape:

type SdtRef = {
  id: string;
  tag?: string;
  alias?: string;
  controlType: string;
  scope: 'inline' | 'block';
};

active is the deepest control (activePath[0]); activePath holds the full stack, innermost first. Controls without an id do not emit these events. How to interpret:

Focus (null -> A): previous === null && active !== null
Switch (A -> B): previous !== null && active !== null && previous.id !== active.id
Blur (A -> null): previous !== null && active === null

`content-control:click`

Fires on pointer click inside a content control.

superdoc.on('content-control:click', ({ target, source }) => {
  // source is always 'pointer'
  // target: SdtRef
});

Both are also available as config callbacks: onContentControlActiveChange and onContentControlClick. To build your own content-control UI on these events, see Custom UI > Content controls.

Comments events

`comments-update`

When comments are modified.

superdoc.on('comments-update', ({ type, comment, changes, pendingSelection }) => {
  // type: 'pending', 'add', 'update', 'deleted', 'resolved'
  // comment: the comment object (when applicable)
  // changes: per-field change set (when the update is a mutation)
  // pendingSelection: SelectionInfo | null on 'pending'
});

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

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

superdoc.on('comments-update', ({ type, comment, changes, pendingSelection }) => {
  // type: 'pending', 'add', 'update', 'deleted', 'resolved'
  // comment: the comment object (when applicable)
  // changes: per-field change set (when the update is a mutation)
  // pendingSelection: SelectionInfo | null on 'pending'
});

Collaboration events

`collaboration-ready`

When collaboration is initialized.

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.

superdoc.on('awareness-update', ({ states, added, removed }) => {
  updateUserCursors(states);
});

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

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

superdoc.on('awareness-update', ({ states, added, removed }) => {
  updateUserCursors(states);
});

`locked`

When document lock state changes.

superdoc.on('locked', ({ isLocked, lockedBy }) => {
  if (isLocked && lockedBy) {
    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 && lockedBy) {
    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.

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

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

UI events

`zoomChange`

When the zoom level changes, from any source: setZoom(), the toolbar zoom control, or fit-width mode. The payload carries the value and the mode that produced it. Also available as the onZoomChange config callback.

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

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

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

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

`viewport-change`

When the fit-width calculation changes. Pixel-level width changes that do not affect the rounded fit are deduped. getViewportMetrics() always reads the latest measurements.

availableWidth - container width in pixels, minus the comments sidebar when visible
documentWidth - the widest document page width in pixels at 100% zoom (zoom-independent; DOCX from laid-out pages with page-styles fallback, PDF from rendered pages)
fitZoom - the unclamped zoom percentage that fits the page into the available width

HTML documents reflow to the container, so an HTML-only instance reports no metrics. For most use cases, prefer zoom.mode: 'fit-width'. Subscribe to this event only when you want to apply custom zoom behavior.

superdoc.on('viewport-change', ({ fitZoom }) => {
  superdoc.setZoom(Math.min(100, Math.max(35, fitZoom)));
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onViewportChange: ({ availableWidth, documentWidth, fitZoom }) => {
    console.log(`Need ${fitZoom}% to fit ${documentWidth}px into ${availableWidth}px`);
  },
});

When the comments sidebar is toggled.

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.

superdoc.on('exception', (payload) => {
  // `payload` is a discriminated union; narrow before reading variant-specific fields.
  // `code` is only on the editor-lifecycle variant; `stage` is only on document-init.
  console.error('SuperDoc error:', payload.error);
});

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

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

superdoc.on('exception', (payload) => {
  // `payload` is a discriminated union; narrow before reading variant-specific fields.
  // `code` is only on the editor-lifecycle variant; `stage` is only on document-init.
  console.error('SuperDoc error:', payload.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

editorBeforeCreate: Before editor mounts
editorCreate: Editor ready
ready: All editors ready
collaboration-ready: If collaboration enabled
pagination-update: After each layout pass (page count available)
Runtime events (editor-update, comments-update, sidebar-toggle, etc.)
editorDestroy: Cleanup

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Subscribing to events

Lifecycle events

`ready`

`editorBeforeCreate`

`editorCreate`

`editorDestroy`

Content events

`editor-update`

`content-error`

`fonts-resolved`

Content controls (SDT fields)

`content-control:active-change`

`content-control:click`

Comments events

`comments-update`

Collaboration events

`collaboration-ready`

`awareness-update`

`locked`

UI events

`zoomChange`

`viewport-change`

`sidebar-toggle`

Error events

`exception`

Configuration-based events

Event order

​Subscribing to events

​Lifecycle events

​ready

​editorBeforeCreate

​editorCreate

​editorDestroy

​Content events

​editor-update

​content-error

​fonts-resolved

​Content controls (SDT fields)

​content-control:active-change

​content-control:click

​Comments events

​comments-update

​Collaboration events

​collaboration-ready

​awareness-update

​locked

​Pagination events

​pagination-update

​UI events

​zoomChange

​viewport-change

​sidebar-toggle

​Error events

​exception

​Configuration-based events

​Event order

Subscribing to events

Lifecycle events

`ready`

`editorBeforeCreate`

`editorCreate`

`editorDestroy`

Content events

`editor-update`

`content-error`

`fonts-resolved`

Content controls (SDT fields)

`content-control:active-change`

`content-control:click`

Comments events

`comments-update`

Collaboration events

`collaboration-ready`

`awareness-update`

`locked`

Pagination events

`pagination-update`

UI events

`zoomChange`

`viewport-change`

`sidebar-toggle`

Error events

`exception`

Configuration-based events

Event order