Methods - SuperDoc

Methods are functions you call on the SuperDoc instance to perform actions.

Document operations

`export`

Export the document with various options.

Object

Export configuration

Hide properties

string[]

default:"['docx']"

Export formats

boolean

default:"false"

Replace fields with values

string

default:"'external'"

Comment handling: ‘external’, ‘clean’, or custom

string

default:"'document'"

Base filename

boolean

default:"true"

Automatically trigger a browser file download. Set to false to get a Blob back without downloading.

string

default:"'#FFFF00'"

Field highlight color

Returns: Promise<Blob> - Document blob

const blob = await superdoc.export({
  isFinalDoc: true,
  commentsType: 'clean',
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: async ({ superdoc }) => {
    const blob = await superdoc.export({
      isFinalDoc: true,
      commentsType: 'clean',
    });
  },
});

`save`

Save document if in collaboration mode. Returns: Promise<void>

await superdoc.save();

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: async ({ superdoc }) => {
    await superdoc.save();
  },
});

`getHTML`

Get HTML content of all editors.

Object

HTML options

Show properties

boolean

default:"false"

Preserve nested list structure

Returns: string[] - Array of HTML strings, one per editor

const htmlArray = superdoc.getHTML();

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    const htmlArray = superdoc.getHTML();
    console.log(htmlArray);
  },
});

Collaboration methods

`upgradeToCollaboration`

Promote a local SuperDoc instance into collaboration without creating a new instance.

This is a promotion flow, not a passive join flow. SuperDoc seeds the target room with the current local document state, comments, and lock state.

Object

required

Upgrade configuration

Hide properties

Y.Doc

required

The Yjs document for the target room

Object

required

The collaboration provider connected to the same room as ydoc

Returns: Promise<void> Requirements:

The SuperDoc instance must already be ready
The instance must not already be collaborative
The current instance must contain a single DOCX document
You must provide a matching { ydoc, provider } pair

SuperDoc waits for provider sync internally. You do not need to wait for the provider’s sync event before calling this method.

await superdoc.upgradeToCollaboration({ ydoc, provider });

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  user: {
    name: 'John Smith',
    email: 'john@example.com',
  },
});

superdoc.on('ready', async () => {
  const ydoc = new Y.Doc();
  const provider = new WebsocketProvider('wss://collab.example.com', 'document-123', ydoc);

  await superdoc.upgradeToCollaboration({ ydoc, provider });
});

See Upgrade to Collaboration for the full workflow guide.

Mode control

`setDocumentMode`

Change the document mode.

string

required

New document mode

Show Available modes

'viewing' - Read-only
'suggesting' - Track changes
'editing' - Normal editing

superdoc.setDocumentMode('suggesting');

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.setDocumentMode('suggesting');
  },
});

`lockSuperdoc`

Lock or unlock the document.

boolean

required

Lock state

User

User who locked the document

superdoc.lockSuperdoc(true, currentUser);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.lockSuperdoc(true, {
      name: 'Jane Smith',
      email: 'jane@example.com',
    });
  },
});

`setHighContrastMode`

Enable/disable high contrast mode.

boolean

required

High contrast state

superdoc.setHighContrastMode(true);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.setHighContrastMode(true);
  },
});

UI methods

`setActiveEditor`

Set which editor is currently active. Useful when working with multiple documents.

Editor

required

Editor instance to set as active

superdoc.setActiveEditor(editor);

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

/** @type {Array<import('superdoc').Editor>} */
const createdEditors = [];

const superdoc = new SuperDoc({
  selector: '#editor',
  documents: [doc1, doc2],
  onEditorCreate: ({ editor }) => {
    // Each per-document editor reaches `onEditorCreate` in `documents` order.
    createdEditors.push(editor);

    // Switch to the second editor as soon as it exists.
    if (createdEditors.length === 2) {
      queueMicrotask(() => {
        superdoc.setActiveEditor(editor);
      });
    }
  },
});

`setDisableContextMenu`

Toggle the custom context menu at runtime.

boolean

default:"true"

Whether to disable the context menu

