Comments

Comments are threads anchored to ranges of text. They render as chips beside the page and are preserved in DOCX import and export. Your code can read and write them.

Read threads

const { commentThreads, activeCommentId, commentsOpen } =
  editor.review.getState();

Each thread has a root comment, replies, an anchor, and related suggestions:

interface ReviseCommentThread {
  root: CommentRecord;
  replies: CommentRecord[];
  anchor: { blockId: string; start: number; end: number } | null;
  relatedSuggestionIds: string[];
}

Add comments

Comment bodies are Markdown. Each method returns the new comment’s ID, or null when the target no longer exists.

// At the user's current selection
editor.review.addCommentAtSelection("Is this cap mutual?");

// At a known range
editor.review.addCommentToRanges(
  [{ blockId: "b12", start: 0, end: 24 }],
  "Confirm the notice period.",
);

// On a whole block, or attached to a suggestion
editor.review.addCommentToBlock("b12", "Needs legal review.");
editor.review.addCommentForSuggestion(suggestionId, "Why this wording?");

// Replies and lifecycle
editor.review.replyToComment(commentId, "Agreed. Updated.");
editor.review.setCommentResolved(commentId, true);
editor.review.deleteComment(commentId);

Each method takes optional mentions as an additional argument.

Panel and selection

editor.view.setCommentsOpen(true);
editor.review.selectComment(commentId); // scrolls to and highlights the thread
editor.review.selectComment(null);      // clear

The SDK has no comments button. Chips render inline, and your UI opens the panel. See chrome. Selecting text in an editable document shows an insert-comment chip in the page margin. Clicking it starts a draft on the selection, like addCommentAtSelection. The chip is hidden during a draft, in read-only documents, and on selections that already have a thread.

Comments and suggestions together

A comment can be linked to suggestions. A reviewer can then accept or reject those suggestions from the comment:

const ids = editor.review.getRelatedSuggestionIds(commentId);
editor.review.acceptCommentSuggestions(commentId); // returns the count
editor.review.rejectCommentSuggestions(commentId);

Agent comments

The leave_comment tool adds comments from an agent:

// Start a thread on one block with one anchor form
await editor.tools.execute("leave_comment", {
  id: "b12",
  anchor: { text: "capped at the fees paid in the preceding twelve months" },
  comment: "Consider making this cap mutual.",
});

Other anchor forms are { start_text, end_text } for a long range, and { whole_block: true } for structural or empty content. To reply, call the same tool without an anchor:

await editor.tools.execute("leave_comment", {
  reply_to_comment_id: threadId,
  comment: "Agreed. The mutual version is market standard.",
});

leave_comment anchors only to text the agent has read. Call a read tool such as read_blocks_from_index first, or the anchor does not resolve.

If the anchor text is not in the block you named, but exactly one block you have read contains it, the comment goes there instead. The result reports both: data.blockId is where it landed and data.requestedBlockId is the block you asked for. Block IDs change when a file is imported again, so this keeps a stale ID from failing. Read tools return existing threads as <comment-thread> elements in their HTML. A new thread that overlaps an unresolved thread is rejected, and the agent should reply to that thread instead. To add an overlapping thread anyway, list the overlapping IDs in acknowledge_existing_thread_ids. Tool comments are signed “Revise Agent” unless you set agent.name.

Comment agents

The comments controller runs an agent scoped to one thread. Use it when each thread is a separate conversation with the model:

await editor.comments.run(threadId, "Draft a redline that addresses this.");
editor.comments.steer(threadId, "Keep it to one sentence.");
editor.comments.cancel(threadId);

useEffect(() => editor.comments.subscribe(setThreadRuns), [editor]);

getState(threadId) returns the thread’s run state. subscribe() publishes a map of every active run.

Getting started

Guides

API reference

Read threads

Add comments

Panel and selection

Comments and suggestions together

Agent comments

Comment agents

​Read threads

​Add comments

​Panel and selection

​Comments and suggestions together

​Agent comments

​Comment agents

Read threads

Add comments

Panel and selection

Comments and suggestions together

Agent comments

Comment agents