API Reference - @liveblocks/client

@liveblocks/client provides you with JavaScript bindings for our realtime collaboration APIs, built on top of WebSockets. Read our getting started guides to learn more.

createClient

Creates a client that allows you to connect to Liveblocks servers. You must define either authEndpoint or publicApiKey. Resolver functions should be placed inside here, and a number of other options are available.

import { createClient } from "@liveblocks/client";
const client = createClient({  authEndpoint: "/api/liveblocks-auth",
  // Other options  // ...});

createClient with public key

When creating a client with a public key, you don’t need to set up an authorization endpoint. We only recommend using a public key when prototyping, or on public landing pages, as it makes it possible for end users to access any room’s data. You should instead use an auth endpoint.

import { createClient } from "@liveblocks/client";
const client = createClient({  publicApiKey: "pk_prod_xxxx…xxxxxxpk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});

createClient with auth endpoint

If you are not using a public key, you need to set up your own authEndpoint. Please refer to our Authentication guide.

import { createClient } from "@liveblocks/client";
const client = createClient({ authEndpoint: "/api/liveblocks-auth" });

createClient with auth endpoint callback

If you need to add additional headers or use your own function to call your endpoint, authEndpoint can be provided as a custom callback. You should return the token created with Liveblocks.prepareSession or liveblocks.identifyUser, learn more in authentication guide.

import { createClient } from "@liveblocks/client";
const client = createClient({  authEndpoint: async (room) => {    // Fetch your authentication endpoint and retrieve your access or ID token    // ...
    return { token: "..." };  },});

room is the room ID that the user is connecting to. When using Notifications, room can be undefined, as the client is requesting a token that grants access to multiple rooms, rather than a specific room.

Fetch your endpoint

Here’s an example of fetching your API endpoint at /api/liveblocks-auth within the callback.

import { createClient } from "@liveblocks/client";
const client = createClient({  authEndpoint: async (room) => {    const response = await fetch("/api/liveblocks-auth", {      method: "POST",      headers: {        Authentication: "<your own headers here>",        "Content-Type": "application/json",      },      // Don’t forget to pass `room` down. Note that it      // can be undefined when using Notifications.      body: JSON.stringify({ room }),    });    return await response.json();  },});

Token details

You should return the token created with Liveblocks.prepareSession or liveblocks.identifyUser. These are the values the functions can return.

1. A valid token, it returns a { "token": "..." } shaped response.
2. A token that explicitly forbids access, it returns an { "error": "forbidden", "reason": "..." } shaped response. If this is returned, the client will disconnect and won’t keep trying to authorize.

Any other error will be treated as an unexpected error, after which the client will retry the request until it receives either 1. or 2.

WebSocket throttle

By default, the client throttles the WebSocket messages sent to one every 100 milliseconds, which translates to 10 updates per second. It’s possible to override that configuration with the throttle option with a value between 16 and 1000 milliseconds.

import { createClient } from "@liveblocks/client";
const client = createClient({  throttle: 16,
  // Other options  // ...});

This option is helpful for smoothing out realtime animations in your application, as you can effectively increase the framerate without using any interpolation. Here are some examples with their approximate frames per second (FPS) values.

throttle:  16, // 60 FPSthrottle:  32, // 30 FPSthrottle: 200, //  5 FPS

Prevent users losing unsaved changes

Liveblocks usually synchronizes milliseconds after a local change, but if a user immediately closes their tab, or if they have a slow connection, it may take longer for changes to synchronize. Enabling preventUnsavedChanges will stop tabs with unsaved changes closing, by opening a dialog that warns users. In usual circumstances, it will very rarely trigger.

import { createClient } from "@liveblocks/client";
const client = createClient({  preventUnsavedChanges: true,
  // Other options  // ...});

More specifically, this option triggers when:

• There are unsaved changes after calling any hooks or methods, in all of our products.
• There are unsaved changes in a Text Editor.
• There’s an unsubmitted comment in the Composer.
• The user has made changes and is currently offline.

Internally, this option uses the beforeunload event.

Lost connection timeout

If you’re connected to a room and briefly lose connection, Liveblocks will reconnect automatically and quickly. However, if reconnecting takes longer than usual, for example if your network is offline, then the room will emit an event informing you about this.

How quickly this event is triggered can be configured with the lostConnectionTimeout setting, and it takes a number in milliseconds. lostConnectionTimeout can be set between 1000 and 30000 milliseconds. The default is 5000, or 5 seconds.

import { createClient } from "@liveblocks/client";
const client = createClient({  lostConnectionTimeout: 5000,
  // Other options  // ...});

You can listen to the event with room.subscribe("lost-connection"). Note that this also affects when others are reset to an empty array after a disconnection. This helps prevent temporary flashes in your application as a user quickly disconnects and reconnects. For a demonstration of this behavior, see our connection status example.

Background keep-alive timeout

By default, Liveblocks applications will maintain an active WebSocket connection to the Liveblocks servers, even when running in a browser tab that’s in the background. However, if you’d prefer for background tabs to disconnect after a period of inactivity, then you can use backgroundKeepAliveTimeout.

When backgroundKeepAliveTimeout is specified, the client will automatically disconnect applications that have been in an unfocused background tab for at least the specified time. When the browser tab is refocused, the client will immediately reconnect to the room and synchronize the document.

import { createClient } from "@liveblocks/client";
const client = createClient({  // Disconnect users after 15 minutes of inactivity  backgroundKeepAliveTimeout: 15 * 60 * 1000,
  // Other options  // ...});

backgroundKeepAliveTimeout accepts a number in milliseconds—we advise using a value of at least a few minutes, to avoid unnecessary disconnections.

resolveUsers

Comments and Text Editor store user IDs in their system, but no other user information. To display user information in Comments, Text Editor, and Notifications components, such as a user’s name or avatar, you need to resolve these IDs into user objects. This function receives a list of user IDs and you should return a list of user objects of the same size, in the same order.

User IDs are automatically resolved in batches with a maximum of 50 users per batch to optimize performance and prevent overwhelming your user resolution function.

import { createClient } from "@liveblocks/client";
const client = createClient({  resolveUsers: async ({ userIds }) => {    const usersData = await __getUsersFromDB__(userIds);
    return usersData.map((userData) => ({      name: userData.name,      avatar: userData.avatar.src,    }));  },
  // Other options  // ...});

The name and avatar you return are rendered in Thread components.

User objects

The user objects returned by the resolver function take the shape of UserMeta["info"], which contains name and avatar by default. These two values are optional, though if you’re using the Comments default components, they are necessary. Here’s an example of userIds and the exact values returned.

resolveUsers: async ({ userIds }) => {  // ["marc@example.com", "nimesh@example.com"];  console.log(userIds);
  return [    { name: "Marc", avatar: "https://example.com/marc.png" },    { name: "Nimesh", avatar: "https://example.com/nimesh.png" },  ];};

You can also return custom information, for example, a user’s color:

resolveUsers: async ({ userIds }) => {  // ["marc@example.com"];  console.log(userIds);
  return [    {      name: "Marc",      avatar: "https://example.com/marc.png",      color: "purple",    },  ];};

Accessing user data in React

You can access any values set within resolveUsers with the useUser hook.

import { useUser } from "@liveblocks/react/suspense";
function Component() {  const user = useUser("marc@example.com");
  // { name: "Marc", avatar: "https://...", ... }  console.log(user);}

resolveRoomsInfo

When using Notifications with Comments, room IDs will be used to contextualize notifications (e.g. “Chris mentioned you in room-id”) in the InboxNotification component. To replace room IDs with more fitting names (e.g. document names, “Chris mentioned you in Document A”), you can provide a resolver function to the resolveRoomsInfo option in createClient.

This resolver function will receive a list of room IDs and should return a list of room info objects of the same size and in the same order.

import { createClient } from "@liveblocks/client";
const client = createClient({  resolveRoomsInfo: async ({ roomIds }) => {    const documentsData = await __getDocumentsFromDB__(roomIds);
    return documentsData.map((documentData) => ({      name: documentData.name,      // url: documentData.url,    }));  },
  // Other options  // ...});

In addition to the room’s name, you can also provide a room’s URL as the url property. If you do so, the InboxNotification component will automatically use it. It’s possible to use an inbox notification’s roomId property to construct a room’s URL directly in React and set it on InboxNotification via href, but the room ID might not be enough for you to construct the URL , you might need to call your backend for example. In that case, providing it via resolveRoomsInfo is the preferred way.

resolveGroupsInfo

When using group mentions with Comments and Text Editor, group IDs will be used instead of user IDs. Similarly to resolveUsers, you can provide a resolver function to the resolveGroupsInfo option in createClient to assign information like names and avatars to group IDs.

import { createClient } from "@liveblocks/client";
const client = createClient({  resolveGroupsInfo: async ({ groupIds }) => {    const groupsData = await __getGroupsFromDB__(groupIds);
    return groupsData.map((groupData) => ({      name: groupData.name,      avatar: groupData.avatar.src,    }));  },
  // Other options  // ...});

Accessing group info in React

You can access any values set within resolveGroupsInfo with the useGroupInfo hook.

import { useGroupInfo } from "@liveblocks/react/suspense";
function Component() {  const group = useGroupInfo("group-engineering");
  // { name: "Engineering", avatar: "https://...", ... }  console.log(group);}

resolveMentionSuggestions

To enable creating mentions in Comments and Text Editor, you can provide a resolver function to the resolveMentionSuggestions option in createClient. These mentions will be displayed in the Composer component and in text editors.

This resolver function will receive the mention currently being typed (e.g. when writing “@jane”, text will be jane) and should return a list of user IDs matching that text. This function will be called every time the text changes but with some debouncing.

import { createClient } from "@liveblocks/client";
const client = createClient({  resolveMentionSuggestions: async ({ text, roomId }) => {    const workspaceUsers = await __getWorkspaceUsersFromDB__(roomId);
    if (!text) {      // Show all workspace users by default      return __getUserIds__(workspaceUsers);    } else {      const matchingUsers = __findUsers__(workspaceUsers, text);      return __getUserIds__(matchingUsers);    }  },
  // Other options  // ...});

Group mentions

To support group mentions in Comments and Text Editor, you can return a list of mention objects instead of user IDs to suggest a mix of user and group mentions.

import { createClient } from "@liveblocks/client";
const client = createClient({  resolveMentionSuggestions: async ({ text, roomId }) => {    const dbUsers = await __findUsersFromDB__(roomId);    const dbGroups = await __findGroupsFromDB__(roomId);
    // Show groups and users matching the text being typed    return [      ...dbGroups.map((group) => ({        kind: "group",        id: group.id,      })),      ...dbUsers.map((user) => ({        kind: "user",        id: user.id,      })),    ];  },
  // Other options  // ...});

The mention objects specify which kind of mention it is, the ID to mention (user ID or group ID), etc.

// A user mention suggestion{  kind: "user",  id: "user-1",}
// A group mention suggestion{  kind: "group",  id: "group-1",}
// A group mention suggestion with fixed group members// When using fixed group members via `userIds`, they will take precedence// if the group ID exists on Liveblocks.{  kind: "group",  id: "here",  members: ["user-1", "user-2"],}

createClient for Node.js

To use @liveblocks/client in Node.js, you need to provide WebSocket and fetch polyfills. As polyfills, we recommend installing ws and node-fetch.

$npm install ws node-fetch

Then, pass them to the createClient polyfill option as below.

import { createClient } from "@liveblocks/client";import fetch from "node-fetch";import WebSocket from "ws";
const client = createClient({  polyfills: {    fetch,    WebSocket,  },
  // Other options  // ...});

Note that node-fetch v3+ does not support CommonJS. If you are using CommonJS, downgrade node-fetch to v2.

createClient for React Native

To use @liveblocks/client with React Native, you need to add an atob polyfill. As a polyfill, we recommend installing base-64.

$npm install base-64

Then you can pass the decode function to our atob polyfill option when you create the client.

import { createClient } from "@liveblocks/client";import { decode } from "base-64";
const client = createClient({  polyfills: {    atob: decode,  },
  // Other options  // ...});

Client

Client returned by createClient which allows you to connect to Liveblocks servers in your application, and enter rooms.

Client.enterRoom

Enters a room and returns both the local Room instance, and a leave unsubscribe function. The authentication endpoint is called as soon as you call this function. Used for setting initial Presence and initial Storage values.

const { room, leave } = client.enterRoom("my-room-id", {  // Options  // ...});

Note that it’s possible to add types to your room.

Setting initial Presence

Presence is used for storing temporary user-based values, such as a user’s cursor coordinates, or their current selection. Each user has their own presence, and this is readable for all other connected users. Set your initial Presence value by using initialPresence.

const { room, leave } = client.enterRoom("my-room-id", {  initialPresence: {    cursor: null,    colors: ["red", "purple"],    selection: {      id: 72426,    },  },
  // Other options  // ...});

Each user’s Presence resets every time they disconnect, as this is only meant for temporary data. Any JSON-serializable object is allowed (the JsonObject type).

Setting initial Storage

Storage is used to store permanent data that’s used in your application, such as shapes on a whiteboard, nodes on a flowchart, or text in a form. The first time a room is entered, you can set an initial value by using initialStorage. initialStorage is only read and set a single time, unless a new top-level property is added.

import { LiveList, LiveObject } from "@liveblocks/client";
const { room, leave } = client.enterRoom("my-room-id", {  initialStorage: {    title: "Untitled",    shapes: new LiveList([      new LiveObject({ type: "rectangle", color: "yellow" }),    ]),  },
  // Other options  // ...});

If a new top-level property is added to initialStorage, the next time a user connects, the new property will be created. Other properties will be unaffected. Any conflict-free live structures and JSON-serializable objects are allowed (the LsonObject type).

Client.getRoom

Gets a room by its ID. Returns null if client.enterRoom has not been called previously.

const room = client.getRoom("my-room");

It’s unlikely you’ll need this API if you’re using the newer client.enterRoom API. Note that it’s possible to add types to your room.

Client.getSyncStatus

Gets the current Liveblocks synchronization status.

const syncStatus = client.getSyncStatus();// "synchronizing" | "synchronized"

Client.logout

Purges any auth tokens from the client’s memory. If there are any rooms that are still connected, they will be forced to reauthorize.

client.logout();

When to logout

Use this function if you have a single page application (SPA) and you wish to log your user out, and reauthenticate them. This is a way to update your user’s info after a connection has begun.

AI Copilots

defineAiTool

Create a custom tool for your AI copilot to use. Defining tools allow the AI copilot to look up information on-demand, render your own components based on the tool’s arguments, or perform actions in your application on behalf of the current user, such as creating content, updating the application state, or interacting with external services.

import { defineAiTool } from "@liveblocks/client";
const myTool = defineAiTool()({  description: "Fetch user information by ID",  parameters: {    type: "object",    properties: {      userId: { type: "string", description: "The user’s unique identifier" },    },    required: ["userId"],    additionalProperties: false,  },  execute: async ({ userId }) => {    const user = await getUserById(userId);    return { data: { user } };  },  render: ({ result }) => (    <AiTool title="User Lookup" icon="👤">      {!result.data ? (        <div>Looking up user...</div>      ) : (        <div>Found user: {result.data.user.name}</div>      )}    </AiTool>  ),});

Tools can be registered globally with RegisterAiTool or passed directly to AiChat.

Tool call rendering stages

Rendering a tool call can be done before the tool call is executed, which allows you to display a UI during its entire lifecycle. The tool call stages are:

• receiving (since 3.4) The tool call is being received and its args are being streamed in. During this stage, you can access partialArgs to display a UI while the tool call arguments are still being constructed, but before the tool call is executed.
• executing The tool call is currently executing, or is ready to be. In this stage, the args are fully known, but the result of the tool call is not known yet.
• executed The tool call has been executed, and the result is known. This happens after your execute function was run, or after you called respond() inside render. In this stage, the result object will be available.

The render component will automatically re-render when its stage changes.

Implementing tool calls

When you implement a tool call, use one of these combinations:

1. Implement execute and render
2. Implement only execute, but no render
3. Implement only render, but make sure to eventually call respond()

Implementing your tool call via execute

If you implement the execute function, this function will automatically be invoked when the tool call gets made. The return value of this function will be the result that will be passed back to the AI copilot.

• { data: any, description?: string } The data to return in case of success. data must be a legal JSON value. Providing a description is optional. If you provide a description, it will be passed to the AI copilot to help it understand the returned data or to provide follow-up instructions for how to respond to this tool result.
• { error: string } The error message in case the tool call failed to execute.
• { cancel: true | string } If the tool call should be cancelled. You can optionally provide a cancel reason as an instruction to the AI copilot.

The returned value can be observed in the render method, through the result param:

defineAiTool()({  /* ... */
  execute: async () => {    await sleep(1000);    return { data: { user: { name: "Alice" } } };  },
  render: ({ result }) => {    if (result.data) {      return <div>Found user: {result.data.user.name}</div>;    }
    // Tool hasn’t executed yet    return <Spinner />;  },});

If you do not implement render alongside execute, the tool call will still be executed, but no UI will be displayed. The result will still be passed back to the AI copilot.

Implementing your tool call via render

Sometimes you may not want to immediately execute the tool call. This is most common to build a Human-in-the-Loop (HITL) style UI where you want the user to confirm or correct the tool call’s behavior. In these scenarios, you do not want to implement execute. Instead, you could display any UI, as long as you eventually call the respond function that is provided to render’s props.

defineAiTool()({  /* ... */  /* NOTE: No execute method used here! */
  render: ({ respond }) => {    return (      <div>        <button          onClick={() => {            respond({ data: { user: { name: "Alice" } } });          }}        >          Confirm        </button>        <button          onClick={() => {            respond({ cancel: true });          }}        >          Cancel        </button>      </div>    );  },});

In this example, until the Confirm button is clicked, the AI chat will remain in “executing” stage, awaiting the result of this tool call.

This example is for illustrative purposes only. In practice, using our AiTool.Confirmation tool is preferred for building confirm/cancel flows.

Like with the execute function, the respond function should be called with a value of this shape:

• { data: any, description?: string } The data to return in case of success. data must be a legal JSON value. Providing a description is optional. If you provide a description, it will be passed to the AI copilot to help it understand the returned data or to provide follow-up instructions for how to respond to this tool result.
• { error: string } The error message in case the tool call failed to execute.
• { cancel: true | string } If the tool call should be cancelled. You can optionally provide a cancel reason as an instruction to the AI copilot.

Handling different tool call stages

You can handle all three stages of a tool call in your render function to provide a smooth user experience during tool call streaming and execution:

const bookFlightTool = defineAiTool()({  description: "Book a flight for a user",  parameters: {    type: "object",    properties: {      origin: { type: "string", description: "Departure city" },      destination: { type: "string", description: "Arrival city" },      departureDate: {        type: "string",        description: "Departure date (YYYY-MM-DD)",      },      passengers: {        type: "array",        items: {          type: "object",          properties: {            name: { type: "string" },            age: { type: "number" },          },          required: ["name", "age"],          additionalProperties: false,        },        description: "List of passengers",      },    },    required: ["origin", "destination", "departureDate", "passengers"],    additionalProperties: false,  },  execute: async ({ origin, destination, departureDate, passengers }) => {    const booking = await bookFlight({      origin,      destination,      departureDate,      passengers,    });    return { data: { bookingId: booking.id } };  },  render: ({ stage, partialArgs, args, result }) => {    return (      <AiTool title="Flight Booking" icon="✈️">        {stage === "receiving" && (          <div>            <h4>Preparing flight booking...</h4>            {partialArgs.origin && <p>From: {partialArgs.origin}</p>}            {partialArgs.destination && <p>To: {partialArgs.destination}</p>}            {partialArgs.departureDate && (              <p>Date: {partialArgs.departureDate}</p>            )}            {partialArgs.passengers && (              <div>                <p>Passengers ({partialArgs.passengers.length}):</p>                <ul>                  {partialArgs.passengers.map((passenger, index) => (                    <li key={index}>                      {passenger?.name || "Loading..."}                      {passenger?.age && ` (${passenger.age})`}                    </li>                  ))}                </ul>              </div>            )}          </div>        )}        {stage === "executing" && (          <div>            <h4>Booking flight...</h4>            <p>              {args.origin} → {args.destination} on {args.departureDate}            </p>            <p>{args.passengers.length} passenger(s)</p>          </div>        )}        {stage === "executed" && result.data && (          <div>            <h4>Flight booked successfully!</h4>            <p>Booking ID: {result.data.bookingId}</p>          </div>        )}      </AiTool>    );  },});

In this example, the tool arguments stream in progressively during the receiving stage, causing multiple re-renders as each field appears:

• 1st render: { stage: "receiving", partialArgs: {} }
• 2nd render: { stage: "receiving", partialArgs: { origin: "New York" } }
• 3rd render: { stage: "receiving", partialArgs: { origin: "New York", destination: "London" } }
• 4th render: { stage: "receiving", partialArgs: { origin: "New York", destination: "London", departureDate: "2024-12-15" } }
• 5th render: { stage: "receiving", partialArgs: { ..., passengers: [] } }
• 6th render: { stage: "receiving", partialArgs: { ..., passengers: [{ name: "John" }] } }
• 7th render: { stage: "receiving", partialArgs: { ..., passengers: [{ name: "John", age: 3 }] } }
• 8th render: { stage: "receiving", partialArgs: { ..., passengers: [{ name: "John", age: 30 }] } }
• Final render: { stage: "executing", args: { /* complete object */ } }

This demonstrates how each field and nested property appears incrementally, providing real-time feedback to users as the AI constructs the tool call arguments.

Arguments are streamed in forward-only order. Once a field begins appearing, all previous fields are complete and won’t be modified. You’ll never see { origin: "New York", destination: "London" } followed by { origin: "San Francisco", destination: "London" }, but you might see { origin: "New" } then { origin: "New York" } then { origin: "New York", destination: "London" }.

Room

Room returned by client.enterRoom (or client.getRoom).

Room.getPresence

Return the current user’s Presence. Presence is used to store custom properties on each user that exist until the user disconnects. An example use would be storing a user’s cursor coordinates.

const presence = room.getPresence();
// { cursor: { x: 363, y: 723 } }console.log(presence);

Presence is set with updatePresence and can be typed when you enter a room. The example above is using the following type:

declare global {  interface Liveblocks {    Presence: {      cursor: { x: number; y: number };    };  }}

Room.updatePresence

Updates the current user’s Presence. Only pass the properties you wish to update—any changes will be merged into the current presence. The entire presence object will not be replaced.

room.updatePresence({ typing: true });room.updatePresence({ status: "Online" });
// { typing: true, status: "Online" }const presence = room.getPresence();

Add Presence to history

By default, Presence values are not added to history. However, using the addToHistory option will add items to the undo/redo stack.

room.updatePresence({ color: "blue" }, { addToHistory: true });room.updatePresence({ color: "red" }, { addToHistory: true });room.history.undo();
// { color: "blue" }const presence = room.getPresence();

See room.history for more information.

Room.getOthers

Returns an array of currently connected users in the room. Returns a User object for each user. Note that you can also subscribe to others using Room.subscribe("others").

const others = room.getOthers();
for (const other of others) {  const { connectionId, id, info, presence, canWrite, canComment } = other;  // Do things}

Room.broadcastEvent

Broadcast an event to other users in the Room. Events broadcast to the room can be listened to with Room.subscribe("event"). Takes a custom event payload as first argument. Should be serializable to JSON.

room.broadcastEvent({ type: "REACTION", emoji: "🔥" });

Receiving an event

To receive an event, use Room.subscribe("event"). The user property received on the other end is the sender’s User instance.

// User 1room.broadcastEvent({ type: "REACTION", emoji: "🔥" });
// User 2const unsubscribe = room.subscribe("event", ({ event, user, connectionId }) => {  //                                                  ^^^^ User 1  if (event.type === "REACTION") {    // Do something  }});

We recommend using a property such as type, so that it’s easy to distinguish between different events on the receiving end.

Typing multiple events

When defining your types, you can pass a RoomEvent type in your config file to receive type hints in your app. To define multiple different custom events, use a union.

declare global {  interface Liveblocks {    RoomEvent:      | { type: "REACTION"; emoji: string }      | { type: "ACTION"; action: string };  }}

room.subscribe("event", ({ event, user, connectionId }) => {  if (event.type === "REACTION") {    // Do something  }  if (event.type === "ACTION") {    // Do something else  }});

Broadcasting an event when disconnected

By default, broadcasting an event is a “fire and forget” action. If the sending client is not currently connected to a room, the event is simply discarded. When passing the shouldQueueEventIfNotReady option, the client will queue up the event, and only send it once the connection to the room is (re)established.

room.broadcastEvent(  { type: "REACTION", emoji: "🔥" },  {    shouldQueueEventIfNotReady: true,  });

Room.getSelf

Gets the current User. Returns null if the client is not yet connected to the room.

const { connectionId, presence, id, info, canWrite, canComment } =  room.getSelf();

Here’s an example of a full return value, assuming Presence and UserMeta have been set.

const user = room.getSelf();
// {//   connectionId: 52,//   presence: {//     cursor: { x: 263, y: 786 },//   },//   id: "mislav.abha@example.com",//   info: {//     avatar: "/mislav.png",//   },//   canWrite: true,//   canComment: true,// }console.log(user);

Room.getStatus

Gets the current WebSocket connection status of the room. The possible value are: initial, connecting, connected, reconnecting, or disconnected.

const status = room.getStatus();
// "connected"console.log(status);

Room.getStorageStatus

Get the Storage status. Use this to tell whether Storage has been synchronized with the Liveblocks servers.

const status = room.getStorageStatus();
// "synchronizing"console.log(status);

Room.subscribe(storageItem)

Subscribe to updates on a particular storage item, and takes a callback function that’s called when the storage item is updated. The Storage root is a LiveObject, which means you can subscribe to this, as well as other live structures. Returns an unsubscribe function.

const { root } = await room.getStorage();
const unsubscribe = room.subscribe(root, (updatedRoot) => {  // Do something});

Typing Storage

To type the Storage values you receive, make sure to set your Storage type.

import { LiveList } from "@liveblocks/client";
declare global {  interface Liveblocks {    Storage: {      animals: LiveList<{ name: string }>;    };  }}

The type received in the callback will match the type passed. Learn more under typing your room.

const { root } = await room.getStorage();const animals = root.get("animals");
const unsubscribe = room.subscribe(animals, (updatedAnimals) => {  // LiveList<[{ name: "Fido" }, { name: "Felix" }]>  console.log(updatedAnimals);});

Subscribe to any live structure

You can subscribe to any live structure, be it the Storage root, a child, or a structure even more deeply nested.

import { LiveMap, LiveObject } from "@liveblocks/client";
type Person = LiveObject<{ name: string; age: number }>;
declare global {  interface Liveblocks {    Storage: {      people: LiveMap<string, Person>;    };  }}

const { root } = await room.getStorage();const people = root.get("people");const steven = people.get("steven");
const unsubscribeRoot = room.subscribe(root, (updatedRoot) => {  // ...});
const unsubscribePeople = room.subscribe(people, (updatedPeople) => {  // ...});
const unsubscribeSteven = room.subscribe(steven, (updatedSteven) => {  // ...});

Listening for nested changes

It’s also possible to subscribe to a Storage item and all of its children by passing an optional isDeep option in the third argument. In this case, the callback will be passed a list of updates instead of just the new Storage item. Each such update is a { type, node, updates } object.

const { root } = await room.getStorage();
const unsubscribe = room.subscribe(  root,  (storageUpdates) => {    for (const update of storageUpdates) {      const {        type, // "LiveObject", "LiveList", or "LiveMap"        node,        updates,      } = update;      switch (type) {        case "LiveObject": {          // updates["property"]?.type; is "update" or "delete"          // update.node is the LiveObject that has been updated/deleted          break;        }        case "LiveMap": {          // updates["key"]?.type; is "update" or "delete"          // update.node is the LiveMap that has been updated/deleted          break;        }        case "LiveList": {          // updates[0]?.type; is "delete", "insert", "move", or "set"          // update.node is the LiveList that has been updated, deleted, or modified          break;        }      }    }  },  { isDeep: true });