Adding Comments to a React Document Editor

Why comments matter

Comments are annotations anchored to text ranges. they don't modify document content. A reviewer highlights a clause and asks "Can we rephrase this?" A compliance team flags a section for legal review. Unlike tracked changes (which record content modifications), comments are a separate discussion layer stored in comments.xml.

This post covers how OOXML comment structures work and how docx-js-editor handles them.

How OOXML stores comments

In the DOCX format, comments are stored 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>

This range-based anchoring means comments survive text edits. if someone inserts words before the commented text, the comment stays attached to the right range.

Comment features in docx-js-editor

docx-js-editor includes a CommentsSidebar component that renders alongside the editor. It handles the full comment lifecycle:

Rendering existing comments

Documents created in Microsoft Word or other editors often contain comments. docx-js-editor parses these on load:

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 support replies via the parentId field. When expanding a comment card in the sidebar, users can type a reply that gets linked to the parent comment.

Resolving and deleting

Comments can be resolved (sets the done flag. visually dimmed but not deleted) or permanently deleted from the document.

Setup

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

The comments sidebar renders automatically when the document contains comments.

Combining comments with track changes

Comments and track changes complement each other:

A typical review workflow:

1. Author sends a draft
2. Reviewer sets mode="suggesting" and edits the text
3. Reviewer adds comments where they have questions (not edits)
4. Author reviews tracked changes (accept/reject) and responds to comments
5. When all comments are resolved and changes accepted, the document is final

Both features work together. Set mode="suggesting" to enable tracked changes alongside comments:

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

Export compatibility

On export, comments are serialized back to the same OOXML structure. comments.xml with comment content, and commentRangeStart/commentRangeEnd markers in the document body. A document with comments added in docx-js-editor opens correctly in Microsoft Word.

Use cases

Contract negotiation

Both parties add comments to discuss specific clauses. The threaded reply structure captures the negotiation: proposal, counter, agreement.

Document approval workflows

A document goes through multiple approvers. Each approver adds comments on their area of expertise. legal reviews the terms, finance reviews the numbers, compliance checks regulatory language.

Collaborative writing

Co-authors leave comments for each other: "Need a source for this statistic," "This section overlaps with chapter 3." Comments are faster and less disruptive than rewriting text.

Next steps

• Learn about tracked changes for content-level revisions
• Follow the React integration tutorial
• See the DOCX editor comparison