---
title: "Comments & replies — Svelte"
description: "Build a comments sidebar with threads, replies, review states and jumping to a comment."
framework: "Svelte"
source: "https://www.embedpdf.com/docs/headless/svelte/annotations/comments"
---

# 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:

**`sidebar.svelte`**

```svelte
<script lang="ts">
  import { annotationKey, useCommentThreads } from '@embedpdf/svelte/annotation';

  const threads = useCommentThreads();
</script>

{#each threads.current as thread (annotationKey(thread.root.ref))}
  <article>
    <p>{thread.root.author}, page {thread.pageLabel}: {thread.root.contents}</p>
    {#each thread.replies as reply (annotationKey(reply.ref))}
      <p>{reply.author}: {reply.contents}</p>
    {/each}
  </article>
{/each}
```

**`App.svelte`**

```svelte
<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { interactionPlugin } from '@embedpdf/svelte/interaction';
  import { AnnotationLayer, annotationPlugin } from '@embedpdf/svelte/annotation';
  import { localEngine } from '@embedpdf/engine';
  import AddComments from './AddComments.svelte';
  import Comments from './Comments.svelte';

  import '../comments.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin(), interactionPlugin(), annotationPlugin()];

  const ebook = async (): Promise<OpenInput> => {
    const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
    return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
  };
</script>

<Viewer
  {engine}
  {plugins}
  identity={{ userId: 'u_381', displayName: 'Dana Smith' }}
  initialDocuments={[{ source: ebook }]}
>
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">Loading…</p>
    {/snippet}
    <AddComments />
    <div class="viewer">
      <Stage class="stage">
        <RenderLayer />
        <AnnotationLayer />
      </Stage>
      <Comments />
    </div>
  </DocumentGate>
</Viewer>
```

**`comments.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --text: #3b4b7a;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --accent: #054fb3;
  --focus: #7db6ff;
  --shadow: rgb(7 32 76 / 0.04);
}

/* The threads: one card each */
.threads {
  display: flex;
  flex-direction: column;
  gap: 10px;
}

.thread {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 10px;
  background: var(--tint);
  border-radius: 10px;
}

.comment {
  margin: 0;
  font-size: 13px;
  line-height: 1.4;
  color: var(--text);
}

.comment strong {
  color: var(--ink);
}

.empty {
  margin: 0;
  font-size: 13px;
  color: var(--muted);
}

/* Where a thread is, its replies, and the reply box */
.thread-head {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.where {
  font-size: 11px;
  font-weight: 700;
  letter-spacing: 0.06em;
  text-transform: uppercase;
  color: var(--muted);
}

.show {
  font: inherit;
  font-size: 12px;
  font-weight: 600;
  color: var(--accent);
  background: none;
  border: 0;
  padding: 0;
  cursor: pointer;
}

.reply {
  padding-left: 10px;
  border-left: 2px solid var(--line-strong);
}

.reply-form {
  margin: 0;
}

.field {
  box-sizing: border-box;
  width: 100%;
  font: inherit;
  font-size: 13px;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 8px;
  padding: 6px 9px;
}

.field:focus-visible {
  outline: none;
  border-color: var(--focus);
  box-shadow: 0 0 0 3px rgb(125 182 255 / 0.35);
}

/* The pages and the panel: stacked, and side by side where there's room */
.viewer {
  container-type: inline-size;
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}

.stage,
.panel {
  flex: 1 1 100%;
  box-sizing: border-box;
  border: 1px solid var(--line);
  border-radius: 14px;
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.stage {
  height: 340px;
  background: var(--canvas);
}

.panel {
  max-height: 260px;
  overflow-y: auto;
  margin: 0;
  padding: 12px;
  background: var(--surface);
}

@container (min-width: 620px) {
  .stage {
    flex: 1 1 0;
    min-width: 0;
    height: 420px;
  }

  .panel {
    flex: 0 0 280px;
    max-height: 420px;
  }
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

**`AddComments.svelte`**

```svelte
<!-- On load: a note with two replies on the cover, and a highlight with a comment on page 2. -->
<script lang="ts">
  import { untrack } from 'svelte';
  import { usePageList } from '@embedpdf/svelte/runtime';
  import { useAnnotation, useAnnotationState, useComments } from '@embedpdf/svelte/annotation';

  const annotation = useAnnotation();
  const comments = useComments();
  const ready = useAnnotationState((state) => state.status === 'ready');
  const pages = usePageList();

  let added = false;
  $effect(() => {
    const [cover, second] = pages.current;
    if (!ready.current || !cover || !second || added) return;
    added = true;
    untrack(() => {
      void annotation
        .create(cover.ref, {
          subtype: 'text',
          rect: { x: 470, y: 232, width: 20, height: 20 },
          contents: 'Can we shorten the title?',
          color: '#facc15',
        })
        .then(async ({ annotation: note }) => {
          await comments.reply(note.ref, 'Maybe drop "(But they Don’t Have to Be)".');
          await comments.reply(note.ref, 'I like it long. It’s a promise.');
        });
      void annotation.create(second.ref, {
        subtype: 'highlight',
        quadPoints: [
          {
            upperLeft: { x: 57, y: 57 },
            upperRight: { x: 322, y: 57 },
            lowerLeft: { x: 57, y: 129 },
            lowerRight: { x: 322, y: 129 },
          },
        ],
        color: '#ffcd45',
        contents: 'A strong opening.',
      });
    });
  });
