API Reference - @liveblocks/yjs

@liveblocks/yjs is a Yjs provider enabling you to use Liveblocks as the hosted back end of your real-time collaborative application. Read our getting started guides to learn more.

LiveblocksProvider

LiveblocksProvider is a Yjs provider that allows you to connect a Yjs document to Liveblocks. Any changes you make to the document will be stored on Liveblocks servers and synchronized with other clients in the room.

You can connect by creating a Yjs document, then passing it to LiveblocksProvider along with the currently connected Liveblocks room.

import * as Y from "yjs";import { createClient } from "@liveblocks/client";import LiveblocksProvider from "@liveblocks/yjs";
const client = createClient({  publicApiKey: "",});
const { room, leave } = client.enterRoom("your-room-id", {  initialPresence: {},});
// Create Yjs document and providerconst yDoc = new Y.Doc();const yProvider = new LiveblocksProvider(room, yDoc);

When using @liveblocks/react you can connect by using LiveblocksProvider within an effect, taking the room from useRoom, and cleaning up afterwards.

import { useEffect } from "react";import * as Y from "yjs";import LiveblocksProvider from "@liveblocks/yjs";import { useRoom } from "../liveblocks.config.ts";
function Component() {  const room = useRoom();
  useEffect(() => {    // Create Yjs document and provider    const yDoc = new Y.Doc();    const yProvider = new LiveblocksProvider(room, yDoc);
    // ...
    return () => {      yDoc.destroy();      yProvider.destroy();    };  }, [room]);
  // ...}

LiveblocksProvider.awareness

The awareness instance attached to the provider.

// Yjs awarenessconst awareness = yProvider.awareness;

LiveblocksProvider.destroy

Cleanup function. Destroys the LiveblocksProvider instance and removes all resources.

// Clean up yProvideryProvider.destroy();

LiveblocksProvider.on("sync")

Add an event listener for the sync event. The sync event is triggered when the client has received content from the server. Can be used to fire events when the document has loaded.

// Listen for the sync eventyProvider.on("sync", (isSynced: boolean) => {  if (isSynced === true) {    // Yjs content is synchronized and ready  } else {    // Yjs content is not synchronized  }});

Aliased by LiveblocksProvider.on("synced").

// "sync" and "synced" both listen to the same eventyProvider.on("sync", (sync: boolean) => /* ... */);yProvider.on("synced", (sync: boolean) => /* ... */);

LiveblocksProvider.off("sync")

Remove an event listener for the sync event. The sync event is triggered when the client has received content from the server. Used to clean up LiveblocksProvider.on("sync").

const handleSync = (synced: boolean) => {};yProvider.on("sync", handleSync);
// Clean up sync eventyProvider.off("sync", handleSync);

Aliased by LiveblocksProvider.on("synced").

// "sync" and "synced" both listen to the same eventyProvider.off("sync", (sync: boolean) => /* ... */);yProvider.off("synced", (sync: boolean) => /* ... */);

LiveblocksProvider.once("sync")

Add a one-time event listener for the sync event. The sync event is triggered when the client has received content from the server. Can be used to fire events when the document has loaded.

// Listen for the sync event only onceyProvider.once("sync", (isSynced: boolean) => {  if (isSynced === true) {    // Yjs content is synchronized and ready  } else {    // Yjs content is not synchronized  }});

Aliased by LiveblocksProvider.once("synced").

// "sync" and "synced" both listen to the same eventyProvider.once("sync", (sync: boolean) => /* ... */);yProvider.once("synced", (sync: boolean) => /* ... */);

LiveblocksProvider.emit("sync")

Synchronously call each listener for the sync event in the order they were registered, passing the supplied arguments to each.

// Call each listener and pass `true` as an argumentyProvider.emit("sync", true);

Aliased by LiveblocksProvider.emit("synced").

// "sync" and "synced" both listen to the same eventyProvider.emit("sync" /* , ... */);yProvider.emit("synced" /* , ... */);

LiveblocksProvider.synced

Boolean. Returns whether the client is synchronized with the back end.

// Check if Yjs content is synchronized with the serverconst isSynced: boolean = yProvider.synced;

LiveblocksProvider.connect

Does nothing, added for compatibility. Connections are handled by the Liveblocks client.

LiveblocksProvider.disconnect

Does nothing, added for compatibility. Connections are handled by the Liveblocks client.

Awareness

LiveblocksProvider instances have an awareness property, which is powered by Liveblocks Presence. You can pass it to various bindings which implement awareness, for example plugins that enable multiplayer cursors in text editors.

const yDoc = new Y.Doc();const yProvider = new LiveblocksProvider(room, yDoc);
// Yjs awarenessconst awareness = yProvider.awareness;

Because awareness is part of presence, it’s also accessible with room.getPresence and useMyPresence under the __yjs property.

// Yjs awarenessconst awareness = room.getPresence().__yjs;

Awareness.doc

The Yjs document that the current awareness instance is attached to.

// The current Yjs documentconst yDoc: Y.Doc = awareness.doc;

Awareness.clientId

A unique number identifying which client this awareness object is attached to.

// A unique number representing the current userconst clientId: number = awareness.clientId;

Awareness.getLocalState

Get the current user’s awareness state.

// The current user’s awarenessconst localState: unknown = awareness.getLocalState();

Awareness.setLocalState

Set the current user’s awareness state. Accepts JSON-compatible objects.

// Set the current user’s awarenessawareness.setLocalState({  user: {    name: "Jonathan",  },});

Awareness.setLocalStateField

Set a single property in the current user’s awareness state. Accepts JSON-compatible objects, or null to remove a property.

// Set a single property on the current user’s awarenessawareness.setLocalStateField("user", { name: "Jonathan" });

Awareness.getStates

Returns a Map of states for each client, with each user’s unique clientId as the key.

// A Map of each user’s awareness stateconst states: Map<number, unknown> = awareness.getStates();

Awareness.states

A Map of states for each client, with each user’s unique clientId as the key.

// A Map of each user’s awareness stateconst states: Map<number, unknown> = awareness.states;

Awareness.meta

Provided for compatibility, but generally not necessary. This would be used for handling user awareness timeouts, but internally awareness uses Liveblocks Presence, and this handles it for you.

const meta: Map<number, { click: number; lastUpdated: number }> =  awareness.meta;

Awareness.destroy

Provided for compatibility, but generally not necessary. Cleanup function. Destroys the Awareness instance and removes all resources. Used internally by LiveblocksProvider.

// Cleanup functionawareness.destroy();

Awareness.on("destroyed")

Provided for compatibility, but generally not necessary. Add an event listener for the destroy event. The destroy event is triggered when awareness.destroy has been called.

awareness.on("destroyed", () => {  // Awareness has been cleaned up});

Awareness.off("destroyed")

Provided for compatibility, but generally not necessary. Remove an event listener for the destroy event. The destroy event is triggered when awareness.destroy has been called. Used to clean up [Awareness.on("destroyed").]

const handleDestroy = () => {};awareness.on("destroyed", handleDestroy);
// Clean up destroy eventawareness.off("destroyed", handleDestroy);

Awareness.once("destroyed")

Provided for compatibility, but generally not necessary. Add a one-time event listener for the destroy event. The destroy event is triggered when awareness.destroy has been called.

awareness.once("destroyed", () => {  // Awareness has been cleaned up});

Awareness.emit("destroyed")

Synchronously call each listener for the destroy event in the order they were registered, passing the supplied arguments to each.

// Call each listener and pass `true` as an argumentawareness.emit("destroy", true);