--- title: Comments & replies description: Build a comments sidebar with threads, replies, review states and jumping to a comment. --- # Comments & replies Any annotation can carry a comment, its `contents`, and people can reply to it. Together they make a **thread**: the first comment and its replies, in order. `useCommentThreads()` gives you every thread in the document, ready for a sidebar: > **Try it:** you're Dana Smith, reviewing Ada's proposal. Reply to a thread, or press **Show** to > go to its comment on the page. Threads come in reading order: by page, then from the top of the page. The list updates by itself when anyone adds, changes or deletes a comment, on this screen or, on a shared document, on someone else's. A thread has: | Field | What it is | | :---------- | :------------------------------------------------------------------------------------------------ | | `root` | The annotation that starts the thread: a note, a highlight, a shape. | | `replies` | Every reply, oldest first. Replies to replies are included. | | `review` | The review states people set, such as accepted or rejected (see [Review states](#review-states)). | | `page` | The page it's on. | | `pageLabel` | The page's label to show, such as `'iv'` or `'7'`. | ## Read a comment on the page The annotation layer draws a note's icon and a highlight's color, not the comment: like the sidebar, the window that shows it is yours. Build it from what you already have: the selected annotation, its thread, and the annotation menu, which keeps your card next to it: > **Try it:** click the note next to the title, or the highlighted sentence, then reply. Press > **Escape** to close the card. The card shows while the annotation is selected, so a click elsewhere closes it too. Any annotation can carry a comment, so the same card opens for a note, a highlight or a shape. ## Reply, edit and delete ```ts const { annotation: reply } = await comments.reply(thread.root.ref, 'Checked, looks right.'); await comments.setText(reply.ref, 'Checked against the invoice, looks right.'); await comments.delete(reply.ref); // one comment await comments.deleteThread(thread.root.ref); // the whole thread ``` A reply always goes to the thread's first comment, whichever comment you pass. It's saved the way Acrobat saves replies, so they show up as replies there too. Deleting the first comment of a thread deletes the whole thread, as Acrobat does. `deleteThread()` does the same, all or nothing, and tells you what happened: when the thread has a comment you may not delete, such as someone else's reply, nothing is deleted and `failed` lists what stopped it. ## Review states A review state is a verdict on a thread: accepted, rejected, cancelled or completed. Each person sets their own, and a check mark is separate: ```ts await comments.setStatus(thread.root.ref, 'accepted'); await comments.setMarked(thread.root.ref, true); // check it off thread.review.lastChange?.state; // the latest verdict, from anyone thread.review.byReviewer; // each person's latest verdict thread.review.markedBy; // who has checked it off ``` States are saved as the PDF's own review states, so Acrobat shows them in its comment list. > **Try it:** accept or reject a comment, or check it off. Dana has already accepted Ada's note on > page 2. ## Jump to a comment The thread's `root` has a page and a `rect`, which is where the view should go: ## Methods Everything `useComments()` gives you. It's the `comments` part of `useAnnotation()`. | Method | What it does | | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | `listThreads()` | Every thread, in reading order. In a component, use `useCommentThreads()`, which also gives each thread its `pageLabel`. | | `getThread(ref)` | The thread a comment is in, whether you pass its first comment, a reply or a review state, or `null`. In a component, use `useCommentThread(ref)`. | | `reply(ref, text)` | Replies to the thread's first comment, whichever comment you pass. Resolves `{ annotation }`. [Reply, edit and delete](#reply-edit-and-delete) | | `setText(ref, text)` | Changes a comment's text | | `delete(ref)` | Deletes a comment with its replies. The first comment of a thread deletes the whole thread. | | `deleteThread(ref)` | Deletes a whole thread, all or nothing. Resolves `{ deleted, failed }`: when a comment in it may not be deleted, nothing goes and `failed` lists it. | | `setStatus(ref, state)` | Sets the user's review state on a thread, such as `'accepted'` or `'rejected'`. [Review states](#review-states) | | `setMarked(ref, marked)` | Checks a thread off for the user, or clears the check mark | | `canReply(ref)`, `canSetText(ref)`, `canDelete(ref)`, `canDeleteThread(ref)`, `canSetStatus(ref)`, `canSetMarked(ref)` | Whether the user may do that to this comment. [Permissions](#permissions) | Every method that returns a promise also takes a `signal` in its options, to cancel it. ## Events | Event | Fires when | Carries | | :------------------------- | :------------------------------------------------- | :------------------- | | `comments.onThreadChanged` | A thread changed through this viewer | `rootRef`, `type` | `type` is `'reply'`, `'text'`, `'status'`, `'marked'` or `'deleted'`. For every change, including other people's, use the annotation events; see [Events, saving & sharing](saving#events). ## Permissions Every comment verb has a check that answers for one comment, so you show only the buttons that work: | Permission | What it allows | Check | | :------------------- | :----------------------------------------------------------------- | :---------------------------------------- | | `annotations:create` | Replying, setting a review state, checking a comment off | `canReply(ref)`, `canSetStatus(ref)`, `canSetMarked(ref)` | | `annotations:update` | Changing a comment's text | `canSetText(ref)` | | `annotations:delete` | Deleting a comment, or every comment in a thread | `canDelete(ref)`, `canDeleteThread(ref)` | A review state and a check mark are small replies of their own, the way Acrobat stores them, so they need the right to create, not to change. The checks also follow the comment's own flags: `lockedContents` stops text edits, and `locked` stops deleting. ## Good to know ### Comments without a note Any annotation can start a thread. A highlight with a comment is a thread whose `root` is the highlight. A plain note (the `note` tool) is a thread with an icon on the page. ### Loading The `status` from `useAnnotationState()`The `status()` signal on `inject(EpdfAnnotation)` is `'loading'` until every annotation is in. Show a loading state in your sidebar until then, so an empty list doesn't look like "no comments". ### Reviewing together On the local engine, a review stays with the file: the next person sees the comments once they have the downloaded PDF. With CloudPDF, everyone with the document open sees new comments, replies and review states as they happen, and the server checks who may reply, change or delete what. Your sidebar stays the same: `useCommentThreads()` updates by itself. Everyone with the document open sees new comments, replies and review states as they happen: `useCommentThreads()` updates by itself.