Adding Comments to a React Document Editor

Comment model

Comments are annotations anchored to text ranges. They do not modify document content. A reviewer can highlight a clause and ask a question. A compliance reviewer can mark a section for legal review. Unlike tracked changes, comments use a separate discussion layer in comments.xml.

How OOXML stores comments

The DOCX format stores comments in a separate comments.xml file within the ZIP archive:

<!-- word/comments.xml -->
<w:comments>
  <w:comment w:id="1" w:author="Alice" w:date="2026-03-05T10:00:00Z">
    <w:p>
      <w:r>
        <w:t>Should we increase this to 60 days?</w:t>
      </w:r>
    </w:p>
  </w:comment>
</w:comments>

The document body references comments using range markers:

<!-- word/document.xml -->
<w:p>
  <w:commentRangeStart w:id="1"/>
  <w:r>
    <w:t>The payment terms are net 30 days.</w:t>
  </w:r>
  <w:commentRangeEnd w:id="1"/>
  <w:r>
    <w:rPr>
      <w:rStyle w:val="CommentReference"/>
    </w:rPr>
    <w:commentReference w:id="1"/>
  </w:r>
</w:p>

Range markers preserve the comment anchor during nearby text edits. If a reviewer inserts words before the commented text, the comment remains attached to the marked range.

Comment features in docx-js-editor

docx-js-editor includes a CommentsSidebar component beside the editor. It supports comment display, replies, resolution, and deletion.

Rendering existing comments

docx-js-editor parses comments from Microsoft Word and other editors when it loads a document:

1. Reads comments.xml for comment content (id, author, initials, date, paragraphs)
2. Reads commentsExtended.xml for thread structure and resolution status (done flag)
3. Maps commentRangeStart/commentRangeEnd markers to ProseMirror marks with a yellow highlight
4. Renders comment cards in the sidebar, positioned alongside their anchored text

Threaded replies

Comments use the parentId field for replies. A reply entered in an expanded comment card references its parent comment.

Resolving and deleting

Resolving a comment sets the done flag and keeps the thread in the document. Deleting a comment removes it.

Setup

import { DocxEditor } from "@eigenpal/docx-js-editor";
 
function Editor({ buffer }: { buffer: ArrayBuffer }) {
  return (
    <DocxEditor
      documentBuffer={buffer}
      author="Current User"
    />
  );
}

The editor renders the comments sidebar when the document contains comments.

Combining comments with track changes

Comments and track changes complement each other:

A review workflow can use these steps:

1. The author sends a draft.
2. The reviewer sets mode="suggesting" and edits the text.
3. The reviewer adds comments for questions that do not require an edit.
4. The author accepts or rejects tracked changes and responds to comments.
5. The author resolves the comments and accepts the required changes.

Set mode="suggesting" to enable tracked changes alongside comments:

<DocxEditor
  documentBuffer={buffer}
  mode="suggesting"
  author="Reviewer Name"
/>

Export compatibility

During export, docx-js-editor serializes comments to the same OOXML structure. It writes thread content to comments.xml. It writes commentRangeStart and commentRangeEnd markers to the document body. Microsoft Word can open the exported document and its comments.

Use cases

Contract negotiation

Each party can add comments to discuss specific clauses. Threaded replies can record proposals, counterproposals, and agreements.

Document approval workflows

Multiple approvers can review one document. Legal reviewers check terms. Finance reviewers check numbers. Compliance reviewers check regulatory language.

Collaborative writing

Co-authors can use comments for questions such as, "Need a source for this statistic." They can discuss text without changing it.

Next steps

• Learn about tracked changes for content-level revisions
• Follow the React Word editor guide