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, or a compliance reviewer can flag a section for legal review. Unlike tracked changes, comments are stored as a separate discussion layer in comments.xml.

This guide covers the OOXML comment structure and the docx-js-editor comment UI.

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 lets comments survive nearby text edits. If someone inserts words before the commented text, the comment stays attached to the marked 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

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 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 for the thread content and commentRangeStart / commentRangeEnd markers in the document body. A document with comments added in docx-js-editor opens 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 can move through multiple approvers. Each reviewer adds comments for their area: legal reviews terms, finance reviews numbers, and compliance reviews 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