> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collab-kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments

> Add threaded comments with replies, reactions, and user tagging.

## Comments Collection

The Comments module provides room-scoped threaded comments with support for replies, emoji reactions, and user tagging. All changes are synced in real time to other participants.

Access it via `client.comments`.

<Note>
  Editors can create and mutate comments. Viewers receive comment updates, but comment writes, reactions, tags, and replies are blocked for viewer sessions.
</Note>

### Methods

#### Add Comment

**`add(text, opts?)`**

Add a top-level comment to the room. Optionally tag users at creation:

```typescript theme={null}
const comment = await client.comments.add('Hello from the comments feature!');

// With tags
const comment = await client.comments.add('Check this out!', {
  tags: ['user-002', 'user-003'],
});
```

The returned `comment` is a `CollabKitCommentInstance` with methods for replies, reactions, and tags.

#### Get Comments

**`getAll()`**

Fetch all comments in the room:

```typescript theme={null}
const comments = await client.comments.getAll();
```

#### Sync Comments

**`sync()`**

Force a full sync of comments from the server:

```typescript theme={null}
await client.comments.sync();
```

#### Delete Comment

**`delete(commentId)`**

Delete a top-level comment. This cascades and removes all its replies:

```typescript theme={null}
await client.comments.delete(comment.id);
```

### Events

Listen for comment changes across the room:

```typescript theme={null}
client.comments.on('add', (comment) => {
  console.log('New comment:', comment.text);
});
```

| Event    | Payload                    | Description                                             |
| -------- | -------------------------- | ------------------------------------------------------- |
| `add`    | `CollabKitCommentInstance` | A new comment was added by another client               |
| `delete` | `string` (comment ID)      | A comment was deleted by another client                 |
| `update` | `CollabKitCommentInstance` | A comment was updated (reaction, tag, or reply changed) |

## Comment Instance

Each comment returned by `add()` or `getAll()` is a `CollabKitCommentInstance` with its own properties and methods.

### Properties

| Property    | Type                         | Description                            |
| ----------- | ---------------------------- | -------------------------------------- |
| `id`        | `string`                     | Unique comment ID                      |
| `text`      | `string`                     | Comment body                           |
| `userId`    | `string`                     | ID of the user who created the comment |
| `parentId`  | `string \| null`             | Parent comment ID (null for top-level) |
| `reactions` | `Reaction[]`                 | List of reactions on this comment      |
| `tags`      | `string[]`                   | List of tagged user IDs                |
| `replies`   | `CollabKitCommentInstance[]` | Child replies (one level deep)         |
| `createdAt` | `string`                     | ISO timestamp                          |

### Methods

#### Reply to Comment

**`reply(text, opts?)`**

Add a reply to this comment (one level of nesting):

```typescript theme={null}
const reply = await comment.reply('Great point!');

// With tags
const reply = await comment.reply('Tagging you on this', {
  tags: ['user-002'],
});
```

#### Delete Reply

**`deleteReply(replyId)`**

Remove a reply:

```typescript theme={null}
await comment.deleteReply(reply.id);
```

#### Add Reaction

**`addReaction(reaction)`**

Add an emoji reaction to the comment:

```typescript theme={null}
await comment.addReaction('👍');
```

Reactions on replies work the same way:

```typescript theme={null}
const reply = await comment.reply('Nice!');
await reply.addReaction('🎉');
```

#### Delete Reaction

**`deleteReaction(reaction)`**

Remove a reaction:

```typescript theme={null}
await comment.deleteReaction('👍');
```

#### Add Tag

**`addTag(userId)`**

Tag a user on this comment:

```typescript theme={null}
await comment.addTag('user-002');
```

#### Delete Tag

**`deleteTag(userId)`**

Remove a user tag:

```typescript theme={null}
await comment.deleteTag('user-002');
```

<Note>
  Tagged users receive a `commentTagged` event on their user instance. See [User Events](/sdk/users#events-1).
</Note>

### Events

Listen for updates to a specific comment:

```typescript theme={null}
comment.on('update', (updatedComment) => {
  console.log('Comment updated:', updatedComment);
  // Fires when reactions, tags, or replies change
});
```

## Examples

### Threaded Comments

```typescript theme={null}
// Listen for new comments from others
client.comments.on('add', (comment) => {
  renderComment(comment);
});

// Listen for being tagged
client.currentUser?.on('commentTagged', (comment) => {
  showNotification(`You were tagged in: "${comment.text}"`);
});

// Add a comment with tags
const comment = await client.comments.add('Design review needed', {
  tags: [client.userId],
});

// Add reactions
await comment.addReaction('👍');

// Reply
const reply = await comment.reply('Looks good to me!');
await reply.addReaction('🎉');

// Listen for changes to this comment
comment.on('update', (updated) => {
  console.log('Reactions:', updated.reactions);
  console.log('Replies:', updated.replies.length);
});

// Clean up
await comment.deleteReply(reply.id);
await client.comments.delete(comment.id);
```