Annotations attach durable ranges to editor text and publish them to sidebars and other React UI. Use Decorations, annotations, and widgets for the broader choice between decorations, annotation stores, and projected text rendering.
Use annotations when a range has identity beyond a single render pass: review comments, issue markers, tracked external diagnostics, resolved threads, or other application-owned ranges.
Use decorations for transient paint such as search matches. Render app-owned UI for nodes, selections, or annotations.
type AnnotationAnchor = {
resolve(): Range | null;
};
type Annotation<TData> = {
anchor: AnnotationAnchor;
data?: TData;
id: string;
};anchor resolves the current range. A local Anchor<Range> satisfies this contract.
Adapters can use the same contract for service-owned anchors, remote positions,
or document-embedded ids.
data is application metadata. useAnnotation and useAnnotations return
it.
Inline paint is a separate DecorationSource. The feature that owns the
visual states converts resolved annotations into keyed decoration attributes.
Use editor.anchor when the anchor belongs to the local editor runtime.
const anchor = editor.anchor(
{
anchor: { path: [0, 0], offset: 3 },
focus: { path: [0, 0], offset: 18 },
},
{ association: "inward", deletion: "nearest" }
);
const annotationStore = useAnnotationStore(editor, [
{
anchor,
data: { label: "Comment 1" },
id: "comment-1",
},
]);const anchor = editor.anchor(
{
anchor: { path: [0, 0], offset: 3 },
focus: { path: [0, 0], offset: 18 },
},
{ association: "inward", deletion: "nearest" }
);
const annotationStore = useAnnotationStore(editor, [
{
anchor,
data: { label: "Comment 1" },
id: "comment-1",
},
]);Use nearest for durable annotations. Complete deletion collapses the range to
a valid position, while saved undo and redo restore its exact endpoints.
When annotations come from React state, pass the current array. A new array identity refreshes the store automatically.
const annotations = comments.map((comment) => ({
anchor: comment.anchor,
data: comment,
id: comment.id,
}));
const annotationStore = useAnnotationStore(editor, annotations);const annotations = comments.map((comment) => ({
anchor: comment.anchor,
data: comment,
id: comment.id,
}));
const annotationStore = useAnnotationStore(editor, annotations);Pass the annotation store explicitly to each reader. Another subtree can use a
different store. CommentThread below is an app-owned component.
<EditorRoot decorations={[commentDecorations]} editor={editor}>
<Editable />
<CommentsSidebar />
</EditorRoot>;
function CommentsSidebar() {
const snapshot = useAnnotations(annotationStore);
return snapshot.allIds.map((id) => {
const comment = snapshot.byId.get(id);
return <CommentThread key={id} comment={comment} />;
});
}<EditorRoot decorations={[commentDecorations]} editor={editor}>
<Editable />
<CommentsSidebar />
</EditorRoot>;
function CommentsSidebar() {
const snapshot = useAnnotations(annotationStore);
return snapshot.allIds.map((id) => {
const comment = snapshot.byId.get(id);
return <CommentThread key={id} comment={comment} />;
});
}Release anchors when the app removes the annotation.
anchor.release();anchor.release();Comment bodies, permissions, resolved state, and audit events belong to the app or sync service. The Plite document value owns document content. Use Document Meta for document metadata and settings that should persist with the document.
useCommentChannel is an app-owned hook that subscribes to the comment service.
const comments = useCommentChannel();
const annotations = comments.map((comment) => ({
anchor: comment.anchor,
data: {
body: comment.body,
label: comment.label,
status: comment.status,
},
id: comment.id,
}));const comments = useCommentChannel();
const annotations = comments.map((comment) => ({
anchor: comment.anchor,
data: {
body: comment.body,
label: comment.label,
status: comment.status,
},
id: comment.id,
}));When an external store knows which comments changed, refresh those ids.
annotationStore.refresh({
ids: [threadId],
reason: "annotation",
});annotationStore.refresh({
ids: [threadId],
reason: "annotation",
});Refresh semantics:
ids for a full refreshUse separate channels for the document and the comments.
// Writer lane: document channel.
writerEditor.update((tx) => {
tx.text.insert("hello", { at });
});
// Reviewer lane: annotation channel.
commentsMap.set(threadId, {
anchor,
body,
status: "open",
});
annotationStore.refresh({ ids: [threadId], reason: "annotation" });// Writer lane: document channel.
writerEditor.update((tx) => {
tx.text.insert("hello", { at });
});
// Reviewer lane: annotation channel.
commentsMap.set(threadId, {
anchor,
body,
status: "open",
});
annotationStore.refresh({ ids: [threadId], reason: "annotation" });A read-only reviewer can select text, create a comment anchor, and update a thread without document-write permission. The adapter resolves the anchor against the current document snapshot for rendering.
The comment-mode example renders this as two panes:
The comment-mode controls do not call editor.update or mutate the
document.
Render app-owned UI from resolved annotation ranges. Use
useAnnotation(annotationStore, id) for one annotation and
useAnnotations(annotationStore) for the complete snapshot.
Use useSelectionGeometry({ editableRef }) for selection-positioned UI in one
exact Editable.
An external adapter can keep the document and comments in separate stores.
type ExternalAnnotationAnchor = {
release(): void;
resolve(): Range | null;
};
const anchor = externalAnnotationAdapter.anchorFromPliteRange(editor, range);
commentChannel.set(threadId, {
anchor,
body,
status: "open",
});type ExternalAnnotationAnchor = {
release(): void;
resolve(): Range | null;
};
const anchor = externalAnnotationAdapter.anchorFromPliteRange(editor, range);
commentChannel.set(threadId, {
anchor,
body,
status: "open",
});The adapter owns mapping, drift recovery, deletion policy, and permissions. Plite React resolves the range once the adapter provides an anchor.
Document-embedded ids are useful when the product wants comments to copy, paste, serialize, or travel with document content.
Use this as an adapter strategy, not as the default storage model for comment bodies or permissions. The document may store a lightweight id; the comment thread still belongs to the app or sync service.
Keep annotation rows stable when their range and app data do not change.
Use refresh({ ids }) for external comment updates when the changed ids are
known. Fall back to refresh() when the external source cannot provide ids.
Targeted subscribers wake only when their resolved range or data changes. Decoration subscribers are independent and wake only when merged text attributes change.