superdoc.setDisableContextMenu(true);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.setDisableContextMenu(true);
  },
});

`openSurface`

Open a dialog or floating surface above the document. Returns: SurfaceHandle

Object

required

Surface request. Set mode to 'dialog' or 'floating', then provide content via render (framework-agnostic) or component (Vue). See Surfaces for the full request shape.

const handle = superdoc.openSurface({
  mode: 'floating',
  title: 'Find',
  floating: { placement: 'top-right', width: 360 },
  render: ({ container }) => {
    container.innerHTML = '<input placeholder="Find..." style="width:100%" />';
  },
});

const handle = superdoc.openSurface({
  mode: 'dialog',
  title: 'Confirm action',
  render: ({ container, close }) => {
    container.innerHTML = '<button type="button">Close</button>';
    container.querySelector('button')?.addEventListener('click', () => close('manual-close'));
  },
});

const outcome = await handle.result;
console.log(outcome.status);

See Surfaces for the full request shape, Vue/React examples, and resolver-based usage.

`closeSurface`

Close a specific surface by id, or the topmost active surface when no id is provided. When both a dialog and a floating surface are open, the dialog closes first.

superdoc.closeSurface();

const handle = superdoc.openSurface({
  mode: 'floating',
  title: 'Find',
  render: ({ container }) => {
    container.innerHTML = '<input placeholder="Find..." style="width:100%" />';
  },
});

superdoc.closeSurface(handle.id);

See Surfaces for lifecycle behavior and close ordering.

`setTrackedChangesPreferences`

Override how tracked changes are rendered in the layout engine.

Object

Hide properties

string

Rendering mode: 'review', 'original', 'final', or 'off'

boolean

Whether tracked change metadata is included

superdoc.setTrackedChangesPreferences({ mode: 'final' });

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.setTrackedChangesPreferences({ mode: 'final' });
  },
});

`toggleRuler`

Toggle ruler visibility.

superdoc.toggleRuler();

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

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

string

deprecated

Removed in v1.0: Pagination is now handled by the layout engine. Use viewOptions.layout in configuration instead.

`getZoom`

Get the current zoom level as a percentage. Returns: number - Current zoom level (e.g., 100, 150, 200). Defaults to 100.

const zoom = superdoc.getZoom();

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    const zoom = superdoc.getZoom();
    console.log(`Current zoom: ${zoom}%`);
  },
});

`setZoom`

Set the zoom level for all documents. Propagates to all presentation editors, PDF viewers, and whiteboard layers.

number

required

Zoom level as a percentage (e.g., 100, 150, 200). Must be a positive finite number.

superdoc.setZoom(150);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.setZoom(150);

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

`focus`

Focus the active editor or first available.

superdoc.focus();

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

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

Search methods

`search`

Search for text or regex in active editor.

string | RegExp

required

Search query

Returns: Array<SearchResult> - Search matches

const results = superdoc.search('contract');
const regexResults = superdoc.search(/section \d+/gi);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    const results = superdoc.search('contract');
    if (results) {
      console.log(`Found ${results.length} matches`);
    }

    const regexResults = superdoc.search(/section \d+/gi);
  },
});

`goToSearchResult`

Navigate to a search result.

SearchResult

required

Search result to navigate to

superdoc.goToSearchResult(results[0]);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    const results = superdoc.search('contract');
    if (results && results.length) {
      superdoc.goToSearchResult(results[0]);
    }
  },
});

Comments methods

addCommentsList and removeCommentsList mount the built-in comments sidebar. For custom React UI, render your own panel from useSuperDocComments instead: see Custom UI › Comments. The methods below stay supported for apps using the built-in sidebar.

`addCommentsList`

Add a comments list to the specified element.

HTMLElement

required

Container element for the comments list

const sidebar = document.getElementById('comments-sidebar');
if (sidebar) superdoc.addCommentsList(sidebar);

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    const sidebar = document.getElementById('comments-sidebar');
    if (sidebar) superdoc.addCommentsList(sidebar);
  },
});

`removeCommentsList`

Remove the comments list.

