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

    Returns a Client, used for connecting to Liveblocks.

Options
  • authEndpoint

    The URL of your back end’s authentication endpoint as a string, or an async callback function that returns a Liveblocks token result. Either authEndpoint or publicApikey are required. Learn more about using a URL string and using a callback.

  • publicApiKeystring

    The public API key taken from your project’s dashboard. Generally not recommended for production use. Either authEndpoint or publicApikey are required. Learn more.

  • throttlenumberDefault is 100

    The throttle time between WebSocket messages in milliseconds, a number between 16 and 1000 is allowed. Using 16 means your app will update 60 times per second. Learn more.

  • lostConnectionTimeoutnumberDefault is 5000

    After a user disconnects, the time in milliseconds before a "lost-connection" event is fired. Learn more.

  • backgroundKeepAliveTimeoutnumber

    The time before an inactive WebSocket connection is disconnected. This is disabled by default, but setting a number will activate it. Learn more.

  • resolveUsers

    A function that resolves user information in Comments. Return an array of TUserMeta["info"] objects in the same order they arrived. Learn more.

  • resolveRoomsInfo

    A function that resolves room information in Comments. Return an array of RoomInfo objects in the same order they arrived. Learn more.

  • resolveMentionSuggestions

    A function that resolves mention suggestions in Comments. Return an array of user IDs. Learn more.

  • polyfills

    Place polyfills for atob, fetch, and WebSocket inside here. Useful when using a non-browser environment, such as Node.js or React Native.

  • unstable_fallbackToHTTPbooleanDefault is false

    Experimental. Automatically fall back to HTTP when a message is too large for WebSockets.

  • unstable_streamDatabooleanDefault is false

    Experimental. Stream the initial Storage content over HTTP, instead of waiting for a large initial WebSocket message to be sent from the server.

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: "",});

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

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 (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 (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 (roomId);
if (!text) { // Show all workspace users by default return (workspaceUsers); } else { const matchingUsers = (workspaceUsers, text); return (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.

Returns
  • roomRoom<TPresence, TStorage, TUserMeta, TRoomEvent>

    A Room, used for building your Liveblocks application. Learn more about typing your room.

  • leave() => void

    A function that’s used to leave the room and disconnect.

Arguments
  • roomIdstringRequired

    The ID of the room you’re connecting to.

  • options.initialPresenceJsonObject

    The initial Presence of the user entering the room. Each user has their own presence, and this is readable for all other connected users. A user’s Presence resets every time they disconnect. This object must be JSON-serializable. Learn more.

  • options.initialStorageLsonObject

    The initial Storage structure for the room when it’s joined for the first time. This is only set a single time, when the room has not yet been populated. This object must contain conflict-free live structures. Learn more.

  • options.autoConnectbooleanDefault is true

    Whether the room immediately connects to Liveblocks servers.

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.

Returns
  • roomRoom<TPresence, TStorage, TUserMeta, TRoomEvent> | null

    A Room, used for building your Liveblocks application. Returns null if the room has not yet been joined by the current client. Learn more about typing your room.

Arguments
  • roomIdstringRequired

    The ID of the room you’re connecting to.

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();
Returns
Nothing
Arguments
None

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:

liveblocks.config.ts
declare global {  interface Liveblocks {    Presence: {      cursor: { x: number; y: number };    };  }}
Returns
  • presenceTPresence

    An object holding the Presence value for the currently connected user. Presence is set with updatePresence. Will always be JSON-serializable. TPresence is the Presence type you set yourself, learn more.

Arguments
None

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();
Returns
Nothing
Arguments
  • updateTPresenceRequired

    The updated Presence properties for the current user inside an object. The user’s entire Presence object will not be replaced, instead these properties will be merged with the existing Presence. This object must be JSON-serializable.

  • options.addToHistorybooleanDefault is false

    Adds Presence values to the history stack, meaning using undo and redo functions will change them. Learn more.

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}
Returns
  • othersUser<TPresence, TUserMeta>[]

    An array holding each connected user’s User object. User contains the current user’s Presence value, along with other information. Presence is set with updatePresence. Returns an empty array when no other users are currently connected. Will always be JSON-serializable.

Arguments
None

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: "🔥" });
Returns
Nothing
Arguments
  • eventTRoomEventRequired

    The event to broadcast to every other user in the room. Must be JSON-serializable. TRoomEvent is the RoomEvent type you set yourself, learn more.

  • options.shouldQueueEventIfNotReadybooleanDefault is false

    Queue the event if the connection is currently closed, or has not been opened yet. We’re not sure if we want to support this option in the future so it might be deprecated to be replaced by something else. Learn more.

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();
Returns
  • userUser<TPresence, TUserMeta> | null

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

