API Reference

@liveblocks/zustand

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

Middleware

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

Arguments

  • stateCreator: Zustand state creator function.
  • options: Liveblocks Middleware Options
    • client: The Liveblocks client instance created with createClient().
    • presenceMapping: Optional mapping to synchronize Zustand state with Liveblocks presence.
    • storageMapping: Optional mapping to synchronize Zustand state with Liveblocks storage.

client

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

presenceMapping

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

storageMapping

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

state.liveblocks

Liveblocks extra state attached by the liveblocks.

enterRoom

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

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

Arguments

  • roomId: string - The ID of the room to enter.
  • options: object
    • engine: 1 | 2 - Preferred storage engine version to use when creating the room. Only takes effect if the room doesn't exist yet.

leaveRoom

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

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

room

The Room currently synced to your Zustand state.

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

others

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

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

isStorageLoading

Whether or not the room storage is currently loading.

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

status

Gets the current WebSocket connection status of the room.

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

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