</script>
```

**`Comments.svelte`**

```svelte
<!-- Every thread in the document, in reading order. -->
<script lang="ts">
  import { annotationKey, useAnnotationState, useCommentThreads } from '@embedpdf/svelte/annotation';
  import Thread from './Thread.svelte';

  const threads = useCommentThreads();
  const loading = useAnnotationState((state) => state.status === 'loading');
</script>

<div class="panel threads">
  {#if loading.current}
    <p class="empty">Loading comments…</p>
  {:else if threads.current.length === 0}
    <p class="empty">No comments</p>
  {/if}
  {#each threads.current as thread (annotationKey(thread.root.ref))}
    <Thread {thread} />
  {/each}
</div>
```

**`Thread.svelte`**

```svelte
<!-- One thread: the first comment, its replies, a reply box, and a button that shows it. -->
<script lang="ts">
  import { useStage } from '@embedpdf/svelte/stage';
  import {
    annotationKey,
    useAnnotation,
    useComments,
    type CommentThreadView,
  } from '@embedpdf/svelte/annotation';

  let { thread }: { thread: CommentThreadView } = $props();

  const comments = useComments();
  const annotation = useAnnotation();
  const stage = useStage();
  let text = $state('');

  function show() {
    stage.reveal(thread.page, { rect: thread.root.rect });
    annotation.selection.set([thread.root.ref]); // and select it
  }

  function reply(event: SubmitEvent) {
    event.preventDefault();
    if (!text.trim()) return;
    void comments.reply(thread.root.ref, text.trim());
    text = '';
  }
</script>

<article class="thread">
  <header class="thread-head">
    <span class="where">Page {thread.pageLabel}</span>
    <button type="button" class="show" onclick={show}>Show</button>
  </header>
  <p class="comment">
    <strong>{thread.root.author}</strong>
    {thread.root.contents}
  </p>
  {#each thread.replies as each (annotationKey(each.ref))}
    <p class="comment reply">
      <strong>{each.author}</strong>
      {each.contents}
    </p>
  {/each}
  {#if comments.canReply(thread.root.ref)}
    <form class="reply-form" onsubmit={reply}>
      <input class="field" aria-label="Reply" placeholder="Reply…" bind:value={text} />
    </form>
  {/if}
</article>
```

> **Try it:** reply to a thread, or press **Show** to go to its comment. Add a note on the page:
> it gets a thread of its own.

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'`.                                                |

## 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.

**`App.svelte`**

```svelte
<script lang="ts" module>
  import { DocumentGate, Viewer, type OpenInput } from '@embedpdf/svelte/runtime';
  import { Stage, stagePlugin } from '@embedpdf/svelte/stage';
  import { RenderLayer, renderPlugin } from '@embedpdf/svelte/render';
  import { interactionPlugin } from '@embedpdf/svelte/interaction';
  import { AnnotationLayer, annotationPlugin } from '@embedpdf/svelte/annotation';
  import { localEngine } from '@embedpdf/engine';
  import AddNotes from './AddNotes.svelte';
  import Reviews from './Reviews.svelte';

  import '../review.css';

  const engine = localEngine();
  const plugins = [stagePlugin(), renderPlugin(), interactionPlugin(), annotationPlugin()];

  const ebook = async (): Promise<OpenInput> => {
    const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
    return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
  };
</script>

<Viewer
  {engine}
  {plugins}
  identity={{ userId: 'u_381', displayName: 'Dana Smith' }}
  initialDocuments={[{ source: ebook }]}
>
  <DocumentGate>
    {#snippet fallback()}
      <p class="loading">Loading…</p>
    {/snippet}
    <AddNotes />
    <div class="viewer">
      <Stage class="stage">
        <RenderLayer />
        <AnnotationLayer />
      </Stage>
      <Reviews />
    </div>
  </DocumentGate>
</Viewer>
```

**`review.css`**

```css
/* Colors */
:root {
  --ink: #1a2748;
  --text: #3b4b7a;
  --muted: #5a6b92;
  --line: #e6eaf2;
  --line-strong: #dce8fc;
  --surface: #ffffff;
  --tint: #f3f7fe;
  --canvas: #f7f9fc;
  --accent: #054fb3;
  --focus: #7db6ff;
  --shadow: rgb(7 32 76 / 0.04);
  --accepted: #1d7a4d;
  --accepted-tint: #d9f5e6;
  --rejected: #b42318;
  --rejected-tint: #fde2e1;
}

.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 6px;
  font: inherit;
  font-size: 13px;
  font-weight: 550;
  line-height: 1.1;
  color: var(--ink);
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 9px;
  padding: 8px 12px;
  cursor: pointer;
  white-space: nowrap;
  box-shadow: 0 1px 2px var(--shadow);
  transition:
    background-color 0.15s ease,
    border-color 0.15s ease;
}

.button:hover {
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:active {
  transform: translateY(1px);
}

.button:focus-visible {
  outline: 2px solid var(--focus);
  outline-offset: 2px;
}

.button[aria-pressed='true'] {
  color: var(--accent);
  background: var(--tint);
  border-color: var(--line-strong);
}

.button:disabled {
  opacity: 0.45;
  cursor: not-allowed;
  transform: none;
}

/* The threads: one card each */
.threads {
  display: flex;
  flex-direction: column;
  gap: 10px;
}

.thread {
  display: flex;
  flex-direction: column;
  gap: 6px;
  padding: 10px;
  background: var(--tint);
  border-radius: 10px;
}

.comment {
  margin: 0;
  font-size: 13px;
  line-height: 1.4;
  color: var(--text);
}

.comment strong {
  color: var(--ink);
}

.empty {
  margin: 0;
  font-size: 13px;
  color: var(--muted);
}

/* A thread's verdict and its buttons */
.verdict {
  display: flex;
  align-items: center;
  gap: 8px;
  margin: 0;
}

.state {
  font-size: 11px;
  font-weight: 700;
  letter-spacing: 0.06em;
  text-transform: uppercase;
  color: var(--muted);
  background: var(--surface);
  border-radius: 6px;
  padding: 2px 6px;
}

.state--accepted {
  color: var(--accepted);
  background: var(--accepted-tint);
}

.state--rejected {
  color: var(--rejected);
  background: var(--rejected-tint);
}

.mark {
  font-size: 12px;
  font-weight: 600;
  color: var(--accepted);
}

.actions {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
}

.actions .button {
  padding: 5px 9px;
  font-size: 12px;
}

/* The pages and the panel: stacked, and side by side where there's room */
.viewer {
  container-type: inline-size;
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}

.stage,
.panel {
  flex: 1 1 100%;
  box-sizing: border-box;
  border: 1px solid var(--line);
  border-radius: 14px;
  box-shadow:
    0 1px 2px var(--shadow),
    0 18px 40px -28px rgb(7 32 76 / 0.28);
}

.stage {
  height: 340px;
  background: var(--canvas);
}

.panel {
  max-height: 260px;
  overflow-y: auto;
  margin: 0;
  padding: 12px;
  background: var(--surface);
}

@container (min-width: 620px) {
  .stage {
    flex: 1 1 0;
    min-width: 0;
    height: 420px;
  }

  .panel {
    flex: 0 0 280px;
    max-height: 420px;
  }
}

.loading {
  margin: 0;
  padding: 24px 0;
  text-align: center;
  font-size: 13px;
  color: var(--muted);
}
```

**`AddNotes.svelte`**

```svelte
<!-- On load: two notes on the cover, one already accepted. -->
<script lang="ts">
  import { untrack } from 'svelte';
  import { usePageList } from '@embedpdf/svelte/runtime';
  import { useAnnotation, useAnnotationState, useComments } from '@embedpdf/svelte/annotation';

  const annotation = useAnnotation();
  const comments = useComments();
  const ready = useAnnotationState((state) => state.status === 'ready');
  const pages = usePageList();

  let added = false;
  $effect(() => {
    const cover = pages.current[0]?.ref;
    if (!ready.current || !cover || added) return;
    added = true;
    untrack(() => {
      void annotation.create(cover, {
        subtype: 'text',
        rect: { x: 470, y: 232, width: 20, height: 20 },
        contents: 'Can we shorten the title?',
        color: '#facc15',
      });
      void annotation
        .create(cover, {
          subtype: 'text',
          rect: { x: 280, y: 520, width: 20, height: 20 },
          contents: 'Add the co-author',
          color: '#facc15',
        })
        .then(({ annotation: note }) => comments.setStatus(note.ref, 'accepted'));
    });
  });
</script>
```

**`Review.svelte`**

```svelte
<!-- A thread's verdict, its check mark, and the buttons the user may use. -->
<script lang="ts">
  import { useComments, type CommentThreadView } from '@embedpdf/svelte/annotation';

  let { thread }: { thread: CommentThreadView } = $props();

  const comments = useComments();
  const ref = $derived(thread.root.ref);
  const verdict = $derived(thread.review.lastChange?.state ?? 'none');
  const marked = $derived(thread.review.markedBy.length > 0);
</script>

<article class="thread">
  <p class="comment">
    <strong>{thread.root.author}</strong>
    {thread.root.contents}
  </p>
  <p class="verdict">
    <span class="state state--{verdict}">{verdict}</span>
    {#if marked}
      <span class="mark">✓ checked off</span>
    {/if}
  </p>
  <div class="actions">
    <button
      type="button"
      class="button"
      disabled={!comments.canSetStatus(ref)}
      onclick={() => comments.setStatus(ref, 'accepted')}
    >
      Accept
    </button>
    <button
      type="button"
      class="button"
      disabled={!comments.canSetStatus(ref)}
      onclick={() => comments.setStatus(ref, 'rejected')}
    >
      Reject
    </button>
    <button
      type="button"
      class="button"
      aria-pressed={marked}
      disabled={!comments.canSetMarked(ref)}
      onclick={() => comments.setMarked(ref, !marked)}
    >
      ✓
    </button>
    <button
      type="button"
      class="button"
      disabled={!comments.canDeleteThread(ref)}
      onclick={() => comments.deleteThread(ref)}
    >
      Delete
    </button>
  </div>
</article>
```

**`Reviews.svelte`**

```svelte
<script lang="ts">
  import { annotationKey, useCommentThreads } from '@embedpdf/svelte/annotation';
  import Review from './Review.svelte';

  const threads = useCommentThreads();
</script>

<div class="panel threads">
  {#if threads.current.length === 0}
    <p class="empty">No comments</p>
  {/if}
  {#each threads.current as thread (annotationKey(thread.root.ref))}
    <Review {thread} />
  {/each}
</div>
```

## Jump to a comment

The thread's `root` has a page and a `rect`, which is where the view should go:

**`jump.svelte`**

```svelte
<script lang="ts">
  import { useAnnotation, type CommentThread } from '@embedpdf/svelte/annotation';
  import { useStage } from '@embedpdf/svelte/stage';

  let { thread }: { thread: CommentThread } = $props();

  const stage = useStage();
  const annotation = useAnnotation();

  function show() {
    stage.reveal(thread.page, { rect: thread.root.rect });
    annotation.selection.set([thread.root.ref]); // and select it
  }
</script>

<button onclick={show}>Show</button>
```

## 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

**`events.svelte`**

```svelte
<script lang="ts">
  import { useAnnotationEvent } from '@embedpdf/svelte/annotation';
  import { notifyThreadAuthor } from './notifications'; // your own

  useAnnotationEvent(
    (annotation) => annotation.comments.onThreadChanged,
    ({ rootRef, change }) => change === 'reply' && notifyThreadAuthor(rootRef),
  );
</script>

<aside><!-- … --></aside>
```

| Event                      | Fires when                           | Carries             |
| :------------------------- | :----------------------------------- | :------------------ |
| `comments.onThreadChanged` | A thread changed through this viewer | `rootRef`, `change` |

`change` 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:

**`permissions.svelte`**

```svelte
<script lang="ts">
  import { useComments, type CommentThread } from '@embedpdf/svelte/annotation';

  let { thread }: { thread: CommentThread } = $props();
  const comments = useComments();
</script>

<button disabled={!comments.canReply(thread.root.ref)}>Reply</button>
<button disabled={!comments.canDeleteThread(thread.root.ref)}>Delete thread</button>
```

| 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()` 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.

> **Turn comments into a live review**
>
> 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.
>
> [Review with CloudPDF](https://www.cloudpdf.com/docs/headless/svelte/annotations/comments)