Comments

Add Word-style commenting to documents with threaded discussions, replies, and resolution workflows.

Quick start

const superdoc = new SuperDoc({
  selector: "#editor",
  document: "contract.docx",
  user: {
    name: "John Smith",
    email: "john@company.com",
  },
  modules: {
    comments: {
      allowResolve: true,
      element: "#comments",
    },
  },
  onCommentsUpdate: ({ type, comment }) => {
    console.log("Comment event:", type);
  },
});

The comments module is enabled by default. To disable it entirely, set modules.comments to false:

modules: {
  comments: false;
}

Configuration

boolean

default:"false"

View-only mode, prevents new comments

boolean

default:"true"

Allow marking comments as resolved

string | HTMLElement

Container for comments sidebar

boolean

default:"false"

Enable dual internal/external comment system

boolean

default:"false"

Hide internal comments from view

boolean

default:"false"

Show resolved comments in the comments list

function

Comments-only override for permission checks. See Permission Resolver.

Object

Custom colors for comment highlights.

Show Properties

string

default:"#B1124B"

Highlight color for external comments

string

default:"#078383"

Highlight color for internal comments

string

Active highlight color override for external comments

string

Active highlight color override for internal comments

Object

Opacity values for comment highlights (0–1).

Show Properties

number

Opacity for the active comment highlight

number

Opacity for inactive comment highlights

string

Hover highlight color for comment marks

Object

Colors for tracked change highlights.

Show Properties

string

Border color for inserted text

string

Background color for inserted text

string

Border color for deleted text

string

Background color for deleted text

string

Border color for format changes

Object

Colors for the active tracked change highlight. Same properties as trackChangeHighlightColors. Defaults to trackChangeHighlightColors values when not set.

Viewing mode visibility

Comments are hidden by default when documentMode is viewing. Use the top-level comments.visible and trackChanges.visible flags to control what renders in read-only mode.

new SuperDoc({
  selector: "#viewer",
  document: "contract.docx",
  documentMode: "viewing",
  comments: { visible: true },      // Standard comment threads
  trackChanges: { visible: false }, // Tracked-change markup + threads
});

Setting up the comments UI

During initialization:

modules: {
  comments: {
    element: "#comments-sidebar";
  }
}

After initialization:

superdoc.on("ready", () => {
  superdoc.addCommentsList("#comments-sidebar");
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.addCommentsList("#comments-sidebar");
  },
});

Permission resolver

Customize who can resolve comments or accept tracked changes. The resolver receives the permission type, current user, and any tracked-change metadata. Return false to block the action. By default, editors can resolve, edit, and delete any user’s comments and tracked changes — regardless of authorship. Use permissionResolver to restrict actions when needed.

modules: {
  comments: {
    permissionResolver: ({
      permission,
      trackedChange,
      currentUser,
      defaultDecision,
    }) => {
      if (
        permission === "RESOLVE_OTHER" &&
        trackedChange?.attrs?.authorEmail !== currentUser?.email
      ) {
        return false; // Block accepting suggestions from other authors
      }
      return defaultDecision;
    },
  },
}

Available permission types:

Permission	Description
`RESOLVE_OWN`	Resolve your own comments
`RESOLVE_OTHER`	Resolve other users’ comments
`REJECT_OWN`	Reject your own tracked changes
`REJECT_OTHER`	Reject other users’ tracked changes
`COMMENTS_OVERFLOW_OWN`	Edit your own comments
`COMMENTS_OVERFLOW_OTHER`	Edit other users’ comments
`COMMENTS_DELETE_OWN`	Delete your own comments
`COMMENTS_DELETE_OTHER`	Delete other users’ comments

You can set a global resolver with the top-level permissionResolver config. Module-level resolvers take precedence when both are defined.

Word import/export

Word comments are automatically imported with the document and marked with importedId. When exporting, use the commentsType option:

// Include comments in export
const blob = await superdoc.export({ commentsType: "external" });

// Remove all comments
const cleanBlob = await superdoc.export({ commentsType: "clean" });

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: async (superdoc) => {
    // Include comments in export
    const blob = await superdoc.export({ commentsType: "external" });

    // Remove all comments
    const cleanBlob = await superdoc.export({ commentsType: "clean" });
  },
});

API methods

These methods are available on the active editor’s commands:

`addComment`

Add a comment to the current text selection. Requires a text selection.

// Simple usage
superdoc.activeEditor.commands.addComment("Review this section");