superdoc.removeCommentsList();

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

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

`scrollToComment`

Scroll to a comment in the document and set it as active.

string

required

The comment ID to scroll to

object

Scroll behavior options

Show child attributes

ScrollBehavior

default:"smooth"

Scroll behavior: "smooth", "instant", or "auto"

ScrollLogicalPosition

default:"start"

Vertical alignment: "start", "center", "end", or "nearest"

Returns: boolean: true if the comment was found, false otherwise.

// Get a comment ID from the document API
const editor = superdoc.activeEditor;
if (editor) {
  const { items } = editor.doc.comments.list();
  if (items.length > 0) superdoc.scrollToComment(items[0].id);
}

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  modules: { comments: {} },
  onReady: ({ superdoc }) => {
    const editor = superdoc.activeEditor;
    if (!editor) return;
    const { items } = editor.doc.comments.list();
    if (items.length > 0) {
      superdoc.scrollToComment(items[0].id, {
        behavior: 'smooth',
        block: 'center',
      });
    }
  },
});

`scrollToElement`

Scroll to any document element by its ID. Pass a paragraph nodeId, comment entityId, or tracked change entityId: the method figures out what kind of element it is and scrolls there.

string

required

The element’s stable ID. Get this from query.match results (address.nodeId), comments.list (entityId), or trackChanges.list (entityId).

Returns: Promise<boolean>: true if the element was found and scrolled to, false otherwise. Never throws.

// Get a paragraph's nodeId from the Document API
const result = editor.doc.query.match({
  select: { type: 'text', pattern: 'Introduction', mode: 'contains' },
  require: 'first',
});
const first = result.items[0];
if (first && first.address.kind === 'block') {
  await superdoc.scrollToElement(first.address.nodeId);
}

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  modules: { comments: {} },
  onReady: async ({ superdoc }) => {
    const editor = superdoc.activeEditor;
    if (!editor) return;

    // Navigate to a paragraph (block addresses carry `nodeId`; narrow first)
    const match = editor.doc.query.match({
      select: { type: 'text', pattern: 'Summary', mode: 'contains' },
      require: 'first',
    });
    const first = match.items[0];
    if (first && first.address.kind === 'block') {
      await superdoc.scrollToElement(first.address.nodeId);
    }

    // Navigate to a comment
    const comments = editor.doc.comments.list();
    if (comments.items.length > 0) {
      await superdoc.scrollToElement(comments.items[0].id);
    }

    // Navigate to a tracked change
    const changes = editor.doc.trackChanges.list();
    if (changes.items.length > 0) {
      await superdoc.scrollToElement(changes.items[0].id);
    }
  },
});

For DOCX-imported documents, paragraph nodeId values come from the OOXML paraId attribute and are stable across sessions. See cross-session block addressing for the full pattern.

User management

`addSharedUser`

Add a user to the shared users list.

User

required

User to add

Show User properties

string

required

Display name

string

required

Email address

superdoc.addSharedUser({
  name: 'Jane Smith',
  email: 'jane@example.com',
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.addSharedUser({
      name: 'Jane Smith',
      email: 'jane@example.com',
    });
  },
});

`removeSharedUser`

Remove a user from shared users.

string

required

Email of user to remove

superdoc.removeSharedUser('jane@example.com');

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    superdoc.removeSharedUser('jane@example.com');
  },
});

Lifecycle

`destroy`

Completely destroy the SuperDoc instance.

This is irreversible. Cleans up all resources, events, and DOM.

superdoc.destroy();

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

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

// Later, when you're done with the editor:
superdoc.destroy();

Event methods

`on`

Subscribe to an event.

superdoc.on('ready', ({ superdoc }) => {
  console.log('SuperDoc ready');
});

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

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

superdoc.on('ready', ({ superdoc }) => {
  console.log('SuperDoc ready');
});

`once`

Subscribe to an event once.

superdoc.once('ready', () => {
  // Only called once
});

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

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

superdoc.once('ready', () => {
  console.log('SuperDoc ready (one-time)');
});

`off`

Unsubscribe from an event.

