TutorialMarch 8, 2026·2 min read

Adding Comments to a React Document Editor

How document comments work in docx-js-editor — threaded discussions, text range anchoring, resolve workflows, and OOXML compatibility with Microsoft Word.

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:

FeaturePurposeModifies content?
Track changesRecord insertions, deletions, formatting changesYes
CommentsDiscuss, question, or approve sectionsNo

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