Configuration

SuperEditor configuration gives you low-level control over the DOCX engine.

Quick start

import "superdoc/style.css";
import { Editor } from "superdoc/super-editor";

const editor = await Editor.open(docxFile, {
  element: document.getElementById("editor"),
  documentMode: "editing",
});

Editor.open() is the recommended way to create an editor. It handles DOCX parsing, extension setup, and mounting automatically.

Required parameters

source · string | File | Blob | Buffer

The document source. Can be a file path (Node.js), File/Blob (browser), or Buffer.

// Browser
const editor = await Editor.open(file, { element: el });

// Node.js
const editor = await Editor.open('/path/to/doc.docx');

// Blank document
const editor = await Editor.open();

element · HTMLElement

DOM element where the editor will mount. If omitted, the editor runs in headless mode.

element: document.getElementById("editor");

documentId · string

Unique identifier for this document instance. Used for collaboration and storage. Auto-generated if not provided.

extensions · Array<Extension>

Extensions that define the editor schema and functionality. If omitted, Editor.open() uses sensible defaults (getStarterExtensions() for DOCX, getRichTextExtensions() for text/HTML).

import { getStarterExtensions } from "superdoc/super-editor";

const editor = await Editor.open(file, {
  element: el,
  extensions: getStarterExtensions(), // explicit, but also the default for DOCX
});

Modes & permissions

mode · string · default: "'docx'"

Editor rendering mode

Show Available modes

• docx - Full DOCX features
• text - Plain text mode
• html - HTML mode

documentMode · string · default: "'editing'"

Current editing state

Show Document modes

• editing - Full editing capabilities
• viewing - Read-only mode
• suggesting - Track changes enabled

role · string · default: "'editor'"

User permission level. Overrides documentMode when more restrictive.

Role always wins over documentMode in permission conflicts

editable · boolean · default: "true"

Whether the editor accepts input

User & collaboration

user · Object

Current user information

Show User properties

name · string · required

Display name

email · string · required

Email address

image · string

Avatar URL

users · Array<User> · default: "[]"

All users with document access. Used for @mentions and awareness.

ydoc · Y.Doc

Yjs document for real-time collaboration

collaborationProvider · HocuspocusProvider

Provider instance for collaboration sync

Content initialization

html · string

Initialize with HTML content (for mode: 'html')

markdown · string

Initialize with Markdown (converts to document)

json · Object

Use ProseMirror JSON content instead of DOCX parsing

onUnsupportedContent · function

Callback invoked with HTML elements that were dropped during import because they have no schema representation. Receives an array of { tagName, outerHTML, count } items. When provided, console.warn is suppressed.

onUnsupportedContent: (items) => {
  items.forEach(({ tagName, count }) => {
    console.log(`Dropped ${count}x <${tagName}>`);
  });
}

warnOnUnsupportedContent · boolean · default: "false"

Log a console.warn listing HTML elements dropped during import. Ignored when onUnsupportedContent is provided.

Features

isCommentsEnabled · boolean · default: "false"

Enable comments system

annotations · boolean · default: "false"

Enable field annotations

pagination · boolean · default: "false"

Enable page-based layout

Advanced options

isHeadless · boolean · default: "false"

Run without mounting an editor view (Node.js/server-side processing). Automatically set to true when no element is provided to Editor.open().

document · Document

DOM Document for serialization in headless mode (e.g., window.document from JSDOM).

fragment · YXmlFragment

Y.Doc XML fragment for collaborative document content. Use with headless mode to read Y.Doc content.

handleImageUpload · function

Custom image upload handler

handleImageUpload: async (file) => {
  const url = await uploadToS3(file);
  return url;
};

Configuration patterns

Full DOCX editor

import "superdoc/style.css";
import { Editor } from "superdoc/super-editor";

const editor = await Editor.open(docxFile, {
  element: document.getElementById("editor"),
  documentMode: "editing",
  user: { name: "John", email: "[e-mail]" },
});

Headless converter (Node.js)

Convert DOCX files server-side without a browser using JSDOM.

See the headless example for a complete implementation.

import { readFile } from "fs/promises";
import { Editor } from "superdoc/super-editor";

const buffer = await readFile("document.docx");
const editor = await Editor.open(buffer);

// Output formats
const html = editor.getHTML();
const json = editor.getJSON();
const text = editor.state.doc.textContent;
const markdown = await editor.getMarkdown();

editor.destroy();

Headless Y.Doc to HTML (collaboration)

Read content from a collaborative Y.Doc in your backend — useful for AI agents or APIs that need to access document content without a browser.

Even with headless mode, methods like getHTML() need a DOM for serialization. JSDOM is set up automatically in Node.js when using Editor.open().

import { Editor, getStarterExtensions } from "superdoc/super-editor";

// Get the YXmlFragment from your Y.Doc
const fragment = ydoc.getXmlFragment("prosemirror");

const editor = new Editor({
  mode: "docx",
  isHeadless: true,
  extensions: getStarterExtensions(),
  fragment,
});

const html = editor.getHTML();
editor.destroy();

Custom collaboration

import { Editor } from "superdoc/super-editor";
import * as Y from "yjs";
import { HocuspocusProvider } from "@hocuspocus/provider";

const editor = await Editor.open(docxFile, {
  element: document.getElementById("editor"),
  documentMode: "editing",
  ydoc: new Y.Doc(),
  collaborationProvider: new HocuspocusProvider({
    url: "wss://collab.example.com",
    name: roomId,
  }),
  user: currentUser,
  users: roomUsers,
});

Track changes mode

import { Editor } from "superdoc/super-editor";

const editor = await Editor.open(docxFile, {
  element: document.getElementById("editor"),
  documentMode: "suggesting",
  user: reviewer,
});