> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

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

> [!TIP]
>
> Building your own comments sidebar in React? Skip this module and read [Custom UI › Comments](https://docs.superdoc.dev/editor/custom-ui/comments.md) instead. It documents `useSuperDocComments`, `ui.selection.capture()`, and the typed posting flow.

## Quick start

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

> [!NOTE]
>
> The comments module is **enabled by default**. To disable it entirely, set `modules.comments` to `false`:
>
> ```javascript theme={null}
> 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](#permission-resolver).

**modules.comments.highlightColors** `Object`

Custom colors for comment highlights.

**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).

**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.

**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.

```javascript theme={null}
modules: {
  comments: {
    displayMode: "auto",
  },
}
```

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

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

> [!NOTE]
>
> 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:

```javascript theme={null}
modules: {
  comments: {
    element: "#comments-sidebar";
  }
}
```

After initialization:

```javascript Usage theme={null}
superdoc.on("ready", () => {
  superdoc.addCommentsList("#comments-sidebar");
});
```

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

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

> [!NOTE]
>
> 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:

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

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

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

> [!NOTE]
>
> **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](https://docs.superdoc.dev/document-api/reference/index.md) and [Custom UI › Comments](https://docs.superdoc.dev/editor/custom-ui/comments.md).

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

### `addComment`

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

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

```javascript Full Example theme={null}
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,
    });
  },
});
```

**contentOrOptions** `string | Object`

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

**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.

```javascript Usage theme={null}
superdoc.activeEditor.commands.addCommentReply({
  parentId: "comment-123",
  content: "I agree with this suggestion",
});
```

```javascript Full Example theme={null}
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",
    });
  },
});
```

**options** `Object` *required*

**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`

```javascript Usage theme={null}
superdoc.activeEditor.commands.removeComment({
  commentId: "comment-123",
});
```

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

```javascript Usage theme={null}
superdoc.activeEditor.commands.setActiveComment({
  commentId: "comment-123",
});
```

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

```javascript Usage theme={null}
superdoc.activeEditor.commands.resolveComment({
  commentId: "comment-123",
});
```

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

```javascript Usage theme={null}
superdoc.activeEditor.commands.setCommentInternal({
  commentId: "comment-123",
  isInternal: true,
});
```

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

```javascript Usage theme={null}
superdoc.activeEditor.commands.setCursorById("comment-123");
```

```javascript Full Example theme={null}
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");
  },
});
```

### `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.

```javascript Usage theme={null}
superdoc.scrollToComment("comment-123");
```

```javascript Full Example theme={null}
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);
    }
  },
});
```

> [!TIP]
>
> See [SuperDoc Methods](https://docs.superdoc.dev/editor/superdoc/methods.md#scrolltocomment) 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](#comment-data-structure) object

**meta** `Object`

Additional metadata

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

## Comment data structure

**comment** `Object`

**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

> [card] [Comments Example](https://go.superdoc.dev/comments)
>
> Runnable example: threaded comments with resolve workflow and event log


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.