Arguments
None

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);
Returns
  • status"initial" | "connecting" | "connected" | "reconnecting" | "disconnected"

    Returns the room’s current connection status. It can return one of five values:

    • "initial" The room has not attempted to connect yet.
    • "connecting" The room is currently authenticating or connecting.
    • "connected" The room is connected.
    • "reconnecting" The room has disconnected, and is trying to connect again.
    • "disconnected" The room is disconnected, and is no longer attempting to connect.
Arguments
None

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);
Returns
  • status"not-loaded" | "loading" | "synchronizing" | "synchronized"

    The current room’s Storage status. status can be one of four types.

    • "not-loaded Storage has not been loaded yet as room.getStorage has not been called.
    • "loading" Storage is currently loading for the first time.
    • "synchronizing" Local Storage changes are currently being synchronized.
    • "synchronized" Local Storage changes have been synchronized.
Arguments
None

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});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • storageItemL extends (LiveObject | LiveMap | LiveList)Required

    The LiveObject, LiveMap, or LiveList which is being subscribed to. Each time the structure is updated, the callback is called.

  • callback(node: L) => voidRequired

    Function that’s called when storageItem updates. Returns the updated storage structure.

  • options.isDeepboolean

    Subscribe to both storageItem and its children. The callback function will be passed a list of updates instead of just the new Storage item. Learn more.

Typing Storage

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

liveblocks.config.ts
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.

liveblocks.config.ts
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 }});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"event"Required

    Listen to events.

  • callbackRequired

    Function that’s called when another user sends an event. Receives the event, the user that sent the event, and their connectionId. If this event was sent via liveblocks.broadcastEvent or the Broadcast event API, user will be null and connectionId will be -1. Learn more

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: "",});
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});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"my-presence"Required

    Listen to the current user’s presence.

  • callback(presence: TPresence) => voidRequired

    Function that’s called when the current user’s Presence has updated, for example with Room.updatePresence. Receives the updates Presence value.

Typing Presence

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

liveblocks.config.ts
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});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"others"Required

    Listen to others.

  • callback(others: User<TPresence, TUserMeta>[], event: OthersEvent) => voidRequired

    Function that’s called when another user’s Presence has updated, for example with Room.updatePresence, or an others event has occurred. Receives an array of User values for each currently connected user. Also received an object with information about the event that has triggered the update, learn more.

Typing Presence

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

liveblocks.config.ts
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.

liveblocks.config.ts
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; (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);});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"status"Required

    Listen to status updates.

  • callbackRequired

    Function that’s called when the room’s connection status has changed. It can return one of five values:

    • "initial" The room has not attempted to connect yet.
    • "connecting" The room is currently authenticating or connecting.
    • "connected" The room is connected.
    • "reconnecting" The room has disconnected, and is trying to connect again.
    • "disconnected" The room is disconnected, and is no longer attempting to connect.

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 connectedreconnectingconnected 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);});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"lost-connection"Required

    Listen to lost connection events.

  • callbackRequired

    Function that’s called when a room’s lost connection event has been triggered. It can return one of three values:

    • "lost" A connection has been lost for longer than lostConnectionTimeout.
    • "restored" The connection has been restored again.
    • "failed" The room has been unable to reconnect again, and is no longer trying. This may happen if a user’s network has recovered, but the room’s authentication values no longer allow them to enter.

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; }});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"error"Required

    Listen to error events.

  • callbackRequired

    Function that’s called when an unrecoverable error event has been triggered. error.code can return one of these values:

    • -1 Authentication error.
    • 4001 Could not connect because you don't have access to this room.
    • 4005 Could not connect because room was full.
    • 4006 The room ID has changed.

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

When a room ID has changed

When a room ID has been changed with liveblocks.updateRoomId or the Update Room ID API, error.message will contain the new room ID.

