API Reference - @liveblocks/zustand

@liveblocks/zustand provides you with Zustand bindings for our real-time collaboration APIs, built on top of WebSockets. Read our getting started guides to learn more.


The liveblocks middleware lets you connect a Zustand state to Liveblocks Presence and Storage features.

import create from "zustand";import { liveblocks } from "@liveblocks/zustand";
const useStore = create( liveblocks( (set) => ({ /* state and actions */ }), { client, presenceMapping: {}, storageMapping: {}, } ));


See different authentication methods in the createClient method.

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


Mapping used to synchronize a part of your Zustand state with one Liveblocks Room presence.

const useStore = create(  liveblocks(    (set) => ({      cursor: { x: 0, y: 0 },    }),    {      client,      presenceMapping: { cursor: true },    }  ));


Mapping used to synchronize a part of your Zustand state with one Liveblocks room storage.

const useStore = create(  liveblocks(    (set) => ({      scientist: { name: "" },    }),    {      client,      storageMapping: { scientist: true },    }  ));


Liveblocks extra state attached by the liveblocks.


Enters a room and starts syncing it with your Zustand state.

  • roomId: The room’s ID.
const {  liveblocks: { enterRoom },} = useStore();

If this is the first time you’re entering the room, the room is initialized from your local Zustand state (only for the keys mentioned in your storageMapping configuration).


Leaves the current room and stops syncing it with Zustand state.

const {  liveblocks: { leaveRoom },} = useStore();


The Room currently synced to your Zustand state.

const {  liveblocks: { room },} = useStore();


Other users in the room. Empty when no room is currently synced.

const {  liveblocks: { others },} = useStore();


Whether or not the room storage is currently loading.

const {  liveblocks: { isStorageLoading },} = useStore();


Gets the current WebSocket connection status of the room.

const {  liveblocks: { status },} = useStore();

The possible value are: initial, connecting, connected, reconnecting, or disconnected.

connection (legacy)

Legacy connection status of the room. This property exists for backward compatibility reasons, but it’s no longer recommended.

The value can be: authenticating, connecting, open, failed, closed or unavailable.

const {  liveblocks: { connection },} = useStore();