// With options
superdoc.activeEditor.commands.addComment({
  content: "Please clarify this section",
  author: "John Smith",
  authorEmail: "john@company.com",
  isInternal: true,
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    // Simple usage
    superdoc.activeEditor.commands.addComment("Review this section");

    // With options
    superdoc.activeEditor.commands.addComment({
      content: "Please clarify this section",
      author: "John Smith",
      authorEmail: "john@company.com",
      isInternal: true,
    });
  },
});

string | Object

Comment content as a string, or an options object with:

Show Options

string

The comment text (text or HTML)

string

Author name (defaults to user.name from config)

string

Author email (defaults to user.email from config)

string

Author image URL

boolean

default:"false"

Whether the comment is internal/private

`addCommentReply`

Add a reply to an existing comment or tracked change.

superdoc.activeEditor.commands.addCommentReply({
  parentId: "comment-123",
  content: "I agree with this suggestion",
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.addCommentReply({
      parentId: "comment-123",
      content: "I agree with this suggestion",
    });
  },
});

Object

required

Show Options

string

required

The ID of the parent comment to reply to

string

Reply content (text or HTML)

string

Author name (defaults to user.name from config)

string

Author email (defaults to user.email from config)

string

Author image URL

`removeComment`

superdoc.activeEditor.commands.removeComment({
  commentId: "comment-123",
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.removeComment({
      commentId: "comment-123",
    });
  },
});

`setActiveComment`

Highlight and focus a comment.

superdoc.activeEditor.commands.setActiveComment({
  commentId: "comment-123",
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.setActiveComment({
      commentId: "comment-123",
    });
  },
});

`resolveComment`

superdoc.activeEditor.commands.resolveComment({
  commentId: "comment-123",
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.resolveComment({
      commentId: "comment-123",
    });
  },
});

`setCommentInternal`

Toggle a comment between internal and external visibility.

superdoc.activeEditor.commands.setCommentInternal({
  commentId: "comment-123",
  isInternal: true,
});

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.setCommentInternal({
      commentId: "comment-123",
      isInternal: true,
    });
  },
});

`setCursorById`

Navigate the cursor to a comment’s position in the document.

superdoc.activeEditor.commands.setCursorById("comment-123");

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: 'john@company.com' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.setCursorById("comment-123");
  },
});

Events

`onCommentsUpdate`

Fired for all comment changes.

string

required

Event type: pending, add, update, deleted, resolved, selected, change-accepted, or change-rejected

Comment

required

The Comment object

Object

Additional metadata

onCommentsUpdate: ({ type, comment, meta }) => {
  switch(type) {
    case 'add':
      await saveComment(comment);
      break;
    case 'resolved':
      await markResolved(comment.id);
      break;
  }
}

Comment data structure

Object

Hide properties

Core

string

Unique identifier

string

HTML content

string | null

Parent comment ID for threaded replies

array

Mentioned users

Author

string

Author display name

string

Author email

number

Unix timestamp

Position

string

Document ID

string

Document type

Object

Position data including selectionBounds, page, and documentId

State

boolean

Internal/external flag (when dual comments enabled)

number | null

Resolution timestamp

string | null

Resolver email

string | null

Resolver name

Track Changes

boolean | null

Whether this is a tracked change comment

string | null

'trackInsert', 'trackDelete', 'trackFormat', or 'both'

string | null

The text content of the tracked change

string | null

The deleted text (for delete tracked changes)

Import

string | null

Original Word comment ID (from DOCX import)

Object | null

Original author info (from DOCX import)

Full example

Comments Example

Runnable example: threaded comments with resolve workflow and event log

Getting Started

Core

Document Engine

Modules

Extensions

Solutions

Guides

Resources

Quick start

Configuration

Viewing mode visibility

Setting up the comments UI

Permission resolver

Word import/export

API methods

`addComment`

`addCommentReply`

`removeComment`

`setActiveComment`

`resolveComment`

`setCommentInternal`

`setCursorById`

Events

`onCommentsUpdate`

Comment data structure

Core

Author

Position

State

Track Changes

Import

Full example

Comments Example

​Quick start

​Configuration

​Viewing mode visibility

​Setting up the comments UI

​Permission resolver

​Word import/export

​API methods

​addComment

​addCommentReply

​removeComment

​setActiveComment

​resolveComment

​setCommentInternal

​setCursorById

​Events

​onCommentsUpdate

​Comment data structure

​Core

​Author

​Position

​State

​Track Changes

​Import

​Full example

Comments Example

Quick start

Configuration

Viewing mode visibility

Setting up the comments UI

Permission resolver

Word import/export

API methods

`addComment`

`addCommentReply`

`removeComment`

`setActiveComment`

`resolveComment`

`setCommentInternal`

`setCursorById`

Events

`onCommentsUpdate`

Comment data structure

Core

Author

Position

State

Track Changes

Import

Full example