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

# Broadcasts

> Send custom events to other participants in real time.

The Broadcasts module lets you send fire-and-forget custom events to other participants in the room. Use it for emoji reactions, pings, notifications, cursor clicks, or any ephemeral communication.

Access it via `client.notifications`.

<Note>
  Broadcasts are fire-and-forget. They are not persisted and cannot be replayed. If a user is offline when an event is sent, they won't receive it.
</Note>

<Note>
  Only editors can send broadcasts. Viewers can receive broadcasts, but `broadcast(...)` is blocked for viewer sessions.
</Note>

## Methods

### Send Event

**`broadcast(event, data, userIds?)`**

Send a custom event to other users in the room:

```typescript theme={null}
// Send to everyone in the room
client.notifications.broadcast('cursor-click', { x: 100, y: 200 });

// Send to specific users
client.notifications.broadcast('ping', { message: 'hello' }, ['user-002']);
```

| Parameter | Type       | Required | Description                                                     |
| --------- | ---------- | -------- | --------------------------------------------------------------- |
| `event`   | `string`   | Yes      | Custom event name. Can be any string.                           |
| `data`    | `object`   | Yes      | Payload to send. Must be JSON-serializable.                     |
| `userIds` | `string[]` | No       | User IDs to target. If omitted, sent to all other participants. |

### Listen for Events

**`on(event, callback)`**

Listen for a specific event type:

```typescript theme={null}
client.notifications.on('cursor-click', (data) => {
  console.log('Click at:', data.x, data.y);
});
```

### Listen Once

**`once(event, callback)`**

Listen for an event, but only fire the callback once:

```typescript theme={null}
client.notifications.once('welcome', (data) => {
  showWelcomeMessage(data.message);
});
```

### Remove Listener

**`off(event, callback)`**

Remove a specific listener:

```typescript theme={null}
const handler = (data) => console.log(data);
const offHandler = client.notifications.on('cursor-click', handler);

// Later, remove the listener
client.notifications.off('cursor-click', handler);
// Alternatively
offHandler();

```

## Examples

### Emoji Reactions

```typescript theme={null}
// Send a floating emoji
function sendEmoji(emoji: string, x: number, y: number) {
  client.notifications.broadcast('emoji', { emoji, x, y });
}

// Render floating emojis from other users
client.notifications.on('emoji', ({ emoji, x, y }) => {
  const el = document.createElement('span');
  el.textContent = emoji;
  el.className = 'floating-emoji';
  el.style.left = `${x}px`;
  el.style.top = `${y}px`;
  document.body.appendChild(el);
  setTimeout(() => el.remove(), 2000);
});
```

### User Notifications

```typescript theme={null}
// Notify a specific user
client.notifications.broadcast(
  'mention',
  { from: client.userId, message: 'Check this out!' },
  ['user-002']
);

// Listen for mentions
client.notifications.on('mention', ({ from, message }) => {
  const sender = client.users.active.get(from) ?? client.users.all.get(from);
  showNotification(`${sender?.name}: ${message}`);
});
```