Handling Changes

A Collab changes state not just when you mutate it locally, but also when you receive updates from a remote collaoborator, or when you load some state from storage. You need to know about these changes so that you can update your display.

Document “Change” Event

The easiest way to handle changes is to listen on your document’s “Change” event, like so:

function refreshDisplay() {
  // Refresh the display (and other views of the collaborative state)
  // so that it reflects the current state of your Collabs.
  // ...
doc.on("Change", refreshDisplay);

Here doc can be a CRuntime or AbstractDoc. This “Change” event is emitted after each synchronous set of changes, as described in our API documentation.

For example, in the Quick Start, we did:

const display = document.getElementById("display")!;
function refreshDisplay() {
  display.innerHTML = counter.value.toString();
doc.on("Change", refreshDisplay);

Collab Events

Each Collab also emits type-specific events describing changes as they occur.

For example, in our whiteboard demo, it would be inefficient to repaint the whole whiteboard after each change. Instead, we listen on CValueMap’s “Set” and “Delete” events:

const boardState: CValueMap<[x: number, y: number], Color> = ...;
const ctx: CanvasRenderingContext2D = ...;

// Draw points
boardState.on("Set", (event) => {
  const [x, y] = event.key;
  const [r, g, b] = event.value;
  ctx.fillStyle = `rgb(${r},${g},${b})`;
  ctx.fillRect(x, y, 1, 1);

// Clear points
boardState.on("Delete", (event) => {
  const [x, y] = event.key;
  ctx.clearRect(x, y, 1, 1);

Each of our built-in Collabs emits events like these that completely describe how its state changes over time. You can find a Collab’s event names and types in the API docs for its on method (click the ...EventsRecord type name). E.g., here is CValueMap.on, and here is its MapEventsRecord.

useCollab React Hook

In a React component, call useCollab(collab) to trigger a rerender whenever collab’s state changes (specifically, when it emits an event):

import { useCollab } from "@collabs/react";
import React from "react";

function BoardInspector({
}: {
  boardState: CValueMap<[x: number, y: number], Color>;
}) {
  // Rerender when boardState changes.

  return <p>The corner pixel is {boardState.get([0, 0])}.</p>;

Next Steps

Finish setting up your Collabs by configuring Providers.