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 stores user IDs in its system, but no other user information. To display user information in Comments 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.

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.

resolveMentionSuggestions

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

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  // ...});

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. Note that this value is only read a single time.

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  // ...});

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.

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 });

Using async functions

You use an async function inside the subscription callback, though bear in mind that the callback itself is synchronous, and there’s no guarantee the async function will complete before the callback is run again.

const { root } = await room.getStorage();
const unsubscribe = room.subscribe(root, (updatedRoot) => {  async function doThing() {    await fetch(/* ... */);  }
  doThing();});

If the order of updates is imporant in your application, and it’s important to ensure that your async function doesn’t start before the previous one finishes, you can use a package such as async-mutex to help you with this. Using runExclusive will effectively form a queue for all upcoming updates, guaranteeing serial execution.

import { Mutex } from "async-mutex";
const { root } = await room.getStorage();const myMutex = new Mutex();
const unsubscribeUpdates = room.subscribe(root, (root) => {  void myMutex.runExclusive(async () => {    await fetch(/* ... */);  });});

Note that this may cause a performance penalty in your application, as certain updates will be ignored.

Room.subscribe("event")

Subscribe to events broadcast by Room.broadcastEvent. Takes a callback that’s run when another user calls Room.broadcastEvent. Provides the event along with the user and their connectionId of the user that sent the message. Returns an unsubscribe function.

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

Typing events

When defining your types, you can pass a RoomEvent type to 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  }});

Receiving events from the server

Events can be received from the server with either liveblocks.broadcastEvent or the Broadcast Event API. In events sent from the server, user will be null, and connectionId will be -1.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "sk_prod_xxxx…xxxxxxsk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
export async function POST() {  await liveblocks.broadcastEvent({ type: "REACTION", emoji: "🔥" });}

const unsubscribe = room.subscribe("event", ({ event, user, connectionId }) => {  // `null`, `-1`  console.log(user, connectionId);});

Room.subscribe("my-presence")

Subscribe to the current user’s Presence. Takes a callback that is called every time the current user presence is updated with Room.updatePresence. Returns an unsubscribe function.

const unsubscribe = room.subscribe("my-presence", (presence) => {  // Do something});

Typing Presence

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

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

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

const unsubscribe = room.subscribe("my-presence", (presence) => {  // { status: "typing", cursor: { x: 45, y: 67 }  console.log(presence);});

Room.subscribe("others")

Subscribe to every other users’ updates. Takes a callback that’s called when a user’s Presence updates, or when they enter or leave the room. Returns an unsubscribe function.

const unsubscribe = room.subscribe("others", (others, event) => {  // Do something});

Typing Presence

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

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

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

const unsubscribe = room.subscribe("others", (others, event) => {  // { status: "typing", cursor: { x: 45, y: 67 }  console.log(others[0].presence);});

Listening for others events

The event parameter returns information on why the callback has just run, for example if their Presence has updated, if they’ve just left or entered the room, or if the current user has disconnected.

const unsubscribe = room.subscribe("others", (others, event) => {  if (event.type === "leave") {    // A user has left the room    // event.user;  }
  if (event.type === "enter") {    // A user has entered the room    // event.user;  }
  if (event.type === "update") {    // A user has updated    // event.user;    // event.updates;  }
  if (event.type === "reset") {    // A disconnection has occurred and others has reset  }});

Live cursors

Here’s a basic example showing you how to render live cursors. Room.updatePresence is being used to update each user’s cursor position.

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

const { room, leave } = client.enterRoom("my-room-id");
// Call this to update the current user's Presencefunction updateCursorPosition({ x, y }) {  room.updatePresence({ cursor: { x, y } });}
const others = room.getOthers();
// Run __renderCursor__ when any other connected user updates their presenceconst unsubscribe = room.subscribe("others", (others, event) => {  for (const { id, presence } of others) {    const { x, y } = presence.cursor;    __renderCursor__(id, { x, y });  }}
// Handle events and rendering// ...

Check our examples page for live demos.

Room.subscribe("status")

Subscribe to WebSocket connection status updates. Takes a callback that is called whenever the connection status changes. Possible value are: initial, connecting, connected, reconnecting, or disconnected. Returns an unsubscribe function.

const unsubscribe = room.subscribe("status", (status) => {  // "connected"  console.log(status);});

When to use status

Status is a low-level API that exposes the WebSocket’s connectivity status. You can use this, for example, to update a connection status indicator in your UI. It would be normal for a client to briefly lose the connection and restore it with quick connected → reconnecting → connected status jumps.

let indicator = "⚪";
const unsubscribe = room.subscribe("status", (status) => {  switch (status) {    case "connecting":      indiciator = "🟡";      break;    case "connected":      indicator = "🟢";      break;    // ...  }});

If you’d like to let users know that there may be connectivity issues, don’t use this API, but instead refer to Room.subscribe("lost-connection") which was specially built for this purpose.

Do not use this API to detect when Storage or Presence are initialized or loaded. "Connected" does not guarantee that Storage or Presence are ready. To detect when Storage is loaded, rely on awaiting the Room.getStorage promise or using the Room.subscribe("storage-status") event.

Room.subscribe("lost-connection")

A special-purpose event that will fire when a previously connected Liveblocks client has lost connection, for example due to a network outage, and was unable to recover quickly. This event is designed to help improve UX for your users, and will not trigger on short interruptions, those that are less than 5 seconds by default. The event only triggers if a previously connected client disconnects.

const unsubscribe = room.subscribe("lost-connection", (event) => {  // "lost"  console.log(event);});

When to use lost connection events

Lost connections events allows you to build high-quality UIs by warning your users that the application is still trying to re-establish the connection, for example through a toast notification. You may want to take extra care in the mean time to ensure their changes won’t go unsaved, or to help them understand why they’re not seeing updates made by others yet.

When this happens, this callback is called with the event lost. Then, once the connection restores, the callback will be called with the value restored. If the connection could definitively not be restored, it will be called with failed (uncommon).

import { toast } from "my-preferred-toast-library";
const unsubscribe = room.subscribe("lost-connection", (event) => {  switch (event) {    case "lost":      toast.warn("Still trying to reconnect...");      break;
    case "restored":      toast.success("Successfully reconnected again!");      break;
    case "failed":      toast.error("Could not restore the connection");      break;  }});

Setting lost connection timeout

The lostConnectionTimeout configuration option will determine how quickly the event triggers after a connection loss occurs. By default, it’s set to 5000ms, which is 5 seconds.

import { createClient } from "@liveblocks/client";
const client = createClient({  // Throw lost-connection event after 5 seconds offline  lostConnectionTimeout: 5000,
  // ...});

Room.subscribe("error")

Subscribe to unrecoverable room connection errors. This event will be emitted immediately before the client disconnects and won’t try reconnecting again. Returns an unsubscribe function. If you’d like to retry connecting, call room.reconnect.

const unsubscribe = room.subscribe("error", (error) => {  switch (error.code) {    case -1:      // Authentication error      break;
    case 4001:      // Could not connect because you don't have access to this room      break;
    case 4005:      // Could not connect because room was full      break;
    case 4006:      // The room ID has changed, get the new room ID (use this for redirecting)      const newRoomId = error.message;      break;
    default:      // Unexpected error      break;  }});

When to use error events

You can use this event to trigger a “Not allowed” screen/dialog. It can also be helpful for implementing a redirect to another page.

const unsubscribe = room.subscribe("error", (error) => {  // Could not connect because you don't have access to this room  if (error.code === 4001)    return __displayForbiddenEntryDialog__();  }});