superdoc.off('ready', handler);

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

superdoc.on('ready', handler);

// Later, unsubscribe:
superdoc.off('ready', handler);

Schema introspection

`getSchemaIntrospection`

Returns a JSON schema summary with all nodes, marks, and their attributes. Useful for AI agents that need schema context.

import { getSchemaIntrospection } from 'superdoc';

const schema = await getSchemaIntrospection({ mode: 'docx' });
// Returns: { version, nodes: [...], marks: [...] }

Object

Show properties

Editor

Existing Editor instance to introspect. If provided, uses this instead of creating a temporary editor.

Array

Custom extensions to use when building the schema.

string

default:"'docx'"

Editor mode: 'docx', 'html', or 'text'

TypeScript types

SuperDoc exports TypeScript interfaces for all node and mark types:

import type { NodeName, NodeAttrs, ParagraphAttrs } from 'superdoc/types';

// NodeName shows all 39 node types in autocomplete
type Test = NodeAttrs<'paragraph'>; // Resolves to ParagraphAttrs

Available types: NodeName, NodeAttrs<N>, MarkName, MarkAttrs<M>, and specific interfaces like ParagraphAttrs, TableAttrs, ImageAttrs, etc.

Properties

`activeEditor`

Currently active editor instance. Returns null before the ready event.

if (superdoc.activeEditor) {
  superdoc.activeEditor.commands.toggleBold();
}

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  onReady: ({ superdoc }) => {
    if (superdoc.activeEditor) {
      superdoc.activeEditor.commands.toggleBold();
    }
  },
});

Always check for null before accessing.

For new code, prefer the typed surfaces. superdoc.activeEditor.commands.X() is the chain-command path; it stays supported for backwards compatibility but isn’t the recommended starting point. Use editor.doc.* for document mutations (insert, replace, format, comments, tracked changes) and ui.commands.* for React UI dispatch (typed, memoized per command).

Property	Type	Description
`superdocId`	`string`	Unique identifier for this instance
`version`	`string`	SuperDoc version number
`activeEditor`	`Editor \| null`	Currently active editor
`element`	`HTMLElement \| null`	Container DOM element
`state`	`{ documents, users }`	Current state snapshot
`isLocked`	`boolean`	Whether the document is locked
`lockedBy`	`User \| null`	User who locked the document
`isCollaborative`	`boolean`	Whether collaboration is enabled
`user`	`User`	Current user information
`users`	`User[]`	All users with document access
`toolbar`	`Toolbar \| null`	Toolbar instance if configured

​Document operations

​export

​save

​getHTML

​Collaboration methods

​upgradeToCollaboration

​Mode control

​setDocumentMode

​lockSuperdoc

​setHighContrastMode

​UI methods

​setActiveEditor

​setDisableContextMenu

​openSurface

​closeSurface

​setTrackedChangesPreferences

​toggleRuler

​getZoom

​setZoom

​focus

​Search methods

​search

​goToSearchResult

​Comments methods

​addCommentsList

​removeCommentsList

​scrollToComment

​scrollToElement

​User management

​addSharedUser

​removeSharedUser

​Lifecycle

​destroy

​Event methods

​on

​once

​off

​Schema introspection

​getSchemaIntrospection

​TypeScript types

​Properties

​activeEditor

Document operations

`export`

`save`

`getHTML`

Collaboration methods

`upgradeToCollaboration`

Mode control

`setDocumentMode`

`lockSuperdoc`

`setHighContrastMode`

UI methods

`setActiveEditor`

`setDisableContextMenu`

`openSurface`

`closeSurface`

`setTrackedChangesPreferences`

`toggleRuler`

`getZoom`

`setZoom`

`focus`

Search methods

`search`

`goToSearchResult`

Comments methods

`addCommentsList`

`removeCommentsList`

`scrollToComment`

`scrollToElement`

User management

`addSharedUser`

`removeSharedUser`

Lifecycle

`destroy`

Event methods

`on`

`once`

`off`

Schema introspection

`getSchemaIntrospection`

TypeScript types

Properties

`activeEditor`