const unsubscribe = room.subscribe("error", (error) => {  // The room ID has changed, get the new room ID  if (error.code === 4006)    const newRoomId = error.message;    return (`/app/${newRoomId}`)  }});

Room.subscribe("history")

Subscribe to the current user’s history changes. Returns an unsubscribe function.

const unsubscribe = room.subscribe("history", ({ canUndo, canRedo }) => {  // Do something});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"history"Required

    Listen to history events.

  • callbackRequired

    Function that’s called when the current user’s history changes. Returns booleans that describe whether the user can use undo or redo.

Room.subscribe("storage-status")

Subscribe to Storage status changes. Use this to tell whether Storage has been synchronized with the Liveblocks servers. Returns an unsubscribe function.

const unsubscribe = room.subscribe("storage-status", (status) => {  switch (status) {    case "not-loaded":      // Storage has not been loaded yet      break;    case "loading":      // Storage is currently loading      break;    case "synchronizing":      // Local Storage changes are being synchronized      break;    case "synchronized":      // Local Storage changes have been synchronized      break;  }});
Returns
  • unsubscribe() => void

    Unsubscribe function. Call it to cancel the subscription.

Arguments
  • eventType"storage-status"Required

    Listen to Storage status events.

  • callbackRequired

    Function that’s called when the current user’s Storage updated status have changed. status can be one of four types.

    • "not-loaded - Storage has not been loaded yet as [getStorage][] has not been called.
    • "loading" - Storage is currently loading for the first time.
    • "synchronizing" - Local Storage changes are currently being synchronized.
    • "synchronized" - Local Storage changes have been synchronized

Room.batch

Batches Storage and Presence modifications made during the given function. Each modification is grouped together, which means that other clients receive the changes as a single message after the batch function has run. When undoing or redoing these changes, the entire batch will be undone/redone together instead of atomically.

const { root } = await room.getStorage();
room.batch(() => { root.set("x", 0); room.updatePresence({ cursor: { x: 100, y: 100 } });});
Returns
  • returnT

    Returns the return value from the callback.

Arguments
  • callback() => TRequired

    A callback containing every Storage and Presence notification that will be part of the batch. Cannot be an async function.

When to batch updates

For the most part, you don’t need to batch updates. For example, given a whiteboard application, it’s perfectly fine to update a note’s position on the board multiple times per second, in separate updates. However, should you implement a “Delete all” button, that may delete 50 notes at once, this is where you should use a batch.

const { root } = await room.getStorage();const notes = root.get("notes");
// ✅ Batch simultaneous changes togetherroom.batch(() => { for (const noteId of notes.keys()) { notes.delete(noteId); }});

This batch places each LiveMap.delete call into a single WebSocket update, instead of sending multiple updates. This will be much quicker.

Batching groups history changes

Batching changes will also group changes into a single history state.

const { root } = await room.getStorage();const pet = root.set("pet", new LiveObject({ name: "Fido", age: 5 }));
// ✅ Batch groups changes into oneroom.batch(() => { pet.set("name", "Felix"); pet.set("age", 10);});
// { name: "Felix", age: 10 }pet.toImmutable();
room.history.undo();
// { name: "Fido", age: 5 }pet.toImmutable();

Doesn’t work with async functions

Note that room.batch cannot take an async function.

// ❌ Won't workroom.batch(async () => {  // ...});
// ✅ Will workroom.batch(() => { // ...});

Room.history

Room’s history contains functions that let you undo and redo operations made to Storage and Presence on the current client. Each user has a separate history stored in memory, and history is reset when the page is reloaded.

const { undo, redo, pause, resume /*, ... */ } = room.history;

Add Presence to history

By default, history is only enabled for Storage. However, you can use the addToHistory option to additionally add Presence state to history.

room.updatePresence({ color: "blue" }, { addToHistory: true });

Room.history.undo

Reverts the last operation. It does not impact operations made by other clients, and will only undo changes made by the current client.

const person = new LiveObject();person.set("name", "Pierre");person.set("name", "Jonathan");
room.history.undo();
// "Pierre"root.get("name");
Returns
Nothing
Arguments
None

Room.history.redo

Restores the last undone operation. It does not impact operations made by other clients, and will only restore changes made by the current client.

const person = new LiveObject();person.set("name", "Pierre");person.set("name", "Jonathan");
room.history.undo();room.history.redo();
// "Jonathan"root.get("name");
Returns
Nothing
Arguments
None

Room.history.canUndo

Returns true or false, depending on whether there are any operations to undo. Helpful for disabling undo buttons.

const person = new LiveObject();person.set("name", "Pierre");
// trueroom.history.canUndo();
room.history.undo();
// falseroom.history.canUndo();
Returns
  • canUndoboolean

    Whether there is an undo operation in the current history stack.

Arguments
None