Skip to main content
SuperEditor configuration gives you low-level control over the DOCX engine.

​
Quick Start

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

// Parse DOCX file first
const [content, media, mediaFiles, fonts] = await Editor.loadXmlData(docxFile);

// Create editor
const editor = new Editor({
  mode: "docx",
  documentMode: "editing",
  element: document.getElementById("editor"),
  documentId: "doc-123",
  extensions: getStarterExtensions(),
  fileSource: docxFile,
  content,
  media,
  mediaFiles,
  fonts,
});

​
Required Parameters

​
element
HTMLElement
required
DOM element where the editor will mount
element: document.getElementById("editor");
​
documentId
string
required
Unique identifier for this document instance. Used for collaboration and storage.
​
extensions
Array<Extension>
required
Extensions that define the editor schema and functionality.
import { getStarterExtensions } from "superdoc/super-editor";

extensions: getStarterExtensions();

​
DOCX Mode Parameters

​
fileSource
File | Blob
required
The DOCX file to load
​
content
Object
required
Parsed XML content from Editor.loadXmlData()
​
media
Object
default:"{}"
Media file mappings from Editor.loadXmlData()
​
mediaFiles
Object
default:"{}"
Media blob data from Editor.loadXmlData()
​
fonts
Object
default:"{}"
Font configuration from Editor.loadXmlData()

​
Modes & Permissions

​
mode
string
default:"'docx'"
Editor rendering mode
​
documentMode
string
default:"'editing'"
Current editing state
​
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
​
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)
​
jsonOverride
Object
Use ProseMirror JSON content instead of DOCX parsing

​
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). You must provide document from JSDOM for serialization methods like getHTML().
​
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.
​
mockDocument
Document
deprecated
Deprecated. Use document instead.
​
mockWindow
Window
deprecated
Deprecated. No longer required — just pass document.
​
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, getStarterExtensions } from "superdoc/super-editor";

async function createDocxEditor(docxFile) {
  const [content, media, mediaFiles, fonts] = await Editor.loadXmlData(
    docxFile
  );

  return new Editor({
    mode: "docx",
    documentMode: "editing",
    element: document.getElementById("editor"),
    documentId: "doc-123",
    extensions: getStarterExtensions(),
    fileSource: docxFile,
    content,
    media,
    mediaFiles,
    fonts,
    user: { name: "John", email: "[email protected]" },
  });
}

​
Headless Converter (Node.js)

Convert DOCX files server-side without a browser using JSDOM.
See the headless-converter example for a complete implementation.
import { readFile } from "fs/promises";
import { JSDOM } from "jsdom";
import { Editor, getStarterExtensions } from "superdoc/super-editor";

const { window } = new JSDOM("<!DOCTYPE html><html><body></body></html>");
const { document } = window;

// Pass `true` as second arg for Node.js
const buffer = await readFile("document.docx");
const [content, media, mediaFiles, fonts] = await Editor.loadXmlData(
  buffer,
  true
);

const editor = new Editor({
  mode: "docx",
  documentId: "headless",
  element: document.createElement("div"),
  extensions: getStarterExtensions(),
  fileSource: buffer,
  content,
  media,
  mediaFiles,
  fonts,
  isHeadless: true,
  mockDocument: document,
  mockWindow: window,
});

// 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 isHeadless: true, methods like getHTML() need a DOM for serialization. Always set up JSDOM first.
import { JSDOM } from "jsdom";
import { Editor, getStarterExtensions } from "superdoc/super-editor";

// Set up JSDOM
const { window } = new JSDOM("<!DOCTYPE html><html><body></body></html>");

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

const editor = new Editor({
  mode: "docx",
  isHeadless: true,
  document: window.document,
  extensions: getStarterExtensions(),
  fragment, // YXmlFragment from Y.Doc
});

const html = editor.getHTML();
editor.destroy();
The document option replaces the deprecated mockDocument and mockWindow options.

​
Custom Collaboration

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

const [content, media, mediaFiles, fonts] = await Editor.loadXmlData(docxFile);

const editor = new Editor({
  mode: "docx",
  documentMode: "editing",
  element: document.getElementById("editor"),
  documentId: roomId,
  extensions: getStarterExtensions(),
  fileSource: docxFile,
  content,
  media,
  mediaFiles,
  fonts,
  ydoc: new Y.Doc(),
  collaborationProvider: new HocuspocusProvider({
    url: "wss://collab.example.com",
    name: roomId,
  }),
  user: currentUser,
  users: roomUsers,
});

​
Track Changes Mode

const [content, media, mediaFiles, fonts] = await Editor.loadXmlData(docxFile);

const editor = new Editor({
  mode: "docx",
  documentMode: "suggesting",
  element: document.getElementById("editor"),
  documentId: "review-doc",
  extensions: getStarterExtensions(),
  fileSource: docxFile,
  content,
  media,
  mediaFiles,
  fonts,
  user: reviewer,
});