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

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

HTMLElement

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

element: document.getElementById("editor");

string

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

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

string

default:"'docx'"

Editor rendering mode

Show Available modes

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

string

default:"'editing'"

Current editing state

Show Document modes

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

string

default:"'editor'"

User permission level. Overrides documentMode when more restrictive.

Role always wins over documentMode in permission conflicts

boolean

default:"true"

Whether the editor accepts input

User & collaboration

Object

Current user information

Show User properties

string

required

Display name

string

required

Email address

string

Avatar URL

Array<User>

default:"[]"

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

Y.Doc

Yjs document for real-time collaboration

HocuspocusProvider

Provider instance for collaboration sync

Content initialization

string

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

string

Initialize with Markdown (converts to document)

Object

Use ProseMirror JSON content instead of DOCX parsing

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

boolean

default:"false"

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

Features

boolean

default:"false"

Enable comments system

boolean

default:"false"

Enable field annotations

boolean

default:"false"

Enable page-based layout

Advanced options

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

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

YXmlFragment

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

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: "john@example.com" },
});

Headless converter (Node.js)

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

See the server-side AI redlining 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,
});

Getting Started

Editor

Document Engine

AI

Solutions

Resources

Quick start

Required parameters

Modes & permissions

User & collaboration

Content initialization

Features

Advanced options

Configuration patterns

Full DOCX editor

Headless converter (Node.js)

Headless Y.Doc to HTML (collaboration)

Custom collaboration

Track changes mode

​Quick start

​Required parameters

​Modes & permissions

​User & collaboration

​Content initialization

​Features

​Advanced options

​Configuration patterns

​Full DOCX editor

​Headless converter (Node.js)

​Headless Y.Doc to HTML (collaboration)

​Custom collaboration

​Track changes mode

Quick start

Required parameters

Modes & permissions

User & collaboration

Content initialization

Features

Advanced options

Configuration patterns

Full DOCX editor

Headless converter (Node.js)

Headless Y.Doc to HTML (collaboration)

Custom collaboration

Track changes mode