Comments

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

Building your own comments sidebar in React? Skip this module and read Custom UI › Comments instead. It documents useSuperDocComments, ui.selection.capture(), and the typed posting flow.

Quick start

const superdoc = new SuperDoc({
  selector: "#editor",
  document: "contract.docx",
  user: {
    name: "John Smith",
    email: "[e-mail]",
  },
  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

modules.comments.readOnly · boolean · default: "false"

View-only mode. Hides the reply input and the edit action on existing comments. Users can still read comments and threads but cannot add, edit, or reply.

modules.comments.allowResolve · boolean · default: "true"

Allow marking comments as resolved

modules.comments.element · string | HTMLElement

Container for comments sidebar

modules.comments.useInternalExternalComments · boolean · default: "false"

Enable dual internal/external comment system

modules.comments.suppressInternalExternal · boolean · default: "false"

Hide internal comments from view

modules.comments.showResolved · boolean · default: "false"

Show resolved comments in the comments list

modules.comments.permissionResolver · function

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

modules.comments.highlightColors · Object

Custom colors for comment highlights.

Show Properties

external · string · default: "#B1124B"

Highlight color for external comments

internal · string · default: "#078383"

Highlight color for internal comments

activeExternal · string

Active highlight color override for external comments

activeInternal · string

Active highlight color override for internal comments

modules.comments.highlightOpacity · Object

Opacity values for comment highlights (0–1).

Show Properties

active · number

Opacity for the active comment highlight

inactive · number

Opacity for inactive comment highlights

modules.comments.highlightHoverColor · string

Hover highlight color for comment marks

modules.comments.trackChangeHighlightColors · Object

Colors for tracked change highlights.

Show Properties

insertBorder · string

Border color for inserted text

insertBackground · string

Background color for inserted text

deleteBorder · string

Border color for deleted text

deleteBackground · string

Background color for deleted text

formatBorder · string

Border color for format changes

modules.comments.trackChangeActiveHighlightColors · Object

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

Small-screen behavior

Use displayMode to control how comment/tracked-change bubbles render when container width is constrained.

modules.comments.displayMode · 'sidebar' | 'inline' | 'auto' · default: "'sidebar'"

Display policy for comment and tracked-change bubbles.

• 'sidebar': always render right sidebar bubbles.
• 'inline': always render compact inline popover mode.
• 'auto': switch between sidebar and inline mode based on measured available width.

modules.comments.compactBreakpointPx · number

Optional fixed compact threshold (px) for displayMode: 'auto'. If set, inline mode activates when available width is below this value.

modules.comments.compactMeasurementSelector · string

Optional CSS selector for the width measurement target in displayMode: 'auto'. Useful for custom flex/grid host shells where the default measurement target is not representative.

modules: {
  comments: {
    displayMode: "auto",
  },
}

modules: {
  comments: {
    displayMode: "auto",
    compactMeasurementSelector: "#editor-shell",
  },
}

Viewing mode visibility

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

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

The top-level trackChanges key still works as a deprecated alias for modules.trackChanges and will emit a one-time console warning.

Setting up the comments UI

During initialization:

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

After initialization:

Usage

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: '[e-mail]' },
  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:

Usage

// 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: '[e-mail]' },
  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

For new code, prefer the typed paths. Use editor.doc.comments.* for document mutations (server-and-client compatible, returns receipts) or ui.comments.* for React UI work (createFromSelection, createFromCapture, reply, resolve, reopen, delete). The chain commands below are kept for backwards compatibility and for code already written against superdoc.activeEditor.commands.*. See Document API › Comments and Custom UI › Comments.

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

addComment

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

Usage

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

// With options
superdoc.activeEditor.commands.addComment({
  content: "Please clarify this section",
  author: "John Smith",
  authorEmail: "[e-mail]",
  isInternal: true,
});

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  user: { name: 'John Smith', email: '[e-mail]' },
  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: "[e-mail]",
      isInternal: true,
    });
  },
});

contentOrOptions · string | Object

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

Show Options

content · string

The comment text (text or HTML)

author · string

Author name (defaults to user.name from config)

authorEmail · string

Author email (defaults to user.email from config)

authorImage · string

Author image URL

isInternal · boolean · default: "false"

Whether the comment is internal/private

addCommentReply

Add a reply to an existing comment or tracked change.

Usage

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: '[e-mail]' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.addCommentReply({
      parentId: "comment-123",
      content: "I agree with this suggestion",
    });
  },
});

options · Object · required

Show Options

parentId · string · required

The ID of the parent comment to reply to

content · string

Reply content (text or HTML)

author · string

Author name (defaults to user.name from config)

authorEmail · string

Author email (defaults to user.email from config)

authorImage · string

Author image URL

removeComment

Usage

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: '[e-mail]' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.removeComment({
      commentId: "comment-123",
    });
  },
});

setActiveComment

Highlight and focus a comment.

Usage

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: '[e-mail]' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.setActiveComment({
      commentId: "comment-123",
    });
  },
});

resolveComment

Usage

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: '[e-mail]' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.resolveComment({
      commentId: "comment-123",
    });
  },
});

setCommentInternal

Toggle a comment between internal and external visibility.

Usage

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: '[e-mail]' },
  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.

Usage

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: '[e-mail]' },
  modules: { comments: { allowResolve: true } },
  onReady: (superdoc) => {
    superdoc.activeEditor.commands.setCursorById("comment-123");
  },
});

scrollToComment

Scroll the document to a comment and set it as active. Unlike setCursorById, this is a top-level SuperDoc method that works without accessing the editor directly.

Usage

superdoc.scrollToComment("comment-123");

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

const superdoc = new SuperDoc({
  selector: '#editor',
  document: yourFile,
  modules: { comments: {} },
  onReady: (superdoc) => {
    const { items } = superdoc.editor.doc.comments.list();
    if (items.length > 0) {
      superdoc.scrollToComment(items[0].id);
    }
  },
});

See SuperDoc Methods for full parameter documentation.

Events

onCommentsUpdate

Fired for all comment changes.

type · string · required

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

comment · Comment · required

The Comment object

meta · 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

comment · Object

Hide properties

Core

commentId · string

Unique identifier

commentText · string

HTML content

parentCommentId · string | null

Parent comment ID for threaded replies

mentions · array

Mentioned users

Author

creatorName · string

Author display name

creatorEmail · string

Author email

createdTime · number

Unix timestamp

Position

fileId · string

Document ID

fileType · string

Document type

selection · Object

Position data including selectionBounds, page, and documentId

State

isInternal · boolean

Internal/external flag (when dual comments enabled)

resolvedTime · number | null

Resolution timestamp

resolvedByEmail · string | null

Resolver email

resolvedByName · string | null

Resolver name

Track Changes

trackedChange · boolean | null

Whether this is a tracked change comment

trackedChangeType · string | null

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

trackedChangeText · string | null

The text content of the tracked change

deletedText · string | null

The deleted text (for delete tracked changes)

Import

importedId · string | null

Original Word comment ID (from DOCX import)

importedAuthor · Object | null

Original author info (from DOCX import)

Full example

Comments Example

Runnable example: threaded comments with resolve workflow and event log