> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-sd-docs-snippet-typecheck-2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

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

## Quick start

```javascript theme={null}
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

<ParamField path="source" type="string | File | Blob | Buffer">
  The document source. Can be a file path (Node.js), File/Blob (browser), or Buffer.

  ```javascript theme={null}
  // 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();
  ```
</ParamField>

<ParamField path="element" type="HTMLElement">
  DOM element where the editor will mount. If omitted, the editor runs in headless mode.

  ```javascript theme={null}
  element: document.getElementById("editor");
  ```
</ParamField>

<ParamField path="documentId" type="string">
  Unique identifier for this document instance. Used for collaboration and
  storage. Auto-generated if not provided.
</ParamField>

<ParamField path="extensions" type="Array<Extension>">
  Extensions that define the editor schema and functionality. If omitted, `Editor.open()` uses sensible defaults (`getStarterExtensions()` for DOCX, `getRichTextExtensions()` for text/HTML).

  ```javascript theme={null}
  import { getStarterExtensions } from "superdoc/super-editor";

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

## Modes & permissions

<ParamField path="mode" type="string" default="'docx'">
  Editor rendering mode

  <Expandable title="Available modes">
    * `docx` - Full DOCX features
    * `text` - Plain text mode
    * `html` - HTML mode
  </Expandable>
</ParamField>

<ParamField path="documentMode" type="string" default="'editing'">
  Current editing state

  <Expandable title="Document modes">
    * `editing` - Full editing capabilities
    * `viewing` - Read-only mode
    * `suggesting` - Track changes enabled
  </Expandable>
</ParamField>

<ParamField path="role" type="string" default="'editor'">
  User permission level. Overrides documentMode when more restrictive.

  <Note>Role always wins over documentMode in permission conflicts</Note>
</ParamField>

<ParamField path="editable" type="boolean" default="true">
  Whether the editor accepts input
</ParamField>

## User & collaboration

<ParamField path="user" type="Object">
  Current user information

  <Expandable title="User properties">
    <ParamField path="name" type="string" required>
      Display name
    </ParamField>

    <ParamField path="email" type="string" required>
      Email address
    </ParamField>

    <ParamField path="image" type="string">
      Avatar URL
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="users" type="Array<User>" default="[]">
  All users with document access. Used for @mentions and awareness.
</ParamField>

<ParamField path="ydoc" type="Y.Doc">
  Yjs document for real-time collaboration
</ParamField>

<ParamField path="collaborationProvider" type="HocuspocusProvider">
  Provider instance for collaboration sync
</ParamField>

## Content initialization

<ParamField path="html" type="string">
  Initialize with HTML content (for `mode: 'html'`)
</ParamField>

<ParamField path="markdown" type="string">
  Initialize with Markdown (converts to document)
</ParamField>

<ParamField path="json" type="Object">
  Use ProseMirror JSON content instead of DOCX parsing
</ParamField>

<ParamField path="onUnsupportedContent" type="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.

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

<ParamField path="warnOnUnsupportedContent" type="boolean" default="false">
  Log a `console.warn` listing HTML elements dropped during import. Ignored when `onUnsupportedContent` is provided.
</ParamField>

## Features

<ParamField path="isCommentsEnabled" type="boolean" default="false">
  Enable comments system
</ParamField>

<ParamField path="annotations" type="boolean" default="false">
  Enable field annotations
</ParamField>

<ParamField path="pagination" type="boolean" default="false">
  Enable page-based layout
</ParamField>

## Advanced options

<ParamField path="isHeadless" type="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()`.
</ParamField>

<ParamField path="document" type="Document">
  DOM Document for serialization in headless mode (e.g., `window.document` from JSDOM).
</ParamField>

<ParamField path="fragment" type="YXmlFragment">
  Y.Doc XML fragment for collaborative document content. Use with headless mode to read Y.Doc content.
</ParamField>

<ParamField path="handleImageUpload" type="function">
  Custom image upload handler

  ```javascript theme={null}
  handleImageUpload: async (file) => {
    const url = await uploadToS3(file);
    return url;
  };
  ```
</ParamField>

## Configuration patterns

### Full DOCX editor

```javascript theme={null}
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.

<Info>
  See the [server-side AI redlining example](https://github.com/superdoc-dev/superdoc/tree/main/examples/document-engine/ai-redlining)
  for a complete implementation.
</Info>

```javascript theme={null}
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.

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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
import { Editor } from "superdoc/super-editor";

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