Methods - SuperDoc

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

Document operations

`export`

Export the document with various options.

options

Object

Export configuration

Hide properties

exportType

string[]

default:"['docx']"

Export formats

isFinalDoc

boolean

default:"false"

Replace fields with values

commentsType

string

default:"'external'"

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

exportedName

string

default:"'document'"

Base filename

triggerDownload

boolean

default:"true"

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

fieldsHighlightColor

string

default:"'#FFFF00'"

Field highlight color

Returns: Promise<Blob> - Document blob

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

`save`

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

await superdoc.save();

`getHTML`

Get HTML content of all editors.

options

Object

HTML options

Show properties

unflattenLists

boolean

default:"false"

Preserve nested list structure

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

const htmlArray = superdoc.getHTML();

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.

options

Object

required

Upgrade configuration

Hide properties

ydoc

Y.Doc

required

The Yjs document for the target room

provider

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

See Upgrade to Collaboration for the full workflow guide.

Mode control

`setDocumentMode`

Change the document mode.

mode

string

required

New document mode

Show Available modes

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

superdoc.setDocumentMode('suggesting');

`lockSuperdoc`

Lock or unlock the document.

isLocked

boolean

required

Lock state

lockedBy

User

User who locked the document

superdoc.lockSuperdoc(true, currentUser);

`setHighContrastMode`

Enable/disable high contrast mode.

enabled

boolean

required

High contrast state

superdoc.setHighContrastMode(true);

UI methods

`setActiveEditor`

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

editor

Editor

required

Editor instance to set as active

superdoc.setActiveEditor(editor);

`setDisableContextMenu`

Toggle the custom context menu at runtime.

disabled

boolean

default:"true"

Whether to disable the context menu

superdoc.setDisableContextMenu(true);

`openSurface`

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

request

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%" />';
  },
});

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

See Surfaces for lifecycle behavior and close ordering.

`setTrackedChangesPreferences`

Override how tracked changes are rendered in the layout engine.

preferences

Object

Hide properties

mode

string

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

enabled

boolean

Whether tracked change metadata is included

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

`toggleRuler`

Toggle ruler visibility.

superdoc.toggleRuler();

togglePagination

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

`setZoom`

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

percent

number

required

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

superdoc.setZoom(150);

`focus`

Focus the active editor or first available.

superdoc.focus();

Search methods

`search`

Search for text or regex in active editor.

query

string | RegExp

required

Search query

Returns: Array<SearchResult> - Search matches

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

`goToSearchResult`

Navigate to a search result.

match

SearchResult

required

Search result to navigate to

superdoc.goToSearchResult(results[0]);

Comments methods

`addCommentsList`

Add a comments list to the specified element.

element

string | HTMLElement

required

Container for comments list

superdoc.addCommentsList('#comments-sidebar');

`removeCommentsList`

Remove the comments list.

superdoc.removeCommentsList();

`scrollToComment`

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

commentId

string

required

The comment ID to scroll to

options

object

Scroll behavior options

Show child attributes

behavior

ScrollBehavior

default:"smooth"

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

block

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 { items } = superdoc.editor.doc.comments.list();
const commentId = items[0].id;

// Scroll to it
superdoc.scrollToComment(commentId);

`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.

elementId

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 nodeId = result.items[0].address.nodeId;

// Scroll to it — one call, any element type
await superdoc.scrollToElement(nodeId);

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

User

required

User to add

Show User properties

name

string

required

Display name

string

required

Email address

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

Lifecycle

`destroy`

Completely destroy the SuperDoc instance.

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

superdoc.destroy();

Event methods

`on`

Subscribe to an event.

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

`once`

Subscribe to an event once.

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

`off`

Unsubscribe from an event.

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: [...] }

options

Object

Show properties

editor

Editor

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

extensions

Array

Custom extensions to use when building the schema.

mode

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

Always check for null before accessing.

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

Getting Started

Core

Document Engine

AI

Modules

Solutions

Guides

Resources

​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`