` element under the hood. Inline styles to apply to the code element. Inline styles to apply to the strong element. Inline styles to apply to the mention element. Inline styles to apply to the link element. #### Resolving data [#prepare-text-mention-notification-email-as-html-resolving-data] Similarly to on the client, you can resolve [users](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers), [group info](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveGroupsInfo), and [room info](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo), making it easier to render your emails. For example, you can resolve a user’s ID into their name, and show their name in the email. When resolving users and groups, the function receives a list of IDs and you should return a list of objects of the same size, in the same order. ```tsx const emailData = await prepareTextMentionNotificationEmailAsHtml( liveblocks, webhookEvent, { // +++ resolveUsers: async ({ userIds }) => { const usersData = await __getUsersFromDB__(userIds); return usersData.map((userData) => ({ name: userData.name, // "Nimesh" avatar: userData.avatar.src, // "https://..." })); }, resolveGroupsInfo: async ({ groupIds }) => { const groupsData = await __getGroupsFromDB__(groupIds); return groupsData.map((groupData) => ({ name: groupData.name, // "Engineering" avatar: groupData.avatar.src, // "https://..." })); }, resolveRoomInfo({ roomId }) { return { name: roomId, // "my-room-name" url: `https://example.com/${roomId}`, }; }, // +++ } ); // { mention: { ... }, ... } console.log(emailData); // { name: "Nimesh", avatar: "https://..." } console.log(emailData.mention.author.info); // { name: "my-room-name", url: "https://example.com/my-room-name" } console.log(emailData.roomInfo); ``` #### Styling elements [#prepare-text-mention-notification-email-as-html-styling-elements] Each element in the comment body can be styled with custom CSS properties, if you would like to change the appearance. Five elements are available: `paragraph`, `code`, `strong`, `mention`, and `link`. ```tsx const emailData = await prepareTextMentionNotificationEmailAsHtml( liveblocks, webhookEvent, { // +++ styles: { paragraph: { margin: "12px 0" }, mention: { fontWeight: "bold", color: "red", }, }, // +++ } ); // { mention: { ... }, ... } console.log(emailData); // The elements in the mention content are now styled console.log(emailData.mention.content); ``` --- meta: title: "@liveblocks/node-lexical" parentTitle: "API Reference" description: "API Reference for the @liveblocks/node-lexical package" alwaysShowAllNavigationLevels: false --- `@liveblocks/node-lexical` provides a Node.js package to export and modify [Lexical](https://lexical.dev/) documents on the server. ## withLexicalDocument `withLexicalDocument` is the main entry point to modifying a document on the server. It takes a room ID and a [Liveblocks Node client](/docs/api-reference/liveblocks-node#Liveblocks-client), and returns a callback used to work with Lexical documents stored in Liveblocks. ```ts highlight="8-14" import { Liveblocks } from "@liveblocks/node"; import { withLexicalDocument } from "@liveblocks/node-lexical"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); await withLexicalDocument( { roomId: "your-room-id", client: liveblocks }, async (doc) => { // Modify your Lexical `doc` // ... } ); ``` Returns the value you return from the `doc` callback. The ID of the room to use. The [Liveblocks client](/docs/api-reference/liveblocks-node#Liveblocks-client) to use. Optional. The Lexical nodes used in the document. Will extend the default schema which uses Liveblocks mentions and Liveblocks comments. ### Returning data Get your editor’s text content by returning `doc.getTextContent` inside the callback. ```ts const textContent = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.getTextContent(); } // +++ ); // "My content" console.log(textContent); ``` ### Custom nodes If your Lexical document has custom nodes, they must be passed into the `withLexicalDocument`, similarly to with a front end Lexical client. ```ts highlight="4" import { CodeNode } from "@lexical/code"; await withLexicalDocument( { roomId: "my-room-id", client: liveblocks, nodes: [CodeNode] }, async (doc) => { // Modify your Lexical `doc` // ... } ); ``` ### Lexical document API You can easily modify your document with the Lexical document API. #### doc.update Liveblocks provides `doc.update` which is a callback function similar to Lexical’s `editor.update`. This makes it easy to use Lexical’s editor functions. Any edits will be persisted and appear in realtime to connected users as soon as the `update` promise resolves. Unlike Lexical’s `editor.update`, this change is always discrete. The callback can also be an `async` function. ```ts await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, async (doc) => { // +++ await doc.update(() => { // Make your modifications // ... }); // +++ } ); ``` _Nothing_ Callback function where you should handle your modifications. ##### Example usage Here’s an example of some modifications to a Lexical document. ```ts import { $getRoot } from "lexical"; import { $createParagraphNode, $createTextNode } from "lexical/nodes"; await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, async (doc) => { await doc.update(() => { // Adding a paragraph node with contained text node // +++ const root = $getRoot(); const paragraphNode = $createParagraphNode(); const textNode = $createTextNode("Hello world"); paragraphNode.append(textNode); root.append(paragraphNode); // +++ }); } ); ``` #### doc.getTextContent Returns the text content from the root node as a `string`. ```ts const textContent = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.getTextContent(); } // +++ ); ``` Returns the text retrieved from the document. _None_ #### doc.getEditorState Returns Lexical’s [editorState](https://lexical.dev/docs/concepts/editor-state). ```ts const editorState = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.getEditorState(); } // +++ ); ``` Your editor’s Lexical state. _None_ #### doc.getLexicalEditor Returns a headless Lexical editor. [@lexical/headless](https://lexical.dev/docs/packages/lexical-headless). ```ts const headlessEditor = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.getLexicalEditor(); } // +++ ); ``` Your headless Lexical editor. _None_ #### doc.toJSON Returns a serialized JSON object representation of your document. See Lexical’s [Serialization & Deserialization](https://lexical.dev/docs/concepts/serialization) page for more information. ```ts const docAsJSON = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.toJSON(); } // +++ ); ``` A serialized JSON object representation of your document. _None_ #### doc.toMarkdown Returns a markdown `string` of your document. See Lexical’s [@lexical/markdown](https://lexical.dev/docs/concepts/serialization) page for more information. ```ts const markdown = await withLexicalDocument( { roomId: "my-room-id", client: liveblocks }, // +++ async (doc) => { return doc.toMarkdown(); } // +++ ); ``` Returns the markdown string. _None_ --- meta: title: "@liveblocks/node-prosemirror" parentTitle: "API Reference" description: "API Reference for the @liveblocks/node-prosemirror package" alwaysShowAllNavigationLevels: false --- `@liveblocks/node-prosemirror` provides a Node.js package to export and modify [ProseMirror](https://prosemirror.net/). Because Tiptap uses ProseMirror under the hood, this package can be used to modify [Tiptap](/docs/api-reference/liveblocks-react-tiptap) documents as well. ## withProsemirrorDocument `withProsemirrorDocument` is the main entry point to modifying a document on the server. It takes a room ID and a [Liveblocks Node client](/docs/api-reference/liveblocks-node#Liveblocks-client), and returns a callback used to work with ProseMirror documents stored in Liveblocks. ```ts highlight="8-14" import { Liveblocks } from "@liveblocks/node"; import { withProsemirrorDocument } from "@liveblocks/node-prosemirror"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); await withProsemirrorDocument( { roomId: "your-room-id", client: liveblocks }, (api) => { // Modify your document with the api // ... } ); ``` Returns the value you return from the `api` callback. The ID of the room to use. The [Liveblocks client](/docs/api-reference/liveblocks-node#Liveblocks-client) to use. Optional. The ProseMirror schema to use for the document. If no schema is provided, the default schema is [Tiptap StarterKit](https://tiptap.dev/docs/editor/extensions/functionality/starterkit), Liveblocks mentions, and Liveblocks comments. Optional. The [field](/docs/api-reference/liveblocks-react-tiptap#Multiple-editors) to use for the document. Defaults to `default`. ### Returning data Get your editor’s text content by returning `api.getText()` inside the callback. ```ts const textContent = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, (api) => api.getText() ); // "My content" console.log(textContent); ``` ### ProseMirror document API You can easily modify your document with the ProseMirror document API. #### api.update Liveblocks provides `api.update` which is a callback that provides the current document and a ProseMirror transaction. This makes it easy to use ProseMirror’s built in functions. When you've finished, return the transaction and any changes will be persisted, and appear in realtime to connected users as soon as the `update` promise resolves. ```ts await withProsemirrorDocument( { client, roomId: "test-room", }, async (api) => { // +++ await api.update((doc, tr) => { return tr.insertText("Hello world"); }); // +++ } ); ``` _Nothing_ `doc` is the ProseMirror document. `tr` is an editor state transaction. Transaction is a subclass of ProseMirror’s Transforms. On the ProseMirror website you can find a full list of [transforms](https://prosemirror.net/docs/ref/#transform.Document_transforms) and [transactions functions](https://prosemirror.net/docs/ref/#state.Transaction). #### api.getText Returns the text content of the document. This API uses Tiptap’s `getText` internally. TextSerializers are a concept from [Tiptap](https://github.com/ueberdosis/tiptap/blob/3e59097b34ce8bc8c39e1def67eb31a1d9f9e5c2/packages/core/src/types.ts#L357). If you are having trouble with a ProseMirror document, you may want to use `api.getEditorState().doc.textBetween()` instead. ```ts const textContent = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.getText({ // Options // ... }); // +++ } ); ``` Returns the text retrieved from the document. Optional. The separator to use for blocks, e.g. `
`. Defaults to `\n\n`. Optional. The serializers to use for text. Defaults to `{}`. #### api.setContent For convenience, some methods such as `setContent` are provided at the API level. Here’s an example that sets a document and returns the JSON content after it has been updated. ```ts const exampleDoc = { type: "doc", content: [ { type: "paragraph", content: [ { type: "text", text: "Example Text", }, ], }, ], }; const json = await withProsemirrorDocument( { client, roomId: "test-room", }, async (api) => { // +++ await api.setContent(exampleDoc); // +++ return JSON.stringify(api.toJSON()); } ); ``` _Nothing_ The content to replace your document. #### api.getEditorState Returns the current ProseMirror state. ```ts const editorState = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.getEditorState(); // +++ } ); ``` Your editor’s ProseMirror state. _None_ #### api.toJSON Returns a serialized JSON object representation of your document. See ProseMirror’s [.toJSON](https://prosemirror.net/docs/ref/#state.EditorState.toJSON) documentation for more information. ```ts const docAsJSON = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.toJSON(); // +++ } ); ``` Your editor’s serialized JSON state. _None_ #### api.clearContent Clears the content of the document. ```ts await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.clearContent(); // +++ } ); ``` _Nothing_ _None_ #### api.toMarkdown Returns a markdown `string` of your document. ```ts const markdown = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.toMarkdown(); // +++ } ); ``` Returns the markdown string. Optional. A markdown serializer to use. By default it uses the `defaultMarkdownSerializer` from [prosemirror-markdown](https://github.com/prosemirror/prosemirror-markdown). ##### Custom markdown serializer You can use a custom markdown serializer. ```ts import { defaultMarkdownSerializer } from "prosemirror-markdown"; const mySerializer = new MarkdownSerializer({ marks: { ...defaultMarkdownSerializer.marks, em: { open: "*", close: "*", mixable: true, expelEnclosingWhitespace: true, }, }, }); const markdown = await withProsemirrorDocument( { roomId: "my-room-id", client: liveblocks }, async (api) => { // +++ return api.toMarkdown(mySerializer); // +++ } ); ``` --- meta: title: "@liveblocks/node" parentTitle: "API Reference" description: "API Reference for the @liveblocks/node package" alwaysShowAllNavigationLevels: false --- `@liveblocks/node` provides you with Node.js APIs for [authenticating Liveblocks users](#Liveblocks-client) and for [implementing webhook handlers](#WebhookHandler). This library is only intended for use in your Node.js back end. ## Liveblocks client [#Liveblocks-client] The `Liveblocks` client offers access to our REST API. ```ts showLineNumbers={false} import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); ``` ### Authentication [#Authorization] To authenticate your users with Liveblocks, you have the choice between two different APIs. - [`Liveblocks.identifyUser`](#id-tokens) ID token authentication is recommend for most applications. - [`Liveblocks.prepareSession`](#access-tokens) Access token authentication is best if you prefer handle permissions on your end, though it has [limitations](/docs/authentication/access-token#limitations). #### Liveblocks.identifyUser [#id-tokens] Creates an ID token that is used to authenticate a user in your application. This is a wrapper around the [Get ID Token API](/docs/api-reference/rest-api-endpoints#post-identify-user) and returns the same response. ```ts const { body, status } = await liveblocks.identifyUser({ // Required, the current user's ID userId: "marie@example.com", }); ``` Learn how to [get started with ID tokens](/docs/authentication). A number of options are also available, enabling you to set up permissions and user metadata. ```ts const { body, status } = await liveblocks.identifyUser( { // Required, the current user's ID userId: "marie@example.com", // Optional, only view resources on this organization organizationId: "acme-corp", // Optional, used to provision room access on group level groupIds: ["marketing", "engineering"], }, { // Optional, custom user metadata userInfo: { name: "Marie", color: "#00ff00", avatar: "https://example.com/avatar/marie.jpg", }, } ); ``` Never cache your access token authentication endpoint, as your client will not function correctly. The Liveblocks client will cache results for you, only making requests to the endpoint if necessary, such as when the token has expired. ##### Granting ID token permissions You can pass additional options to `identifyUser`, enabling you to create complex [workspace permissions](/docs/authentication#permissions) and [room permissions](/docs/authentication#Room-permissions). For example, this user can only see resources in the `acme-corp` workspace, and they’re part of a `marketing` rooms group within it. ```ts const { body, status } = await liveblocks.identifyUser({ // Required, the current user's ID userId: "marie@example.com", // Optional, only view resources on this workspace // +++ organizationId: "acme-corp", // +++ // Optional, used to provision room access on group level // +++ groupIds: ["marketing"], // +++ }); ``` Learn more about [ID token permissions](/docs/authentication#permissions). ##### Text editor user data When using [text editor integrations](/docs/ready-made-features/multiplayer#Text-editor-integrations), user data is inserted into their live cursor within the editor, showing their name and color. This data originates from the `userInfo` property. ```ts const { body, status } = await liveblocks.identifyUser( { // Required, the current user's ID userId: "marie@example.com", }, { // Optional, custom user metadata userInfo: { // Used in text editor live carets // +++ name: "Marie", color: "#00ff00", // +++ }, } ); ``` ##### Custom user metadata You can pass additional options to `prepareSession`, enabling you to add custom user metadata to the session. This metadata can be accessed by all users in the room, and is useful for building features such as live avatar stacks. ```ts const { body, status } = await liveblocks.identifyUser( { // Required, the current user's ID userId: "marie@example.com", }, { // Optional, custom user metadata userInfo: { // Add custom properties to use on front end, e.g. avatar stacks // +++ avatar: "https://example.com/avatar/marie.jpg", // +++ // ... }, } ); ``` To access it on the front end, use hooks such as [`useSelf`](/docs/api-reference/liveblocks-react#useSelf) and [`useOthers`](/docs/api-reference/liveblocks-react#useOthers). ```tsx const currentUser = useSelf(); // "https://example.com/avatar/marie.jpg" console.log(currentUser.info.avatar); ``` ##### How ID tokens work The purpose of this API is to help you implement your custom authentication back end (i.e. the _server_ part of the diagram). You use the `liveblocks.identifyUser()` API if you’d like to issue [ID tokens](/docs/authentication/id-token) from your back end. An ID token does not grant any permissions in the token directly. Instead, it only securely identifies your user, and then uses any permissions set via the [Permissions REST API][] to decide whether to allow the user on a room-by-room basis. Use this approach if you’d like Liveblocks to be the source of truth for your user’s permissions. Issuing identity tokens is like issuing _membership cards_. Anyone with a membership card can try to enter a room, but your permissions will be checked at the door. The Liveblocks servers perform this authorization, so your permissions need to be set up front using the Liveblocks REST API.

Implement your back end endpoint as follows: ```ts showLineNumbers={false} const { body, status } = await liveblocks.identifyUser( { userId: "marie@example.com", // Required, user ID from your DB groupIds: ["marketing", "engineering"], // Optional, identify the user in a specific organization organizationId: "acme-corp", }, // Optional { userInfo: { name: "Marie", avatar: "https://example.com/avatar/marie.jpg", }, } ); return new Response(body, { status }); ``` `userId` (required) is a string identifier to uniquely identify your user with Liveblocks. This value will be used when counting unique MAUs in your Liveblocks dashboard. You can refer to these user IDs in the [Permissions REST API][] when assigning group permissions. `groupIds` (optional) can be used to specify which groups this user belongs to. These are arbitrary identifiers that make sense to your app, and that you can refer to in the [Permissions REST API][] when assigning group permissions. `organizationId` (optional) is the organization for this user, will be set to `default` if not provided. `userInfo` (optional) is any custom JSON value, which you can use to attach static metadata to this user’s session. This will be publicly visible to all other people in the room. Useful for metadata like the user’s full name, or their avatar URL. ##### ID tokens example Here’s a real-world example of ID tokens in a Next.js route handler/endpoint. You can find examples for other frameworks in our [authentication section](/docs/authentication/id-token). ```ts file="Next.js" import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); export default async function auth(req, res) { /** * Implement your own security here. * * It's your responsibility to ensure that the caller of this endpoint * is a valid user by validating the cookies or authentication headers * and that it has access to the requested room. */ // Get the current user from your database const user = __getUserFromDB__(req); // Create an ID token for the user const { body, status } = await liveblocks.identifyUser( { userId: user.id, }, { userInfo: { name: user.fullName, color: user.favoriteColor, }, } ); return new Response(body, { status }); } ``` #### Liveblocks.prepareSession [#access-tokens] Creates an access token that is used to authenticate a user in your application. This is a wrapper around the [Get Access Token API](/docs/api-reference/rest-api-endpoints#post-authorize-user) and returns the same response. ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com" ); ``` Learn how to [get started with access tokens](/docs/authentication/access-token). A number of options are also available, enabling you to set up permissions and user metadata. ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com", { // Optional, only view resources on this organization organizationId: "acme-corp", // Optional, used to provision room access on group level groupIds: ["marketing"], // Optional, custom user metadata userInfo: { name: "Marie", color: "#00ff00", avatar: "https://example.com/avatar/marie.jpg", }, } ); ``` Never cache your access token authentication endpoint, as your client will not function correctly. The Liveblocks client will cache results for you, only making requests to the endpoint if necessary, such as when the token has expired. ##### Granting access token permissions Using `session.allow()`, you can grant full or read-only permissions to the user to select rooms. Wildcards can be used to enable granting permissions to multiple rooms at once using [naming patterns](/docs/authentication/access-token#Naming-pattern). ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com" ); // Giving access to an individual rooms session.allow("room-id-1", session.FULL_ACCESS); // Giving read-only access to this room session.allow("room-id-2", session.READ_ACCESS); // Giving access to multiple rooms with a wildcard // `design-room-1`, `design-room-2`, etc. session.allow("design-room:*", session.FULL_ACCESS); ``` Learn more about [access token permissions](/docs/authentication/access-token#permissions). Additionally, you can pass additional options to `prepareSession`, enabling you to create complex permissions using [organizations](/docs/authentication/organizations) and [accesses](/docs/authentication/access-tokens/permissions). For example, this user can only see resources in the `acme-corp` organization, and they're part of a `marketing` group within it. ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com", { // Optional, only view resources on this organization // +++ organizationId: "acme-corp", // +++ // Optional, used to provision room access on group level // +++ groupIds: ["marketing"], // +++ } ); ``` ##### Text editor user data When using [text editor integrations](/docs/ready-made-features/multiplayer#Text-editor-integrations), user data is inserted into their live cursor within the editor, showing their name and color. This data originates from the `userInfo` property of the session. ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com", { // Optional, user metadata userInfo: { // Used in text editor live carets // +++ name: "Marie", color: "#00ff00", // +++ }, } ); ``` ##### Custom user metadata You can pass additional options to `prepareSession`, enabling you to add custom user metadata to the session. This metadata can be accessed by all users in the room, and is useful for building features such as live avatar stacks. ```ts const session = liveblocks.prepareSession( // Required, the current user's ID "marie@example.com", { // Optional, custom user metadata userInfo: { // Add custom properties to use on front end, e.g. avatar stacks // +++ avatar: "https://example.com/avatar/marie.jpg", // +++ // ... }, } ); ``` To access it on the front end, use hooks such as [`useSelf`](/docs/api-reference/liveblocks-react#useSelf) and [`useOthers`](/docs/api-reference/liveblocks-react#useOthers). ```tsx const currentUser = useSelf(); // "https://example.com/avatar/marie.jpg" console.log(currentUser.info.avatar); ``` ##### How access tokens work The purpose of this API is to help you implement your custom authentication back end (i.e. the _server_ part of the diagram). You use the `liveblocks.prepareSession()` API if you’d like to issue [access tokens](/docs/authentication/access-token) from your back end. Issuing access tokens is like issuing _hotel key cards_ from a hotel’s front desk (your back end). Any client with a key card can enter any room that the card gives access to. It’s easy to give out those key cards right from your back end.

To implement your back end, follow these steps: Create a session ```ts showLineNumbers={false} const session = liveblocks.prepareSession( "marie@example.com", // Required, user ID from your DB { // Optional, custom static metadata for the session userInfo: { name: "Marie", avatar: "https://example.com/avatar/marie.jpg", }, // Optional, authenticate this user on a specific organization organizationId: "acme-corp", } ); ``` The `userId` (required) is an identifier to uniquely identifies your user with Liveblocks. This value will be used when counting unique MAUs in your Liveblocks dashboard. The `userInfo` (optional) is any custom JSON value, which can be attached to static metadata to this user’s session. This will be publicly visible to all other people in the room. Useful for metadata like the user’s full name, or their avatar URL. The `organizationId` (optional) is the organization for this session, will be set to `default` if not provided. Decide which permissions to allow this session ```ts showLineNumbers={false} session.allow("my-room-1", session.FULL_ACCESS); session.allow("my-room-2", session.FULL_ACCESS); session.allow("my-room-3", session.FULL_ACCESS); session.allow("my-team:*", session.READ_ACCESS); ``` You’re specifying what’s going to be allowed so be careful what permissions you’re giving your users. You’re responsible for this part. Authorize the session Finally, authorize the session. This step makes the HTTP call to the Liveblocks servers. Liveblocks will return a signed **access token** that you can return to your client. ```ts showLineNumbers={false} // Requests the Liveblocks servers to authorize this session const { body, status } = await session.authorize(); return new Response(body, { status }); ``` ##### Access tokens example [#access-token-example] Here’s a real-world example of access tokens in a Next.js route handler/endpoint. You can find examples for other frameworks in our [authentication section](/docs/authentication/access-token). ```ts file="route.ts" import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); export async function POST(request: Request) { /** * Implement your own security here. * * It's your responsibility to ensure that the caller of this endpoint * is a valid user by validating the cookies or authentication headers * and that it has access to the requested room. */ // Get the current user from your database const user = __getUserFromDB__(request); // Start an auth session inside your endpoint const session = liveblocks.prepareSession( user.id, { userInfo: user.metadata } // Optional ); // Implement your own security, and give the user access to the room const { room } = await request.json(); if (room && __shouldUserHaveAccess__(user, room)) { session.allow(room, session.FULL_ACCESS); } // Retrieve a token from the Liveblocks servers and pass it to the // requesting client const { body, status } = await session.authorize(); return new Response(body, { status }); } ``` ### Room #### Liveblocks.getRooms [#get-rooms] Returns a list of rooms that are in the current project. The project is determined by the secret key you’re using. Rooms are sorted by creation time, with the newest room at index `0`. This is a wrapper around the [Get Rooms API](/docs/api-reference/rest-api-endpoints#get-rooms) and returns the same response. ```ts const { data: rooms, nextCursor } = await liveblocks.getRooms(); // A list of rooms // [{ type: "room", id: "my-room-id", ... }, ...] console.log(rooms); // A pagination cursor used for retrieving the next page of results with `startingAfter` // "L3YyL3Jvb21z..." console.log(nextCursor); ``` A number of options are also available, enabling you to filter for certain rooms. ```ts const { data: rooms, nextCursor } = await liveblocks.getRooms({ // Optional, the amount of rooms to load, between 1 and 100, defaults to 20 limit: 20, // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses` groupIds: ["engineering", "design"], // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses` userId: "my-user-id", // Optional, use advanced filtering query: { // Optional, filter for rooms with an ID that starts with specific string roomId: { startsWith: "liveblocks:", }, // Optional, filter for rooms with custom metadata in `metadata` metadata: { roomType: "whiteboard", }, }, // Optional, authenticate this user on a specific organization organizationId: "my-organization-id", // Optional, cursor used for pagination, use `nextCursor` from the previous page's response startingAfter: "L3YyL3Jvb21z...", }); ``` The `query` option also allows you to pass a [query language](/docs/guides/how-to-filter-rooms-using-query-language) string instead of a `query` object. ##### Pagination You can use `nextCursor` to paginate rooms. In this example, when `getNextPage` is called, the next set of rooms is added to `pages`. ```ts import { RoomData } from "@liveblocks/node"; // An array of pages, each containing a list of retrieved rooms const pages: RoomData[][] = []; // Holds the pagination cursor for the next set of rooms let startingAfter; // Call to get the next page of rooms async function getNextPage() { const { data, nextCursor } = await liveblocks.getRooms({ startingAfter }); pages.push(data); startingAfter = nextCursor; } ``` If you’d like to iterate over all your rooms, it’s most convenient to use [`liveblocks.iterRooms`](#iter-rooms) instead. This method automatically paginates your API requests. #### Liveblocks.iterRooms [#iter-rooms] Works similarly to [`liveblocks.getRooms`](#get-rooms), but instead returns an asynchronous iterator, which helps you iterate over all selected rooms in your project, without having to manually paginate through the results. ```ts const roomsIterator = liveblocks.iterRooms(); for await (const room of roomsIterator) { // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); } ``` A number of options are also available, enabling you to filter for certain rooms. ```ts const roomsIterator = await liveblocks.iterRooms({ // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses` groupIds: ["engineering", "design"], // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses` userId: "my-user-id", // Optional, use advanced filtering query: { // Optional, filter for rooms with an ID that starts with specific string roomId: { startsWith: "liveblocks:", }, // Optional, filter for rooms with custom metadata in `metadata` metadata: { roomType: "whiteboard", }, }, }); for await (const room of roomsIterator) { // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); } ``` The `query` option also allows you to pass a [query language](/docs/guides/how-to-filter-rooms-using-query-language) string instead of a `query` object. ##### Mass deleting rooms You can use `iterRooms` to efficiently delete multiple rooms at once. This example shows how to delete rooms in batches of 50 concurrent deletions at a time: ```ts const MAX_CONCURRENT = 50; const queue: Promise[] = []; for await (const room of liveblocks.iterRooms({ // Optionally filter for certain rooms // ... })) { if (queue.length >= MAX_CONCURRENT) { await Promise.race(queue); } const promise = liveblocks .deleteRoom(room.id) .finally(() => queue.splice(queue.indexOf(promise), 1)); queue.push(promise); } await Promise.all(queue); ``` This approach is useful when you need to delete a large number of rooms, as it automatically handles pagination and allows you to control the concurrency of deletions. You can use any of the filtering options shown above to select which rooms to delete. #### Liveblocks.createRoom [#post-rooms] Programmatically creates a new room from a room ID. The `defaultAccesses` option is required. Setting `defaultAccesses` to `["room:write"]` creates a public room, whereas setting it to `[]` will create a private room that needs [ID token permission to enter](/docs/authentication/id-token). This is a wrapper around the [Create Room API](/docs/api-reference/rest-api-endpoints#post-rooms) and returns the same response. ```ts const room = await liveblocks.createRoom("my-room-id", { defaultAccesses: ["room:write"], }); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` A number of room creation options are available, allowing you to set permissions and attach custom metadata. ```ts const room = await liveblocks.createRoom("my-room-id", { // The default room permissions. `[]` for private, `["room:write"]` for public. defaultAccesses: [], // Optional, the room's group ID permissions groupsAccesses: { design: ["room:write"], engineering: ["room:presence:write", "room:read"], }, // Optional, the room's user ID permissions usersAccesses: { "my-user-id": ["room:write"], }, // Optional, custom metadata to attach to the room metadata: { myRoomType: "whiteboard", }, // Optional, create it on a specific organization organizationId: "acme-corp", }); ``` Group and user permissions are only used with [ID token authorization](/docs/api-reference/liveblocks-node#id-tokens), learn more about [managing permission with ID tokens](/docs/authentication/id-token). #### Liveblocks.getRoom [#get-rooms-roomId] Returns a room. Throws an error if the room isn’t found. This is a wrapper around the [Get Room API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId) and returns the same response. ```ts const room = await liveblocks.getRoom("my-room-id"); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` #### Liveblocks.getOrCreateRoom [#get-or-create-rooms-roomId] Get a room by its ID. If the room doesn’t exist, create it instead. The `defaultAccesses` option is required. Setting `defaultAccesses` to `["room:write"]` creates a public room, whereas setting it to `[]` will create a private room that needs [ID token permission to enter](/docs/authentication/id-token). Returns the same response as the [Create Room API](/docs/api-reference/rest-api-endpoints#post-rooms). ```ts const room = await liveblocks.getOrCreateRoom("my-room-id", { defaultAccesses: ["room:write"], }); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` A number of room creation options are available, allowing you to set permissions and attach custom metadata. ```ts const room = await liveblocks.getOrCreateRoom("my-room-id", { // The default room permissions. `[]` for private, `["room:write"]` for public. defaultAccesses: [], // Optional, the room's group ID permissions groupsAccesses: { design: ["room:write"], engineering: ["room:presence:write", "room:read"], }, // Optional, the room's user ID permissions usersAccesses: { "my-user-id": ["room:write"], }, // Optional, custom metadata to attach to the room metadata: { myRoomType: "whiteboard", }, // Optional, create it on a specific organization organizationId: "acme-corp", }); ``` Group and user permissions are only used with [ID token authorization](/docs/api-reference/liveblocks-node#id-tokens), learn more about [managing permission with ID tokens](/docs/authentication/id-token). #### Liveblocks.updateRoom [#post-rooms-roomId] Updates properties on a room. Throws an error if the room isn’t found. This is a wrapper around the [Update Room API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId) and returns the same response. ```ts const room = await liveblocks.updateRoom("my-room-id", { // The metadata or permissions you're updating // ... }); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` Permissions and metadata properties can be updated on the room. Note that you need only pass the properties you’re updating. Setting a property to `null` will delete the property. ```ts const room = await liveblocks.updateRoom("my-room-id", { // Optional, update the default room permissions. `[]` for private, `["room:write"]` for public. defaultAccesses: [], // Optional, update the room's group ID permissions groupsAccesses: { design: ["room:write"], engineering: ["room:presence:write", "room:read"], }, // Optional, update the room's user ID permissions usersAccesses: { "my-user-id": ["room:write"], }, // Optional, custom metadata to update on the room metadata: { myRoomType: "whiteboard", }, }); ``` Group and user permissions are only used with [ID token authorization](/docs/api-reference/liveblocks-node#id-tokens), learn more about [managing permission with ID tokens](/docs/authentication/id-token). #### Liveblocks.upsertRoom [#upsert-rooms-roomId] Update a room’s properties by its ID. If the room doesn’t exist, create it instead. The `defaultAccesses` option is required. Setting `defaultAccesses` to `["room:write"]` creates a public room, whereas setting it to `[]` will create a private room that needs [ID token permission to enter](/docs/authentication/id-token). Returns the same response as the [Create Room API](/docs/api-reference/rest-api-endpoints#post-rooms). ```ts const room = await liveblocks.upsertRoom("my-room-id", { // These fields will get updated when the room exists, or will be created update: { metadata: { color: "red" }, }, // These fields will only be set when the room will get created create: { defaultAccesses: ["room:write"], }, }); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` A number of room update or creation options are available, allowing you to set permissions and attach custom metadata. ```ts const room = await liveblocks.upsertRoom("my-room-id", { update: { // The default room permissions. `[]` for private, `["room:write"]` for public. defaultAccesses: [], // Optional, the room's group ID permissions groupsAccesses: { design: ["room:write"], engineering: ["room:presence:write", "room:read"], }, // Optional, the room's user ID permissions usersAccesses: { "my-user-id": ["room:write"], }, // Optional, custom metadata to attach to the room metadata: { myRoomType: "whiteboard", }, }, }); ``` Group and user permissions are only used with [ID token authorization](/docs/api-reference/liveblocks-node#id-tokens), learn more about [managing permission with ID tokens](/docs/authentication/id-token). #### Liveblocks.deleteRoom [#delete-rooms-roomId] Deletes a room. If the room doesn’t exist, or has already been deleted, no error will throw. This is a wrapper around the [Delete Room API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId) and returns no response. ```ts await liveblocks.deleteRoom("my-room-id"); ``` ##### Mass deleting rooms If you need to delete multiple rooms at once, you can use [`liveblocks.iterRooms`](#iter-rooms) to efficiently iterate through rooms and delete them in batches. This example shows how to delete rooms in batches of 50 concurrent deletions at a time: ```ts const MAX_CONCURRENT = 50; const queue: Promise[] = []; for await (const room of liveblocks.iterRooms({ // Optionally filter for certain rooms // ... })) { if (queue.length >= MAX_CONCURRENT) { await Promise.race(queue); } const promise = liveblocks .deleteRoom(room.id) .finally(() => queue.splice(queue.indexOf(promise), 1)); queue.push(promise); } await Promise.all(queue); ``` You can use any of the filtering options available in [`liveblocks.iterRooms`](#iter-rooms) to select which rooms to delete, such as filtering by metadata, room ID prefix, or user/group access. #### Liveblocks.prewarmRoom [#get-rooms-roomId-prewarm] Speeds up connecting to a room for the next 10 seconds. Use this when you know a user will be connecting to a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider) or [`enterRoom`](/docs/api-reference/liveblocks-client#Client.enterRoom) within 10 seconds, and the room will load quicker. This is a wrapper around the [Prewarm Room API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-prewarm) and returns no response. ```ts await liveblocks.prewarmRoom("my-room-id"); ``` ##### Warm a room before navigating Triggering a room directly before a user navigates to a room is an easy to way use this API. Here’s a Next.js server actions example, showing how to trigger prewarming with `onPointerDown`. ```ts title="actions.ts" "use server"; import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); export async function prewarmRoom(roomId: string) { // +++ await liveblocks.prewarmRoom(roomId); // +++ } ``` ```tsx title="RoomLink.tsx" "use client"; import { prewarmRoom } from "../actions"; import Link from "next/link"; export function JoinButton({ roomId }: { roomId: string }) { return ( // +++ prewarmRoom(roomId)}> // +++ {roomId} ); } ``` `onPointerDown` is slightly quicker than `onClick` because it triggers before the user releases their pointer. #### Liveblocks.updateRoomId [#post-rooms-update-roomId] Permanently updates a room’s ID. `newRoomId` will replace `currentRoomId`. Note that this will disconnect connected users from the room, but this can be worked around. Throws an error if the room isn’t found. This is a wrapper around the [Update Room API](/docs/api-reference/rest-api-endpoints#post-rooms-update-roomId) and returns the same response. ```ts const room = await liveblocks.updateRoomId({ currentRoomId: "my-room-id", newRoomId: "new-room-id", }); // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); ``` ##### Redirect connected users to the new room When a room’s ID is changed it disconnects all users that are currently connected. To redirect connected users to the new room you can use [`useErrorListener`](/docs/api-reference/liveblocks-react#useErrorListener) or [`room.subscribe("error")`](/docs/api-reference/liveblocks-client#Room.subscribe.error) in your application to get the new room’s ID, and redirect users to the renamed room. ```tsx import { useErrorListener } from "@liveblocks/react/suspense"; function App() { useErrorListener((error) => { if (error.context.code === 4006) { // Room ID has been changed, get the new ID and redirect const newRoomId = error.message; __redirect__(`https://example.com/document/${newRoomId}}`); } }); } ``` #### Liveblocks.getActiveUsers [#get-rooms-roomId-active-users] Returns a list of users that are currently present in the room. Throws an error if the room isn’t found. This is a wrapper around the [Get Active Users API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-active-users) and returns the same response. ```ts const activeUsers = await liveblocks.getActiveUsers("my-room-id"); // { data: [{ type: "user", id: "my-user-id", ... }, ...] } console.log(activeUsers); ``` #### Liveblocks.broadcastEvent [#post-broadcast-event] Broadcasts a custom event to the room. Throws an error if the room isn’t found. This is a wrapper around the [Broadcast Event API](/docs/api-reference/rest-api-endpoints#post-broadcast-event) and returns no response. ```ts const customEvent = { type: "EMOJI", emoji: "🔥", }; await liveblocks.broadcastEvent("my-room-id", customEvent); ``` You can respond to custom events on the front end with [`useEventListener`](/docs/api-reference/liveblocks-react#useEventListener) and [`room.subscribe("event")`](/docs/api-reference/liveblocks-client#Room.subscribe.event). When receiving an event sent with `Liveblocks.broadcastEvent`, `user` will be `null` and `connectionId` will be `-1`. ```tsx import { useEventListener } from "@liveblocks/react/suspense"; // When receiving an event sent from `@liveblocks/node` useEventListener(({ event, user, connectionId }) => { // `null` console.log(user); // `-1` console.log(connectionId); }); ``` #### Liveblocks.setPresence [#post-rooms-roomId-presence] Sets ephemeral presence for a user in a room without requiring a WebSocket connection. The presence data automatically expires after the specified TTL (time-to-live). This is useful for scenarios like showing an AI agent’s presence in a room. The presence is broadcast to all connected users in the room. This is a wrapper around the [Set Presence API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-presence) and returns no response on success. ```ts await liveblocks.setPresence("my-room-id", { userId: "agent-123", data: { status: "active", cursor: { x: 100, y: 200 }, }, userInfo: { name: "AI Assistant", avatar: "https://example.com/avatar.png", }, ttl: 60, // optional, 2–3599 seconds }); ``` - **userId** (required): The ID of the user to set presence for. - **data** (required): Presence data as a JSON object. - **userInfo** (optional): Metadata about the user or agent - **ttl** (optional): Time-to-live in seconds (minimum 2, maximum 3599). Defaults to 60. After this duration, the presence expires automatically. ### Groups Groups allow you to manage users for group mentions in comments and text editors. #### Liveblocks.createGroup [#create-group] Creates a new group with the specified members. This is a wrapper around the [Create Group API](/docs/api-reference/rest-api-endpoints#post-groups) and returns the same response. ```ts const group = await liveblocks.createGroup({ groupId: "engineering-team", memberIds: ["alice@example.com", "bob@example.com"], }); // { type: "group", id: "engineering-team", organizationId: "acme-corp", createdAt: "...", updatedAt: "...", scopes: { mention: true }, members: [...] } console.log(group); ``` You can also create a group without members and add them later: ```ts const group = await liveblocks.createGroup({ groupId: "design-team", // Optional, add members when creating the group memberIds: ["charlie@example.com"], // Optional, create it on a specific organization organizationId: "company-123", // Optional, set group scopes (defaults to { mention: true }) scopes: { mention: true }, }); ``` #### Liveblocks.getGroup [#get-group] Returns a group by its ID. Throws an error if the group isn’t found. This is a wrapper around the [Get Group API](/docs/api-reference/rest-api-endpoints#get-groups-groupId) and returns the same response. ```ts const group = await liveblocks.getGroup({ groupId: "engineering-team", }); // { type: "group", id: "engineering-team", organizationId: "acme-corp", createdAt: "...", updatedAt: "...", scopes: { mention: true }, members: [...] } console.log(group); ``` #### Liveblocks.getGroups [#get-groups] Returns a list of all groups in your project. This is a wrapper around the [Get Groups API](/docs/api-reference/rest-api-endpoints#get-groups) and returns the same response. ```ts const { data: groups, nextCursor } = await liveblocks.getGroups(); // A list of groups // [{ type: "group", id: "engineering-team", organizationId: "acme-corp", createdAt: "...", updatedAt: "...", scopes: { mention: true }, members: [...] }, ...] console.log(groups); // A pagination cursor for the next page console.log(nextCursor); ``` You can also paginate through groups: ```ts const { data: groups, nextCursor } = await liveblocks.getGroups({ // Optional, the number of groups to return (defaults to 20) limit: 50, // Optional, cursor for pagination startingAfter: nextCursor, }); ``` #### Liveblocks.getUserGroups [#get-user-groups] Returns all groups that a specific user is a member of. This is a wrapper around the [Get User Groups API](/docs/api-reference/rest-api-endpoints#get-users-userId-groups) and returns the same response. ```ts const { data: userGroups, nextCursor } = await liveblocks.getUserGroups({ userId: "alice@example.com", }); // A list of groups the user belongs to // [{ type: "group", id: "engineering-team", ... }, ...] console.log(userGroups); ``` You can also paginate through user groups: ```ts const { data: userGroups, nextCursor } = await liveblocks.getUserGroups({ userId: "alice@example.com", limit: 25, startingAfter: "L3YyL2dyb3Vwcy...", }); ``` #### Liveblocks.addGroupMembers [#add-group-members] Adds new members to an existing group. This is a wrapper around the [Add Group Members API](/docs/api-reference/rest-api-endpoints#post-groups-groupId-add-members) and returns the same response. ```ts const updatedGroup = await liveblocks.addGroupMembers({ groupId: "engineering-team", memberIds: ["david@example.com", "eve@example.com"], }); // { type: "group", id: "engineering-team", organizationId: "acme-corp", createdAt: "...", updatedAt: "...", scopes: { mention: true }, members: [...] } console.log(updatedGroup); ``` #### Liveblocks.removeGroupMembers [#remove-group-members] Removes members from an existing group. This is a wrapper around the [Remove Group Members API](/docs/api-reference/rest-api-endpoints#post-groups-groupId-remove-members) and returns the same response. ```ts const updatedGroup = await liveblocks.removeGroupMembers({ groupId: "engineering-team", memberIds: ["david@example.com"], }); // { type: "group", id: "engineering-team", organizationId: "acme-corp", createdAt: "...", updatedAt: "...", scopes: { mention: true }, members: [...] } console.log(updatedGroup); ``` #### Liveblocks.deleteGroup [#delete-group] Deletes a group. If the group doesn’t exist, no error will be thrown. This is a wrapper around the [Delete Group API](/docs/api-reference/rest-api-endpoints#delete-groups-groupId) and returns no response. ```ts await liveblocks.deleteGroup({ groupId: "old-team", }); ``` ### Storage #### Liveblocks.getStorageDocument [#get-rooms-roomId-storage] Returns the contents of a room’s Storage tree. By default, returns Storage in LSON format. Throws an error if the room isn’t found. This is a wrapper around the [Get Storage Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage) and returns the same response. ```ts const storage = await liveblocks.getStorageDocument("my-room-id"); ``` LSON is a custom Liveblocks format that preserves information about the conflict-free data types used. By default, `getStorageDocument` returns Storage in this format. This is the same as using `"plain-json"` in the second argument. ```ts highlight="2" // Retrieve LSON Storage data const storage = await liveblocks.getStorageDocument("my-room-id", "plain-lson"); // If this were your Storage type... declare global { interface Liveblocks { Storage: { names: LiveList; }; } } // { // liveblocksType: "LiveObject", // data: { // names: { // liveblocksType: "LiveList", // data: ["Olivier", "Nimesh"], // } // } // } console.log(storage); ``` You can also retrieve Storage as JSON by passing `"json"` into the second argument. ```ts highlight="2" // Retrieve JSON Storage data const storage = await liveblocks.getStorageDocument("my-room-id", "json"); // If this were your Storage type... declare global { interface Liveblocks { Storage: { names: LiveList; }; } } // { // names: ["Olivier", "Nimesh"] // } console.log(storage); ``` #### Liveblocks.initializeStorageDocument [#post-rooms-roomId-storage] Initializes a room’s Storage tree with given LSON data. To use this, the room must have [already been created](#post-rooms) and have empty Storage. Throws an error if the room isn’t found. Calling this will disconnect all active users from the room. This is a wrapper around the [Initialize Storage Document API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-storage) and returns the same response. ```ts // Create a new room const room = await liveblocks.createRoom("my-room-id", { defaultAccesses: ["room:write"], }); // Initialize Storage const storage = await liveblocks.initializeStorageDocument("my-room-id", { // Your LSON Storage value // ... }); ``` LSON is a custom Liveblocks format that preserves information about conflict-free data types. The easiest way to create it is using the `toPlainLson` helper provided by `@liveblocks/client`. Note that your Storage root should always be a `LiveObject`. ```ts highlight="11-13,18-20,25" import { toPlainLson, LiveList, LiveObject } from "@liveblocks/client"; // Create a new room const room = await liveblocks.createRoom("my-room-id", { defaultAccesses: ["room:write"], }); // If this were your Storage type... declare global { interface Liveblocks { Storage: { names: LiveList; }; } } // Create the initial conflict-free data const initialStorage: LiveObject = new LiveObject({ names: new LiveList(["Olivier", "Nimesh"]), }); // Convert to LSON and create Storage const storage = await liveblocks.initializeStorageDocument( "my-room-id", toPlainLson(initialStorage) ); ``` It’s also possible to create plain LSON manually, without the helper function. ```ts highlight="9-11,17-23" // Create a new room const room = await liveblocks.createRoom("my-room-id", { defaultAccesses: ["room:write"], }); // If this were your Storage type... declare global { interface Liveblocks { Storage: { names: LiveList; }; } } // Create this Storage and add names to the LiveList const storage = await liveblocks.initializeStorageDocument("my-room-id", { liveblocksType: "LiveObject", data: { names: { liveblocksType: "LiveList", data: ["Olivier", "Nimesh"], }, }, }); ``` #### Liveblocks.mutateStorage [#mutate-storage] Modify Storage contents from the server. No presence will be shown when you make changes. ```ts // Mutate a single room await liveblocks.mutateStorage( "my-room-id", ({ root }) => { root.get("list").push("item3"); } ); ``` The callback can be asynchronous, in which case a stream of mutations can happen over time. ```ts // Mutate a single room await liveblocks.mutateStorage( "my-room-id", async ({ root }) => { // These changes happen immediately const animals = root.get("animals"); animals.clear(); animals.push("Thinking..."); await thinkForAWhile(); // These changes happen after `await` has run animals.clear(); animals.push("🐶"); animals.push("🦘"); } ); ``` Learn how to [type your Storage](/docs/api-reference/liveblocks-react#Typing-your-data). #### Liveblocks.massMutateStorage [#mass-mutate-storage] Modify Storage contents for multiple rooms simultaneously. With the default query value `{}` it will loop through every room in your project. ```ts // Mutate a number of rooms await liveblocks.massMutateStorage( {}, // Callback runs on every selected room ({ room, root }) => { // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); root.get("animals").push("🦍"); } ); ``` A number of options are also available, enabling you to filter for certain rooms. Additionally, you can set options for concurrency and provide an abort signal to cancel the mutations. ```ts // Mutate a number of rooms await liveblocks.massMutateStorage( { // +++ // Optional, filter for rooms that allow entry to group ID(s) in `groupsAccesses` groupIds: ["engineering", "design"], // Optional, filter for rooms that allow entry to a user's ID in `usersAccesses` userId: "my-user-id", // Optional, use advanced filtering query: { // Optional, filter for rooms with an ID that starts with specific string roomId: { startsWith: "liveblocks:", }, // Optional, filter for rooms with custom metadata in `metadata` metadata: { roomType: "whiteboard", }, }, // +++ }, ({ room, root }) => { // { type: "room", id: "my-room-id", metadata: {...}, ... } console.log(room); root.get("animals").push("🦍"); }, // Optional // +++ { concurrency: 10, // Optional, process at most 10 rooms simultaneously signal, // Optional, provide an abort signal to cancel mutations mid-way } // +++ ); ``` Learn how to [type your Storage](/docs/api-reference/liveblocks-react#Typing-your-data). #### Liveblocks.deleteStorageDocument [#delete-rooms-roomId-storage] Deletes a room’s Storage data. Calling this will disconnect all active users from the room. Throws an error if the room isn’t found. This is a wrapper around the [Delete Storage Document API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-storage) and returns no response. ```ts await liveblocks.deleteStorageDocument("my-room-id"); ``` ### Yjs #### Liveblocks.getYjsDocument [#get-rooms-roomId-ydoc] Returns a JSON representation of a room’s Yjs document. Throws an error if the room isn’t found. This is a wrapper around the [Get Yjs Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc) and returns the same response. ```ts const yjsDocument = await liveblocks.getYjsDocument("my-room-id"); // { yourYText: "...", yourYArray: [...], ... } console.log(yjsDocument); ``` A number of options are available. ```ts const yjsDocument = await liveblocks.getYjsDocument("my-room-id", { // Optional, if true, `yText` values will return formatting format: true, // Optional, return a single key's value, e.g. `yDoc.get("my-key-id").toJson()` key: "my-key-id", // Optional, override the inferred `key` type, e.g. "ymap" for `doc.get(key, Y.Map)` type: "ymap", }); ``` #### Liveblocks.sendYjsBinaryUpdate [#put-rooms-roomId-ydoc] Send a Yjs binary update to a room’s Yjs document. You can use this to update or initialize the room’s Yjs document. Throws an error if the room isn’t found. This is a wrapper around the [Send a Binary Yjs Update API](/docs/api-reference/rest-api-endpoints#put-rooms-roomId-ydoc) and returns no response. ```ts await liveblocks.sendYjsBinaryUpdate("my-room-id", update); ``` Here’s an example of how to update a room’s Yjs document with your changes. ```ts import * as Y from "yjs"; // Create a Yjs document const yDoc = new Y.Doc(); // Create your data structures and make your update // If you're using a text editor, you need to match its format const yText = yDoc.getText("text"); yText.insert(0, "Hello world"); // Encode the document state as an update const update = Y.encodeStateAsUpdate(yDoc); // Send update to Liveblocks await liveblocks.sendYjsBinaryUpdate("my-room-id", update); ``` To update a subdocument instead of the main document, pass its `guid`. ```ts await liveblocks.sendYjsBinaryUpdate("my-room-id", update, { // Optional, update a subdocument instead. guid is its unique identifier guid: "c4a755...", }); ``` To create a new room and initialize its Yjs document, call [`liveblocks.createRoom`](#post-rooms) before sending the binary update. ```ts highlight="1-2" // Create new room const room = await liveblocks.createRoom("my-room-id"); // Set initial Yjs document value await liveblocks.sendYjsBinaryUpdate("my-room-id", state); ``` ##### Different editors Note that each text and code editor handles binary updates in a different way, and may use a different Yjs shared type, for example [`Y.XmlFragment`](https://docs.yjs.dev/api/shared-types/y.xmlfragment) instead of [`Y.Text`](https://docs.yjs.dev/api/shared-types/y.text). Create a binary update with [Slate](https://www.slatejs.org/): ```ts title="Slate binary update" highlight="3,13-17,19-21" isCollapsed isCollapsable import { Liveblocks } from "@liveblocks/node"; import * as Y from "yjs"; import { slateNodesToInsertDelta } from "@slate-yjs/core"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); export async function POST() { // Create a Yjs document const yDoc = new Y.Doc(); // Create Slate document state const slateDoc = { type: "paragraph", children: [{ text: "Hello world" }], }; // Create your data structures and make your update const insertDelta = slateNodesToInsertDelta(slateDoc); (yDoc.get("content", Y.XmlText) as Y.XmlText).applyDelta(insertDelta); // Encode the document state as an update const update = Y.encodeStateAsUpdate(yDoc); // Send update to Liveblocks await liveblocks.sendYjsBinaryUpdate("my-room-id", update); } ``` Create a binary update with [Tiptap](https://tiptap.dev/docs/editor/api/extensions/collaboration): ```ts title="Tiptap binary update" highlight="12-14,16-18" isCollapsed isCollapsable import * as Y from "yjs"; import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); export async function POST() { // Create a Yjs document const yDoc = new Y.Doc(); // Create Tiptap Yjs state const yXmlElement = new Y.XmlElement("paragraph"); yXmlElement.insert(0, [new Y.XmlText("Hello world")]); // Create your data structures and make your update const yXmlFragment = yDoc.getXmlFragment("default"); yXmlFragment.insert(0, [yXmlElement]); // Encode the document state as an update message const yUpdate = Y.encodeStateAsUpdate(yDoc); // Initialize the Yjs document with the update await liveblocks.sendYjsBinaryUpdate("my-room-id", { update: yUpdate, }); } ``` Read the [Yjs documentation](https://docs.yjs.dev/api/document-updates) to learn more about creating binary updates. #### Liveblocks.getYjsDocumentAsBinaryUpdate [#get-rooms-roomId-ydoc-binary] Return a room’s Yjs document as a single binary update. You can use this to get a copy of your Yjs document in your back end. Throws an error if the room isn’t found. This is a wrapper around the [Get Yjs Document Encoded as a Binary Yjs Update API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc-binary) and returns the same response. ```ts const binaryYjsUpdate = await liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id"); ``` To return a subdocument instead of the main document, pass its `guid`. ```ts const binaryYjsUpdate = await liveblocks.getYjsDocumentAsBinaryUpdate( "my-room-id", { // Optional, return a subdocument instead. guid is its unique identifier guid: "c4a755...", } ); ``` Read the [Yjs documentation](https://docs.yjs.dev/api/document-updates) to learn more about using binary updates. ### Attachments #### Liveblocks.getAttachment [#get-rooms-roomId-attachments-attachmentId] Returns an attachment's metadata and a presigned download URL. Throws an error if the room or attachment isn't found. ```ts const attachment = await liveblocks.getAttachment({ roomId: "my-room-id", attachmentId: "at_d75sF3...", }); // { type: "attachment", id: "at_d75sF3...", name: "document.pdf", ... } console.log(attachment); // The presigned URL to download the attachment console.log(attachment.url); ``` Returns an `AttachmentWithUrl` object with the following properties: The type of the object. The attachment ID (starts with "at_"). The name of the attachment file. The MIME type of the attachment. The size of the attachment in bytes. A presigned URL to download the attachment. The expiration time of the presigned URL. ### Comments #### Liveblocks.getThreads [#get-rooms-roomId-threads] Returns a list of threads found inside a room. Throws an error if the room isn’t found. This is a wrapper around the [Get Room Threads API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads) and returns the same response. ```ts const { data: threads } = await liveblocks.getThreads({ roomId: "my-room-id", }); // [{ type: "thread", id: "th_d75sF3...", ... }, ...] console.log(threads); ``` It’s also possible to filter threads by their string, boolean, and number metadata using a query parameter. You can also pass `startsWith` to match the start of a string. ```ts const { data: threads } = await liveblocks.getThreads({ roomId: "my-room-id", // Optional, use advanced filtering query: { // Optional, filter based on resolved status resolved: false, // Optional, filter for metadata values metadata: { status: "open", pinned: true, priority: 3, // You can match the start of a metadata string organization: { startsWith: "liveblocks:", }, }, }, }); ``` You can also pass a [query language](/docs/guides/how-to-filter-threads-using-query-language) string instead of a `query` object. #### Liveblocks.createThread [#post-rooms-roomId-threads] Creates a new thread within a specific room, using room ID and thread data. This is a wrapper around the [Create Thread API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads) and returns the new thread. ```ts const thread = await liveblocks.createThread({ roomId: "my-room-id", data: { comment: { userId: "florent@example.com", body: { version: 1, content: [ /* The comment's body text goes here, see below */ ], }, }, }, }); // { type: "thread", id: "th_d75sF3...", ... } console.log(thread); ``` A comment’s body is an array of paragraphs, each containing child nodes. Here’s an example of how to construct a comment’s body, which can be submitted under `data.comment.body`. ```tsx highlight="3-11,20" import { CommentBody } from "@liveblocks/node"; const body: CommentBody = { version: 1, content: [ { type: "paragraph", children: [{ text: "Hello " }, { text: "world", bold: true }], }, ], }; const thread = await liveblocks.createThread({ roomId: "my-room-id", data: { // ... comment: { // The comment's body, uses the `CommentBody` type body, // ... }, }, }); ``` This method has a number of options, allowing for custom metadata and a creation date for the comment. ```ts const thread = await liveblocks.createThread({ roomId: "my-room-id", data: { // Optional, custom metadata properties metadata: { color: "blue", page: 3, pinned: true, }, // Data for the first comment in the thread comment: { // The ID of the user that created the comment userId: "florent@example.com", // Optional, when the comment was created. createdAt: new Date(), // Optional, custom comment metadata metadata: { tag: "important", spam: false, }, // The comment's body, uses the `CommentBody` type body: { version: 1, content: [ /* The comment's body text goes here, see above */ ], }, }, }, }); // { type: "thread", id: "th_d75sF3...", ... } console.log(thread); ``` #### Liveblocks.getThread [#get-rooms-roomId-threads-threadId] Returns a thread. Throws an error if the room or thread isn’t found. This is a wrapper around the [Get Thread API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads-threadId) and returns the same response. ```ts const thread = await liveblocks.getThread({ roomId: "my-room-id", threadId: "th_d75sF3...", }); // { type: "thread", id: "th_d75sF3...", ... } console.log(thread); ``` #### Liveblocks.editThreadMetadata [#post-rooms-roomId-threads-threadId-metadata] Updates the metadata of a specific thread within a room. This method allows you to modify the metadata of a thread, including user information and the date of the last update. Throws an error if the room or thread isn’t found. This is a wrapper around the [Update Thread Metadata API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-metadata) and returns the updated metadata. ```ts const editedMetadata = await liveblocks.editThreadMetadata({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { metadata: { color: "yellow", }, userId: "marc@example.com", updatedAt: new Date(), // Optional }, }); // { color: "yellow", page: 3, pinned: true } console.log(editedMetadata); ``` Metadata can be a `string`, `number`, or `boolean`. You can also use `null` to remove metadata from a thread. Here’s an example using every option. ```ts const editedMetadata = await liveblocks.editThreadMetadata({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { // Custom metadata metadata: { // Metadata can be a string, number, or boolean title: "My thread title", page: 3, pinned: true, // Remove metadata with null color: null, }, // The ID of the user that updated the metadata userId: "marc@example.com", // Optional, the time the user updated the metadata updatedAt: new Date(), }, }); // { title: "My thread title", page: 3, pinned: true } console.log(editedMetadata); ``` #### Liveblocks.editCommentMetadata [#post-rooms-roomId-threads-threadId-comments-commentId-metadata] Updates the metadata of a specific comment within a thread. This method allows you to modify the metadata of a comment, including user information and the date of the last update. Throws an error if the room, thread, or comment isn’t found. This is a wrapper around the [Update Comment Metadata API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId-metadata) and returns the updated metadata. ```ts const editedMetadata = await liveblocks.editCommentMetadata({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { metadata: { spam: false, }, userId: "stacy@example.com", updatedAt: new Date(), // Optional }, }); // { spam: false } console.log(editedMetadata); ``` Metadata can be a `string`, `number`, or `boolean`. You can also use `null` to remove metadata from a comment. Here’s an example using every option. ```ts const editedMetadata = await liveblocks.editCommentMetadata({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { // Custom metadata metadata: { // Metadata can be a string, number, or boolean tag: "important", priority: 2, spam: true, // Remove metadata with null assignedTo: null, }, // The ID of the user that updated the metadata userId: "stacy@example.com", // Optional, the time the user updated the metadata updatedAt: new Date(), }, }); // { tag: "important", priority: 2, flagged: true } console.log(editedMetadata); ``` #### Liveblocks.markThreadAsResolved [#post-rooms-roomId-threads-threadId-mark-as-resolved] Marks a thread as resolved, which means it sets the `resolved` property on the specified thread to `true`. Takes a `userId`, which is the ID of the user that resolved the thread. Throws an error if the room or thread isn’t found. This is a wrapper around the [Mark Thread As Resolved API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-mark-as-resolved) and returns the same response. ```ts const thread = await liveblocks.markThreadAsResolved({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { userId: "steven@example.com", }, }); // { type: "thread", id: "th_d75sF3...", ... } console.log(thread); ``` #### Liveblocks.markThreadAsUnresolved [#post-rooms-roomId-threads-threadId-mark-as-unresolved] Marks a thread as unresolved, which means it sets the `resolved` property on the specified thread to `false`. Takes a `userId`, which is the ID of the user that unresolved the thread. Throws an error if the room or thread isn’t found. This is a wrapper around the [Mark Thread As Unresolved API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-mark-as-unresolved) and returns the same response. ```ts const thread = await liveblocks.markThreadAsUnresolved({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { userId: "steven@example.com", }, }); // { type: "thread", id: "th_d75sF3...", ... } console.log(thread); ``` #### Liveblocks.deleteThread [#delete-rooms-roomId-threads-threadId] Deletes a thread. Throws an error if the room or thread isn’t found. This is a wrapper around the [Delete Thread API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-threads-threadId) and returns no response. ```ts await liveblocks.deleteThread({ roomId: "my-room-id", threadId: "th_d75sF3...", }); ``` #### Liveblocks.subscribeToThread [#post-rooms-roomId-threads-threadId-subscribe] Subscribes a user to a thread, meaning they will receive inbox notifications when new comments are posted. Throws an error if the room or thread isn’t found. This is a wrapper around the [Subscribe To Thread API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-subscribe) and returns the same response. ```ts const subscription = await liveblocks.subscribeToThread({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { userId: "steven@example.com", }, }); // { kind: "thread", subjectId: "th_d75sF3...", ... } console.log(subscription); ``` Subscribing will replace any existing subscription for the current thread [set at room-level](#post-rooms-roomId-users-userId-subscription-settings). This value can also be overridden by a room-level call that is run afterwards. ```ts const roomId = "my-room-id"; const userId = "steven@example.com"; // 1. Disables notifications for all threads await liveblocks.updateRoomSubscriptionSettings({ roomId, userId, data: { threads: "none", }, }); // 2. Enables notifications just for this thread, "th_d75sF3..." await liveblocks.subscribeToThread({ roomId, threadId: "th_d75sF3...", data: { userId }, }); // 3. Disables notifications for all threads, including "th_d75sF3..." await liveblocks.updateRoomSubscriptionSettings({ roomId, userId, data: { threads: "none", }, }); ``` #### Liveblocks.unsubscribeFromThread [#post-rooms-roomId-threads-threadId-unsubscribe] Unsubscribes a user from a thread, meaning they will no longer receive inbox notifications when new comments are posted. Throws an error if the room or thread isn’t found. This is a wrapper around the [Unsubscribe From Thread API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-unsubscribe) and returns the same response. ```ts await liveblocks.unsubscribeFromThread({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { userId: "steven@example.com", }, }); ``` Unsubscribing will replace any existing subscription for the current thread [set at room-level](#post-rooms-roomId-users-userId-subscription-settings). This value can also be overridden by a room-level call that is run afterwards. ```ts const roomId = "my-room-id"; const userId = "steven@example.com"; // 1. Enables notifications for all thread activity await liveblocks.updateRoomSubscriptionSettings({ roomId, userId, data: { threads: "all", }, }); // 2. Disables notifications just for this thread, "th_d75sF3..." await liveblocks.unsubscribeFromThread({ roomId, threadId: "th_d75sF3...", data: { userId }, }); // 3. Enables notifications for all thread activity, including "th_d75sF3..." await liveblocks.updateRoomSubscriptionSettings({ roomId, userId, data: { threads: "none", }, }); ``` #### Liveblocks.getThreadSubscriptions [#get-rooms-roomId-threads-threadId-subscriptions] Gets a thread’s subscriptions, returning a list of users that will receive notifications when new comments are posted. Throws an error if the room or thread isn’t found. This is a wrapper around the [Get Thread Subscriptions API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads-threadId-subscriptions) and returns the same response. ```ts const { data: subscriptions } = await liveblocks.getThreadSubscriptions({ roomId: "my-room-id", threadId: "th_d75sF3...", }); // [{ kind: "thread", subjectId: "th_d75sF3...", userId: "steven@example.com", ... }, ...] console.log(subscriptions); ``` #### Liveblocks.createComment [#post-rooms-roomId-threads-threadId-comments] Creates a new comment in a specific thread within a room. This method allows users to add comments to a conversation thread, specifying the user who made the comment and the content of the comment. This method is a wrapper around the [Create Comment API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments) and returns the new comment. ```ts const comment = await liveblocks.createComment({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { body: { version: 1, content: [ /* The comment's body text goes here, see below */ ], }, userId: "pierre@example.com", createdAt: new Date(), // Optional }, }); ``` A comment’s body is an array of paragraphs, each containing child nodes. Here’s an example of how to construct a comment’s body, which can be submitted under `data.body`. ```tsx highlight="3-11,19" import { CommentBody } from "@liveblocks/node"; const body: CommentBody = { version: 1, content: [ { type: "paragraph", children: [{ text: "Hello " }, { text: "world", bold: true }], }, ], }; const comment = await liveblocks.createComment({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { // The comment's body, uses the `CommentBody` type body, // ... }, }); ``` This method has a number of options, including the option to add a custom creation date and metadata to the comment. ```ts const comment = await liveblocks.createComment({ roomId: "my-room-id", threadId: "th_d75sF3...", data: { // The comment's body, uses the `CommentBody` type body: { version: 1, content: [ /* The comment's body text goes here, see above */ ], }, // The ID of the user that created the comment userId: "adrien@example.com", // Optional, the time the comment was created createdAt: new Date(), // Optional, custom comment metadata metadata: { tag: "important", reviewed: false, }, }, }); ``` #### Liveblocks.getComment [#get-rooms-roomId-threads-threadId-comments-commentId] Returns a comment. Throws an error if the room, thread, or comment isn’t found. This is a wrapper around the [Get Comment API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads-threadId-comments-commentId) and returns the same response. ```ts const comment = await liveblocks.getComment({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", }); // { type: "comment", threadId: "th_d75sF3...", ... } console.log(comment); ``` #### Liveblocks.editComment [#post-rooms-roomId-threads-threadId-comments-commentId] Edits an existing comment in a specific thread within a room. This method allows users to update the content of their previously posted comments, with the option to specify the time of the edit. Throws an error if the comment isn’t found. This is a wrapper around the [Edit Comment API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId) and returns the updated comment. ```ts const editedComment = await liveblocks.editComment({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { userId: "alicia@example.com", body: { version: 1, content: [ /* The comment's body text goes here, see below */ ], }, // Optional, the time the comment was edited editedAt: new Date(), // Optional, custom comment metadata metadata: { tag: "important", spam: false, }, }, }); // { type: "comment", threadId: "th_d75sF3...", ... } console.log(editedComment); ``` A comment’s body is an array of paragraphs, each containing child nodes. Here’s an example of how to construct a comment’s body, which can be submitted under `data.body`. ```tsx import { CommentBody } from "@liveblocks/node"; // +++ const body: CommentBody = { version: 1, content: [ { type: "paragraph", children: [{ text: "Hello " }, { text: "world", bold: true }], }, ], }; // +++ const editedComment = await liveblocks.editComment({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { // The comment's body, uses the `CommentBody` type // +++ body, // +++ // ... }, }); ``` #### Liveblocks.deleteComment [#delete-rooms-roomId-threads-threadId-comments-commentId] Deletes a specific comment from a thread within a room. If there are no remaining comments in the thread, the thread is also deleted. This method throws an error if the comment isn’t found. This is a wrapper around the [Delete Comment API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId) and returns no response. ```ts await liveblocks.deleteComment({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", }); ``` #### Liveblocks.addCommentReaction [#post-rooms-roomId-threads-threadId-comments-commentId-add-reaction] Adds a reaction to a specific comment in a thread within a room. Throws an error if the comment isn’t found or if the user has already added the same reaction on the comment. This is a wrapper around the [Add Comment Reaction API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId-add-reaction) and returns the new reaction. ```ts const reaction = await liveblocks.addCommentReaction({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { emoji: "👨‍👩‍👧", userId: "guillaume@example.com", createdAt: new Date(), // Optional, the time the reaction was added }, }); // { emoji: "👨‍👩‍👧", userId "guillaume@example.com", ... } console.log(reaction); ``` #### Liveblocks.removeCommentReaction [#post-rooms-roomId-threads-threadId-comments-commentId-remove-reaction] Removes a reaction from a specific comment in a thread within a room. Throws an error if the comment reaction isn’t found. This is a wrapper around the [Remove Comment Reaction API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId-remove-reaction) and returns no response. ```ts await liveblocks.removeCommentReaction({ roomId: "my-room-id", threadId: "th_d75sF3...", commentId: "cm_agH76a...", data: { emoji: "👨‍👩‍👧", userId: "steven@example.com", removedAt: new Date(), // Optional, the time the reaction is to be removed }, }); ``` #### Liveblocks.getRoomSubscriptionSettings [#get-rooms-roomId-users-userId-subscription-settings] Returns a user’s subscription settings for a specific room, specifying which `thread` and `textMention` inbox notifications they are set to receive. This is a wrapper around the [Get Room Subscription Settings API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-users-userId-subscription-settings). ```ts const subscriptionSettings = await liveblocks.getRoomSubscriptionSettings({ roomId: "my-room-id", userId: "steven@example.com", }); // { threads: "all", textMentions: "mine" } console.log(subscriptionSettings); ``` For `"threads"`, these are the three possible values: - `"all"` Receive notifications for every activity in every thread. - `"replies_and_mentions"` Receive notifications for mentions and threads you’re participating in. - `"none"` No notifications are received. For `"textMentions"`, these are the two possible values: - `"mine"` Receive notifications for mentions of you. - `"none"` No notifications are received. #### Liveblocks.updateRoomSubscriptionSettings [#post-rooms-roomId-users-userId-subscription-settings] Updates a user’s subscription settings for a specific room, defining which `thread` and `textMention` inbox notifications they will receive. This is a wrapper around the [Update Room Subscription Settings API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-users-userId-subscription-settings). ```ts const updatedSubscriptionSettings = await liveblocks.updateRoomSubscriptionSettings({ roomId: "my-room-id", userId: "steven@example.com", data: { threads: "replies_and_mentions", textMentions: "mine", }, }); // { threads: "replies_and_mentions", ... } console.log(updatedSubscriptionSettings); ``` For `"threads"`, these are the three possible values that can be set: - `"all"` Receive notifications for every activity in every thread. - `"replies_and_mentions"` Receive notifications for mentions and threads you’re participating in. - `"none"` No notifications are received. For `"textMentions"`, these are the two possible values that can be set: - `"mine"` Receive notifications for mentions of you. - `"none"` No notifications are received. ##### Replacing individual thread subscriptions Subscribing will replace any [existing thread subscriptions](#post-rooms-roomId-users-userId-subscription-settings) in the current room. This value can also be overridden by a room-level call that is run afterwards. ```ts const roomId = "my-room-id"; const userId = "steven@example.com"; // 1. Enables notifications just for this thread, "th_d75sF3..." await liveblocks.subscribeToThread({ roomId, threadId: "th_d75sF3...", data: { userId }, }); // 2. Disables notifications for all threads, including "th_d75sF3..." await liveblocks.updateRoomSubscriptionSettings({ roomId, userId, data: { threads: "none", }, }); ``` #### Liveblocks.deleteRoomSubscriptionSettings [#delete-rooms-roomId-users-userId-subscription-settings] Deletes a user’s subscription settings for a specific room. This is a wrapper around the [Delete Room Subscription Settings API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-users-userId-subscription-settings). ```ts await liveblocks.deleteRoomSubscriptionSettings({ roomId: "my-room-id", userId: "steven@example.com", }); ``` #### Liveblocks.getUserRoomSubscriptionSettings [#get-users-userId-room-subscription-settings] Returns a list of a user’s subscription settings for all rooms. This is a wrapper around the [Get User Room Subscription Settings API](/docs/api-reference/rest-api-endpoints#get-users-userId-room-subscription-settings). ```ts const { data: subscriptionSettings, nextCursor } = await liveblocks.getUserRoomSubscriptionSettings({ userId: "steven@example.com", // Optional, filter for a specific organization organizationId: "acme-corp", }); console.log(subscriptionSettings); // { roomId: "my-room-id", threads: "all", ... } // Pagination if (nextCursor) { const { data: nextPage } = await liveblocks.getUserRoomSubscriptionSettings({ userId: "steven@example.com", startingAfter: nextCursor, }); } ``` ### Feeds #### Liveblocks.getFeeds [#get-rooms-roomId-feeds] Returns a list of feeds in a room. This is a wrapper around the [Get Room Feeds API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-feeds) and returns the same response. ```ts const { data: feeds } = await liveblocks.getFeeds({ roomId: "my-room-id", }); // [{ feedId: "feed-1", metadata: {...}, timestamp: 1234567890 }, ...] console.log(feeds); ``` #### Liveblocks.createFeed [#post-rooms-roomId-feed] Creates a new feed in a room. This is a wrapper around the [Create Feed API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-feed) and returns the created feed. ```ts const feed = await liveblocks.createFeed({ roomId: "my-room-id", feedId: "my-feed-id", // Optional, custom metadata for the feed metadata: { name: "My Feed", channel: true, }, // Optional, timestamp in milliseconds. Defaults to current time if not provided timestamp: Date.now(), }); // { feedId: "my-feed-id", metadata: {...}, timestamp: 1234567890 } console.log(feed); ``` #### Liveblocks.getFeed [#get-rooms-roomId-feeds-feedId] Returns a feed by its ID. This is a wrapper around the [Get Feed API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-feeds-feedId) and returns the same response. ```ts const feed = await liveblocks.getFeed({ roomId: "my-room-id", feedId: "my-feed-id", }); // { feedId: "my-feed-id", metadata: {...}, timestamp: 1234567890 } console.log(feed); ``` #### Liveblocks.updateFeed [#patch-rooms-roomId-feeds-feedId] Updates the metadata of a feed. This is a wrapper around the [Update Feed API](/docs/api-reference/rest-api-endpoints#patch-rooms-roomId-feeds-feedId). ```ts await liveblocks.updateFeed({ roomId: "my-room-id", feedId: "my-feed-id", metadata: { name: "Updated Feed Name", updated: new Date().toISOString(), }, }); ``` #### Liveblocks.deleteFeed [#delete-rooms-roomId-feeds-feedId] Deletes a feed. This is a wrapper around the [Delete Feed API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-feeds-feedId). ```ts await liveblocks.deleteFeed({ roomId: "my-room-id", feedId: "my-feed-id", }); ``` #### Liveblocks.getFeedMessages [#get-rooms-roomId-feeds-feedId-messages] Returns a list of messages in a feed. This is a wrapper around the [Get Feed Messages API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-feeds-feedId-messages) and returns the same response. ```ts const { data: messages } = await liveblocks.getFeedMessages({ roomId: "my-room-id", feedId: "my-feed-id", }); // [{ id: "msg-1", timestamp: 1234567890, data: {...} }, ...] console.log(messages); ``` #### Liveblocks.createFeedMessage [#post-rooms-roomId-feeds-feedId-messages] Creates a new message in a feed. This is a wrapper around the [Create Feed Message API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-feeds-feedId-messages) and returns the created message. ```ts const message = await liveblocks.createFeedMessage({ roomId: "my-room-id", feedId: "my-feed-id", // The message data data: { role: "user", content: "Hello, world!", }, // Optional, custom message ID. One will be generated if not provided id: "my-message-id", // Optional, timestamp in milliseconds. Defaults to current time if not provided timestamp: Date.now(), }); // { id: "my-message-id", timestamp: 1234567890, data: {...} } console.log(message); ``` #### Liveblocks.updateFeedMessage [#patch-rooms-roomId-feeds-feedId-messages-messageId] Updates a feed message. This is a wrapper around the [Update Feed Message API](/docs/api-reference/rest-api-endpoints#patch-rooms-roomId-feeds-feedId-messages-messageId). ```ts await liveblocks.updateFeedMessage({ roomId: "my-room-id", feedId: "my-feed-id", messageId: "my-message-id", data: { role: "user", content: "Updated content", }, }); ``` #### Liveblocks.deleteFeedMessage [#delete-rooms-roomId-feeds-feedId-messages-messageId] Deletes a feed message. This is a wrapper around the [Delete Feed Message API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-feeds-feedId-messages-messageId). ```ts await liveblocks.deleteFeedMessage({ roomId: "my-room-id", feedId: "my-feed-id", messageId: "my-message-id", }); ``` ### Notifications #### Liveblocks.getInboxNotifications [#get-users-userId-inboxNotifications] Returns a list of a user’s inbox notifications. This is a wrapper around the [Get Inbox Notifications API](/docs/api-reference/rest-api-endpoints#get-users-userId-inboxNotifications). It also provides an unread query parameter to filter unread notifications. ```ts const { data: inboxNotifications, nextCursor } = await liveblocks.getInboxNotifications({ userId: "steven@example.com" }); // [{ id: "in_3dH7sF3...", kind: "thread", ... }, { id: "in_3dH7sF3...", kind: "textMention", ... }, ...] console.log(inboxNotifications); // Filter unread notifications const { data: unreadInboxNotifications, nextCursor } = await liveblocks.getInboxNotifications({ userId: "steven@example.com", query: { unread: true }, // Optional, filter for a specific organization organizationId: "acme-corp", }); ``` ##### Pagination You can use `nextCursor` to paginate inbox notifications. In this example, when `getNextPage` is called, the next page of inbox notifications is added to `pages`. ```ts import { InboxNotificationData } from "@liveblocks/node"; // An array of pages, each containing a list of retrieved inbox notifications const pages: InboxNotificationData[][] = []; // Holds the pagination cursor for the next set of inbox notifications let startingAfter; // Call to get the next page of inbox notifications async function getNextPage() { const { data, nextCursor } = await liveblocks.getInboxNotifications({ startingAfter, }); pages.push(data); startingAfter = nextCursor; } ``` If you’d like to iterate over all your inbox notifications, it’s most convenient to use [`liveblocks.iterInboxNotifications`](#iter-users-userId-inboxNotifications) instead. This method automatically paginates your API requests. #### Liveblocks.iterInboxNotifications [#iter-users-userId-inboxNotifications] Returns a list of inbox notifications for the given user. Works similarly to [`liveblocks.getInboxNotifications`](#get-users-userId-inboxNotifications), but instead returns an asynchronous iterator, which helps you iterate over all the inbox notifications, without having to manually paginate through the results. ```ts const userId = "steven@example.com"; for await (const item of liveblocks.iterInboxNotifications({ userId, // Optional, filter for a specific organization organizationId: "acme-corp", })) { console.log(item.id); // in_3dH7sF3... console.log(item.kind); // "thread", "textMention", ... } ``` #### Liveblocks.getInboxNotification [#get-users-userId-inboxNotifications-inboxNotificationId] Returns a user’s inbox notification. This is a wrapper around the [Get Inbox Notification API](/docs/api-reference/rest-api-endpoints#get-users-userId-inboxNotifications-inboxNotificationId). ```ts const inboxNotification = await liveblocks.getInboxNotification({ userId: "steven@example.com", inboxNotificationId: "in_3dH7sF3...", }); // { id: "in_3dH7sF3...", kind: "thread", ... } // or { id: "in_3dH7sF3...", kind: "textMention", ... } // or { id: "in_3dH7sF3...", kind: "$yourKind", ... } console.log(inboxNotification); ``` #### Liveblocks.triggerInboxNotification [#post-inbox-notifications-trigger] Triggers a custom inbox notification. `kind` must start with a `$`, and represents the type of notification. `activityData` is used to send custom data with the notification, and properties can have `string`, `number`, or `boolean` values. Notifications [can be batched](#Batching-custom-notifications). This is a wrapper around the [Trigger Inbox Notification API](/docs/api-reference/rest-api-endpoints#post-inbox-notifications-trigger). ```ts await liveblocks.triggerInboxNotification({ // The ID of the user that will receive the inbox notification userId: "steven@example.com", // The custom notification kind, must start with a $ kind: "$fileUploaded", // Custom ID for this specific notification subjectId: "my-file", // Custom data related to the activity that you need to render the inbox notification activityData: { // Data can be a string, number, or boolean file: "https://example.com/my-file.zip", size: 256, success: true, }, // Optional, define the room ID the notification was sent from roomId: "my-room-id", // Optional, trigger it for a specific organization organizationId: "acme-corp", }); ``` ##### Typing custom notifications To type custom notifications, edit the `ActivitiesData` type in your config file. ```ts file="liveblocks.config.ts" highlight="4-10" declare global { interface Liveblocks { // Custom activities data for custom notification kinds ActivitiesData: { // Example, a custom $alert kind $alert: { title: string; message: string; }; }; // Other kinds // ... } } ``` ##### Batching custom notifications You can configure a custom notification kind to have batching enabled. When it’s enabled, triggering an inbox notification activity for a specific `subjectId`, will update the existing inbox notification instead of creating a new one. To use this, you must first [enable batching in the dashboard](/docs/ready-made-features/notifications/concepts#Notification-batching). Next, trigger a notification with the same `subjectId` as an existing notification, and the result will be added to the `activityData` array. ```ts const options = { userId: "steven@example.com", kind: "$fileUploaded", subjectId: "my-file", }; await liveblocks.triggerInboxNotification({ ...options, // +++ activityData: { status: "processing", }, // +++ }); await liveblocks.triggerInboxNotification({ ...options, // +++ activityData: { status: "complete", }, // +++ }); const { data: inboxNotifications } = await liveblocks.getInboxNotifications({ userId: "steven@example.com", }); // { // id: "in_3dH7sF3...", // kind: "$fileUploaded", // +++ // activities: [ // { status: "processing" }, // { status: "complete" }, // ], // +++ // ... // } console.log(inboxNotifications[0]); ``` An inbox notification can have up to 50 activities, if you exceed this number, a new inbox notification will be created. #### Liveblocks.deleteInboxNotification [#delete-users-userId-inboxNotifications-inboxNotificationId] Deletes a user’s inbox notification. This is a wrapper around the [Delete Inbox Notification API](/docs/api-reference/rest-api-endpoints#delete-users-userId-inboxNotifications-inboxNotificationId). ```ts await liveblocks.deleteInboxNotification({ userId: "steven@example.com", inboxNotificationId: "in_3dH7sF3...", }); ``` #### Liveblocks.deleteAllInboxNotifications [#delete-users-userId-inboxNotifications] Deletes all the user’s inbox notifications. This is a wrapper around the [Delete Inbox Notifications API](/docs/api-reference/rest-api-endpoints#delete-users-userId-inboxNotifications). ```ts await liveblocks.deleteAllInboxNotifications({ userId: "steven@example.com", // Optional, delete for a specific organization organizationId: "acme-corp", }); ``` #### Liveblocks.getNotificationSettings [#get-users-userId-notification-settings] [@badge=Beta] Returns a user’s notification settings in the current project, in other words which [notification webhook events](/docs/platform/webhooks#NotificationEvent) will be sent for the user. Notification settings are project-based, which means that this returns the user’s settings for every room. This a wrapper around the [Get Notification Settings API](/docs/api-reference/rest-api-endpoints#get-users-userId-notification-settings). ```ts const settings = await liveblocks.getNotificationSettings({ userId: "guillaume@liveblocks.io", }); // { email: { thread: true, ... }, slack: { thread: false, ... }, ... } console.log(settings); ``` A user’s initial settings are set in the dashboard, and different kinds should be enabled there. If no kind is enabled on the current channel, `null` will be returned. For example, with the email channel: ```ts const settings = await liveblocks.getNotificationSettings({ userId: "guillaume@liveblocks.io", }); // { email: null, ... } console.log(settings); ``` #### Liveblocks.updateNotificationSettings [#post-users-userId-notification-settings] [@badge=Beta] Updates a user’s notification settings, which affects which [notification webhook events](/docs/platform/webhooks#NotificationEvent) will be sent for the user. Notification settings are project-based, which means that this modifies the user’s settings in every room. Each notification `kind` must first be enabled on your project’s notification dashboard page before settings can be used. This a wrapper around the [Update Notification Settings API](/docs/api-reference/rest-api-endpoints#post-users-userId-notification-settings). ```ts const updatedSettings = await liveblocks.updateNotificationSettings({ userId: "steven@example.com", data: { email: { thread: false }, slack: { textMention: true }, }, }); // { email: { thread: false, ... }, slack: { textMention: true, ... }, ... } console.log(updatedSettings); ``` You can pass a partial object, or many settings at once. ```ts // You only need to pass partials await liveblocks.updateNotificationSettings({ userId: "steven@example.com", email: { thread: true }, }); // Enabling a custom notification on the slack channel await liveblocks.updateNotificationSettings({ userId: "steven@example.com", slack: { $myCustomNotification: true }, }); // Setting complex settings await liveblocks.updateNotificationSettings({ userId: "steven@example.com", email: { thread: true, textMention: false, $newDocument: true, }, slack: { thread: false, $fileUpload: false, }, teams: { thread: true, }, }); ``` #### Liveblocks.deleteNotificationSettings [#delete-users-userId-notification-settings] [@badge=Beta] Deletes the user’s notification settings, resetting them to the default values. The default values can be adjusted in a project’s notification dashboard page. This a wrapper around the [Delete Notification Settings API](/docs/api-reference/rest-api-endpoints#delete-users-userId-notification-settings). ```ts await liveblocks.deleteNotificationSettings({ userId: "adri@example.com", }); ``` ### AI Copilots #### Liveblocks.getAiCopilots [#get-ai-copilots] Returns a paginated list of AI copilots. The copilots are returned sorted by creation date, from newest to oldest. This is a wrapper around the [Get AI Copilots API](/docs/api-reference/rest-api-endpoints#get-ai-copilots) and returns the same response. ```ts const { data: copilots, nextCursor } = await liveblocks.getAiCopilots(); // A list of AI copilots // [{ type: "copilot", id: "co_abc123...", name: "My Copilot", ... }, ...] console.log(copilots); // A pagination cursor used for retrieving the next page of results with `startingAfter` // "L3YyL3Jvb21z..." console.log(nextCursor); ``` Pagination options are available to control the number of results returned. ```ts const { data: copilots, nextCursor } = await liveblocks.getAiCopilots({ // Optional, the amount of copilots to load, between 1 and 100, defaults to 20 limit: 20, // Optional, cursor used for pagination, use `nextCursor` from the previous page's response startingAfter: "L3YyL3Jvb21z...", }); ``` #### Liveblocks.createAiCopilot [#create-ai-copilot] Creates a new AI copilot with the given configuration. This is a wrapper around the [Create AI Copilot API](/docs/api-reference/rest-api-endpoints#create-ai-copilot) and returns the same response. ```ts const copilot = await liveblocks.createAiCopilot({ name: "My AI Assistant", systemPrompt: "You are a helpful AI assistant for our team.", provider: "openai", providerModel: "gpt-4", providerApiKey: "sk-...", // Your OpenAI API key }); // { type: "copilot", id: "co_abc123...", name: "My AI Assistant", ... } console.log(copilot); ``` The method supports various configuration options for different AI providers. ```ts const copilot = await liveblocks.createAiCopilot({ // Required, the name of the copilot name: "Documentation Helper", // Optional, a description of what the copilot does description: "Helps users understand our documentation", // Required, the system prompt that defines the copilot's behavior systemPrompt: "You are an expert at helping users understand technical documentation.", // Optional, additional knowledge context for the copilot knowledgePrompt: "Use our company's style guide when providing examples.", // Optional, always retrieve knowledge sources on each query alwaysUseKnowledge: true, // Required, the AI provider to use provider: "openai", // Required for standard providers, the model to use providerModel: "gpt-4-turbo", // Required, your API key for the provider providerApiKey: "sk-...", // Optional, provider-specific options providerOptions: { openai: { reasoningEffort: "low", // Optional, restrict web search to specific domains for OpenAI webSearch: { allowedDomains: ["docs.liveblocks.io", "example.com"], }, }, }, // Optional, model settings settings: { maxTokens: 1000, temperature: 0.7, topP: 0.9, frequencyPenalty: 0.1, presencePenalty: 0.1, stopSequences: ["END"], seed: 42, maxRetries: 3, }, }); ``` For OpenAI-compatible providers, use a different configuration: ```ts const copilot = await liveblocks.createAiCopilot({ name: "Custom AI Helper", systemPrompt: "You are a helpful assistant.", provider: "openai-compatible", compatibleProviderName: "my-custom-provider", providerBaseUrl: "https://api.mycustomprovider.com/v1", providerApiKey: "your-api-key-here", // Your API key for the custom provider providerModel: "custom-provider-model", }); ``` You can also configure Anthropic or Google providers with provider-specific options: ```ts // Anthropic example await liveblocks.createAiCopilot({ name: "Anthropic Helper", systemPrompt: "You are a helpful assistant.", provider: "anthropic", providerModel: "claude-3-5-sonnet-latest", providerApiKey: "sk-...", providerOptions: { anthropic: { thinking: { type: "disabled" }, webSearch: { allowedDomains: ["example.com"], }, }, }, }); // Google example await liveblocks.createAiCopilot({ name: "Gemini Helper", systemPrompt: "You are a helpful assistant.", provider: "google", providerModel: "gemini-2.5-pro", providerApiKey: "sk-...", providerOptions: { google: { thinkingConfig: { thinkingBudget: 2000 }, }, }, }); ``` #### Liveblocks.getAiCopilot [#get-ai-copilot] Returns an AI copilot by its ID. Throws an error if the copilot isn’t found. This is a wrapper around the [Get AI Copilot API](/docs/api-reference/rest-api-endpoints#get-ai-copilot) and returns the same response. ```ts const copilot = await liveblocks.getAiCopilot("co_abc123..."); // { type: "copilot", id: "co_abc123...", name: "My AI Assistant", ... } console.log(copilot); ``` #### Liveblocks.updateAiCopilot [#update-ai-copilot] Updates an existing AI copilot’s configuration. You only need to pass the properties you want to update. Throws an error if the copilot isn’t found. This is a wrapper around the [Update AI Copilot API](/docs/api-reference/rest-api-endpoints#update-ai-copilot) and returns the same response. ```ts const updatedCopilot = await liveblocks.updateAiCopilot("co_abc123...", { name: "Updated AI Assistant", description: "Now with improved capabilities", }); // { type: "copilot", id: "co_abc123...", name: "Updated AI Assistant", ... } console.log(updatedCopilot); ``` You can update various aspects of the copilot: ```ts const updatedCopilot = await liveblocks.updateAiCopilot("co_abc123...", { // Optional, update the name name: "Better AI Helper", // Optional, update the description description: "Enhanced with new features", // Optional, update the system prompt systemPrompt: "You are an even more helpful AI assistant.", // Optional, update the knowledge prompt knowledgePrompt: "Reference our latest guidelines.", // Optional, always retrieve knowledge sources on each query alwaysUseKnowledge: true, // Optional, update provider-specific options (replaces the entire nested options object) // Set to null to clear options providerOptions: null, // Optional, update model settings settings: { temperature: 0.5, maxTokens: 1500, }, }); ``` You can also update provider options. When updating `providerOptions`, it fully replaces the previous nested options (no deep merge): ```ts // Update OpenAI provider options (replaces prior options) await liveblocks.updateAiCopilot("co_abc123...", { provider: "openai", providerOptions: { openai: { reasoningEffort: "medium", webSearch: { allowedDomains: ["docs.liveblocks.io"] }, }, }, }); // Update Anthropic thinking/web search settings await liveblocks.updateAiCopilot("co_abc123...", { provider: "anthropic", providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 2000 }, webSearch: { maxUses: 2 }, }, }, }); ``` Certain properties can be set to `null` to clear them from the copilot’s configuration. This includes `description`, `knowledgePrompt`, `settings`, and `providerOptions`. ```ts const updatedCopilot = await liveblocks.updateAiCopilot("co_abc123...", { // Clear the description description: null, // Clear the knowledge prompt knowledgePrompt: null, // Clear all model settings settings: null, }); ``` The method returns a 422 response if the update doesn’t apply due to validation failures. For example, if the existing copilot uses the "openai" provider and you attempt to update the provider model to an incompatible value for the provider, like "gemini-2.5-pro", you’ll receive a 422 response with an error message explaining where the validation failed. #### Liveblocks.deleteAiCopilot [#delete-ai-copilot] Deletes an AI copilot by its ID. A deleted copilot is no longer accessible and cannot be restored. Throws an error if the copilot isn’t found. This is a wrapper around the [Delete AI Copilot API](/docs/api-reference/rest-api-endpoints#delete-ai-copilot) and returns no response. ```ts await liveblocks.deleteAiCopilot("co_abc123..."); ``` ### Knowledge Sources #### Liveblocks.createWebKnowledgeSource [#create-web-knowledge-source] Creates a web knowledge source for an AI copilot. This allows the copilot to access and learn from web content. This is a wrapper around the [Create Web Knowledge Source API](/docs/api-reference/rest-api-endpoints#create-web-knowledge-source) and returns the ID of the created knowledge source. ```ts const { id } = await liveblocks.createWebKnowledgeSource({ copilotId: "co_abc123...", url: "https://example.com/documentation", type: "individual_link", }); // "ks_def456..." console.log(id); ``` Different types of web knowledge sources are supported: ```ts // Index a single web page const singlePage = await liveblocks.createWebKnowledgeSource({ copilotId: "co_abc123...", url: "https://example.com/important-page", type: "individual_link", }); // Crawl an entire website const crawledSite = await liveblocks.createWebKnowledgeSource({ copilotId: "co_abc123...", url: "https://example.com", type: "crawl", }); // Use a sitemap to index multiple pages const sitemapSource = await liveblocks.createWebKnowledgeSource({ copilotId: "co_abc123...", url: "https://example.com/sitemap.xml", type: "sitemap", }); ``` #### Liveblocks.createFileKnowledgeSource [#create-file-knowledge-source] Creates a file knowledge source for an AI copilot by uploading a file. The copilot can then reference the content of the file when responding. This is a wrapper around the [Create File Knowledge Source API](/docs/api-reference/rest-api-endpoints#create-file-knowledge-source) and returns the ID of the created knowledge source. **Note:** Currently only PDF files (`application/pdf`) and images (`image/*`) are supported. ```ts const { id } = await liveblocks.createFileKnowledgeSource({ copilotId: "co_abc123...", file: pdfFile, // Must be a PDF or image file }); // "ks_ghi789..." console.log(id); ``` #### Liveblocks.getKnowledgeSources [#get-knowledge-sources] Returns a paginated list of knowledge sources for a specific AI copilot. This is a wrapper around the [Get Knowledge Sources API](/docs/api-reference/rest-api-endpoints#get-knowledge-sources) and returns the same response. ```ts const { data: sources, nextCursor } = await liveblocks.getKnowledgeSources({ copilotId: "co_abc123...", }); // [{ type: "ai-knowledge-web-source", id: "ks_abc123...", ... }, ...] console.log(sources); ``` Pagination options are available: ```ts const { data: sources, nextCursor } = await liveblocks.getKnowledgeSources({ copilotId: "co_abc123...", // Optional, the amount of knowledge sources to load, between 1 and 100, defaults to 20 limit: 20, // Optional, cursor used for pagination startingAfter: "L3YyL3Jvb21z...", }); ``` #### Liveblocks.getKnowledgeSource [#get-knowledge-source] Returns a specific knowledge source by its ID. Throws an error if the knowledge source isn’t found. This is a wrapper around the [Get Knowledge Source API](/docs/api-reference/rest-api-endpoints#get-knowledge-source) and returns the same response. ```ts const source = await liveblocks.getKnowledgeSource({ copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", }); // { type: "ai-knowledge-web-source", id: "ks_def456...", ... } // or { type: "ai-knowledge-file-source", id: "ks_def456...", ... } console.log(source); ``` #### Liveblocks.getFileKnowledgeSourceMarkdown [#get-file-knowledge-source-markdown] Returns the content of a file knowledge source as Markdown. This allows you to see what content the AI copilot has access to from uploaded files. Throws an error if the knowledge source isn’t found. This is a wrapper around the [Get File Knowledge Source Content API](/docs/api-reference/rest-api-endpoints#get-file-knowledge-source-content) and returns the content as a string. ```ts const content = await liveblocks.getFileKnowledgeSourceMarkdown({ copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", }); // "# Document Title\n\nThis is the content of the uploaded file..." console.log(content); ``` #### Liveblocks.getWebKnowledgeSourceLinks [#get-web-knowledge-source-links] Returns a paginated list of links that were indexed from a web knowledge source. This is useful for understanding what content the AI copilot has access to from web sources. This is a wrapper around the [Get Web Knowledge Source Links API](/docs/api-reference/rest-api-endpoints#get-web-knowledge-source-links) and returns the same response. ```ts const { data: links, nextCursor } = await liveblocks.getWebKnowledgeSourceLinks( { copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", } ); // [{ id: "link_123...", url: "https://example.com/page1", status: "ready", ... }, ...] console.log(links); ``` Pagination options are available: ```ts const { data: links, nextCursor } = await liveblocks.getWebKnowledgeSourceLinks( { copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", // Optional, the amount of links to load, between 1 and 100, defaults to 20 limit: 20, // Optional, cursor used for pagination startingAfter: "L3YyL3Jvb21z...", } ); ``` #### Liveblocks.deleteWebKnowledgeSource [#delete-web-knowledge-source] Deletes a web knowledge source from an AI copilot. The copilot will no longer have access to the content from this source. Throws an error if the knowledge source isn’t found. This is a wrapper around the [Delete Web Knowledge Source API](/docs/api-reference/rest-api-endpoints#delete-web-knowledge-source) and returns no response. ```ts await liveblocks.deleteWebKnowledgeSource({ copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", }); ``` #### Liveblocks.deleteFileKnowledgeSource [#delete-file-knowledge-source] Deletes a file knowledge source from an AI copilot. The copilot will no longer have access to the content from this file. Throws an error if the knowledge source isn’t found. This is a wrapper around the [Delete File Knowledge Source API](/docs/api-reference/rest-api-endpoints#delete-file-knowledge-source) and returns no response. ```ts await liveblocks.deleteFileKnowledgeSource({ copilotId: "co_abc123...", knowledgeSourceId: "ks_def456...", }); ``` ### Error handling [#error-handling] Errors in our API methods, such as network failures, invalid arguments, or server-side issues, are reported through the `LiveblocksError` class. This custom error class extends the standard JavaScript [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) and includes a `status` property, which provides the HTTP status code for the error, such as 404 for not found or 500 for server errors. Example of handling errors in a typical API call: ```ts try { const room = await liveblocks.getRoom("my-room-id"); // Process room } catch (error) { if (error instanceof LiveblocksError) { // Handle specific LiveblocksError cases console.error(`Error fetching room: ${error.status} - ${error.message}`); switch ( error.status // Specific cases based on status codes ) { } } else { // Handle general errors console.error(`Unexpected error: ${error.message}`); } } ``` ## Utilities ### getMentionsFromCommentBody [#get-mentions-from-comment-body] Returns an array of mentions from a `CommentBody` (found under `comment.body`). ```ts import { getMentionsFromCommentBody } from "@liveblocks/node"; const mentions = getMentionsFromCommentBody(comment.body); ``` An optional second argument can be used to filter the returned mentions. By default, if it’s not provided, all mentions are returned, including future mention kinds (e.g. group mentions in the future). ```tsx // All mentions (same as `getMentionsFromCommentBody(commentBody)`) getMentionsFromCommentBody(commentBody); // Only user mentions with an ID of "123" getMentionsFromCommentBody( commentBody, (mention) => mention.kind === "user" && mention.id === "123" ); // Only mentions with an ID which starts with "prefix:" getMentionsFromCommentBody(commentBody, (mention) => ( mention.id.startsWith("prefix:") ); ``` This is most commonly used in combination with the [Comments API functions](/docs/api-reference/liveblocks-node#Comments), for example [`getComment`](/docs/api-reference/liveblocks-node#get-comment). ```ts import { Liveblocks, getMentionsFromCommentBody } from "@liveblocks/node"; // Create a node client const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); // Retrieve a comment const comment = await liveblocks.getComment({ roomId: "my-room-id", threadId: "my-thread-id", commentId: "my-comment-id", }); // Get the mentions inside the comment's body const mentions = getMentionsFromCommentBody(comment.body); // [{ kind: "user", id: "marc@example.com" }, { kind: "user", id: "vincent@example.com" }, ...] console.log(mentions); ``` Here’s an example with a custom `CommentBody`. ```ts import { CommentBody, getMentionsFromCommentBody } from "@liveblocks/node"; // Create a custom `CommentBody` const commentBody: CommentBody = { version: 1, content: [ { type: "paragraph", children: [ { text: "Hello " }, { type: "mention", id: "chris@example.com" }, ], }, ], }; // Get the mentions inside the comment's body const mentions = getMentionsFromCommentBody(commentBody); // [{ kind: "user", id: "chris@example.com" }] console.log(mentions); ``` If you’d like to use this on the client side, it’s also available from [`@liveblocks/client`](/docs/api-reference/liveblocks-client#get-mentions-from-comment-body). ### stringifyCommentBody [#stringify-comment-body] Used to convert a `CommentBody` (found under `comment.body`) into either a plain string, Markdown, HTML, or a custom format. ```ts import { stringifyCommentBody } from "@liveblocks/node"; const stringComment = await stringifyCommentBody(comment.body); ``` This is most commonly used in combination with the [Comments API functions](/docs/api-reference/liveblocks-node#Comments), for example [`getComment`](/docs/api-reference/liveblocks-node#get-comment). ```ts import { Liveblocks, stringifyCommentBody } from "@liveblocks/node"; // Create a node client const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); // Retrieve a comment const comment = await liveblocks.getComment({ roomId: "my-room-id", threadId: "my-thread-id", commentId: "my-comment-id", }); // Convert CommentBody to plain string const stringComment = await stringifyCommentBody(comment.body); // "Hello marc@example.com from https://liveblocks.io" console.log(stringComment); ``` A number of options are also available. ```ts import { stringifyCommentBody } from "@liveblocks/client"; const stringComment = await stringifyCommentBody(comment.body, { // Optional, convert to specific format, "plain" (default) | "markdown" | "html" format: "markdown", // Optional, supply a separator to be used between paragraphs separator: `\n\n`, // Optional, override any elements in the CommentBody with a custom string elements: { // Optional, override the `paragraph` element paragraph: ({ element, children }) => `

${children}

`, // Optional, override the `text` element text: ({ element }) => element.bold ? `${element.text}` : `${element.text}`, // Optional, override the `link` element link: ({ element, href }) => `${element.url}`, // Optional, override the `mention` element. // `user` and `group` are the optional data returned from `resolveUsers` and `resolveGroupsInfo` mention: ({ element, user, group }) => `${element.id}`, }, // Optional, get your user’s names and info from their ID to be displayed in mentions async resolveUsers({ userIds }) { const usersData = await __getUsersFromDB__(userIds); return usersData.map((userData) => ({ // Name is inserted into the output instead of a user’s ID name: userData.name, // Custom formatting in `elements.mention` allows custom properties to be used profileUrl: userData.profileUrl, })); }, // Optional, get your group’s names and info from their ID to be displayed in mentions async resolveGroupsInfo({ groupIds }) { const groupsData = await __getGroupsFromDB__(groupIds); return groupsData.map((groupData) => ({ // Name is inserted into the output instead of a group’s ID name: groupData.name, // Custom formatting in `elements.mention` allows custom properties to be used settingsUrl: groupData.settingsUrl, })); }, }); ``` If you’d like to use this on the client side, it’s also available from [`@liveblocks/client`](/docs/api-reference/liveblocks-client#stringify-comment-body). #### Formatting examples Here are a number of different formatting examples derived from the same `CommentBody`. ```ts // "Hello marc@example.com from https://liveblocks.io" await stringifyCommentBody(comment.body); // "Hello @Marc from https://liveblocks.io" await stringifyCommentBody(comment.body, { resolveUsers({ userIds }) { return [{ name: "Marc" }]; }, }); // "**Hello** @Marc from [https://liveblocks.io](https://liveblocks.io)" await stringifyCommentBody(comment.body, { format: "markdown", resolveUsers() { return [{ name: "Marc" }]; }, }); // "Hello @Marc from // https://liveblocks.io" await stringifyCommentBody(comment.body, { format: "html", resolveUsers() { return [{ name: "Marc" }]; }, }); // "Hello @Marc from // https://liveblocks.io" await stringifyCommentBody(comment.body, { format: "html", mention: ({ element, user }) => `${user.name}`, resolveUsers() { return [{ name: "Marc", profileUrl: "https://example.com" }]; }, }); ``` ### WebhookHandler [#WebhookHandler] Read the [Webhooks guide](/docs/platform/webhooks) to learn how to use them within your product, allowing you to react to Liveblocks events as they happen. The `WebhookHandler` class is a helper to handle webhook requests from Liveblocks. It’s initialized with a signing secret that you can find in your project’s webhook page. ```js const webhookHandler = new WebhookHandler(process.env.WEBHOOK_SECRET); ``` #### verifyRequest [#verifyRequest] Verifies the request and returns the event. Note that `rawBody` takes the body as a `string`. ```js const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: req.body, }); ``` Some frameworks parse request bodies into objects, which means using `JSON.stringify` may be necessary. ```js highlight="3" const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: JSON.stringify(req.body), }); ``` ##### Example using Next.js [#webhook-example] ```js import { WebhookHandler } from "@liveblocks/node"; // Will fail if not properly initialized with a secret // Obtained from the Webhooks section of your project dashboard // https://liveblocks.io/dashboard const webhookHandler = new WebhookHandler(process.env.WEBHOOK_SECRET); export function POST(request) { try { const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: JSON.stringify(req.body), }); // Handle `WebhookEvent` if (event.type === "storageUpdated") { // Handle `StorageUpdatedEvent` } else if (event.type === "userEntered") { // Handle `UserEnteredEvent` } else if (event.type === "userLeft") { // Handle `UserLeftEvent` } } catch (error) { console.error(error); return new Response(error, { status: 400 }); } } ``` ### isThreadNotificationEvent [#isThreadNotificationEvent] Type guard to check if a received webhook event is a [`ThreadNotificationEvent`](/docs/platform/webhooks#Thread-notification) send from Comments. Particularly helpful when creating [thread notification emails](/docs/api-reference/liveblocks-emails#thread-notification-emails) with webhooks. ```js import { isThreadNotificationEvent } from "@liveblocks/node"; const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: req.body, }); // +++ if (isThreadNotificationEvent(event)) { // Handle `ThreadNotificationEvent` } // +++ ``` The check is made against the event type and event data kind. ### isTextMentionNotificationEvent [#isTextMentionNotificationEvent] Type guard to check if a received webhook event is a [`TextMentionNotificationEvent`](/docs/platform/webhooks#TextMention-notification) sent from Text Editor. Particularly helpful for identifying text mentions when sending email notifications. ```js import { isTextMentionNotificationEvent } from "@liveblocks/node"; const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: req.body, }); // +++ if (isTextMentionNotificationEvent(event)) { // Handle `TextMentionNotificationEvent` } // +++ ``` ### isCustomNotificationEvent [#isCustomNotificationEvent] Type guard to check if a received webhook event is a [`CustomNotificationEvent`](/docs/platform/webhooks#Custom-notification) sent from [`triggerInboxNotification`](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger). Particularly helpful for identifying custom notifications when sending email notifications. ```js import { isCustomNotificationEvent } from "@liveblocks/node"; const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: req.body, }); // +++ if (isCustomNotificationEvent(event)) { // Handle `CustomNotificationEvent` } // +++ ``` The check is made against the event type and event data kind. [`room.getothers`]: /docs/api-reference/liveblocks-client#Room.getOthers [Permissions REST API]: /docs/authentication/id-token --- meta: title: "@liveblocks/react-blocknote" parentTitle: "API Reference" description: "API Reference for the @liveblocks/react-blocknote package" alwaysShowAllNavigationLevels: false --- `@liveblocks/react-blocknote` provides you with a [React](https://react.dev/) plugin that adds collaboration to any [BlockNote rich-text editor](https://www.blocknotejs.org/). It also adds realtime cursors, document persistence on the cloud, comments, and mentions. Use [`@liveblocks/node-prosemirror`](/docs/api-reference/liveblocks-node-prosemirror) for server-side editing. ## Setup To set up your collaborative BlockNote editor, create an editor with [`useCreateBlockNoteWithLiveblocks`](#useCreateBlockNoteWithLiveblocks) and pass it into the [`BlockNoteView`](https://www.blocknotejs.org/docs/editor-basics/setup#rendering-the-editor-with-blocknoteview) component provided by `@blocknote/mantine`. ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { // +++ const editor = useCreateBlockNoteWithLiveblocks({}); // +++ return (

// +++ // +++

); } ``` Liveblocks BlockNote components should be passed `editor` to enable them. ```tsx import { useCreateBlockNoteWithLiveblocks, // +++ FloatingComposer, // +++ } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks({}); return (

// +++ // +++

); } ``` Learn more in our [get started guides](/docs/get-started/text-editor/blocknote). ## Default components ### FloatingComposer Displays a [`Composer`][] near the current BlockNote selection, allowing you to create threads. ```tsx highlight="3" ```

Submitting a comment will attach an annotation thread at the current selection. Should be passed your BlockNote `editor`, and it’s recommended you set a width value. Display created threads with [`AnchoredThreads`][] or [`FloatingThreads`][]. ```tsx import { // +++ FloatingComposer, // +++ FloatingThreads, useCreateBlockNoteWithLiveblocks, } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks({}); return (

// +++ // +++

); } ``` #### Opening the composer To open the `FloatingComposer`, you need to click the comment button in the BlockNote toolbar, or call the `addPendingComment` [command](https://tiptap.dev/docs/editor/api/commands) added by Liveblocks. You can use `liveblocksCommentMark` to check if the current selection is a comment. ```tsx import { BlockNoteEditor } from "@blocknote/core"; function Toolbar({ editor }: { editor: BlockNoteEditor | null }) { if (!editor) { return null; } return ( ); } ``` #### Props [#FloatingComposer-props] The metadata of the thread to create. The metadata of the comment to create. The event handler called when the composer is submitted. The composer’s initial value. Whether the composer is collapsed. Setting a value will make the composer controlled. The event handler called when the collapsed state of the composer changes. Whether the composer is initially collapsed. Setting a value will make the composer uncontrolled. Whether the composer is disabled. Whether to focus the composer on mount. Override the component’s strings. ### FloatingThreads Displays floating [`Thread`][] components below text highlights in the editor. ```tsx highlight="3" ```

Takes a list of threads retrieved from [`useThreads`][] and renders them to the page. Each thread is opened by clicking on its corresponding text highlight. Should be passed your BlockNote `editor`, and it’s recommended you set a width value. ```tsx // +++ import { useThreads } from "@liveblocks/react/suspense"; // +++ import { FloatingComposer, // +++ FloatingThreads, // +++ useCreateBlockNoteWithLiveblocks, } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks({}); // +++ const { threads } = useThreads(); // +++ return (

// +++ // +++

); } ``` The `FloatingThreads` component automatically excludes resolved threads from display. Any resolved threads passed in the threads list will not be shown. #### Recommended usage [#FloatingThreads-recommended-usage] [`FloatingThreads`][] and [`AnchoredThreads`][] have been designed to work together to provide the optimal experience on mobile and desktop. We generally recommend using both components, hiding one on smaller screens, as we are below with Tailwind classes. Most apps also don’t need to display resolved threads, so we can filter those out with a [`useThreads`][] option. ```tsx import { useThreads } from "@liveblocks/react/suspense"; import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-blocknote"; import { BlockNoteEditor } from "@blocknote/core"; function ThreadOverlay({ editor }: { editor: BlockNoteEditor | null }) { const { threads } = useThreads({ query: { resolved: false } }); return ( <> ); } ``` ```tsx title="Alternatively use a media query hook" isCollapsed isCollapsable import { useSyncExternalStore } from "react"; import { useThreads } from "@liveblocks/react/suspense"; import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-blocknote"; import { BlockNoteEditor } from "@blocknote/core"; function ThreadOverlay({ editor }: { editor: BlockNoteEditor | null }) { const { threads } = useThreads({ query: { resolved: false } }); // +++ const isMobile = useIsMobile(); // +++ // +++ if (isMobile) { return ( ); } // +++ // +++ return ( ); // +++ } export function useIsMobile() { return useSyncExternalStore(subscribe, getSnapshot, getSnapshot); } function subscribe(callback: () => void) { const query = window.matchMedia("(max-width: 1024px)"); query.addEventListener("change", callback); return () => query.removeEventListener("change", callback); } function getSnapshot() { const query = window.matchMedia("(max-width: 1024px)"); return query.matches; } ``` We can place this component inside [`ClientSideSuspense`][] to prevent it rendering until threads have loaded. ```tsx

// +++ // +++

``` #### Customization [#FloatingThreads-customization] The `FloatingThreads` component acts as a wrapper around each individual [`Thread`][]. You can treat the component like you would a `div`, using classes, listeners, and more. ```tsx ``` To apply styling to each [`Thread`][], you can pass a custom `Thread` property to `components` and modify this in any way. This is the best way to modify a thread’s width. ```tsx import { Thread } from "@liveblocks/react-ui"; ( ), }} // +++ />; ``` You can return any custom `ReactNode` here, including anything from a simple wrapper around [`Thread`][]. You can also use [`Thread`][]'s [`components`](/docs/api-reference/liveblocks-react-ui#Thread-components) prop to customize individual comments, or build a fully custom `Thread` component using our [Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment). ```tsx import { Comment, Thread } from "@liveblocks/react-ui"; ( // +++ ( ), }} /> // +++ ), }} />; ``` #### Props [#FloatingThreads-props] The threads to display. Override the component’s components. Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component. ### AnchoredThreads Displays a list of [`Thread`][] components vertically alongside the editor. ```tsx highlight="3" ```

Takes a list of threads retrieved from [`useThreads`][] and renders them to the page. Each thread is displayed at the same vertical coordinates as its corresponding text highlight. If multiple highlights are in the same location, each thread is placed in order below the previous thread. ```tsx // +++ import { useThreads } from "@liveblocks/react/suspense"; // +++ import { FloatingComposer, // +++ AnchoredThreads, // +++ useCreateBlockNoteWithLiveblocks, } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks({}); // +++ const { threads } = useThreads(); // +++ return (

// +++ // +++

); } ``` The `AnchoredThreads` component automatically excludes resolved threads from display. Any resolved threads passed in the threads list will not be shown. #### Recommended usage [#AnchoredThreads-recommended-usage] [`FloatingThreads`][] and [`AnchoredThreads`][] have been designed to work together to provide the optimal experience on mobile and desktop. We generally recommend using both components, hiding one on smaller screens, as we are below with Tailwind classes. Most apps also don’t need to display resolved threads, so we can filter those out with a [`useThreads`][] option. ```tsx import { useThreads } from "@liveblocks/react/suspense"; import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-blocknote"; import { BlockNoteEditor } from "@blocknote/core"; function ThreadOverlay({ editor }: { editor: BlockNoteEditor | null }) { const { threads } = useThreads({ query: { resolved: false } }); return ( <> ); } ``` ```tsx title="Alternatively use a media query hook" isCollapsed isCollapsable import { useSyncExternalStore } from "react"; import { useThreads } from "@liveblocks/react/suspense"; import { AnchoredThreads, FloatingThreads } from "@liveblocks/react-blocknote"; import { BlockNoteEditor } from "@blocknote/core"; function ThreadOverlay({ editor }: { editor: BlockNoteEditor | null }) { const { threads } = useThreads({ query: { resolved: false } }); // +++ const isMobile = useIsMobile(); // +++ // +++ if (isMobile) { return ( ); } // +++ // +++ return ( ); // +++ } export function useIsMobile() { return useSyncExternalStore(subscribe, getSnapshot, getSnapshot); } function subscribe(callback: () => void) { const query = window.matchMedia("(max-width: 1024px)"); query.addEventListener("change", callback); return () => query.removeEventListener("change", callback); } function getSnapshot() { const query = window.matchMedia("(max-width: 1024px)"); return query.matches; } ``` We can place this component inside [`ClientSideSuspense`][] to prevent it rendering until threads have loaded. ```tsx

// +++ // +++

``` #### Customization [#AnchoredThreads-customization] The `AnchoredThreads` component acts as a wrapper around each [`Thread`][]. It has no width, so setting this is required, and each thread will take on the width of the wrapper. You can treat the component like you would a `div`, using classes, listeners, and more. ```tsx ``` To apply styling to each [`Thread`][], you can pass a custom `Thread` property to `components` and modify this in any way. ```tsx import { Thread } from "@liveblocks/react-ui"; ( ), }} // +++ />; ``` You can return any custom `ReactNode` here, including anything from a simple wrapper around [`Thread`][]. You can also use [`Thread`][]'s [`components`](/docs/api-reference/liveblocks-react-ui#Thread-components) prop to customize individual comments, or build a fully custom `Thread` component using our [Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment). ```tsx import { Comment, Thread } from "@liveblocks/react-ui"; ( // +++ ( ), }} /> // +++ ), }} />; ``` ##### Modifying thread floating positions Using CSS variables you can modify the gap between threads, and the horizontal offset that’s added when a thread is selected. ```css .lb-tiptap-anchored-threads { /* Minimum gap between threads */ --lb-tiptap-anchored-threads-gap: 8px; /* How far the active thread is offset to the left */ --lb-tiptap-anchored-threads-active-thread-offset: 12px; } ``` #### Props [#AnchoredThreads-props] The threads to display. Override the component’s components. Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component. ### HistoryVersionPreview [@badge=beta] The `HistoryVersionPreview` component allows you to display a preview of a specific version of your BlockNote editor’s content. It also contains a button and logic for restoring. To render a list of versions, see [`VersionHistory`](/docs/api-reference/liveblocks-react-ui#Version-History). #### Usage [#HistoryVersionPreview-usage] ```tsx import { HistoryVersionPreview } from "@liveblocks/react-blocknote"; function VersionPreview({ selectedVersion, onVersionRestore }) { return ( ); } ``` #### Props [#HistoryVersionPreview-props] The version of the editor content to preview. Callback function called when the user chooses to restore this version. The `HistoryVersionPreview` component renders a read-only view of the specified version of the editor content. It also provides a button for users to restore the displayed version. ## Hooks ### useCreateBlockNoteWithLiveblocks Creates a Liveblocks collaborative BlockNote editor. Use this hook instead of [`useCreateBlockNote`](https://www.blocknotejs.org/docs/editor-basics/setup#usecreateblocknote-hook). `editor` should be passed to [`BlockNoteView`](https://www.blocknotejs.org/docs/editor-basics/setup#rendering-the-editor-with-blocknoteview). ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { // +++ const editor = useCreateBlockNoteWithLiveblocks({}); // +++ return (

// +++ // +++

); } ``` A number of options can be applied to BlockNote and Liveblocks. ```tsx const editor = useCreateBlockNoteWithLiveblocks( { // +++ animations: false, trailingBlock: false, // +++ // Other BlockNote options // ... }, { // +++ initialContent: "

Hello world

", field: "editor-one", // +++ // Other Liveblocks options // ... } ); ``` Returns a [BlockNote editor](https://www.blocknotejs.org/docs/editor-basics/setup) with collaborative Liveblocks features. Options to apply to BlockNote. [Learn more](https://www.blocknotejs.org/docs/editor-basics/setup#usecreateblocknote-hook). Options to apply to Liveblocks. The initial content for the editor, if it’s never been set. [Learn more](#Setting-initial-content). The name of this text editor’s field. Allows you to use multiple editors on one page, if each has a separate field value. [Learn more](#Multiple-editors). Experimental. Enable offline support using IndexedDB. This means that after the first load, documents will be stored locally and load instantly. [Learn more](#Offline-support). Enable comments in the editor. Enable mentions in the editor. #### Setting initial content Initial content for the editor can be set with `initialContent`. This content will only be used if the current editor has never been edited by any users, and is ignored otherwise. ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { // +++ initialContent: "

Hello world

", // +++ } ); // ... } ``` #### Multiple editors It’s possible to use multiple editors on one page by passing values to the `field` property. Think of it like an ID for the current editor. ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { // +++ field: "editor-one", // +++ } ); // ... } ``` Here’s an example of how multiple editors may be set up. ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditors() { return (

// +++ // +++

); } function TextEditor({ field }: { field: string }) { const editor = useCreateBlockNoteWithLiveblocks( {}, { // +++ field, // +++ } ); return (

); } ``` #### Offline support [@badge=experimental] It’s possible to enable offline support in your editor with an experimental option. This means that once a document has been opened, it’s saved locally on the browser, and can be shown instantly without a loading screen. As soon as Liveblocks connects, any remote changes will be synchronized, without any load spinner. Enable this by passing a `offlineSupport_experimental` value. ```tsx import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { // +++ offlineSupport_experimental: true, // +++ } ); // ... } ``` To make sure that your editor loads instantly, you must structure your app carefully to avoid any Liveblocks hooks and [`ClientSideSuspense`][] components from triggering a loading screen. For example, if you’re displaying threads in your editor with [`useThreads`][], you must place this inside a separate component and wrap it in [`ClientSideSuspense`][]. ```tsx "use client"; import { ClientSideSuspense, useThreads } from "@liveblocks/react/suspense"; import { useCreateBlockNoteWithLiveblocks, AnchoredThreads, FloatingComposer, } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; import { BlockNoteEditor } from "@blocknote/core"; export function BlockNoteEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { // +++ offlineSupport_experimental: true, // +++ } ); return ( <> // +++ // +++ ); } // +++ function Threads({ editor }: { editor: BlockNoteEditor }) { const { threads } = useThreads(); return ; } // +++ ``` ### useIsEditorReady Used to check if the editor content has been loaded or not, helpful for displaying a loading skeleton. ```ts import { useIsEditorReady } from "@liveblocks/react-blocknote"; const status = useIsEditorReady(); ``` Here's how it can be used in the context of your editor. ```tsx import { useCreateBlockNoteWithLiveblocks, useIsEditorReady, } from "@liveblocks/react-blocknote"; import { BlockNoteView } from "@blocknote/mantine"; function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks({}); // +++ const ready = useIsEditorReady(); // +++ return (

// +++ {!ready ?

: } // +++

); } ``` ## Stylesheets React BlockNote comes with default styles, and these can be imported into the root of your app or directly into a CSS file with `@import`. Note that you must also install and import a stylesheet from [`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui) to use these styles. ```tsx import "@liveblocks/react-ui/styles.css"; import "@liveblocks/react-blocknote/styles.css"; ``` ### Customizing your styles Adding dark mode and customizing your styles is part of `@liveblocks/react-ui`, learn how to do this under [styling and customization](/docs/api-reference/liveblocks-react-ui#Styling-and-customization). [`Thread`]: /docs/api-reference/liveblocks-react-ui#Thread [`Composer`]: /docs/api-reference/liveblocks-react-ui#Composer [`useThreads`]: /docs/api-reference/liveblocks-react#useThreads [`Icon`]: /docs/api-reference/liveblocks-react-ui#Icon [`FloatingToolbar`]: #FloatingToolbar [`FloatingComposer`]: #FloatingComposer [`FloatingThreads`]: #FloatingThreads [`AnchoredThreads`]: #AnchoredThreads [`ClientSideSuspense`]: /docs/api-reference/liveblocks-react#ClientSideSuspense --- meta: title: "@liveblocks/react-lexical" parentTitle: "API Reference" description: "API Reference for the @liveblocks/react-lexical package" alwaysShowAllNavigationLevels: false --- `@liveblocks/react-lexical` provides you with a [React](https://react.dev/) plugin that adds collaboration to any [Lexical](https://lexical.dev/) text editor. It also adds realtime cursors, document persistence on the cloud, comments, and mentions. Read our [get started guides](/docs/get-started/text-editor/lexical) to learn more. ## Setup To set up your collaborative Lexical editor, you must use [`LiveblocksPlugin`](#LiveblocksPlugin) and [`liveblocksConfig`](#liveblocksConfig). ### LiveblocksPlugin Liveblocks plugin for Lexical that adds collaboration to your editor. ```tsx highlight="2" ``` {/* TODO: Image */} `LiveblocksPlugin` should always be nested inside [`LexicalComposer`][], and each [Lexical default component](#Default-components) you’re using should be placed inside the plugin. ```tsx import { LexicalComposer } from "@lexical/react/LexicalComposer"; import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin"; import { ContentEditable } from "@lexical/react/LexicalContentEditable"; import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary"; // +++ import { liveblocksConfig, LiveblocksPlugin } from "@liveblocks/react-lexical"; // +++ const initialConfig = liveblocksConfig({ namespace: "MyEditor", theme: {}, nodes: [], onError: (err) => console.error(err), }); function Editor() { return ( // +++ // +++ } placeholder={

Enter some text...

} ErrorBoundary={LexicalErrorBoundary} /> ); } ``` Annotations associated with resolved threads are hidden by default on the editor. Learn more in our [get started guides](/docs/get-started/text-editor/lexical). ### liveblocksConfig Function that takes a Lexical editor config and modifies it to add the necessary `nodes` and `theme` to make [`LiveblocksPlugin`][] works correctly. ```tsx import { liveblocksConfig } from "@liveblocks/react-lexical"; const initialConfig = liveblocksConfig({ namespace: "MyEditor", theme: {}, nodes: [], onError: (err) => console.error(err), }); ``` The config created by `liveblocksConfig` should be passed to `initialConfig` in [`LexicalComposer`][]. ```tsx highlight="7-12,16" import { LexicalComposer } from "@lexical/react/LexicalComposer"; import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin"; import { ContentEditable } from "@lexical/react/LexicalContentEditable"; import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary"; import { liveblocksConfig, LiveblocksPlugin } from "@liveblocks/react-lexical"; const initialConfig = liveblocksConfig({ namespace: "MyEditor", theme: {}, nodes: [], onError: (err) => console.error(err), }); function Editor() { return ( } placeholder={

Enter some text...

} ErrorBoundary={LexicalErrorBoundary} /> ); } ``` Note that `liveblocksConfig` sets `editorState` to `null` because `LiveblocksPlugin` is responsible for initializing it on the server. ## Default components ### Toolbar Displays a toolbar, allowing you to change the styles of selected text. You can add content [before or after](#toolbar-extending-the-defaults), or the toolbar’s options can be [customized](#creating-a-custom-toolbar). A [floating toolbar](#FloatingToolbar) also exists. ```tsx // +++ // +++ ```

By default, one of the toolbar buttons can create comment threads—to enable this add [`FloatingComposer`][] and display threads with [`AnchoredThreads`][] or [`FloatingThreads`][]. Should be nested inside [`LiveblocksPlugin`][]. ```tsx import { LexicalComposer } from "@lexical/react/LexicalComposer"; import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin"; import { ContentEditable } from "@lexical/react/LexicalContentEditable"; import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary"; import { useThreads } from "@liveblocks/react/suspense"; import { liveblocksConfig, LiveblocksPlugin, FloatingComposer, // +++ Toolbar, // +++ } from "@liveblocks/react-lexical"; const initialConfig = liveblocksConfig({ namespace: "MyEditor", theme: {}, nodes: [], onError: (err) => console.error(err), }); function Editor() { const { threads } = useThreads(); return ( // +++ // +++ } placeholder={

Enter some text...

} ErrorBoundary={LexicalErrorBoundary} /> ); } ``` #### Extending the defaults [#toolbar-extending-the-defaults] You can insert content `before` the first button and `after` the last button using `before` and `after`. Components such as [`Toolbar.Button`][] and [`Toolbar.Toggle`][] can be used to create new buttons. ```tsx import { Toolbar } from "@liveblocks/react-lexical"; import { Icon } from "@liveblocks/react-ui"; I'm at the start} after={ } shortcut="CMD-H" onClick={() => console.log("help")} /> } // +++ />; ``` For more complex customization, instead read [creating a custom floating toolbar](#creating-a-custom-toolbar). #### Creating a custom toolbar [#creating-a-custom-toolbar] By passing elements as children, it’s possible to create a fully custom toolbar. ```tsx highlight="6" import { Toolbar } from "@liveblocks/react-lexical"; function CustomToolbar() { return ( Hello world ); } ``` Each part of our default toolbar is available as blocks which can be slotted together. This is how the default toolbar is constructed: ```tsx import { Toolbar } from "@liveblocks/react-lexical"; function CustomToolbar() { return ( // +++ // +++ ); } ``` You can mix these default components with any custom ones of your own. Below the [`Toolbar.SectionHistory`][] component is added alongside some custom buttons created with [`Toolbar.Button`][], [`Toolbar.Toggle`][], and [`Icon`][]. ```tsx import { FORMAT_TEXT_COMMAND } from "lexical"; import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext"; import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical"; import { Icon } from "@liveblocks/react-ui"; function CustomToolbar() { const [editor] = useLexicalComposerContext(); return ( // +++ } shortcut="CMD-H" onClick={() => console.log("help")} /> B️} active={isTextFormatActive(editor, "bold")} onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")} /> // +++ ); } ``` To learn more about the different components, read more below. #### Props [#Toolbar-props] The Lexical editor. The content of the toolbar, overriding the default content. Use the `before` and `after` props if you want to keep and extend the default content. Any `ReactNode` or `Toolbar.*` components work inside. The content to display at the start of the toolbar. Any `ReactNode` or `Toolbar.*` components work inside. The content to display at the end of the toolbar. Any `ReactNode` or `Toolbar.*` components work inside. #### Toolbar.Button A button for triggering actions. The `name` is displayed in a tooltip. Props such as `onClick` will be passed to the underlying `button` element. ```tsx import { Toolbar } from "@liveblocks/react-lexical"; console.log("Clicked")} /> ; ``` Optionally takes an icon which will visually replace the `name`. Also optionally accepts a shortcut, which is displayed in the tooltip. Comment key names are converted to symbols. Here are various examples. ```tsx import { Toolbar } from "@liveblocks/react-lexical"; import { Icon } from "@liveblocks/react-ui"; // Button says "Question" // Tooltip says "Question [⌘+Q]" // Custom icon, replaces the name in the button ?

{chat.title || "Untitled chat"}

🟢 Ready

🟡 Generating…

Error}> Loading...}>

Error

// +++ // +++ ); } ``` After adding this, the AI will understand that the user is on the Advanced Plan and be able to answer questions on it, for example: > User: _What's my current plan?_ > > Assistant: _You're on the Advanced Plan, it expires on January 1st, 2026._ ### Combine front-end knowledge with tools You can combine front-end knowledge with [tools](/docs/ready-made-features/ai-copilots/tools) to create an AI assistant that can take actions. For example, say you have a document on the current page. You can use knowledge to share the document content with the AI, then create a tool that allows AI to edit the document. ```tsx import { RegisterAiKnowledge } from "@liveblocks/react"; import { AiChat } from "@liveblocks/react-ui"; import { RegisterAiTool } from "@liveblocks/react"; import { defineAiTool } from "@liveblocks/client"; import { useState } from "react"; function Document() { // +++ const [document, setDocument] = useState("Hello world"); // +++ return ( <> { // +++ setDocument(args.text); // +++ return { data: {}, description: "Document updated" }; }, })} /> ); } ``` Learn about more ways to use it in our documentation under [`RegisterAiKnowledge`](/docs/api-reference/liveblocks-react#RegisterAiKnowledge). ## Back-end knowledge Back-end knowledge is data that’s passed to your AI from the server, through your [copilot](/docs/ready-made-features/ai-copilots/copilots#Adding-back-end-knowledge). You can submit PDF/image files, web pages, or entire websites which will be crawled and indexed. This is most useful for passing large amounts of information, for example: - **Knowledge bases**: Documentation, FAQs, and support tickets. - **Domain-specific data**: Detailed information that your AI must understand. - **Documents**: Submit PDF or image scans of reports, contracts, and invoices. ### How it works [#back-end-knowledge-how-it-works] Back-end knowledge uses Retrieval-Augmented Generation (RAG) search, and is triggered by a hidden tool call, meaning the AI will search through its back-end knowledge when it feels its relevant. You can define [when AI should use back-end knowledge](/docs/ready-made-features/ai-copilots/copilots#When-should-AI-use-knowledge) in your copilot settings, and AI will understand what should trigger a back-end knowledge query. The AI will rewrite your query, and may even run multiple queries in a row, each of which will be displayed in the [`AiChat`](/docs/api-reference/liveblocks-react-ui#AiChat) UI as a search. ### Adding back-end knowledge through the dashboard After [creating a copilot](/docs/ready-made-features/ai-copilots/copilots#Creating-a-copilot) in the [dashboard](/dashboard), you can navigate to the “Knowledge” tab to add back-end knowledge. Select which type of knowledge you’d like to submit, and enter your URLs or upload your files.

Screenshot of the Liveblocks dashboard, adding knowledge to a copilot

Make sure to use your copilot ID in [`AiChat`](/docs/api-reference/liveblocks-react-ui#AiChat) and [`useSendAiMessage`](/docs/api-reference/liveblocks-react#useSendAiMessage) to use the knowledge in your application. ### Adding back-end knowledge programmatically You aren’t limited to modifying knowledge through the dashboard—you can also add copilot knowledge programmatically, allowing users or teams in your app to have their own individual knowledge bases. ```ts import { Liveblocks } from "@liveblocks/node"; const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}", }); // +++ const { id } = await liveblocks.createWebKnowledgeSource({ copilotId: "co_abc123...", url: "https://example.com", type: "crawl", }); // +++ ``` This is made possible using the [Liveblocks Node.js client](/docs/api-reference/liveblocks-node#AI-Copilots) and [REST API](/docs/api-reference/rest-api-endpoints#AI), where a number of APIs are available for managing copilots and knowledge sources. - [`createWebKnowledgeSource`](/docs/api-reference/liveblocks-node#create-web-knowledge-source) - [`createFileKnowledgeSource`](/docs/api-reference/liveblocks-node#create-file-knowledge-source) - [`getKnowledgeSources`](/docs/api-reference/liveblocks-node#get-knowledge-sources) - [`getKnowledgeSource`](/docs/api-reference/liveblocks-node#get-knowledge-source) - [`getFileKnowledgeSourceMarkdown`](/docs/api-reference/liveblocks-node#get-file-knowledge-source-markdown) - [`getWebKnowledgeSourceLinks`](/docs/api-reference/liveblocks-node#get-web-knowledge-source-links) - [`deleteWebKnowledgeSource`](/docs/api-reference/liveblocks-node#delete-web-knowledge-source) - [`deleteFileKnowledgeSource`](/docs/api-reference/liveblocks-node#delete-file-knowledge-source) ## Web search Web search is a feature that allows your AI to search the internet for information. It is disabled by default, and can be enabled by toggling the `webSearch` option in [your copilot settings](/docs/ready-made-features/ai-copilots/copilots#Web-search). ```text title="Web search" on ``` You can also [limit the domains that the AI can search](/docs/ready-made-features/ai-copilots/copilots#Limit-web-search-to-specific-domains) by setting an option on your copilot. ```text title="Limit web search to specific domains" encyclopedia.com en.wikipedia.org ``` It’s also possible to enable web search through the back-end with `allowedDomains`, for example using [`liveblocks.createAiCopilot`](/docs/api-reference/liveblocks-node#create-ai-copilot). ```ts const copilot = await liveblocks.createAiCopilot({ name: "My AI Assistant", systemPrompt: "You are a helpful AI assistant for our team.", provider: "openai", providerModel: "gpt-4", providerApiKey: "sk-...", providerOptions: { openai: { // Optional, restrict web search to specific domains // +++ webSearch: { allowedDomains: ["encyclopedia.com", "en.wikipedia.org"], }, // +++ }, }, }); ``` Not all models support web search, but most OpenAI and Anthropic models do. --- meta: title: "Styling and customization" parentTitle: "AI Copilots" description: "Customize the appearance and behavior of AI Copilots" --- Styling [default components](/docs/ready-made-features/ai-copilots/default-components) is enabled through a range of means, such as CSS variables, class names, and more. It’s also possible to use [overrides](#Overrides-and-localization) to modify any strings used in the default components, which is especially helpful for localization. ## Default components To add the default components’ theme, import the [default styles](/docs/api-reference/liveblocks-react-ui#Default-styles) CSS file. ```ts import "@liveblocks/react-ui/styles.css"; ``` You can also import one of two CSS files to enable [dark mode](/docs/api-reference/liveblocks-react-ui#Dark-mode), depending on how you’d like to enable it. ```ts // Dark mode using the system theme with `prefers-color-scheme` import "@liveblocks/react-ui/styles/dark/media-query.css"; ``` ```ts // Dark mode using `className="dark"`, `data-theme="dark"`, or `data-dark="true"` import "@liveblocks/react-ui/styles/dark/attributes.css"; ``` ### CSS variables A number of [CSS variables](/docs/api-reference/liveblocks-react-ui#CSS-variables) can be used to customize colors, spacing, and more. This is our recommended path for styling the default components, as you can quickly and easily modify all components with just a few variables. ```css /* Styles all default components */ .lb-root { --lb-accent: purple; --lb-spacing: 1em; --lb-radius: 0; } ``` ### Class names Should you need deeper customization, [class names](/docs/api-reference/liveblocks-react-ui#Class-names) can be styled, some of which provide contextual data attributes. ```css .lb-ai-chat { /* Customize AI chat */ } .lb-ai-composer { /* Customize message composer */ } ``` ### Overrides and localization It’s possible to [override strings](/docs/api-reference/liveblocks-react-ui#Overrides) used in the default components, which has a couple of different uses, the first being localization. In this example, we’re globally setting the AI composer’s placeholder from “Ask anything…” to “Posez une question” for French users. ```tsx import { LiveblocksUiConfig } from "@liveblocks/react-ui"; export function App() { return ( {/* ... */} ); } ``` You can also override strings on a component basis, for example if you’d like to change the “Send” button tooltip to “Post message” in the chat’s message composer. ```tsx import { Composer } from "@liveblocks/react-ui"; function Component() { return ( ); } ``` {/* prettier-ignore */} {/* TODO add back later when we enable it ## Custom interfaces You can bypass the default components and build completely custom UI for your AI copilots, for example using [`useAiChatMessages`](/docs/api-reference/liveblocks-react#useAiChatMessages) and [`useSendAiMessage`](/docs/api-reference/liveblocks-react#useSendAiMessage) to build your own chat history and composer. ```tsx import { useAiChatMessages, useSendAiMessage, } from "@liveblocks/react/suspense"; function ChatMessages({ chatId }: { chatId: string }) { // +++ const { messages } = useAiChatMessages(chatId); const sendAiMessage = useSendAiMessage(chatId, { copilotId: "co_a7Gd3x..." }); // +++ return (

// +++ {messages.map((message) => { // +++ if (message.role === "user") { return (

{message.content.map((part) => (

👤 You: {part.text}

))}

); } return (

{(message.contentSoFar ?? message.content).map((part) => (

🤖 Assistant: {part.text}

))}

); })}

); } ``` Learn more about what you can build under [hooks](/docs/ready-made-features/ai-copilots/hooks). \*/} --- meta: title: "Tools" parentTitle: "AI Copilots" description: "Allow AI to interact with your application" --- Tools allow AI to make actions, modify your application state, interact with your front-end, and render custom components within your AI chat. Use tools to extend the capabilities of AI Copilots beyond simple text, allowing autonomous and human-in-the-loop interactions. ## Tool use cases Tools can be used to create various different interactions inside of your AI chat, such as: - **Actions**: Autonomously perform actions like editing documents, redirecting users, sending emails. - **Custom components**: Render custom React components like forms, graphs, videos, callouts. - **Query actions**: AI can query your app, search documents, find pages, check invoices. - **Human-in-the-loop actions**: Show confirm/deny buttons before taking destructive actions. - **AI presence**: Tool results can be streamed in, allowing AI to show live updates in your app. ### How tools work You can define a list of tools in your application, and your AI can choose to use them whenever it decides they’re needed. Within each tool you can set certain parameters which AI will fill in for you. For example, a weather tool may have a `location` parameter, and AI may enter `"Paris"` as the value. Here’s an example of a tool call interaction: In your weather tool, `location` is defined as a `string` ```json { "location": { type: "string" } } ``` {" "} User asks about the weather in Paris ```js User: "What's the weather in Paris?" ``` AI calls the weather tool with `Paris` as the `location` ```js { "location": "Paris" } ``` {" "} You write code to fetch the weather for the `location` ```js execute: async ({ location }) => { // { "temperature": 20, "condition": "sunny" }; const weather = await __fetchWeather__(location); return { data: { weather }}; } ``` AI answers the user ```js AI: "It's sunny in Paris, with a temperature of 20°C." ``` When writing your [system prompt](/docs/ready-made-features/ai-copilots/copilots#System-prompt) you can suggest when certain tools should be used, helping AI respond as you like. This is just an example of a simple tool, but below we’ll detail how to create more complex tools that have confirm/deny dialogs, render custom components, query data, and more. ## Defining tools You can define a tool with [`defineAiTool`](/docs/api-reference/liveblocks-client#defineAiTool) and [`RegisterAiTool`](/docs/api-reference/liveblocks-react#RegisterAiTool). First, you first need to give your tool a unique name, and a description, which helps AI understand when to call it. You can place the component anywhere in your app. ```tsx import { RegisterAiTool } from "@liveblocks/react"; import { defineAiTool } from "@liveblocks/client"; import { AiChat } from "@liveblocks/react-ui"; function Chat() { return ( <> // +++ // +++ ); } ``` For AI to use your tools intelligently, parameters must be defined, which AI will fill in for you. Tools use [JSON schema](/docs/ready-made-features/ai-copilots/tools#Advanced-JSON-schema) to define these. For example, you can define `location` parameter as a `string`. ```tsx ``` To add functionality to your tool, a combination of `execute` and `render` functions are used. ```tsx { // ... }, render: ({ stage, partialArgs, args, result, respond }) => { // ... }, // +++ })} /> ``` In each of the following sections, different ways to implement `execute` and `render` are detailed. ## Actions If you’d like your AI to perform an action when the tool is called, you can use `execute` to define what should happen. The arguments passed to `execute` are the parameters defined in your tool, filled in by AI. After the tool has run, return any `data` you’d like to pass back to AI. ```tsx { const weather = await __fetchWeather__(location); return { data: { weather } }; }, // +++ })} /> ``` After running `execute`, AI will read the `data` object, and choose how to respond. Additionally, you can define a `description` to pass back to AI. This is a way to inform AI what has just taken place, so it can understand the context of the result, and what it should do next. This text will never be shown to the user. ```ts execute: async ({ location }) => { const weather = await __fetchWeather__(location); return { data: { weather }, // +++ description: "You've just fetched the weather, share the temperature in °C." // +++ }; }, ``` The [AI Calendar](/examples/ai-calendar/nextjs-ai-calendar) example contains an action that allows AI to create new calendar events. ### Display a loading message You can easily display a loading message while an action takes place using `render` and [`AiTool`](/docs/api-reference/liveblocks-react-ui#AiTool). You can also choose to display a message after the action has finished, as in the example below. ```tsx import { AiChat, AiTool } from "@liveblocks/react-ui"; import { RegisterAiTool } from "@liveblocks/react"; function Chat() { <> { const weather = await __fetchWeather__(location); return { data: { weather }, description: "You've just fetched the weather.", }; }, // +++ render: ({ stage }) => { // `execute` is still running if (stage !== "executed") { return ; } // `execute` has finished return ; }, // +++ })} /> ; } ``` [`AiTool`](/docs/api-reference/liveblocks-react-ui#AiTool) isn’t required here, as you can return any JSX, but it’s an easy way to match the styling of the default chat. Returning `null` will display nothing. ### Combine actions with front-end knowledge You can combine actions with [front-end knowledge](/docs/ready-made-features/ai-copilots/knowledge) to create an AI assistant that can take actions. For example, say you have a document on the current page. You can use knowledge to pass the document’s text to the AI, then create a tool that allows AI to edit the document. ```tsx import { RegisterAiKnowledge } from "@liveblocks/react"; import { AiChat } from "@liveblocks/react-ui"; import { RegisterAiTool } from "@liveblocks/react"; import { defineAiTool } from "@liveblocks/client"; import { useState } from "react"; function Document() { // +++ const [document, setDocument] = useState("Hello world"); // +++ return ( <> { // +++ setDocument(args.text); // +++ return { data: {}, description: "Document updated" }; }, render: ({ stage }) => { if (stage !== "executed") { return ; } return ; }, })} /> ); } ``` ## Custom components You can use tools to display custom components inside the chat with the `render` function. These don’t have to be simple components, but can be complex, like forms, graphs, videos, callouts. When displaying a simple component, include an `execute` function, even if it’s empty, otherwise the chat will assume it’s a [human-in-the-loop action](#Human-in-the-loop-actions). ```tsx {}, // +++ render: () => { return ; }, // +++ })} /> ``` You can go further than this, and allow AI to [create parameters](#Advanced-JSON-schema) which you can use in your custom component, for example `x` and `y` values on a graph. ```tsx {}, render: ({ args, stage }) => { if (stage !== "executed") { return

; } // +++ return ; // +++ }, })} /> ``` AI will most likely write a response after using your tool, but you can prompt the AI to not respond by adding a `description` to `execute`. ```tsx { return { data: {}, // +++ description: "You’re displaying a graph. Do not respond further.", // +++ }; }, render: ({ args, stage }) => { if (stage !== "executed") { return

; } // +++ return ; // +++ }, })} /> ``` The [AI Support Chat](/examples/ai-support/nextjs-ai-support) example uses custom components in its support ticket tool to display a contact form. ### Fetching data for custom components You can take custom components a step further by combining them with [actions](#Actions), and then showing the results inside the custom component. The `result` property contains the data returned from the action. ```tsx { // { "temperature": 20, "condition": "sunny" }; const weather = await __fetchWeather__(location); return { data: { weather } }; }, // +++ render: ({ stage, args, result }) => { if (stage !== "executed") { return

Fetching weather…

; } return ( ); }, // +++ })} /> ``` `args` contains the arguments passed to the tool from AI, and `result` contains the data returned from the tool. ## Query actions A helpful way to use tools is to allow AI to query data from your application, such as documents, pages, or other data sources. If your application already contains a search function, you can easily plug it into your tool to create a powerful AI assistant. For example, this tool can search through documents by title, folder, and category. ```tsx { const documents = await __queryDocuments__({ title, folder, category }); return { data: { documents }, description: documents.length > 0 ? `${documents.length} results` : "No results" }; }, // +++ render: ({ stage, args, result }) => { if (stage !== "executed") { return ; } return null; }, })} /> ``` Since the query is happening on the front-end, you don’t need to implement separate authentication for your AI tool—it can leverage the same APIs that your users are already authorized to access. The [AI Reports Dashboard](/examples/ai-dashboard-reports/nextjs-ai-dashboard-reports) example has a query transactions tool allowing for complex searching. ## Human-in-the-loop actions Human-in-the-loop actions allow the user to confirm or deny an action before it’s executed. This is particularly useful when it comes to destructive and stateful actions, such as deleting a document, or sending an email. Confirmable actions like these will freeze the chat until the user responds, either by confirming or cancelling the action. User asks to delete a document ```js User: "Can you delete my-document.txt?" ``` AI calls the delete document tool, “Confirm” and “deny” buttons are displayed _The chat waits for the user to respond._ The user clicks “Confirm” _The document is deleted._ The chat unfreezes and is ready to continue ```js AI: "I've deleted it! How else can I help you?" ``` To create confirmable actions, you must skip using the `execute` function, and instead move your logic to `render`, as we detail below. This will always freeze the chat until the user responds. The [AI Reports Dashboard](/examples/ai-dashboard-reports/nextjs-ai-dashboard-reports) example demonstrates human-in-the-loop actions with its invite member tool. ### Default confirmation component The easiest way to create confirmable actions, is to return the ready-made [`AiTool.Confirmation`](/docs/api-reference/liveblocks-react-ui#AiTool.Confirmation) component in `render`. The `confirm` and `cancel` callbacks work very similarly to `execute`, and are triggered when the user clicks “Confirm” or “Cancel”. ```tsx { return ( // +++ { await __deleteDocument__(documentId); return { data: { documentId }, description: "The user chose to delete the document", }; }} cancel={() => { return { data: { documentId }, description: "The user cancelled deleting the document", }; }} /> // +++ ); }, })} /> ``` In the `cancel` callback it’s important to let the AI know that the user cancelled the action, otherwise it may assume the action failed and try to run it again. ```js description: "The user cancelled deleting the document", ``` ### Building a custom confirmation component By utilizing the `respond` argument in `render`, and the different stages of a tool’s lifecycle, you can build a fully custom confirmation component. These are the different stages: 1. `receiving` - Displayed when AI is streaming in the parameters. 2. `executing` - Displayed when the chat is frozen, and is waiting for a response. 3. `executed` - Displayed after a response has been recorded. Here’s how to leverage the different stages to create a custom “send email” tool—note how `respond` is used similarly to `execute`. ```tsx { // `emailAddress` param is still streaming in, wait // +++ if (stage === "receiving") { return

; } // +++ // The tool is waiting for `respond` to be called // +++ if (stage === "executing") { return (

{ e.preventDefault(); const message = e.target.message.value; await __sendEmail__(args.emailAddress, message); // Similar to `execute`/`confirm`, let AI know it succeeded respond({ data: { emailAddress: args.emailAddress, message }, description: "You sent an email for the user", }); }} >

<button type="submit">Send</button>
            <button
              type="button"
              onClick={() =>
                // Similar to `execute`/`cancel`, let AI know the user cancelled
                respond({
                  data: { emailAddress: args.emailAddress, message },
                  description: "The user cancelled sending an email",
                })
              }
            >
              Cancel
            </button>
          </form>
        );
      }
      // +++

// `respond` has already been called, show the result
      // +++
      return (
        <div>
          You sent an email to {args.emailAddress}: "{result.data.message}".
        </div>
      );
      // +++
    },
  })}
/>
```

A tool’s stages never reset, which means that once an email has been sent, the
tool will remain in the `executed` stage showing “You sent an email to…”, even
after refreshing the page. This enables stateful interaction.

## AI presence & streaming

You can stream in tool results as they arrive, allowing you to show live updates
and AI presence in your application. An example would be a tool that generates
documents—you can display the partially generated document as each chunk
arrives, for example:

<Steps>

<StepCompact>
```json
{ "content": "Here’s" }
```
</StepCompact>

<StepCompact>
```json
{ "content": "Here’s my suggestions" }
```
</StepCompact>

<StepCompact>
```json
{ "content": "Here’s my suggestions for a" }
```
</StepCompact>

<StepCompact lastStep>
```json
{ "content": "Here’s my suggestions for a marketing email!" }
```
</StepCompact>

</Steps>

To show this inside the tool, you can use `render`. While you’d normally access
AI-generated arguments via `args`, but to access streaming results, you can use
`partialArgs` to get the whole stream up to this point. This all occurs during
the `receiving` stage, and as each chunk is received, `render` will re-render
and update the UI.

```tsx
<RegisterAiTool
  name="create-document"
  tool={defineAiTool()({
    description: "Create a document",
    parameters: {
      type: "object",
      properties: {
        content: { type: "string" },
      },
      required: ["content"],
      additionalProperties: false,
    },
    execute: () => {},
    render: ({ stage, partialArgs, args }) => {
      // Document is streaming in
      // +++
      if (stage === "receiving") {
        return <div>Document: {partialArgs.content}</div>;
      }
      // +++

// Document has fully streamed in
      // +++
      return <div>Document: {args.content}</div>;
      // +++
    },
  })}
/>
```

[`RegisterAiTool`](/docs/api-reference/liveblocks-react#RegisterAiTool) allows
you to stream in strings, objects, and arrays, and you can use them in `render`
as they arrive.

The [AI App Builder](/examples/ai-app-builder/nextjs-ai-app-builder) example
demonstrates AI presence and streaming in a code editor.

</Banner>

### Streaming into a document with AI presence

To stream results outside of the chat window, and show AI presence, you can call
functions inside `render`. In this case, we’re updating a document outside of
the chat window, and inside the chat, we’re showing a simple
[`AiTool`](/docs/api-reference/liveblocks-react-ui#AiTool) message.

```tsx
<RegisterAiTool
  name="create-document"
  tool={defineAiTool()({
    description: "Create a document",
    parameters: {
      type: "object",
      properties: {
        content: { type: "string" },
      },
      required: ["content"],
      additionalProperties: false,
    },
    execute: () => {},
    render: ({ stage, partialArgs }) => {
      // Document is streaming in, update document and presence
      // +++
      if (stage === "receiving") {
        __updateDocument__(partialArgs.content);
        __renderPresenceAtPosition__(partialArgs.content.length);
        return <AiTool title="Creating document…" />;
      }
      // +++

// Final chunk of stream is here, update document and end presence
      // +++
      if (stage === "executing") {
        __updateDocument__(args.content);
        __renderPresenceAtPosition__(null);
        return <AiTool title="Creating document…" />;
      }
      // +++

// Document has fully streamed in
      // +++
      return <AiTool title="Document complete!" />;
      // +++
    },
  })}
/>
```

## Advanced JSON schema

Up to this point, we’ve only covered generating objects and strings with AI, but
[JSON schema](https://json-schema.org/learn/getting-started-step-by-step) allows
for more complex data types, such as numbers, arrays, enums, as well as
constraints, and hints for AI.

<Banner type="warning" title="Model compatibility">
  Some AI models don’t allow certain JSON schema types, but we’ve found these
  types work with most models. Many models enforce using the `required` array,
  and setting `additionalProperties: "false"`, which is why we recommend this.
</Banner>

```js
parameters: {
  type: "object",

properties: {
    // String
    name: { type: "string" },

// Number
    age: { type: "number" },

// Boolean
    sendEmail: { type: "boolean" },

// Union
    count: { type: ["string", "number", "null"] },

// Array
    pets: { type: "array", items: { type: "string" } },

// Description, helps AI understand the type
    job: { type: "string", description: "A job title, 1-2 words" },

// String constraints
    fullName: {
      type: "string",
      minLength: 1,
      maxLength: 100,
      pattern: "^[A-Z][a-zA-Z'-]+(?: [A-Z][a-zA-Z'-]+)+$",
    },

// Number constraints
    ageInYears: { type: "number", minimum: 18, maximum: 100 },

// Combination of all
    people: {
      type: "array",
      description: "A list of all people",
      items: {
        type: "object",
        properties: {
          sendEmail: { type: "boolean", description: "Notify them by?" },
          name: { type: "string", description: "First and last names" },
          age: { type: "number", minimum: 18, description: "Age in years" },
          job: { type: ["string", "null"], description: "`null` for unemployed" },
        }
      },
    },
  },

// Recommended to always set the following, passing all properties to `required`
  additionalProperties: false,
  required: ["name", "age", "sendEmail", "job", "fullName", "ageInYears", "pets", "people"],
}
```

## Updating tools

After a tool has been used in the chat, its AI-filled parameters are permanently
set. This leaves us with a problem—if we remove or change the tool’s parameters,
old versions of the tool will display an empty space in the chat (or in
development mode, an error box).

```diff
// ❌ Will render `null` in the chat instead of a tool
‎<RegisterAiTool
  name="send-email"
  tool={defineAiTool()({
    description: "Send an email",
    parameters: {
      type: "object",
      properties: {
-       email: { type: "string" },
+       emailAddress: { type: "string" },
      },
-     required: ["email"],
+     required: ["emailAddress"],
      additionalProperties: false,
    },
  })}
  // ...
/>
```

Care needs to be taken when creating a new version of each tool if you wish for
old chats to display fully working components. For this reason, we recommend
versioning your tools, and disabling the old tool until you’re sure the old
tools aren’t needed anymore. This will ensure the tool won’t be used in new
chats, but the old component will still render correctly.

```tsx
import { RegisterAiTool } from "@liveblocks/react";
import { defineAiTool } from "@liveblocks/client";
import { AiChat } from "@liveblocks/react-ui";

function Chat() {
  return (
    <>
      <AiChat chatId="my-chat-id" />
      <RegisterAiTool
        name="send-email"
        // +++
        // Disabling the old tool so it won't be used in new chats
        enabled={false}
        // +++
        tool={defineAiTool()({
          description: "Send an email",
          parameters: {
            type: "object",
            properties: {
              // +++
              email: { type: "string" },
              // +++
            },
            required: ["email"],
            additionalProperties: false,
          },
        })}
        // ...
      />
      <RegisterAiTool
        // +++
        // Version 2, which will be used in new chats
        name="send-email-v2"
        // +++
        tool={defineAiTool()({
          description: "Send an email",
          parameters: {
            type: "object",
            properties: {
              // +++
              emailAddress: { type: "string" },
              // +++
            },
            required: ["emailAddress"],
            additionalProperties: false,
          },
        })}
        // ...
      />
    </>
  );
}
```

---
meta:
  title: "Troubleshooting"
  parentTitle: "AI Copilots"
  description: "Troubleshoot common issues"
---

AI models are often unreliable and tricky to debug. Here are some common issues
you may encounter, and how to troubleshoot them.

## Common issues

Here’s a list of common issues you may encounter, and how to fix them.

### The AI provider is currently overloaded or unavailable

This means that the AI provider you’re using is currently not available. You can
check the status of your provider by visiting their status pages:
[OpenAI](https://status.openai.com/), [Anthropic](https://status.claude.com/),
[Google](https://aistudio.google.com/status). To avoid this issue, you can
[set up fallback models](/docs/guides/how-to-use-fallback-ai-models-in-ai-copilots)
that use other providers.

### The AI provider's rate limit or quota exceeded

This means that you’ve hit token limits defined by your AI provider (e.g.
OpenAI, Anthropic, Google). You can reach out to your provider to increase your
limits, use a model with lower limits, or consider
[setting up fallback models](/docs/guides/how-to-use-fallback-ai-models-in-ai-copilots)
for busy times.

### For this AI provider, 'additionalProperties: false' is required to be set in the properties [#additionalproperties-false-is-required]

This means that your provider requires the `additionalProperties` field to be
set to `false` in tool `parameters`. Fix this by adding the following line to
your tool definition:

```tsx
<RegisterAiTool
  name="weather-tool"
  tool={defineAiTool()({
    description: "Get the weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: { type: "string" },
      },
      required: ["location"],
      // +++
      additionalProperties: false,
      // +++
    },
    // ...
  })}
/>
```

### A model is ignoring my back-end knowledge

If an AI model doesn’t seem to be using your
[back-end knowledge](/docs/ready-made-features/ai-copilots/knowledge#Back-end-knowledge)
correctly, there are a few things you can check:

#### Check you’re using the correct copilot ID in all APIs

Check you’re using the copilot ID throughout your application, specifically in
every use of [`AiChat`](/docs/api-reference/liveblocks-react-ui#AiChat) and
[`useSendAiMessage`](/docs/api-reference/liveblocks-react#useSendAiMessage).

```tsx
import { AiChat } from "@liveblocks/react-ui";

function Chat() {
  return (
    <AiChat
      chatId="my-chat-id"
      // +++
      copilotId="co_tUYtNctLAtUIAAIZBc1Zk"
      // +++
    />
  );
}
```

```tsx
import { useSendAiMessage } from "@liveblocks/react";

function SendMessage() {
  const sendAiMessage = useSendAiMessage("my-chat-id", {
    // +++
    copilotId: "co_tUYtNctLAtUIAAIZBc1Zk",
    // +++
  });

return (
    <button onClick={() => sendAiMessage("What's new?")}>What's new?</button>
  );
}
```

#### Make sure you’re letting AI know when to use knowledge

Make sure you’re defining
[when AI should use knowledge](/docs/ready-made-features/ai-copilots/copilots#When-should-AI-use-knowledge)
in your copilot settings. When defining copilots from the server, this is the
`knowledgePrompt` field. If it doesn’t seem to be working, try experimenting
with your prompt to be more specific, authoritative, and use examples.

```diff title="When should AI use knowledge?"
- When the user asks a question about code.
+ It's required to do this whenever the user mentions React code, e.g. `useOthers`.
```

It’s worth checking if there’s an official guide for your specific model, which
details how to talk to it. For example the
[official prompting guide for GPT-4.1](https://cookbook.openai.com/examples/gpt4-1_prompting_guide).

### The AI provider response exceeded the maximum token limit

This means that the response from the AI provider exceeded the maximum token
limit.

This error is usually caused:

- When the model’s generated output would exceed the `max tokens` you set in the
  dashboard for a copilot.
- When the request would exceed the model/provider’s token limits (e.g.,
  combined prompt + expected completion), leading the provider to return a
  token-limit error

Check first in your dashboard if the max tokens limit is set correctly.

## Error table

Every error you may encounter is listed in the table below, along with a
suggestion.

| Error                                                                                        | Info                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The AI provider is currently overloaded or unavailable                                       | Your provider is down, check its status. [Learn more](#The-AI-provider-is-currently-overloaded-or-unavailable)                                                                                    |
| The AI provider's rate limit or quota exceeded                                               | You’ve breached the rate limit or quota for your model. [Learn more](#The-AI-provider's-rate-limit-or-quota-exceeded)                                                                             |
| A technical error happened while invoking the AI provider.                                   | A internal technical error happened. [Contact support](https://liveblocks.io/contact/support) if the problem persists.                                                                            |
| For this AI provider, 'additionalProperties: false' is required to be set in the properties` | You need to add `additionalProperties: false` to your tool `parameters` object. [Learn more](#additionalproperties-false-is-required)                                                             |
| Error from AI provider: ...                                                                  | Generic error received from the AI Provider. [Contact support](https://liveblocks.io/contact/support) if the problem persists.                                                                    |
| The AI copilot’s model does not exist or you have insufficient access to it                  | Most likely the wrong `copilotId` is set. Potentially the current user has no permissions to view it.                                                                                             |
| Invalid credentials or insufficient permissions                                              | The API key used in the copilot is invalid or it not has the required permissions to use the model defined in the copilot.                                                                        |
| The AI copilot could not make the request because it is too large                            | Usually the token limit for the model to process is exceeded.                                                                                                                                     |
| The AI provider blocked the request due to a content filter                                  | The request was blocked by the AI provider own content filter.                                                                                                                                    |
| The AI provider response exceeded the maximum token limit                                    | The response from the AI provider exceeded the maximum token limit. Check your max tokens limit in the copilot settings. [Learn more](#The-AI-provider-response-exceeded-the-maximum-token-limit) |
| An unexpected database error happened.                                                       | An internal database error happened. [Contact support](https://liveblocks.io/contact/support) if the problem persists.                                                                            |
| Timeout error.                                                                               | The request timed out. [Contact support](https://liveblocks.io/contact/support) if the problem persists.                                                                                          |
| Abort error.                                                                                 | The request was aborted by the user but the operation did not succeed to abort. [Contact support](https://liveblocks.io/contact/support) if the problem persists.                                 |
| Aborted by user.                                                                             | The current request was aborted by the user.                                                                                                                                                      |
| Messages deleted by user.                                                                    | A message in the chat no longer exists because it was deleted by a user.                                                                                                                          |
| Chat deleted by user.                                                                        | A chat was deleted by a user and our infra cannot proceed the request.                                                                                                                            |

---
meta:
  title: "Comments"
  parentTitle: "Ready-made features"
  description:
    "Embed a customizable commenting experience into your product to enable
    people to collaborate."
---

Embed a customizable commenting experience into your product, enabling
collaboration between your users. Liveblocks Comments is fully customizable,
allowing you to create a range of commenting experiences that look and feel like
your product. It enables you to build mentions, thread resolution, text
annotations, video annotations, and more.

## Overview

## Comments API Reference

## Examples using Comments

---
meta:
  title: "Concepts"
  parentTitle: "Comments"
  description: "Learn about threads and comments"
---

A quick overview of the concepts used in Liveblocks Comments.

## Threads

In Liveblocks Comments, everything revolves around _threads_. In each
[multiplayer room](/docs/concepts/how-liveblocks-works#Rooms) you can create a
number of threads. Each individual thread contains a list of _comments_ written
by your users.

Threads can be retrieved by
[a React hook](/docs/ready-made-features/comments/hooks#threads-hook) or
[on your server](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads).
Here’s an example of a thread object.

```ts
{
  type: "thread",
  id: "th_sf8s6sh...",
  roomId: "my-room-id",
  createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
  resolved: false,
  comments: [
    // A list of comments in the thread
    // ...
  ],
  metadata: {
    // Your custom thread metadata
    // ...
  },
}
```

Threads can store
[custom metadata](/docs/ready-made-features/comments/metadata), which is helpful
for integrating them into your product.

## Comments

Each comment is created by a user, referenced by their
[user ID](/docs/ready-made-features/comments/users-and-mentions), and is part of
a thread. The first comment in a thread is displayed at the top.

Here’s an example of a single comment inside a thread object.

```ts highlight="8-24"
{
  type: "thread",
  id: "th_sf8s6sh...",
  roomId: "my-room-id",
  createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
  resolved: false,
  comments: [
    {
      type: "comment",
      threadId: "th_sf8s6sh...",
      id: "cm_agH76a...",
      roomId: "my-room-id",
      userId: "alicia@example.com",
      createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
      editedAt: Date <Fri Dec 15 2023 15:07:19 GMT+0000 (Greenwich Mean Time)>,
      body: {
        // The comment's text in `CommentBody` format
        // ...
      },
      metadata: {
        // Your custom comment metadata
        // ...
      },
    },

// Other comments in the thread
    // ...
  ],
  metadata: {
    // Your custom thread metadata
    // ...
  },
}
```

A comment’s `body` is in a custom `CommentBody` format, though you most likely
won’t need to use this, as we render it in React for you. We also provide a
number of functions that allow you to easily
[convert a comment’s body into Markdown, HTML, or plain text](/docs/api-reference/liveblocks-node#stringify-comment-body),
which is especially helpful for creating email notifications.

Similarly to threads, comments can also store
[custom metadata](/docs/ready-made-features/comments/metadata), which is helpful
for integrating them into your product.

### Deleted comments

Deleting a comment doesn’t remove the comment object from the thread, instead
the `comment.body` property is removed, and a `comment.deletedAt` property is
added, which contains the deletion time. This allows you to handle the deleted
comment in whichever way you see fit, for example you may like to create a
“message deleted” placeholder for the comment. Alternatively, the comment can be
hidden completely.

A thread is only deleted after all its comments have been deleted.

---
meta:
  title: "Default components"
  parentTitle: "Comments"
  description: "Ready-to-use customizable components"
---

The default components included in Comments are a great way to start building
your application. With these components you can render entire threads, along
with a comment composer.

- Fully styled commenting components, with an optional dark mode.
- Customize through CSS variables and class names.
- Localize and modify strings with overrides.
- Can be used alongside
  [primitives](/docs/ready-made-features/comments/primitives).

## Thread

The [`Thread`][] component renders a thread and its contained comments, as well
a composer for adding new comments to thread.

### Usage

The best way to get started is to import the [`useThreads`][] hook, and loop
through each thread in the current room.

```tsx highlight="5,9-11"
import { Thread } from "@liveblocks/react-ui";
import { useThreads } from "../liveblocks.config";

function Component() {
  const { threads } = useThreads();

return (
    <>
      {threads.map((thread) => (
        <Thread key={thread.id} thread={thread} />
      ))}
    </>
  );
}
```

This will render a list containing every thread in the room, each with its own
composer for adding new comments.

## Composer

The [`Composer`][] component renders a rich-text composer that’s used to create
new threads. It can also be used to add comments to an existing thread, or to
edit comments.

### Usage

Get started by importing the component. By default, it’ll create a new thread
when the form’s submitted.

```tsx
import { Composer } from "@liveblocks/react-ui";

// Creates a new thread
function Component() {
  return <Composer />;
}
```

[`Composer`][] can also be used in other ways:

- [Adding metadata to a new thread](/docs/api-reference/liveblocks-react-ui#Adding-thread-metadata)
- [Replying to a thread](/docs/api-reference/liveblocks-react-ui#Replying-to-a-thread)
- [Adding metadata to a reply](/docs/api-reference/liveblocks-react-ui#Adding-comment-metadata)
- [Modifying a comment](/docs/api-reference/liveblocks-react-ui#Modifying-a-comment)
- [Custom behavior](/docs/api-reference/liveblocks-react-ui#Custom-behavior)

## Comment

The [`Comment`][] component renders a single comment. It’s useful if you’re
building a custom [Thread](#Thread) component, or if you’re displaying a
standalone comment.

### Usage

Start by importing the component, and passing the comment to it.

```tsx highlight="9"
import { Comment } from "@liveblocks/react-ui";
import { ThreadData } from "@liveblocks/client";

// Renders a list of comments attached to the specified `thread`
function MyComment({ thread }: { thread: ThreadData }) {
  return (
    <>
      {thread.comments.map((comment) => (
        <Comment key={comment.id} comment={comment} />
      ))}
    </>
  );
}
```

[`Composer`]: /docs/api-reference/liveblocks-react-ui#Composer
[`Comment`]: /docs/api-reference/liveblocks-react-ui#Comment
[`Thread`]: /docs/api-reference/liveblocks-react-ui#Thread
[`useThreads`]: /docs/api-reference/liveblocks-react#useThreads

## Customization

It’s possible to style and localize the default components:

- Import dark mode styles.
- Modify the style with CSS variables and class names.
- Use overrides to change default text used in the components.

Learn more under
[styling and customization](/docs/ready-made-features/comments/styling-and-customization).

---
meta:
  title: "Email notifications"
  parentTitle: "Comments"
  description: "Send notifications with webhooks"
---

Using Liveblocks webhooks, it’s possible to trigger your API endpoints when
certain events occur, such as a thread being created, or a comment being
modified. One use for these events is sending unread comment notifications, for
example via email or Slack.

This page is an overview of creating email notifications for Comments. If you’d
prefer a full step-by-step tutorial, make sure to read
[how to send email notifications of unread comments](/docs/guides/how-to-send-email-notifications-of-unread-comments).

</Banner>

## Inbox notifications

Email notifications are built around the concept of inbox notifications, which
are different from “normal” notifications in the sense that they can group
multiple activities together and evolve over time, which makes more sense when
sending email notifications because it helps to avoid sending too many emails.
In the case of Comments, inbox notifications are grouped per thread, which means
that if there are 4 new comments in a thread you’re participating in, you will
have a single inbox notification for it, instead of 4 “normal” notifications.

Learn more about Notifications for Comments in the
[overview page](/docs/ready-made-features/comments/email-notifications).

## Sending email notifications with webhooks

Using [Liveblocks webhooks](/docs/platform/webhooks#Liveblocks-events) you can
listen to a range of events such as comments being deleted, or comment reactions
being added. On [your dashboard](https://liveblocks.io/dashboard) you can create
a webhook for a project, and select which events you’d like to listen to. You
only need to select the `"notification"` webhook event for our recommended
solution.

The endpoint URL you pass will receive request with relevant data when the event
occurs. The webhook event built for creating these unread notification emails is
called `"notification"`, and by default is sent up to every 30 minutes to each
user, though this can be customized in the webhooks dashboard.

`"notification"` webhooks can be enabled and disabled on certain channels.
Channels are used to represent different places your users may receive
notifications, such as on `email`, `slack`, `teams`, and `webPush`.

Here’s an example of an event object that’s sent when a user receives a new (or
updated) inbox notification.

```ts
const event = {
  type: "notification",
  data: {
    channel: "email",
    kind: "thread",
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "th_d75sF3...",
    inboxNotificationId: "in_xt3p7ak...",
    userId: "my-user-id",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

### Your endpoint

In your endpoint, you can use this `event` object to get information on unread
mentions and replies, and start rendering emails with
[HTML](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-html)
or
[React](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react).

```tsx
// Get email data as React JSX
const emailData = await prepareThreadNotificationEmailAsReact(
  liveblocks,
  event
);

let email;
switch (emailData.type) {
  // The user has an unread mention
  case "unreadMention": {
    email = (
      // +++
      <div>
        <div>
          @{emailData.comment.author.id} at {emailData.comment.createdAt}
        </div>
        <div>{emailData.comment.body}</div>
      </div>
      // +++
    );
    break;
  }

// The user has multiple unread replies
  case "unreadReplies": {
    email = (
      // +++
      <div>
        {emailData.comments.map((comment) => (
          <div key={comment.id}>
            <div>
              @{comment.author.id} at {comment.createdAt}
            </div>
            <div>{comment.body}</div>
          </div>
        ))}
      </div>
      // +++
    );
  }
}
```

You can customize this further, resolving user and room IDs into data, allowing
you to render names instead of IDs. You can also add custom React components to
the comment bodies, helpful for custom stying.

```tsx
// Get email data as React JSX
const emailData = await prepareThreadNotificationEmailAsReact(
  liveblocks,
  event,
  {
    // +++
    resolveUsers: async ({ userIds }) => {
      const usersData = await __getUsersFromDB__(userIds);

return usersData.map((userData) => ({
        name: userData.name,
        avatar: userData.avatar.src,
      }));
    },
    // +++
    // ...
    components: {
      // `user` is the optional data returned from `resolveUsers`
      // +++
      Mention: ({ element, user }) => (
        <span style={{ color: "red" }}>@{user.name}</span>
      ),
      // +++

// ...
    },
  }
);
```

You can then send an email containing the comment to the owner of `userId`
received in `event`.

```ts
const emailAddress = __getUserEmail__(userId);

// Send email to the user that received the inbox notification
__sendEmail__({
  from: "hello@my-company.com",
  to: emailAddress,
  title: "Unread comment",
  react: `
    <h1>Unread comment</h1>
    ${commentHtml}
  `,
});
```

Here’s an example with every step linked together, along with the code necessary
to verify a webhook request is valid, and using [Resend](https://resend.com) to
send an email.

```ts title="Full example" isCollapsable isCollapsed
import {
  Liveblocks,
  WebhookHandler,
  isThreadNotificationEvent,
} from "@liveblocks/node";
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";
import { Resend } from "resend";

// Create Resend client (add your API key)
const resend = new Resend("re_123456789");

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);

// Add your secret key from a project's API keys dashboard
const API_SECRET = "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx";
const liveblocks = new Liveblocks({ secret: API_SECRET });

export async function POST(request: Request) {
  const body = await request.json();
  const headers = request.headers;

// Verify if this is a real webhook request
  let event;
  try {
    event = webhookHandler.verifyRequest({
      headers: headers,
      rawBody: JSON.stringify(body),
    });
  } catch (err) {
    console.error(err);
    return new Response("Could not verify webhook call", { status: 400 });
  }

// When an inbox notification has been created
  if (isThreadNotificationEvent(event)) {
    // Check if user has access to room
    if (!__hasRoomAccess__(event.userId, event.roomId)) {
      return new Response(null, { status: 200 });
    }

// The user to send the email to
    const emailAddress = __getEmailAddressFromDB__(event.userId);

let emailData;

try {
      emailData = await prepareThreadNotificationEmailAsReact(
        liveblocks,
        event,
        {
          resolveUsers: async ({ userIds }) => {
            const usersData = await __getUsersFromDB__(userIds);

return usersData.map((userData) => ({
              name: userData.name, // "Steven"
              avatar: userData.avatar.src, // "https://example.com/steven.jpg"
            }));
          },
          resolveRoomInfo: async ({ roomId }) => {
            const roomData = await __getRoomFromDB__(roomId);

return {
              name: roomData.name, // "Untitled document"
              url: roomData.url, //`https://example.com/my-room-id`
            };
          },
          components: {
            Paragraph: ({ children }) => (
              <p style={{ margin: "12px 0" }}>{children}</p>
            ),

// `user` is the optional data returned from `resolveUsers`
            Mention: ({ element, user }) => (
              <span style={{ color: "red" }}>@{user?.name ?? element.id}</span>
            ),

// If the link is rich-text render it, otherwise use the URL
            Link: ({ element, href }) => (
              <a href={href} style={{ textDecoration: "underline" }}>
                {element?.text ?? href}
              </a>
            ),
          },
        }
      );
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch thread notification data", {
        status: 500,
      });
    }

// All comments have already been read
    if (!emailData) {
      return new Response(null, { status: 200 });
    }

let email;
    switch (emailData.type) {
      case "unreadMention": {
        email = (
          <div>
            <div>
              @{emailData.comment.author.id} at {emailData.comment.createdAt}
            </div>
            <div>{emailData.comment.body}</div>
          </div>
        );
        break;
      }

case "unreadReplies": {
        email = (
          <div>
            {emailData.comments.map((comment) => (
              <div key={comment.id}>
                <div>
                  @{comment.author.id} at {comment.createdAt}
                </div>
                <div>{comment.body}</div>
              </div>
            ))}
          </div>
        );
        break;
      }
    }

// Send email to the user's email address
    try {
      const data = await resend.emails.send({
        from: "My company <hello@my-company.com>",
        to: emailAddress,
        subject: "New comment",
        react: email,
      });
    } catch (err) {
      console.error(err);
    }
  }

return new Response(null, { status: 200 });
}
```

If you’re planning on building this, we recommend learning more in our
[how to send email notifications](/docs/guides/how-to-send-email-notifications-of-unread-comments)
guide, as it’s possible to create much more complex emails than this simple
example.

### Permissions

When you receive a `notification` webhook event, it's essential to verify if the
user has access to the room before sending an email. Liveblocks lacks the
necessary information to determine if a user has access to a room. For instance,
we create an inbox notification when a user is mentioned in a comment. In this
user's client context, we can determine if they have access to the notification
thanks to the token generated for that user. However, when we send a
`notification` webhook event, we lack this information.

#### Access token authentication

If you are using access tokens, this will always be true, Liveblocks will never
have the information.

#### ID token authentication

If you are using ID tokens, Liveblocks already possesses certain information
about the permissions you have configured for each room, specifying which users
and groups have access. However, what we currently lack is the relationship
between a user and a group. At present, you need to verify user access before
sending an email. We do, however, plan to include full permissions info in
Liveblocks in our future updates. If you're interested in learning more about
this feature, please feel free to reach out to us.

## Webhook events

There are more webhook events than just the `NotificationEvent` event used
above—a number related to Comments are available to use.

- [`CommentCreatedEvent`](/docs/platform/webhooks#CommentCreatedEvent)
- [`CommentEditedEvent`](/docs/platform/webhooks#CommentEditedEvent)
- [`CommentDeletedEvent`](/docs/platform/webhooks#CommentDeletedEvent)
- [`CommentReactionAddedEvent`](/docs/platform/webhooks#CommentReactionAddedEvent)
- [`CommentReactionRemovedEvent`](/docs/platform/webhooks#CommentReactionRemovedEvent)
- [`CommentMetadataUpdatedEvent`](/docs/platform/webhooks#CommentMetadataUpdatedEvent)
- [`ThreadCreatedEvent`](/docs/platform/webhooks#ThreadCreatedEvent)
- [`ThreadMetadataUpdatedEvent`](/docs/platform/webhooks#ThreadMetadataUpdatedEvent)
- [`ThreadMarkedAsResolvedEvent`](/docs/platform/webhooks#ThreadMarkedAsResolvedEvent)
- [`ThreadMarkedAsUnresolvedEvent`](/docs/platform/webhooks#ThreadMarkedAsUnresolvedEvent)

There are also more events, for example you can trigger events when users enter
or leave rooms. We recommend reading our guide on
[testing webhooks locally](/docs/guides/how-to-test-webhooks-on-localhost) to
get started.

## Retrieving and modifying Comments data

Here’s every Comments-related
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) function. Each also
has a corresponding REST API, you can find more info by following the links.

- [`getThreads`](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads)
- [`createThread`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads)
- [`getThread`](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads-threadId)
- [`getThreadParticipants`](/docs/api-reference/liveblocks-node#get-thread-participants)
- [`editThreadMetadata`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-metadata)
- [`createComment`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments)
- [`getComment`](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads-threadId-comments-commentId)
- [`editComment`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId)
- [`editCommentMetadata`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId-metadata)
- [`deleteComment`](/docs/api-reference/liveblocks-node#delete-rooms-roomId-threads-threadId-comments-commentId)
- [`addCommentReaction`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId-add-reaction)
- [`removeCommentReaction`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId-remove-reaction)
- [`getInboxNotification`](/docs/api-reference/liveblocks-node#get-users-userId-inboxNotifications-inboxNotificationId)
- [`getRoomSubscriptionSettings`](/docs/api-reference/liveblocks-node#get-rooms-roomId-users-userId-subscription-settings)
- [`updateRoomSubscriptionSettings`](/docs/api-reference/liveblocks-node#post-rooms-roomId-users-userId-subscription-settings)
- [`deleteRoomSubscriptionSettings`](/docs/api-reference/liveblocks-node#delete-rooms-roomId-users-userId-subscription-settings)

---
meta:
  title: "Hooks"
  parentTitle: "Comments"
  description: "Get users, threads, and modify comments"
---

The Comments React hooks can be used to fetch, create, and modify threads on the
client.

## List a room’s threads [#threads-hook]

The most important Comments hook is
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads), which retrieves
a list of each thread in the current room. This can be used to render a list of
threads, either using the
[default components](/docs/ready-made-features/comments/default-components), or
[primitives](/docs/ready-made-features/comments/primitives). Here’s an example
of it used with the default
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component.

```tsx
import { useThreads } from "../liveblocks.config";

function Component() {
  const { threads } = useThreads();

// [{ type: "thread", id: "th_sf8s6sh...", ... }, ...]
  console.log(threads);

return (
    <>
      {threads.map((thread) => (
        <Thread key={thread.id} thread={thread} />
      ))}
    </>
  );
}
```

There are two versions of the
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads) hook, the
[Suspense version](#suspense-hooks), which we recommend by default, and the
[regular version](#regular-hooks).

## Fetch a user’s information [#user-hook]

The only information Liveblocks stores about users is their user ID, which is
set when [authenticating with Liveblocks](/docs/authentication). With the
[`useUser`](/docs/api-reference/liveblocks-react#useUser) hook, you can fetch a
user’s information from their ID. This is particularly helpful when building
primitive components, as this allows you fetch their name, avatar, and any other
custom data you’ve set.

```tsx
import { useUser } from "../liveblocks.config";

function Component() {
  const { user } = useUser("olivier@example.com");

// { name: "Olivier", avatar: "https://...", color: "red" }
  console.log(user);

return <img src={user.avatar} alt={user.name} />;
}
```

The user data retrieved is set within the
[`resolveUsers`](/docs/api-reference/liveblocks-client#resolveUsers) function in
your `liveblocks.config.ts` file.

```ts
async function resolveUsers({ userIds }) {
  // ["olivier@example.com"]
  console.log(userIds);

return [
    {
      name: "Olivier",
      avatar: "https://example.com/olivier.png",
      color: "red",
    },
  ];
}
```

There are two versions of the
[`useUser`](/docs/api-reference/liveblocks-client#useUser) hook,
[Suspense](#suspense-hooks), which we recommend by default, and
[regular](#regular-hooks).

## Fetch a group’s information [#group-hook]

Similar to users, Liveblocks only stores group IDs for groups. With the
[`useGroupInfo`](/docs/api-reference/liveblocks-react#useGroupInfo) hook, you
can fetch a group’s information from their ID. This is particularly helpful when
building primitive components, as this allows you to fetch their name, avatar,
and any other custom data you’ve set.

```tsx
import { useGroupInfo } from "../liveblocks.config";

function Component() {
  const { group } = useGroupInfo("engineering");

// { name: "Engineering", avatar: "https://...", color: "blue" }
  console.log(group);

return <img src={group.avatar} alt={group.name} />;
}
```

The group data retrieved is set within the
[`resolveGroupsInfo`](/docs/api-reference/liveblocks-client#resolveGroupsInfo)
function in your `liveblocks.config.ts` file.

```ts
async function resolveGroupsInfo({ groupIds }) {
  // ["engineering"]
  console.log(groupIds);

return [
    {
      name: "Engineering",
      avatar: "https://example.com/engineering.png",
      color: "blue",
    },
  ];
}
```

There are two versions of the
[`useGroupInfo`](/docs/api-reference/liveblocks-client#useGroupInfo) hook,
[Suspense](#suspense-hooks), which we recommend by default, and
[regular](#regular-hooks).

## Create and modify threads and comments [#mutation-hooks]

A number of hooks can be used to mutate comment and thread data, for example:

- Creating threads
- Deleting comments
- Adding emoji reactions

Some of these hooks are quite simple, such as
[`useAddReaction`](/docs/api-reference/liveblocks-react#useAddReaction) which
adds a reaction to a specified comment.

```tsx highlight="6,9-13"
import { CommentData } from "@liveblocks/client";
import { useAddReaction } from "../liveblocks.config.ts";

// A button that adds a "⭐" reaction to a comment
function Component({ comment }: { CommentData }) {
  const addReaction = useAddReaction();

function handleClick() {
    addReaction({
      threadId: comment.threadId,
      commentId: comment.commentId,
      emoji: "⭐",
    });
  }

return <button onClick={handleClick}>Star ⭐</button>;
}
```

Whereas others, such as
[`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread), have
more complex behaviour and are designed to work alongside
[primitives](/docs/ready-made-features/comments/primitives).

```tsx highlight="10,18-21"
import {
  Composer,
  ComposerSubmitComment,
} from "@liveblocks/react-ui/primitives";
import { useCreateThread } from "../liveblocks.config.ts";
import { FormEvent } from "react";

// A custom composer that creates a thread on submit
function MyComposer() {
  const createThread = useCreateThread();

function handleComposerSubmit(
    { body }: ComposerSubmitComment,
    event: FormEvent<HTMLFormElement>
  ) {
    event.preventDefault();

const thread = createThread({
      body,
      metadata: {},
    });
  }

return (
    <Composer.Form onComposerSubmit={handleComposerSubmit}>
      <Composer.Editor />
      <Composer.Submit>Create thread</Composer.Submit>
    </Composer.Form>
  );
}
```

You can find more information on each mutation hook in our API reference pages:

- [`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread)
- [`useDeleteThread`](/docs/api-reference/liveblocks-react#useDeleteThread)
- [`useEditThreadMetadata`](/docs/api-reference/liveblocks-react#useEditThreadMetadata)
- [`useMarkThreadAsResolved`](/docs/api-reference/liveblocks-react#useMarkThreadAsResolved)
- [`useMarkThreadAsUnresolved`](/docs/api-reference/liveblocks-react#useMarkThreadAsUnresolved)
- [`useCreateComment`](/docs/api-reference/liveblocks-react#useCreateComment)
- [`useEditComment`](/docs/api-reference/liveblocks-react#useEditComment)
- [`useEditCommentMetadata`](/docs/api-reference/liveblocks-react#useEditCommentMetadata)
- [`useDeleteComment`](/docs/api-reference/liveblocks-react#useDeleteComment)
- [`useAddReaction`](/docs/api-reference/liveblocks-react#useAddReaction)
- [`useRemoveReaction`](/docs/api-reference/liveblocks-react#useRemoveReaction)

There’s only one version of these hooks, so it doesn’t make a difference if you
export them from `suspense` in your config file or not.

## Hook types [#hook-types]

There are two different ways to use the [threads](#threads-hook) and
[user](#user-hook) hooks; with
[React Suspense](https://react.dev/reference/react/Suspense), and without it. We
recommend using the Suspense versions, as they often result in simpler code.

### Suspense hooks [#suspense-hooks]

Using Suspense hooks means that any data retrieved, for example `threads` from
`useThreads`, will never be `undefined`, and your component will never see an
error.

```tsx
import { useThreads } from "@liveblocks/react/suspense";

// Suspense: `threads` is always defined
function MyThreads() {
  const { threads } = useThreads();

// [{ type: "thread", id: "th_sf8s6sh...", ... }, ...]
  console.log(threads);
}
```

To catch errors and display a loading screen, you can use
[`ErrorBoundary`](https://www.npmjs.com/package/react-error-boundary) and
[`ClientSideSuspense`](/docs/api-reference/liveblocks-react#suspense-avoid-ssr).

```tsx highlight="7-11"
import { ClientSideSuspense } from "@liveblocks/react/suspense";
import { ErrorBoundary } from "react-error-boundary";

// Handle errors and loading state in the component above
function Component() {
  return (
    <ErrorBoundary fallback={<div>Error</div>}>
      <ClientSideSuspense fallback={<div>Loading...</div>}>
        <MyThreads />
      </ClientSideSuspense>
    </ErrorBoundary>
  );
}
```

To use Suspense, make sure you’re exporting your hooks from
`@liveblocks/react/suspense`.

```tsx
// Suspense version of hooks
import { useThreads, useUser, useGroupInfo } from "@liveblocks/react/suspense";
//                                                                   ^^^^^^^^
```

### Regular hooks [#regular-hooks]

The regular versions of Liveblocks hooks require you to check for `error` and
`isLoading` properties. You can then handle these states in the same component.

```tsx
import { useThreads } from "@liveblocks/react";

// Handle errors and loading state in the same component
function MyThreads() {
  const { threads, error, isLoading } = useThreads();

if (error) {
    return <div>Error</div>;
  }

if (isLoading) {
    return <div>Loading...</div>;
  }

// Non-Suspense: `threads` is only defined AFTER the `if` checks
  // [{ type: "thread", id: "th_sf8s6sh...", ... }, ...]
  console.log(threads);
}
```

To use the regular hooks, make sure you’re exporting from `@liveblocks/react`.

```tsx
// Regular version of hooks
import { useThreads, useUser, useGroupInfo } from "@liveblocks/react";
//                                                 ^^^^^^^^^^^^^^^^^
```

---
meta:
  title: "Metadata"
  parentTitle: "Comments"
  description: "Add custom metadata to threads and comments"
---

In Comments, each thread and comment can be given custom metadata. This is
helpful for integrating Comments into various applications, for example it can
be used to store:

- The priority, status, or category of a thread.
- Coordinates or timestamps related to the thread.
- Quoted text in a text editor.
- Tags, context, or flags on a comment.
- External IDs like Slack message IDs on comments to build two-way integrations.

## Valid metadata

You can store any `string`, `boolean`, or `number` in metadata, for example:

```ts
metadata: {
  priority: "URGENT",
  pinned: false,
  timestamp: 1703073188013,
}
```

Setting a property to `null` will remove it.

```ts
metadata: {
  timestamp: null,
}
```

You can store up to 50 metadata properties per thread or comment, and each
property can be 4000 characters long.

## Setting metadata

Metadata can be set using the default components, React hooks, or by editing
threads and comments using the REST APIs. But before making any changes, it’s
recommended to set your metadata types in your config file.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // +++
    ThreadMetadata: {
      priority: string;
      pinned: boolean;
      timestamp: number;
    };
    CommentMetadata: {
      slackMessageTs: string;
      spam: boolean;
      upvotes: number;
    };
    // +++

// ...
  }
}
```

Learn more about
[typing your data](/docs/api-reference/liveblocks-react#Typing-your-data).

### Composer component

The [`<Composer />`](/docs/api-reference/liveblocks-react-ui#Composer) component
is used to create threads and comments, and by default it’ll create a new
thread, with optional metadata, when its form is submitted.

When using it to create a thread, you can
[pass custom metadata](/docs/api-reference/liveblocks-react-ui#Adding-thread-metadata),
which will be attached to the thread.

```tsx
import { Composer } from "@liveblocks/react-ui";

// Creates a new thread with custom metadata
function Component() {
  return (
    <Composer
      // +++
      metadata={{
        // Custom metadata here
        priority: "URGENT",
        pinned: false,
        timestamp: 1703073188013,
      }}
      // +++
    />
  );
}
```

When using it to reply to a thread, you can also
[pass custom metadata](/docs/api-reference/liveblocks-react-ui#Adding-comment-metadata),
which will be attached to the comment.

```tsx
import { Composer } from "@liveblocks/react-ui";

// Creates a new reply to an existing thread with custom metadata
function Component({ threadId }) {
  return (
    <Composer
      // +++
      threadId={threadId}
      commentMetadata={{
        // Custom metadata here
        tag: "engineering",
        reviewed: false,
      }}
      // +++
    />
  );
}
```

### Mutation hooks

Several
[mutation hooks](/docs/ready-made-features/comments/hooks#mutation-hooks) allow
you to edit thread and comment metadata:
[`useEditThreadMetadata`](/docs/api-reference/liveblocks-react#useEditThreadMetadata),
[`useEditCommentMetadata`](/docs/api-reference/liveblocks-react#useEditCommentMetadata),
and [`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread).
Here’s one way to create a button that sets the `pinned` metadata property to
`true` on a thread.

```tsx highlight="5,10-13"
import { useEditThreadMetadata } from "@liveblocks/react/suspense";

// Button that sets `pinned` metadata to `true`
function Component() {
  const editThreadMetadata = useEditThreadMetadata();

return (
    <button
      onClick={() =>
        editThreadMetadata({
          threadId: "th_d75sF3...",
          metadata: { pinned: true },
        })
      }
    >
      Pin thread
    </button>
  );
}
```

Here’s an example of editing comment metadata:

```tsx highlight="5,10-15"
import { useEditCommentMetadata } from "@liveblocks/react/suspense";

// Button that sets `spam` metadata to `true` on a comment
function Component() {
  const editCommentMetadata = useEditCommentMetadata();

return (
    <button
      onClick={() =>
        editCommentMetadata({
          threadId: "th_d75sF3...",
          commentId: "cm_agH76a...",
          metadata: { spam: true },
        })
      }
    >
      Mark as spam
    </button>
  );
}
```

### REST APIs

It’s possible to modify metadata from our REST APIs using the
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) package. Here’s an
example using
[`liveblocks.editThreadMetadata`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-metadata)
for threads.

```ts highlight="12-14"
import { Liveblocks } from "@liveblocks/node";

// Create a Node.js client
const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}" });

// Edit a thread's `priority` metadata, passing the user ID that made the change
await liveblocks.editThreadMetadata({
  roomId: "my-room-id",
  threadId: "th_d75sF3...",

data: {
    metadata: {
      priority: "IMPORTANT",
    },
    userId: "florent@example.com",
  },
});
```

And here’s an example using
[`liveblocks.editCommentMetadata`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId-metadata)
for comments.

```ts highlight="12-14"
import { Liveblocks } from "@liveblocks/node";

// Create a Node.js client
const liveblocks = new Liveblocks({ secret: "{{SECRET_KEY}}" });

// Edit a comment's `tag` metadata, passing the user ID that made the change
await liveblocks.editCommentMetadata({
  roomId: "my-room-id",
  threadId: "th_d75sF3...",
  commentId: "cm_agH76a...",

data: {
    metadata: {
      tag: "engineering",
    },
    userId: "florent@example.com",
  },
});
```

The same result can also be achieved directly through our
[edit thread metadata](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-metadata)
REST API.

```bash
curl -X POST https://api.liveblocks.io/v2/rooms/my-room-id/threads/th_d75sF3.../metadata \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": "IMPORTANT"}, "userId": "florent@example.com"}'
```

And our
[edit comment metadata](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId-metadata)
REST API.

```bash
curl -X POST https://api.liveblocks.io/v2/rooms/my-room-id/threads/th_d75sF3.../comments/cm_agH76a.../metadata \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"tag": "engineering"}, "userId": "olivier@example.com"}'
```

---
meta:
  title: "Primitives"
  parentTitle: "Comments"
  description: "Construct fully custom components"
---

The primitive components included in Comments are a great way to build complex,
completely custom components. These are headless and unstyled, and can be used
to construct a fully styled comment body and rich-text comment composer.

- Liveblocks functionality, but your own fully custom styles.
- Build custom components for mentions, suggestions, links, and more.
- Composable components that work similarly to
  [Radix UI](https://www.radix-ui.com/) and
  [Headless UI](https://headlessui.com/).
- Can be used alongside the
  [default components](/docs/ready-made-features/comments/default-components).

## Concepts

Each primitive is made up of one or more components, for example
[`Comment`](/docs/api-reference/liveblocks-react-ui#primitives-Comment) only
needs `Comment.Body`. This component takes a comment’s body, and turns it into
readable text, with links and mentions.

```tsx highlight="6"
import { CommentData } from "@liveblocks/client";
import { Comment } from "@liveblocks/react-ui/primitives";

// Render a custom comment body
function MyComment({ comment }: { comment: CommentData }) {
  return <Comment.Body body={comment.body} />;
}
```

### Use regular props

Each primitive accepts regular HTML props, and passes them down to it’s root
component. For example a `style` prop on `Comment.Body` will be passed down to
its root `div` component. This means you can use regular `div` properties with
your component.

```tsx highlight="9-11"
import { CommentData } from "@liveblocks/client";
import { Comment } from "@liveblocks/react-ui/primitives";

// Render a custom comment body
function MyComment({ comment }: { comment: CommentData }) {
  return (
    <Comment.Body
      body={comment.body}
      className="text-gray-500"
      style={{ width: "300px" }}
      onPointerEnter={() => {}}
    />
  );
}
```

By default, each component uses an appropriate root element, for example
`Composer.Submit` is a `button`, and `Composer.Form` is a `form`. You can use a
custom component with
[`asChild`](/docs/ready-made-features/comments/primitives#Merge-with-your-design-system-components).

### Use custom component parts

Many primitives allow you to customize their parts by passing a `components`
property. In this example, we’re modifying links in the comment, so that they’re
purple and bold.

```tsx
import { CommentData } from "@liveblocks/client";
import { Comment, CommentBodyLinkProps } from "@liveblocks/react-ui/primitives";

// Render a custom comment body
function MyComment({ comment }: { comment: CommentData }) {
  return (
    <div>
      <Comment.Body
        body={comment.body}
        // +++
        components={{
          Link,
        }}
        // +++
      />
    </div>
  );
}

// +++
// Render a purple link in the comment, e.g. "https://liveblocks.io"
function Link({ href, children }: CommentBodyLinkProps) {
  return (
    <Comment.Link href={href} style={{ color: "purple", fontWeight: 700 }}>
      {children}
    </Comment.Link>
  );
}
// +++
```

### Merge with your design system components

You can also add components directly from your design system. Let’s say you have
a `DesignSystemLink` that looks like this.

```tsx
function DesignSystemLink({ url, children }) {
  return (
    <a href={url} target="_blank">
      {children}
    </a>
  );
}
```

If you were to place this inside `<Comment.Link>`, you’d render two `<a>`
elements, which is not valid HTML. This occurs because both `<Comment.Link>` and
`<DesignSystemLink>` render `<a>` elements.

```tsx
<Comment.Link href={href} style={{ color: "purple " }}>
  <DesignSystemLink url={href}>{children}</DesignSystemLink>
</Comment.Link>

// ===================================================================

// ❌ Renders two separate <a> tags
 <a href="https://liveblocks.io" style="color: purple">
   <a href="https://liveblocks.io" target="_blank">https://liveblocks.io</a>
 </a>
```

However, if you add the `asChild` property to `Comment.Link` it won’t render any
component, and will instead merge into the child element. This means you can use
a link element from your design system, and only render a single `<a>` element.

```tsx highlight="1"
<Comment.Link href={href} style={{ color: "purple " }} asChild>
  <DesignSystemLink url={href}>{children}</DesignSystemLink>
</Comment.Link>

// ===================================================================

// ✅ Renders one combined <a> tag
<a href="https://liveblocks.io" style="color: purple" target="_blank">
  https://liveblocks.io
</a>
```

This is called composability, and virtually all Comments primitives are
composable with `asChild`; they forward their props and refs, merge their
classes and styles, and chain their event handlers with the child element.

```tsx
import { Button } from "@/my-design-system";

// Use the default <button> element
<Composer.Submit disabled>Send</Composer.Submit>;

// Use an existing custom <Button> component
<Composer.Submit disabled asChild>
  <Button variant="primary">Send</Button>
</Composer.Submit>;
```

## Composer

The [`Composer`](/docs/api-reference/liveblocks-react-ui#primitives-Composer)
primitive allows you to build a custom rich-text composer, which can be used for
creating, or editing, threads and comments. Here’s an example of a composer that
creates a new thread when it’s submitted.

```tsx
import { Composer } from "@liveblocks/react-ui/primitives";
import { useCreateThread } from "../liveblocks.config.ts";

// Render a custom composer that creates a thread on submit
function MyComposer() {
  const createThread = useCreateThread();

return (
    <Composer.Form
      onComposerSubmit={({ body }, event) => {
        event.preventDefault();
        const thread = createThread({
          body,
          metadata: {},
        });
      }}
    >
      <Composer.Editor components={/* Your custom component parts */} />
      <Composer.Submit>Create thread</Composer.Submit>
    </Composer.Form>
  );
}
```

Custom component parts can be used to render custom
[mentions](/docs/api-reference/liveblocks-react-ui#primitives-Composer.Editor-Mention),
[links](/docs/api-reference/liveblocks-react-ui#primitives-Composer.Link), and a
[suggestions selection popover](/docs/api-reference/liveblocks-react-ui#primitives-Composer.Suggestions).

### useComposer

The [`useComposer`](/docs/api-reference/liveblocks-react-ui#useComposer) hook
can be placed within `<Composer.Form>` to check if the composer input is empty,
or to submit the form, helpful for creating your own button, or styling the UI.

```tsx highlight="14,17-19"
import { Composer, useComposer } from "@liveblocks/react-ui/primitives";

function MyComposer() {
  return (
    <Composer.Form onComposerSubmit={/* handle submit */}>
      <Composer.Editor components={/* Your custom component parts */} />
      <MyComposerButton />
    </Composer.Form>
  );
}

// Button that submits the form, and is disabled when the input is empty
function MyComposerButton() {
  const { isEmpty, submit } = useComposer();

return (
    <button onClick={submit} disabled={isEmpty}>
      Create thread
    </button>
  );
}
```

## Comment

The [`Comment`](/docs/api-reference/liveblocks-react-ui#primitives-Comment)
primitive is used to render a `comment.body` object as text, mentions, and
links.

```tsx
import { Comment } from "@liveblocks/react-ui/primitives";
import { CommentData } from "@liveblocks/client";

// Render custom comments in a thread.
function MyComments({ comments }: { comments: CommentData[] }) {
  return (
    <>
      {comments.map((comment) => (
        <div key={comment.id}>
          <Comment.Body
            body={comment.body}
            components={/* Your custom component parts */}
          />
        </div>
      ))}
    </>
  );
}
```

The component above would typically be combined with
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads).

```tsx
import { useThreads } from "../liveblocks.config";

function MyThreads() {
  const { threads } = useThreads();

return (
    <>
      {threads.map((thread) => (
        <MyComments key={thread.id} comments={thread.comments} />
      ))}
    </>
  );
}
```

Custom component parts can be used to render
[mentions](/docs/api-reference/liveblocks-react-ui#primitives-Comment.Mention)
and [links](/docs/api-reference/liveblocks-react-ui#primitives-Comment.Link).

## Timestamp

The [`Timestamp`](/docs/api-reference/liveblocks-react-ui#primitives-Timestamp)
primitive is a quick helper that will convert a date object, or timestamp, into
a friendly format. For example, it’ll render a format similar to “5 minutes ago”
for a recent comment, and “22 Dec” for an older comment.

```tsx highlight="12"
import { Timestamp } from "@liveblocks/react-ui";
import { useThreads } from "../liveblocks.config";

// Render threads with friendly datetime messages above
function Component() {
  const { threads } = useThreads();

return (
    <>
      {threads.map((thread) => (
        <div key={thread.id}>
          Thread posted at: <Timestamp date={thread.createdAt} />
          {/* Render `thread` ... */}
        </div>
      ))}
    </>
  );
}
```

---
meta:
  title: "Styling and customization"
  parentTitle: "Comments"
  description: "CSS variables, dark mode, localization, and more"
---

Styling
[default components](/docs/ready-made-features/comments/default-components) and
[primitives](/docs/ready-made-features/comments/primitives) is enabled through a
range of means, such as CSS variables, class names, and more. It’s also possible
to use
[overrides](/docs/ready-made-features/comments/styling-and-customization#Overrides-and-localization)
to modify any strings used in the default components, which is especially
helpful for localization.

## Default components

To add the default components’ theme, import the
[default styles](/docs/api-reference/liveblocks-react-ui#Default-styles) CSS
file.

```ts
import "@liveblocks/react-ui/styles.css";
```

You can also import one of two CSS files to enable
[dark mode](/docs/api-reference/liveblocks-react-ui#Dark-mode), depending on how
you’d like to enable it.

```ts
// Dark mode using the system theme with `prefers-color-scheme`
import "@liveblocks/react-ui/styles/dark/media-query.css";
```

```ts
// Dark mode using `className="dark"`, `data-theme="dark"`, or `data-dark="true"`
import "@liveblocks/react-ui/styles/dark/attributes.css";
```

### CSS variables

A number of
[CSS variables](/docs/api-reference/liveblocks-react-ui#CSS-variables) can be
used to customize colors, spacing, and more. This is our recommended path for
styling the default components, as you can quickly and easily modify all
components with just a few variables.

```css
/* Styles all default components */
.lb-root {
  --lb-accent: purple;
  --lb-spacing: 1em;
  --lb-radius: 0;
}
```

### Class names

Should you need deeper customization,
[class names](/docs/api-reference/liveblocks-react-ui#Class-names) can be
styled, some of which provide contextual data attributes.

```css
.lb-thread {
  /* Customize thread */
}

.lb-avatar[data-loading] {
  /* Customize avatar loading state */
}
```

### Overrides and localization

It’s possible to
[override strings](/docs/api-reference/liveblocks-react-ui#Overrides) used in
the default components, which has a couple of different uses, the first being
localization. In this example, we’re globally switching the word “Anonymous” to
“Anonyme” for French users.

```tsx
import { LiveblocksUiConfig } from "@liveblocks/react-ui";

export function App() {
  return (
    <LiveblocksUiConfig
      overrides={{ locale: "fr", USER_UNKNOWN: "Anonyme" /* ... */ }}
    >
      {/* ... */}
    </LiveblocksUiConfig>
  );
}
```

You can also override strings on a component basis, for example if you’d like to
change the placeholder text in the
[`Composer`](/docs/api-reference/liveblocks-react-ui#Composer).

```tsx
import { Composer } from "@liveblocks/react-ui";

function Component() {
  return (
    <Composer
      overrides={{
        COMPOSER_PLACEHOLDER: "Reply to thread…",
      }}
    />
  );
}
```

## Primitives

Primitives
[can be styled like any other element](/docs/ready-made-features/comments/primitives#Use-regular-props)
in your React application—each component passes down props to its root element,
meaning you can use regular HTML props.

```tsx
import { Composer } from "@liveblocks/react-ui/primitives";

function Component() {
  return (
    <Composer.Submit className="btn-primary" style={{ color: "#ffffff" }}>
      Reply
    </Composer.Submit>
  );
}
```

You can use your custom design system components with primitives by using the
`asChild` property, which will
[merge the primitive’s props](/docs/ready-made-features/comments/primitives#Merge-with-your-design-system-components)
into your component’s.

```tsx highlight="6"
import { Composer } from "@liveblocks/react-ui/primitives";
import { Button } from "@/my-design-system";

function Component() {
  return (
    <Composer.Submit asChild>
      <Button variant="primary">Reply</Button>
    </Composer.Submit>
  );
}
```

### Tailwind

Style primitives with [Tailwind](https://tailwindcss.com) by adding class names.

```tsx
import { Composer } from "@liveblocks/react-ui/primitives";

function Component() {
  return (
    <Composer.Submit className="bg-black text-white">Reply</Composer.Submit>
  );
}
```

### CSS modules

Style primitives with [CSS modules](https://github.com/css-modules/css-modules)
as you would any other component.

```tsx
import { Composer } from "@liveblocks/react-ui";
import styles from "./Component.module.css";

function Component() {
  return <Composer.Submit className={styles.submit}>Reply</Composer.Submit>;
}
```

---
meta:
  title: "Users and mentions"
  parentTitle: "Comments"
  description: "Add users and groups to comments and mentions"
---

When a comment is posted, Liveblocks doesn’t store any user metadata, for
example their avatar or name. Instead, it only saves their user ID, which you
manually set when authenticating. To fetch user metadata, we provide functions
that allow you to return the correct data.

This page explains the concepts behind adding users and mentions to Comments. If
you’d prefer a full step-by-step tutorial, make sure to read
[how to add users to Liveblocks Comments](/docs/guides/how-to-add-users-to-liveblocks-comments).

</Banner>

## Authenticate your users

You can set a user’s ID when authenticating your application, for example with
[`liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens).
This ID is then used inside Comments to represent the current user, for example
we’re using an email address as a user ID below.

```ts highlight="1"
const session = liveblocks.prepareSession("charlie.layne@example.com", {
  userInfo: {
    // Custom user info to be used in Presence
    // This is NOT used in Comments
    // ...
  },
});
```

There are two different authentication methods—make sure to follow an
[authentication guide for your framework](/docs/authentication) to get started.

## Adding user information

To add names and avatars to Comments, you need to convert user IDs into user
objects. For example, here’s a `userIds` array and the information you need to
return. You should return the same number of users as the number of user IDs, in
the same order.

```shell
# If this is `userIds`
["marc@example.com", "pierre@example.com"]

# Return `users`
[{ name: "Marc", avatar: "https://example.com/marc.png" }, { name: "Pierre", avatar: "https://example.com/pierre.png" }]
```

To do this, add a property named
[`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers)
to your
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
where you can return this information.

```tsx
<LiveblocksProvider
  authEndpoint="/api/liveblocks-auth"
  // +++
  resolveUsers={async ({ userIds }) => {
    // ["marc@example.com", ...]
    console.log(userIds);

// Get users from your back-end
    const users = await __fetchUsers__(userIds);

// [{ name: "Marc", avatar: "https://example.com/marc.png" }, ...]
    console.log(users);

// Return a list of users
    return users;
  }}
  // +++
>
```

### Custom user information

The `name`, and `avatar` are handled by the default components, but you can also
return custom metadata here. For example, each user may have a `color` property.
You can retrieve these properties in your app with
[`useUser`](/docs/api-reference/liveblocks-react#useUser).

```tsx
function Component() {
  // +++
  const { user } = useUser("marc@example.com");
  // +++

// { color: "red", name: "Marc", avatar: "https://example.com/marc.png" }
  console.log(user);

// ...
}
```

## Mentions

Comments allows you to use mentions/tag users by typing the `@` character. You
can also tag groups, for example `@everyone`. After a user’s mentioned in a
thread, they’ll receive an
[inbox notification](/docs/ready-made-features/notifications/concepts#Inbox-Notifications).

### Resolving mention suggestions

To define which mentions appear in the suggestion pop-up, you need to return a
list of users that are being searched for. When a user types `@` Comments passes
you a `text` property, the text that the user has typed so far, which you can
use to find and return matching user IDs.

```shell
# If "@mar" has been typed, this is `text`
"mar"

# Return matching `userIds` and `groupIds`
["marc@example.com", "marissa@example.com"]
```

You can resolve these search results by adding a
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveMentionSuggestions)
property to your
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider).
Here’s what the function might look like if the user has typed `"@mar"` into the
input.

```tsx
<LiveblocksProvider
  authEndpoint="/api/liveblocks-auth"
  resolveUsers={async ({ userIds }) => {
    // ...
  }}
  // +++
  resolveMentionSuggestions={async ({ text, roomId }) => {
    // "mar"
    console.log(text);

// Return an array of user IDs for the query "mar"
    let userIds;

if (text) {
      // If there's a query, get user IDs from your back-end that match
      userIds = await __queryUserIds__(text);
    } else {
      // If there's no query, get all of the room's user IDs
      userIds = await __getAllUserIds__();
    }

// ["marc@example.com", "marissa@example.com"]
    console.log(userIds);
    return userIds;
  }}
  // +++
>
```

You can also resolve group mentions in here, though that requires you to
structure the function differently.

## Group mentions

Alongside user mentions, you can also mention groups by typing the `@`
character, for example `@everyone` or `@engineering`.

There are two different ways to set up group mentions:

1. Passing group members on the front-end, particularly helpful for global
   mentions like `@everyone` and `@here`.
2. Using managed groups of users on the back-end, helpful for handling specific
   groups of users like `@engineering` or `@design`.

### Return a different format

When using group mentions, you must return a list of mention objects with a
`kind` property, instead of a list user ID strings, like below.

```diff
- return ["marc@example.com"];
+ return [
+  {
+    kind: "user",
+    id: "marc@example.com",
+  },
+ ];
```

Users have a `user` kind and groups have `group` kind.

```tsx
return [
  {
    // +++
    kind: "user",
    // +++
    id: "marc@example.com",
  },
  {
    // +++
    kind: "group",
    // +++
    id: "engineering",
  },
];
```

### Passing group members on the front-end

The easiest way to create a group mention is to pass a list of group members to
the
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveMentionSuggestions)
function. This allows you to suggest a list of users that are part of the group,
and requires no back-end code, simply return a list of user IDs. In the example
below, a `@everyone` suggestion is added, which will tag all users in the app.

```tsx
resolveMentionSuggestions={async ({ text, roomId }) => {
  const allUserIds = await __getAllUserIds__();
  const queryUserIds = await __queryUserIds__(text);

// `@everyone`, `@here`, etc.
  // +++
  const globalMentions: MentionData[] = [];
  // +++

// Create `@everyone` suggestion, for all users in app
  // +++
  globalMentions.push({
    kind: "group",
    id: "everyone",
    userIds: allUserIds, // Array of all user IDs
  });
  // +++

return [
    // +++
    ...globalMentions,
    // +++
    ...queryUserIds.map((user) => ({
      kind: "user",
      id: user.id,
    })),
  ];
}}
```

In the example above, `@everyone` will _always_ be displayed in the suggestions
list. Make sure to filter using the search text if you’d like to only show it
when the user is typing `"@everyone"`.

```tsx
import type { MentionData } from "@liveblocks/client";

resolveMentionSuggestions={async ({ text, roomId }) => {
  const allUserIds = await __getAllUserIds__();
  const queryUserIds = await __queryUserIds__(text);

// `@everyone`, `@here`, etc.
  const globalMentions: MentionData[] = [];

// Show `@everyone` suggestion when users search for it
  // +++
  if ("everyone".includes(text.toLowerCase())) {
  // +++
    globalMentions.push({
      kind: "group",
      id: "everyone",
      userIds: allUserIds, // Array of all user IDs
    });
  // +++
  }
  // +++

return [
    ...globalMentions,
    ...queryUserIds.map((user) => ({
      kind: "user",
      id: user.id,
    })),
  ];
}}
```

This method is generally most useful for dynamically fetching group mentions,
for example with `@everyone`, `@here`, `@online`, but you can use it to create
fixed group mentions as well.

### Managed groups on the back-end

You can create mention groups on the back-end using the Node.js SDK or REST API,
and they’ll be saved permanently. You can add new members, create new groups,
list groups, and more. If your app has teams or groups of users, it makes sense
to synchronize them with Liveblocks whenever there’s a change.

To get started, create a group using
[`liveblocks.createGroup`](/docs/api-reference/liveblocks-node#create-group),
defining each member by their user ID.

```ts
const group = await liveblocks.createGroup({
  groupId: "engineering-team",
  memberIds: ["marc@example.com", "florent@example.com"],
});
```

In your
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveMentionSuggestions)
function, you can then query all the groups you’ve created for the current
search text, and return them.

```tsx
resolveMentionSuggestions={async ({ text, roomId }) => {
  // +++
  const groupIds = await queryGroupIds(text);
  // +++
  const userIds = await __queryUserIds__(text);

return [
    // +++
    ...groupIds.map((group) => ({
      kind: "group",
      id: group.id,
    })),
    // +++
    ...userIds.map((user) => ({
      kind: "user",
      id: user.id,
    })),
  ];
}}
```

Here’s how your `queryGroupIds` function can use
[`liveblocks.getGroups`](/docs/api-reference/liveblocks-node#get-groups) to
query all groups and filter them by the search text.

```ts file="queryGroupIds.ts"
"use server";

export async function queryGroupIds(text: string) {
  // +++
  const { data: groups } = await liveblocks.getGroups();
  // +++

// +++
  return groups
    .filter((group) => group.id.includes(text))
    .map((group) => group.id);
  // +++
}
```

If your app has multi-tenancy, make sure you handle permissions correctly, and
filter out any groups that the user doesn’t have access to.

#### First-party multi-tenancy

Using the Liveblocks [organizations](/docs/authentication/organizations) feature, you can
create groups with the same ID in different organizations. This is an easy way to
compartmentalize resources in your app for each organization. In the snippet
below, both organizations have an engineering team, but because separate organizations
are used, they are different groups.

```ts
const group = await liveblocks.createGroup({
  groupId: "engineering-team",
  memberIds: ["marc@example.com", "florent@example.com"],
  // +++
  organizationId: "apple-corp",
  // +++
});

const group = await liveblocks.createGroup({
  groupId: "engineering-team",
  memberIds: ["chris@example.com", "olivier@example.com"],
  // +++
  organizationId: "banana-inc",
  // +++
});
```

## Adding group information

Similar to when
[displaying user information](/docs/ready-made-features/comments/users-and-mentions#adding-user-information),

You can also add groups to Comments, allowing you to tag a team of people with
one mention. Similar to users, group information is retrieved from a list of
group IDs. You should return the same number of groups as the number of group
IDs, in the same order.

```shell
# If this is `groupIds`
["engineering", "design"]

# Return `groups`
[{ name: "Engineering", avatar: "https://example.com/engineering.png" }, { name: "Design", avatar: "https://example.com/design.png" }]
```

Add a property named
[`resolveGroupsInfo`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveGroupsInfo)
to your
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
where you can return this information.

```tsx
<LiveblocksProvider
  authEndpoint="/api/liveblocks-auth"
  // +++
  resolveGroupsInfo={async ({ groupIds }) => {
    // ["engineering", ...]
    console.log(groupIds);

// Get groups from your back-end
    const groups = await __fetchGroups__(groupIds);

// [{ name: "Engineering", avatar: "https://example.com/engineering.png" }, ...]
    console.log(groups);

// Return a list of groups
    return groups;
  }}
  // +++
>
```

The `name` and `avatar` are handled by the default components, but you can also
return custom metadata here. For example, each group may have a `color`
property. You can retrieve these properties in your app with
[`useGroupInfo`](/docs/api-reference/liveblocks-react#useGroupInfo).

```tsx
function Component() {
  const { group } = useGroupInfo("engineering");

// { color: "blue", name: "Engineering", avatar: "https://example.com/engineering.png" }
  console.log(group);

// ...
}
```

---
meta:
  title: "Multiplayer"
  parentTitle: "Ready-made features"
  description:
    "Add realtime collaboration to any surface in your product—from text editors
    to whiteboards, forms, and beyond."
---

Enable realtime collaboration across any surface in your product—just like in
Figma, Notion, or Linear. With Liveblocks Multiplayer, you can make anything
multiplayer: rich text editors, whiteboards, flowcharts, forms, spreadsheets, or
fully custom interfaces.

Liveblocks provides a permanent, realtime data store for your collaborative
state—so you don’t need to synchronize, scale, or maintain any infrastructure
yourself. All the hard parts of multiplayer—conflict resolution, presence,
history, and storage—are handled for you.

Depending on what you’re building, you can use purpose-built SDKs for rich text
editors (like Tiptap, Lexical, or BlockNote), or more general packages like
`@liveblocks/client`, `@liveblocks/react`, `@liveblocks/zustand`, or
`@liveblocks/redux`.

## Text editor integrations

## Sync engine integrations

## Multiplayer API Reference

### Text editor SDKs

Use these SDKs to add multiplayer editing to rich text editors.

### Sync engine SDKs

Use these SDKs to add multiplayer editing to whiteboards, forms, tables, or any
custom UI. These SDKs integrate directly with
[Liveblocks Storage](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-storage)
and
[Liveblocks Yjs](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-yjs).

## Examples using Multiplayer

---
meta:
  title: "Sync engines"
  parentTitle: "Multiplayer"
  description:
    "Embed a custom collaborative experience into your application using
    Liveblocks Storage and Liveblocks Yjs."
---

Build a custom collaborative experience using Sync Datastore. This can include
anything from whiteboards, flowcharts, spreadsheets, and more. Liveblocks
permanently stores all sync engine data in each
[room](/docs/concepts/how-liveblocks-works#Rooms), handling scaling and
maintenance for you.

## Overview

## Examples using Sync Datastore

---
meta:
  title: "Liveblocks Storage"
  parentTitle: "Sync engine"
  description:
    "Liveblocks Storage is a realtime sync engine designed for multiplayer
    creative tools such as Figma, Pitch, and Spline."
---

Liveblocks Storage is a realtime sync engine designed for multiplayer creative
tools such as Figma, Pitch, and Spline. `LiveList`, `LiveMap`, and `LiveObject`
conflict-free data types can be used to build all sorts of multiplayer tools.
Liveblocks permanently stores Storage data in each
[room](/docs/concepts/how-liveblocks-works#Rooms), handling scaling and
maintenance for you.

Our [interactive React tutorial](/docs/tutorial/react/getting-started/storage) guides you through
using each of the concepts listed on this page.

</Banner>

## Presence

Easily create online presence indicators such as online avatar stacks and live
cursors, with hooks like
[`useOthers`](/docs/api-reference/liveblocks-react#useOthers), which returns an
array of currently connected users in the room, and
[`useSelf`](/docs/api-reference/liveblocks-react#useSelf) which returns your own
data.

```tsx
import { useOthers, useSelf } from "@liveblocks/react/suspense";

function AvatarStack() {
  // +++
  const others = useOthers();
  const self = useSelf();
  // +++

return (
    <div>
      // +++
      {others.map(({ connectionId, info }) => (
        <img key={connectionId} src={info.avatar} />
      ))}
      <img src={self.info.avatar} />
      // +++
    </div>
  );
}
```

User info is set when [authenticating with a secret key](/docs/authentication/).

## Conflict-free data structures

Create realtime document state such as shapes on a canvas, notes on a
whiteboard, or cells in a spreadsheet, with our
[permanent CRDT-like data structures](/docs/api-reference/liveblocks-react#Data-structures).
[`useStorage`](/docs/api-reference/liveblocks-react#useStorage) returns data
structures as simple JSON, and
[`useMutation`](/docs/api-reference/liveblocks-react#useMutation) allows you to
modify the data structures themselves.

```tsx
import { useStorage, useMutation } from "@liveblocks/react/suspense";

function MultiplayerCanvas() {
  // +++
  const shapes = useStorage((root) => root.shapes);
  // +++

// +++
  const handleShapeDrag = useMutation(({ storage }, shapeId, { x, y }) => {
    const shape = storage.get("shapes").get(shapeId);
    shape.update({ x, y });
  }, []);
  // +++

return (
    <div>
      // +++
      {shapes.map((shape) => (
        <DraggableShape key={shape.id} shape={shape} onDrag={handleShapeDrag} />
      ))}
      // +++
    </div>
  );
}
```

Conflict-free data structures use
[`LiveObject`](/docs/api-reference/liveblocks-client#LiveObject),
[`LiveList`](/docs/api-reference/liveblocks-client#LiveList), and
[`LiveMap`](/docs/api-reference/liveblocks-client#LiveMap) under the hood, and
will automatically resolve conflicts when multiple users modify the same data at
the same time. Additionally, they can be
[nested to create complex data structures](/docs/api-reference/liveblocks-react#Nesting-data-structures)
and are
[automatically typed](/docs/api-reference/liveblocks-react#typing-storage)
throughout your app.

### Manage document history

Multiplayer undo and redo is
[notoriously tough to implement](/blog/how-to-build-undo-redo-in-a-multiplayer-environment)
which is why we provide simple hooks like
[`useUndo`](/docs/api-reference/liveblocks-react#useUndo) and
[`useCanUndo`](/docs/api-reference/liveblocks-react#useCanUndo) to handle it for
you.

```tsx
import {
  useStorage,
  useMutation,
  useUndo,
  useCanUndo,
} from "@liveblocks/react/suspense";

function MultiplayerCanvas() {
  // +++
  const undo = useUndo();
  const canUndo = useCanUndo();
  // +++

const shapes = useStorage((root) => root.shapes);

const handleShapeDrag = useMutation(({ storage }, shapeId, { x, y }) => {
    const shape = storage.get("shapes").get(shapeId);
    shape.update({ x, y });
  }, []);

return (
    <div>
      // +++
      {canUndo ?? <button onClick={undo}>Undo</button>}
      // +++
      {shapes.map((shape) => (
        <DraggableShape key={shape.id} shape={shape} onDrag={handleShapeDrag} />
      ))}
    </div>
  );
}
```

We also provide [`useRedo`](/docs/api-reference/liveblocks-react#useRedo) and
[`useCanRedo`](/docs/api-reference/liveblocks-react#useCanRedo) to handle redo.

## Broadcast

Broadcast realtime events to other clients, helpful for triggering live actions
such as playing a video, or for revalidating your database’s data after a
change.
[`useBroadcastEvent`](/docs/api-reference/liveblocks-react#useBroadcastEvent)
sends events, and
[`useEventListener`](/docs/api-reference/liveblocks-react#useEventListener)
listens for them.

```tsx
import {
  useBroadcastEvent,
  useEventListener,
} from "@liveblocks/react/suspense";

function VideoPlayer() {
  const [playing, setPlaying] = useState(false);
  // +++
  const broadcast = useBroadcastEvent();
  // +++

// +++
  useEventListener(({ event }) => {
    if (event.type === "PLAY_VIDEO") {
      setPlaying(true);
    }
  });
  // +++

return (
    <div>
      // +++
      <button onClick={() => broadcast({ type: "PLAY_VIDEO" })}>
        ▶️ Play Video
      </button>
      // +++
      <Video playing={playing} />
    </div>
  );
}
```

## Handle connection status

We’ve designed a number of hooks to help you handle different network
conditions, such as
[`useLostConnectionListener`](/docs/api-reference/liveblocks-react#useLostConnectionListener)
which helps you render UI when user’s have connection loss.

```tsx
import { toast } from "my-preferred-toast-library";
import { useLostConnectionListener } from "@liveblocks/react/suspense";

function App() {
  // +++
  useLostConnectionListener((event) => {
    if (event === "lost") {
      return toast.warn("Trying to reconnect…");
    }

if (event === "restored") {
      return toast.success("Successfully reconnected!");
    }
  });
  // +++

// ...
}
```

### Sync status

[`useSyncStatus`](/docs/api-reference/liveblocks-react#useSyncStatus) is a
related hook which allows you to render the current sync state in your app,
before a change has been saved.

```tsx
import { useSyncStatus } from "@liveblocks/react/suspense";

function StorageStatusBadge() {
  // +++
  const syncStatus = useSyncStatus({ smooth: true });
  // +++

// +++
  return <div>{syncStatus === "synchronized" ? "✅ Saved" : "🔄 Saving"}</div>;
  // +++
}
```

## Other hooks

A number of other hooks are available to help you with different aspects of
multiplayer development, check our API reference for more information.

## Server-side modifications

Storage’s presence and conflict-free data structures can be modified through our
[Node.js package](/docs/api-reference/liveblocks-node) or via
[REST API](/docs/api-reference/rest-api-endpoints).

### Presence [#server-side-modifications-presence]

Presence can be modified with
[`liveblocks.setPresence`](/docs/api-reference/liveblocks-node#set-rooms-roomId-presence),
allowing you set an ephemeral value that will expire after a certain amount of
time.

```ts
await liveblocks.setPresence("my-room-id", {
  userId: "agent-123",
  data: {
    status: "active",
    cursor: { x: 100, y: 200 },
  },
  userInfo: {
    name: "AI Assistant",
    avatar: "https://example.com/avatar.png",
  },
  ttl: 60,
});
```

The same operation can be performed in other languages with the
[Set ephemeral presence REST API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-presence).\

### Conflict-free data structures [#server-side-modifications-conflict-free-data-structures]

Conflict-free data structures can be modified with
[`liveblocks.mutateStorage`](/docs/api-reference/liveblocks-node#mutate-storage),
allowing you to modify the data structures similarly to on the client-side.

```ts
await liveblocks.mutateStorage(
  "my-room-id",

({ root }) => {
    root.get("list").push("item3");
  }
);
```

The same operation can be performed using the
[Apply JSON Patch to Storage REST API](/docs/api-reference/rest-api-endpoints#patch-rooms-roomId-storage-json-patch).
We have a guide on
[Modifying Storage via REST API with JSON Patch](/docs/guides/modifying-storage-via-rest-api-with-json-patch)
that covers this in more detail.

### Broadcast [#server-side-modifications-broadcast]

Broadcast can be performed with
[`liveblocks.broadcastEvent`](/docs/api-reference/liveblocks-node#post-broadcast-event),
allowing you to send events to all connected clients.

```ts
await liveblocks.broadcastEvent("my-room-id", { type: "PLAY_VIDEO" });
```

The same operation can be performed using the
[Broadcast event to a room REST API](/docs/api-reference/rest-api-endpoints#post-broadcast-event).

## API Reference

### Presence

### Broadcast

### Storage

## Examples using Liveblocks Storage

---
meta:
  title: "Liveblocks Yjs"
  parentTitle: "Sync engine"
  description:
    "Liveblocks Yjs is a realtime sync engine designed for collaborative text
    editors such as Notion and Google Docs."
---

Liveblocks Yjs is a realtime sync engine designed for building collaborative
text editors such as Notion and Google Docs. Liveblocks permanently stores Yjs
data in each [room](/docs/concepts/how-liveblocks-works#Rooms), handling scaling
and maintenance for you.

If you’re using Tiptap, BlockNote, or Lexical, we recommend using our
[Text Editor plugins](/docs/ready-made-features/multiplayer-editing/text-editor)
instead. These are alternatives to Yjs, with extra features specifically created
for those editors. Yjs is intended for other editors, or for completely custom
solutions.

</Banner>

## Y.Doc

[`Y.Doc`](https://docs.yjs.dev/api/y.doc) is the core data structure used by
Yjs. It is a JSON-like object that represents the state of a collaborative
document. It is used to store the content of the document, and to synchronize it
between clients. In Liveblocks, get the current room’s `Y.Doc` with
[`getYjsProviderForRoom`](/docs/api-reference/liveblocks-yjs#getYjsProviderForRoom).

```ts
import { useRoom } from "@liveblocks/react";
import { getYjsProviderForRoom } from "@liveblocks/yjs";

function App() {
  const room = useRoom();
  // +++
  const yProvider = getYjsProviderForRoom(room);
  const yDoc = yProvider.getYDoc();
  // +++

// ...
}
```

## Shared types

[Shared types](https://docs.yjs.dev/api/shared-types) in Yjs are CRDT-backed
data structures (like maps, arrays, and text) stored inside a `Y.Doc` that
automatically synchronize and merge changes across multiple clients without
conflicts.

```tsx
import { useRoom } from "@liveblocks/react";
import { getYjsProviderForRoom } from "@liveblocks/yjs";

function App() {
  const room = useRoom();
  const yProvider = getYjsProviderForRoom(room);
  const yDoc = yProvider.getYDoc();

// +++
  const insertText = useCallback(() => {
    const yText = yDoc.getText("editor"); // Y.Text
    yText.insert(0, "Hello collaborative world");
  }, []);
  // +++

// +++
  const changeTheme = useCallback(() => {
    const yMap = yDoc.getMap("settings"); // Y.Map
    yMap.set("theme", "dark");
  }, []);
  // +++

// ...
}
```

## Text and code editor integrations

Liveblocks Yjs integrates with popular text and code editors such as Slate,
Monaco, and CodeMirror. Check our get started guides for more information on
different editors.

<Button asChild>
  <a href="/docs/get-started/multiplayer/text-documents">
    Get started with text editor integrations
  </a>
</Button>

## API Reference

## Examples using Liveblocks Yjs

---
meta:
  title: "Text editor"
  parentTitle: "Multiplayer"
  description:
    "Transform your existing text editor into a collaborative one with realtime
    synchronization using our ready-made integrations."
---

Transform your existing text editor into a collaborative one that feels like
Google Docs or Notion. Our ready-made integrations with Tiptap, Blocknote, and
Lexical handle all the realtime synchronization and storage for you, so you can
focus on building your application.

## Features

Our text editor integrations go beyond multiplayer editing to provide a complete
collaborative experience:

- **Inline comments & annotations**: Let users highlight text and leave
  comments, creating discussion threads right in the document.
- **Mentions and notifications**: Tag team members to notify them about
  important changes or discussions.
- **Version history**: Track changes over time and restore previous versions
  when needed.
- **Multiplayer undo/redo**: Each user has their own undo stack, preventing
  conflicts when multiple people edit simultaneously.
- **AI capabilities** (Tiptap only): Enhance your editor with AI-powered
  features through our built-in AI toolbar.

## Overview

## Examples using text editor integrations

---
meta:
  title: "BlockNote"
  parentTitle: "Text editor"
  description: "Learn about using Multiplayer for BlockNote"
---

A quick overview of the packages for BlockNote.

## Concepts

Liveblocks BlockNote allows you add collaboration to any
[BlockNote](https://blocknotejs.org/) text editor, along with a number of
related features. Each
[collaborative room](/docs/concepts/how-liveblocks-works#Rooms) in your
application can store one document each, and these documents are persisted on
the cloud, visible on [your dashboard](/dashboard), and are integrated into
other Liveblocks products such as [Comments](/docs/ready-made-features/comments)
and [Notifications](/docs/ready-made-features/notifications).

### Permanent storage

All documents created with BlockNote are **permanently stored**. You don’t need
to sync, scale, or maintain any infrastructure.

### Users and mentions

Users and groups can be added to your document, and you can tag others inline.
You can also easily enable mention suggestions for both users and groups.

Users, groups, and mention suggestions can be added with
[`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers),
[`resolveGroupsInfo`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveGroupsInfo),
and
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveMentionSuggestions).

```tsx highlight="6-16"
import { LiveblocksProvider } from "@liveblocks/react/suspense";

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        // Return user info from their `userIds`
        // ...
      }}
      resolveGroupsInfo={async ({ groupIds }) => {
        // Return group info from their `groupIds`
        // ...
      }}
      resolveMentionSuggestions={async ({ text, roomId }) => {
        // Return suggestions from the search `text`
        // Can return user IDs or mention objects for both users and groups
        // ...
      }}
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

### Realtime editing

Your document can be edited in real-time by multiple users at once. Each user
renders a cursor on screen that updates live as they move, select, and edit.

When [authenticating your users](/docs/authentication) with
[`prepareSession`](/docs/api-reference/liveblocks-node#access-tokens) or
[`identifyUser`](/docs/api-reference/liveblocks-node#id-tokens), pass `name` and
`color` properties to their `userInfo` to add their cursor information.

```js
userInfo: {
  name: "Marie",
  color: "#00ff00",
}
```

### Annotations and comments

Add [Comments](/docs/ready-made-features/comments) to your text editor, allowing
others to select words in the editor, and leave annotations. Each annotation
creates a [thread](/docs/ready-made-features/comments/concepts#Threads), and
inside each you can reply, use emoji reactions, mention others, and more.

Add a floating Comments composer to your text editor using
[`FloatingComposer`](/docs/api-reference/liveblocks-react-blocknote#FloatingComposer).

```tsx
<FloatingComposer editor={editor} />
```

Add [`useThreads`](/docs/ready-made-features/comments/hooks#threads-hook)
alongside
[`FloatingThreads`](/docs/api-reference/liveblocks-react-blocknote#FloatingThreads)
and
[`AnchoredThreads`](/docs/api-reference/liveblocks-react-blocknote#AnchoredThreads)
to render your comments to the page.

```tsx
export function Threads({ editor }) {
  const { threads } = useThreads();

return (
    <>
      <AnchoredThreads editor={editor} threads={threads} />
      <FloatingThreads editor={editor} threads={threads} />
    </>
  );
}
```

`FloatingThreads` displays floating threads below text highlights in the editor,
ideal for mobile, whereas `AnchoredThreads` displays threads vertically
alongside the editor which is great on desktop. To create a new thread use the
button in the BlockNote toolbar, or
[build a button yourself](/docs/api-reference/liveblocks-react-blocknote#Opening-the-composer).

### Notifications

Add a [Notifications](/docs/ready-made-features/notifications) UI to your
application, and automatically notify users when they’ve been mentioned.
Notifications also allows you to trigger sending emails, Slack, or any other
kind of notification, using our webhooks.

Notifications is enabled by default, which means you just need to add our UI
components to keep your users notified. Follow our
[get started guides](/docs/get-started/notifications) to learn how to set up
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification).

```tsx
export function CollaborativeApp() {
  const { inboxNotifications } = useInboxNotifications();

return (
    <InboxNotificationList>
      {inboxNotifications.map((inboxNotification) => (
        <InboxNotification
          key={inboxNotification.id}
          inboxNotification={inboxNotification}
        />
      ))}
    </InboxNotificationList>
  );
}
```

Inline mentions also trigger
[`TextMention`](/docs/platform/webhooks#TextMention-notification) notification
webhook events. Learn more about
[sending email notifications](/docs/ready-made-features/notifications/email-notifications).

### Multiple editors

It’s possible to use multiple BlockNote editors on a single page, and each
editor having its own collaboration and extensions. You can enable this by
giving each editor a unique `field` value.

```tsx
import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote";

function TextEditor() {
  const editor = useCreateBlockNoteWithLiveblocks(
    {},
    {
      field: "editor-one",
    }
  );

// ...
}
```

Learn more about
[using multiple editors](/docs/api-reference/liveblocks-react-blocknote#Multiple-editors).

### Offline support

Liveblocks BlockNote has an experimental option that enables offline support.
Offline support means that once a document has been opened, it’s saved locally
on the browser, and can be shown instantly without a loading screen. Enable this
by passing a `offlineSupport_experimental` value.

```tsx
import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote";

function TextEditor() {
  const editor = useCreateBlockNoteWithLiveblocks(
    {},
    {
      offlineSupport_experimental: true,
    }
  );

// ...
}
```

Learn more about
[offline support](/docs/api-reference/liveblocks-react-blocknote#Offline-support).

### Version History

Liveblocks BlockNote enables version history for your document. Versions can be
automatically created when enabled in your project settings, or manually created
using the
[REST API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-version).
These versions can be easily displayed to users using a few simple components.
This allows for a comprehensive version history feature in your collaborative
text editor.

To implement version history in your application, you can use the
`useHistoryVersions` hook along with the `HistoryVersionsList` and
`HistoryVersionPreview` components. Here's an example of how to set this up:

```tsx
import {
  useHistoryVersions,
  HistoryVersionSummaryList,
} from "@liveblocks/react";
import { HistoryVersionPreview } from "@liveblocks/react-blocknote";

function DocumentHistory() {
  const [selectedVersionId, setSelectedVersionId] = useState<string>();
  const { versions, isLoading } = useHistoryVersions();
  const selectedVersion = useMemo(
    () => versions?.find((version) => version.id === selectedVersionId),
    [selectedVersionId, versions]
  );

if (isLoading) {
    return <div>Loading version history...</div>;
  }

return (
    <>
      <div>
        {selectedVersion ? (
          <HistoryVersionPreview
            version={selectedVersion}
            className="h-full w-full"
            onVersionRestore={onVersionRestore}
          />
        ) : (
          <div>No version selected</div>
        )}
      </div>

<div>
        <HistoryVersionSummaryList>
          {versions?.map((version) => (
            <HistoryVersionSummary
              onClick={() => {
                setSelectedVersionId(version.id);
              }}
              key={version.id}
              version={version}
              selected={version.id === selectedVersionId}
            />
          ))}
        </HistoryVersionSummaryList>
      </div>
    </>
  );
}
```

In this example, `useHistoryVersions` fetches the version history,
`HistoryVersionSummaryList` displays a list of available versions, and
`HistoryVersionPreview` shows a preview of the selected version. This setup
provides users with an interface to browse through the document's history and
restore different versions.

## BlockNote API Reference

---
meta:
  title: "Lexical"
  parentTitle: "Text editor"
  description: "Learn about using Multiplayer for Lexical"
---

A quick overview of the packages for Lexical.

## Concepts

Liveblocks Lexical allows you to add collaboration to any
[Lexical](https://lexical.dev/) text editor, along with a number of related
features. Each [collaborative room](/docs/concepts/how-liveblocks-works#Rooms)
in your application can store one document each, and these documents are
persisted on the cloud, visible on [your dashboard](/dashboard), and are
integrated into other Liveblocks products such as
[Comments](/docs/ready-made-features/comments) and
[Notifications](/docs/ready-made-features/notifications).

### Permanent storage

All documents created with Lexical are **permanently stored**. You don’t need to
sync, scale, or maintain any infrastructure.

### Users and mentions

Users and groups can be added to your document, and you can tag others inline.
You can also easily enable mention suggestions for both users and groups.

```tsx highlight="6-16"
import { LiveblocksProvider } from "@liveblocks/react/suspense";

### Realtime editing

Your document can be edited in real-time by multiple users at once. Each user
renders a cursor on screen that updates live as they move, select, and edit.

```js
userInfo: {
  name: "Marie",
  color: "#00ff00",
}
```

### Toolbars

Two toolbars are available allowing you to create a
[static toolbar](/docs/api-reference/liveblocks-react-lexical#Toolbar), or a
[floating toolbar](/docs/api-reference/liveblocks-react-lexical#FloatingToolbar),
as seen below.

Add [`Toolbar`](/docs/api-reference/liveblocks-react-lexical#Toolbar) and
[`FloatingToolbar`](/docs/api-reference/liveblocks-react-lexical#FloatingToolbar)
to enable these features.

```tsx
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    <Toolbar />
  </LiveblocksPlugin>
</LexicalComposer>
```

It’s easy to
[customize a toolbar’s content](/docs/api-reference/liveblocks-react-lexical#toolbar-extending-the-defaults),
piecing together sections like blocks.

```tsx
function CustomToolbar() {
  return (
    <Toolbar>
      // +++
      <Toolbar.BlockSelector />
      <Toolbar.SectionInline />
      <Toolbar.Separator />
      <Toolbar.SectionCollaboration />
      // +++
    </Toolbar>
  );
}
```

You can also easily create
[custom styled buttons](/docs/api-reference/liveblocks-react-lexical#Toolbar.Button),
and
[more](/docs/api-reference/liveblocks-react-lexical#creating-a-custom-toolbar),
with any functionality you like.

```tsx
function CustomButton() {
  return (
    // +++
    <Toolbar.Button
      name="Help"
      icon={<Icon.QuestionMark />}
      shortcut="CMD-H"
      onClick={() => console.log("help")}
    />
    // +++
  );
}
```

### Annotation comments

Add a floating Comments composer to your text editor using
[`FloatingComposer`](/docs/api-reference/liveblocks-react-lexical#FloatingComposer).

```tsx highlight="3"
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    <FloatingComposer />
  </LiveblocksPlugin>
</LexicalComposer>
```

Add [`useThreads`](/docs/ready-made-features/comments/hooks#threads-hook)
alongside
[`FloatingThreads`](/docs/api-reference/liveblocks-react-lexical#FloatingThreads)
and
[`AnchoredThreads`](/docs/api-reference/liveblocks-react-lexical#AnchoredThreads)
to render your comments to the page.

```tsx
export function Threads({ editor }) {
  const { threads } = useThreads();

return (
    <>
      <AnchoredThreads threads={threads} />
      <FloatingThreads threads={threads} />
    </>
  );
}
```

`FloatingThreads` displays floating threads below text highlights in the editor,
ideal for mobile, whereas `AnchoredThreads` displays threads vertically
alongside the editor which is great on desktop. To create a new thread use the
button in a [pre-built toolbar](#Toolbars), or
[build a button yourself](/docs/api-reference/liveblocks-react-lexical#Opening-the-FloatingComposer).

### Notifications

```tsx
export function CollaborativeApp() {
  const { inboxNotifications } = useInboxNotifications();

### AI agents and editing on the server

Fetch and modify your text editor’s content from the server, enabling features
such as AI agents. Easily make changes that update in real-time for every
connected user.

Use
[`withLexicalDocument`](/docs/api-reference/liveblocks-node-lexical#withLexicalDocument)
to get your editor’s content and make modifications live.

```tsx
await withLexicalDocument(
  { roomId: "my-room-id", client: liveblocks },
  async (doc) => {
    // Get editor content
    const textContent = doc.getTextContent();

await doc.update(async () => {
      // Make real-time updates
      // ...
    });
  }
);
```

### Version History

Liveblocks Lexical enables version history for your document. Versions can be
automatically created when enabled in your project settings, or manually created
using the
[REST API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-version).
These versions can be easily displayed to users using a few simple components.
This allows for a comprehensive version history feature in your collaborative
text editor.

```tsx
import {
  useHistoryVersions,
  HistoryVersionSummaryList,
} from "@liveblocks/react";
import { HistoryVersionPreview } from "@liveblocks/react-lexical";

if (isLoading) {
    return <div>Loading version history...</div>;
  }

## Lexical API Reference

---
meta:
  title: "Tiptap"
  parentTitle: "Text editor"
  description: "Learn about using Multiplayer for Tiptap"
---

A quick overview of the packages for Tiptap.

## Concepts

Liveblocks Tiptap allows you to add collaboration to any
[Tiptap](https://tiptap.dev/) text editor, along with a number of related
features. Each [collaborative room](/docs/concepts/how-liveblocks-works#Rooms)
in your application can store one document each, and these documents are
persisted on the cloud, visible on [your dashboard](/dashboard), and are
integrated into other Liveblocks products such as
[Comments](/docs/ready-made-features/comments) and
[Notifications](/docs/ready-made-features/notifications).

### Permanent storage

All documents created with Tiptap are **permanently stored**. You don’t need to
sync, scale, or maintain any infrastructure.

### Users and mentions

Users and groups can be added to your document, and you can tag others inline.
You can also easily enable mention suggestions for both users and groups.

```tsx highlight="6-16"
import { LiveblocksProvider } from "@liveblocks/react/suspense";

### Realtime editing

Your document can be edited in real-time by multiple users at once. Each user
renders a cursor on screen that updates live as they move, select, and edit.

```js
userInfo: {
  name: "Marie",
  color: "#00ff00",
}
```

## Toolbars

Two toolbars are available allowing you to create a
[static toolbar](/docs/api-reference/liveblocks-react-tiptap#Toolbar), or a
[floating toolbar](/docs/api-reference/liveblocks-react-tiptap#FloatingToolbar),
as seen below.

Add [`Toolbar`](/docs/api-reference/liveblocks-react-tiptap#Toolbar) and
[`FloatingToolbar`](/docs/api-reference/liveblocks-react-tiptap#FloatingToolbar)
to enable these features.

```tsx
<Toolbar editor={editor} />
```

It’s easy to
[customize a toolbar’s content](/docs/api-reference/liveblocks-react-tiptap#toolbar-extending-the-defaults),
piecing together sections like blocks.

```tsx
function CustomToolbar({ editor }: { editor: Editor | null }) {
  return (
    <Toolbar editor={editor}>
      // +++
      <Toolbar.BlockSelector />
      <Toolbar.SectionInline />
      <Toolbar.Separator />
      <Toolbar.SectionCollaboration />
      // +++
    </Toolbar>
  );
}
```

You can also easily create
[custom styled buttons](/docs/api-reference/liveblocks-react-tiptap#Toolbar.Button),
and
[more](/docs/api-reference/liveblocks-react-tiptap#creating-a-custom-toolbar),
with any functionality you like.

### AI features

We’re working on AI features for Tiptap, such as a floating AI toolbar. To get
involved, [request access to AI Copilots](/ai-copilots).

### Annotations and comments

Add a floating Comments composer to your text editor using
[`FloatingComposer`](/docs/api-reference/liveblocks-react-tiptap#FloatingComposer).

```tsx
<FloatingComposer editor={editor} />
```

Add [`useThreads`](/docs/ready-made-features/comments/hooks#threads-hook)
alongside
[`FloatingThreads`](/docs/api-reference/liveblocks-react-tiptap#FloatingThreads)
and
[`AnchoredThreads`](/docs/api-reference/liveblocks-react-tiptap#AnchoredThreads)
to render your comments to the page.

```tsx
export function Threads({ editor }) {
  const { threads } = useThreads();

return (
    <>
      <AnchoredThreads editor={editor} threads={threads} />
      <FloatingThreads editor={editor} threads={threads} />
    </>
  );
}
```

`FloatingThreads` displays floating threads below text highlights in the editor,
ideal for mobile, whereas `AnchoredThreads` displays threads vertically
alongside the editor which is great on desktop. To create a new thread use the
button in a [pre-built toolbar](#Toolbars), or
[build a button yourself](/docs/api-reference/liveblocks-react-tiptap#Opening-the-composer).

### Notifications

```tsx
export function CollaborativeApp() {
  const { inboxNotifications } = useInboxNotifications();

## Server-side modifications

Fetch and modify your text editor’s content from the server, enabling features
such as AI agents. Easily make changes that update in real-time for every
connected user. Use
[`withProsemirrorDocument`](/docs/api-reference/liveblocks-node-prosemirror#withProsemirrorDocument)
to get your editor’s content and make modifications live.

```tsx
await withProsemirrorDocument(
  { roomId: "your-room-id", client: liveblocks },
  async (api) => {
    // get editor content
    const text = api.getText();

await api.update((doc, tr) => {
      // Make real-time updates
      // ...
    });
  }
);
```

### Multiple editors

It’s possible to use multiple Tiptap editors on a single page, and each editor
having its own collaboration and extensions. You can enable this by giving each
editor a unique `field` value.

```tsx
import { useLiveblocksExtension } from "@liveblocks/react-tiptap";

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    field: "editor-one",
  });

// ...
}
```

Learn more about
[using multiple editors](/docs/api-reference/liveblocks-react-tiptap#Multiple-editors).

### Offline support

Liveblocks Tiptap has an experimental option that enables offline support.
Offline support means that once a document has been opened, it’s saved locally
on the browser, and can be shown instantly without a loading screen. Enable this
by passing a `offlineSupport_experimental` value.

```tsx
import { useLiveblocksExtension } from "@liveblocks/react-tiptap";

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    offlineSupport_experimental: true,
  });

// ...
}
```

Learn more about
[offline support](/docs/api-reference/liveblocks-react-tiptap#Offline-support).

### Version History

Liveblocks Tiptap enables version history for your document. Versions can be
automatically created when enabled in your project settings, or manually created
using the
[REST API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-version).
These versions can be easily displayed to users using a few simple components.
This allows for a comprehensive version history feature in your collaborative
text editor.

```tsx
import {
  useHistoryVersions,
  HistoryVersionSummaryList,
} from "@liveblocks/react";
import { HistoryVersionPreview } from "@liveblocks/react-tiptap";

if (isLoading) {
    return <div>Loading version history...</div>;
  }

## Tiptap API Reference

---
meta:
  title: "Notifications"
  parentTitle: "Ready-made features"
  description:
    "Embed a customizable notification experience into your product to enable
    people to collaborate."
---

Embed a notification experience into your product, enabling collaboration
between your users. Liveblocks Notifications is fully customizable, allowing you
to create a range of notification experiences that look and feel like your
product. Easily send notifications, create inbox notification trays, and trigger
emails with aggregated notifications. Any custom notification can be sent, but
other parts of Liveblocks, such as
[Comments](/docs/ready-made-features/comments) and
[text editors](/docs/ready-made-features/multiplayer-editing/text-editor), can
also automatically trigger collaboration notifications where appropriate.

## Overview

## Notifications API Reference

## Examples using Notifications

---
meta:
  title: "Concepts"
  parentTitle: "Notifications"
  description: "Learn about Notifications"
---

A quick overview of the concepts used in Liveblocks Notifications.

## Inbox Notifications

In Liveblocks Notifications, everything revolves around _inbox notifications_.
Each user can receive these notifications, and a list of them can be rendered in
your application to create a notification tray. Inbox notifications can be sent
either automatically by other Liveblocks products, or manually by calling a
function on the server.

A user’s inbox notifications can be retrieved by a
[React hook](/docs/api-reference/liveblocks-react#useInboxNotifications) or
[individually on your server](/docs/api-reference/liveblocks-node#get-users-userId-inboxNotifications-inboxNotificationId),
which is helpful after receiving a
[notification webhook event](/docs/platform/webhooks#NotificationEvent). Here’s
an example of an inbox notification object for a custom notification.

```ts
{
  id: "in_sfj29g...",
  kind: "$myCustomNotification",
  subjectId: "myCustomId_dxs9s0",
  readAt: Date <Fri Dec 16 2023 15:16:25 GMT+0000 (Greenwich Mean Time)>,
  notifiedAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
  activities: [
    { myCustomProperty: "myCustomValue" },
  ]
}
```

To build a notification tray, you can use a combination of
[default components](/docs/ready-made-features/notifications/default-components)
and [hooks](/docs/ready-made-features/notifications/hooks).

## Project-based

Inbox notifications are
[project-based](/docs/concepts/how-liveblocks-works#Projects), which means that
a user can receive notifications that were sent from other
[rooms](/docs/concepts/how-liveblocks-works#Rooms). This differs to other
Liveblocks products which are room-based, and rely on users inhabiting the same
space.

Project-based components require only
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
in React, which is different to other room-based Liveblocks products which also
require [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

## Notification kinds

Each inbox notification has a `kind`, and this represents the type of
notification it is. A `kind` is either a custom string prefixed with `$` (e.g.
`$myCustomNotification`) when sending a custom notification, or a predefined
string set by Liveblocks (e.g. `thread`) when it’s sent by a Liveblocks product.

### Custom notifications

A custom notification is a notification that you specify yourself, and can
contain any content.

Custom notifications can be sent using
[`liveblocks.triggerInboxNotification`](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger)
on the server, and the `kind` must always begin with a `$`, for example
`$myCustomNotification`.

When you trigger an inbox notification, you pass the activity data, which
represents the events that happened. If you’d like to update an existing inbox
notification when a new activity happens, you can
[configure the custom notification to use batching](#notification-batching).

### Collaboration notifications

[Comments](/docs/ready-made-features/comments) can send `thread` notifications
for you automatically, notifying you of events such as a mention, or a new reply
in a thread you’re participating in. Additionally,
[text editors](/docs/ready-made-features/multiplayer-editing) can send
`textMention` notifications when users are mentioned inside the editor.

These are enabled by default and the notification `kind` names are `thread` and
`textMention`. Threads and mentions leverage Notifications behind-the-scenes to
keep track of unread comments so viewing a thread will also mark its inbox
notification as read, and vice versa.

If you use the default
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component, it will
automatically handle marking threads as read when they are viewed and show
unread indicators when there are unread comments in threads you are
participating in.

## Notification batching

Batching allows you to group multiple activities into a single notification.
This is useful for reducing the number of notifications that are sent to the
user, and can be enabled on custom notification kinds. It’s always enabled for
Liveblocks `thread` notifications, where new comments in a thread are grouped
into a single notification.

Within the “Notifications” page in the [dashboard](/dashboard), you can add a
custom kind and enable batching. When it’s enabled, triggering an inbox
notification activity for a specific `subjectId`, will update the existing inbox
notification instead of creating a new one.

An inbox notification can have up to 50 activities, if you exceed this number, a
new inbox notification will be created. Liveblocks `textMention` notifications
are never batched.

## Notification channels

You can also send notifications on other channels, such as email or Slack,
letting users know when they’ve missed in-app notifications. Using our dashboard
and hooks you can allow users to set their own notification settings.

There are default channel types for email, Slack, Microsoft Teams, and Web Push.
Each channel works the same, but you can enable different settings for each and
use them differently. Learn more about notification channels in our
[email notifications](/docs/ready-made-features/notifications/email-notifications)
page.

## Data flow

An unread inbox notification will trigger a notification based on the project
notification settings and the user notification settings. Liveblocks evaluates
both the project-level configuration and user preferences to determine whether
to send a channel notification.

## Permissions

### Access tokens

When using [access token authentication](/docs/authentication/access-token),
Liveblocks disregards the permissions specified in the tokens and returns all
notifications created for the user. Consequently, a user will receive
notifications for mentions in comments within rooms they do not have access to.

For greater control over notification permissions, we recommend utilizing
[ID tokens](/docs/authentication/id-token).

### ID token

When using [ID token authentication](/docs/authentication/id-token), Liveblocks
reads the permissions set on the room, and uses these to deliver notifications
that the user is authorized to view.

## Email notifications

It’s possible to send email notifications to your users, listing all their
unread inbox notifications using a [webhook](/docs/platform/webhooks) event that
Liveblocks provides. Learn more about
[email notifications](/docs/ready-made-features/notifications/email-notifications).

---
meta:
  title: "Default components"
  parentTitle: "Notifications"
  description: "Ready-to-use customizable components"
---

The default components included in Notifications are a great way to start
building your application. With these components you can render inbox
notification components.

- Fully styled notification components, with an optional dark mode.
- Customize through CSS variables and class names.
- Receive collaboration notifications automatically triggered by Liveblocks
  [Comments](/docs/ready-made-features/comments) or
  [text editors](/docs/ready-made-features/multiplayer-editing/text-editor).
- Receive fully custom notifications.

## InboxNotification

The [`InboxNotification`][] component renders a single inbox notification.

### Usage

The best way to get started is to import the [`useInboxNotifications`][] hook,
and loop through each of the current user’s notifications.

```tsx highlight="5,10-13"
import { InboxNotification } from "@liveblocks/react-ui";
import { useInboxNotifications } from "../liveblocks.config";

function Component() {
  const { inboxNotifications } = useInboxNotifications();

return (
    <>
      {inboxNotifications.map((inboxNotification) => (
        <InboxNotification
          key={inboxNotification.id}
          inboxNotification={inboxNotification}
        />
      ))}
    </>
  );
}
```

#### Room titles

Room titles displayed in notifications are obtained using the
[`resolveRoomsInfo`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo)
function in
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider).
This allows you to display meaningful document or room names instead of room IDs
in your notifications. Learn more in our guide on
[how to customize room names in inbox notifications](/guides/how-to-customize-room-names-in-inbox-notifications).

#### Rendering different components

As well as displaying the default notification component, you can render
alternate components for different notification `kinds` (the type of
notification). Below we’re rendering a different component for custom
`$fileUploaded` notifications.

```tsx highlight="14-18"
import { InboxNotification } from "@liveblocks/react-ui";
import { useInboxNotifications } from "../liveblocks.config";

function Component() {
  const { inboxNotifications } = useInboxNotifications();

return (
    <>
      {inboxNotifications.map((inboxNotification) => (
        <InboxNotification
          key={inboxNotification.id}
          inboxNotification={inboxNotification}
          kinds={{
            $fileUploaded: (props) => (
              <InboxNotification.Custom {...props} title="New file" aside="📁">
                A new file has been uploaded
              </InboxNotification.Custom>
            ),
          }}
        />
      ))}
    </>
  );
}
```

You can also render any plain JSX you like. Learn more about this under
[rendering notification kinds differently](/docs/api-reference/liveblocks-react-ui#Rendering-notification-kinds-differently).

## InboxNotificationList

The [`InboxNotificationList`][] component renders your inbox notifications as a
list.

### Usage

Wrap your [`InboxNotification`][] components in [`InboxNotificationList`][] to
render your notifications as an ordered HTML list, `ol > li`.

```tsx highlight="8,15"
import { InboxNotification, InboxNotificationList } from "@liveblocks/react-ui";
import { useInboxNotifications } from "../liveblocks.config";

function Component() {
  const { inboxNotifications } = useInboxNotifications();

[`InboxNotification`]: /docs/api-reference/liveblocks-react-ui#InboxNotification
[`InboxNotificationList`]:
  /docs/api-reference/liveblocks-react-ui#InboxNotificationList
[`useInboxNotifications`]:
  /docs/api-reference/liveblocks-react#useInboxNotifications

## Customization

It’s possible to style and localize the default components:

- Import dark mode styles.
- Modify the style with CSS variables and class names.
- Use overrides to change default text used in the components.

Learn more under
[styling and customization](/docs/ready-made-features/notifications/styling-and-customization).

---
meta:
  title: "Email notifications"
  parentTitle: "Notifications"
  description: "Send notifications with webhooks"
---

Using Liveblocks webhooks, it’s possible to trigger your API endpoints when
certain events occur, such as users joining or leaving rooms. One of these
events was created specifically for sending notifications from your back end,
the "`notification"` event. Certain notifications can be enabled or disabled on
different channels for this event, for example you could enable notifications on
`email` and `slack`, but not on `teams`.

## Step-by-step guides

This page is an overview—if you’re looking to send email notifications after
Comments or Text Editor updates, makes sure to read our specific guides:

- [How to send email notifications of unread comments](/docs/guides/how-to-send-email-notifications-of-unread-comments).
- [How to send email notifications for unread text editor mentions](/docs/guides/how-to-send-email-notifications-for-unread-text-editor-mentions).

## Inbox notifications

## Sending email notifications with webhooks

Using [Liveblocks webhooks](/docs/platform/webhooks#Liveblocks-events) you can
listen to a range of events such as user joining rooms, or threads being
created. On [your dashboard](https://liveblocks.io/dashboard) you can create a
webhook for a project, and select which events you’d like to listen to.

### Notification channels

`"notification"` webhooks can be enabled and disabled on certain channels in the
notifications dashboard page. Channels are used to represent different places
your users may receive notifications, such as on `email`, `slack`, `teams`, and
`webPush`.

### Event object

Here’s an example of an event object that’s sent when a user receives a new (or
updated) inbox notification. Note that this is custom notification sent on the
`email` channel.

```ts
const event = {
  type: "notification",
  data: {
    channel: "email",
    kind: "$myCustomNotification",
    projectId: "my-project-id",
    roomId: "my-room-id",
    userId: "my-user-id",
    inboxNotificationId: "in_xt3p7ak...",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

### Your endpoint

In your endpoint, you can use this `event` object with
[`liveblocks.getInboxNotification`](/docs/api-reference/liveblocks-node#get-users-userId-inboxNotifications-inboxNotificationId),
which will return the inbox notification for the event.

```ts
// Data from the `notification` event
const { inboxNotificationId, userId } = event.data;

// Get the inbox notification, which details when the user last read the thread
const inboxNotification = await liveblocks.getInboxNotification({
  inboxNotificationId,
  userId,
});

// { kind: "$myCustomNotification", readAt: Date<2024-07-13T14:32:50.697Z>, ... }
console.log(inboxNotification);
```

Once you have the inbox notification you can then send an email to the `userId`
containing information from the notification.

```ts
const emailAddress = __getUserEmail__(userId);

// Send email to the user that received the inbox notification
__sendEmail__({
  from: "hello@my-company.com",
  to: emailAddress,
  title: "New notification",
  html: `
    <h1>New notification</h1>
    <a href="...">Learn more</a>
  `,
});
```

Here’s an example with every step linked together, along with the code necessary
to verify a webhook request is valid.

```ts title="Full example" isCollapsable isCollapsed
import {
  Liveblocks,
  WebhookHandler,
  stringifyCommentBody,
} from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_SECRET);

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";
const liveblocks = new Liveblocks({ secret: API_SECRET });

export async function POST(request: Request) {
  const body = await request.json();
  const headers = request.headers;

// When a notification webhook event has triggered
  if (event.type === "notification") {
    const { inboxNotificationId, userId } = event.data;

// Get the inbox notification, which details when the user last read the thread
    const inboxNotification = await liveblocks.getInboxNotification({
      inboxNotificationId,
      userId,
    });

// Send email to the user that received the inbox notification
    const emailAddress = __getUserEmail__(userId);
    __sendEmail__({
      from: "hello@my-company.com",
      to: emailAddress,
      title: "New comment",
      html: `
        <h1>New notification</h1>
        <a href="...">Learn more</a>
      `,
    });
  }

return new Response(null, { status: 200 });
}
```

This page is an overview of creating email notifications with Notifications. If
you’d like to send emails about new comments, make sure to read
[how to send email notifications of unread comments](/docs/guides/how-to-send-email-notifications-of-unread-comments).

</Banner>

### Permissions

#### Access token authentication

If you are using access tokens, this will always be true, Liveblocks will never
have the information.

#### ID token authentication

## Notification settings

It’s possible to allow users to choose their own notification settings for each
channel in your application.

To implement this, import
[`useNotificationSettings`](/docs/api-reference/liveblocks-react#useNotificationSettings)
into your component, and create a list of toggles. Here’s an example of a
checkbox that toggles thread notification emails.

```tsx highlight="4,8-17"
import { useNotificationSettings } from "@liveblocks/react/suspense";

function NotificationSettings() {
  const [{ settings }, updateSettings] = useNotificationSettings();

return (
    <>
      <label>
        Receive thread notifications by email:
        <input
          type="checkbox"
          checked={settings.email?.thread}
          onChange={(e) =>
            updateSettings({ email: { thread: e.target.checked } })
          }
        />
      </label>
      {/* Other checkboxes */}
    </>
  );
}
```

## Retrieving and modifying Comments data

Here’s every Notifications-related
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) function. Each also
has a corresponding REST API, you can find more info by following the links.

- [`getInboxNotification`](/docs/api-reference/liveblocks-node#get-users-userId-inboxNotifications-inboxNotificationId)
- [`triggerInboxNotification`](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger)

---
meta:
  title: "Hooks"
  parentTitle: "Notifications"
  description: "Get inbox notifications"
---

The Notifications React hooks can be used to fetch inbox notifications on the
client, and change their behavior.

## List a user’s inbox notifications [#inbox-notifications-hook]

The most important Notifications hook is [`useInboxNotifications`][], which
retrieves every inbox notification for the current user. This can be used to
render a list of notifications, either using the
[default components](/docs/ready-made-features/comments/default-components), or
with your own components. Here’s an example of it used with the default
[`InboxNotification`][] component.

```tsx
import { useInboxNotifications } from "../liveblocks.config";

function Component() {
  const { inboxNotifications } = useInboxNotifications();

// [{ kind: "$myCustomNotification", id: "in_sf8s6sh...", ... }, ...]
  console.log(inboxNotifications);

There are two versions of the [`useInboxNotifications`][] hook, the
[Suspense version](#suspense-hooks), which we recommend by default, and the
[regular version](#regular-hooks).

## Get unread notifications count [#unread-notifications-count-hook]

The
[`useUnreadInboxNotificationsCount`](/docs/api-reference/liveblocks-react#useUnreadInboxNotificationsCount)
hook is useful for creating a badge that displays the unread notifications
count.

```tsx
import { useUnreadInboxNotificationsCount } from "../liveblocks.config";

function Component() {
  const { count } = useUnreadInboxNotificationsCount();

// 3
  console.log(count);

return <div>You have {count} unread notifications</div>;
}
```

## Mark all notifications as read

To mark all notifications as read for the current user, you can add
[`useMarkAllInboxNotificationsAsRead`](/docs/api-reference/liveblocks-react#useMarkAllInboxNotificationsAsRead).

```tsx
function NotificationReadButton() {
  const markAllInboxNotificationsAsRead = useMarkAllInboxNotificationsAsRead();

return (
    <button onClick={markAllInboxNotificationsAsRead}>Mark all as read</button>
  );
}
```

## Fetch a user’s information [#user-hook]

The only information Liveblocks stores about users is their user ID, which is
set when [authenticating with Liveblocks](/docs/authentication). With the
[`useUser`](/docs/api-reference/liveblocks-react#useUser) hook, you can fetch a
user’s information from their ID. This is particularly helpful when building
custom components, as this allows you fetch their name, avatar, and any other
custom data you’ve set.

```tsx
import { useUser } from "../liveblocks.config";

function Component() {
  const { user } = useUser("olivier@example.com");

// { name: "Olivier", avatar: "https://...", color: "red" }
  console.log(user);

return <img src={user.avatar} alt={user.name} />;
}
```

The user data retrieved is set within the
[`resolveUsers`](/docs/api-reference/liveblocks-client#resolveUsers) function in
your `liveblocks.config.ts` file.

```ts
async function resolveUsers({ userIds }) {
  // ["olivier@example.com"]
  console.log(userIds);

return [
    {
      name: "Olivier",
      avatar: "https://example.com/olivier.png",
      color: "red",
    },
  ];
}
```

There are two versions of the
[`useUser`](/docs/api-reference/liveblocks-client#useUser) hook,
[Suspense](#suspense-hooks), which we recommend by default, and
[regular](#regular-hooks).

## Fetch a group’s information [#group-hook]

Similar to users, Liveblocks only stores group IDs for groups. With the
[`useGroupInfo`](/docs/api-reference/liveblocks-react#useGroupInfo) hook, you
can fetch a group’s information from their ID. This is particularly helpful when
building custom components, as this allows you to fetch their name, avatar, and
any other custom data you’ve set.

```tsx
import { useGroupInfo } from "../liveblocks.config";

function Component() {
  const { group } = useGroupInfo("engineering");

// { name: "Engineering", avatar: "https://...", color: "blue" }
  console.log(group);

return <img src={group.avatar} alt={group.name} />;
}
```

The group data retrieved is set within the
[`resolveGroupsInfo`](/docs/api-reference/liveblocks-client#resolveGroupsInfo)
function in your `liveblocks.config.ts` file.

```ts
async function resolveGroupsInfo({ groupIds }) {
  // ["engineering"]
  console.log(groupIds);

return [
    {
      name: "Engineering",
      avatar: "https://example.com/engineering.png",
      color: "blue",
    },
  ];
}
```

There are two versions of the
[`useGroupInfo`](/docs/api-reference/liveblocks-client#useGroupInfo) hook,
[Suspense](#suspense-hooks), which we recommend by default, and
[regular](#regular-hooks).

## Comments hooks

[Comments](/docs/ready-made-features/comments) integrates seamlessly into
Notifications, and a number of hooks are provided to modify this behavior.

### Unread indicator

Threads keep track of unread comments so viewing a thread will also mark its
inbox notification as read, and vice versa. If you use the default
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component, it will
automatically handle marking threads as read when they are viewed and show
unread indicators when there are unread comments in threads you are
participating in.

If you’re building your own custom `Thread` component, you can use
[`useMarkThreadAsRead`](/docs/api-reference/liveblocks-react#useMarkThreadAsRead)
and
[`useThreadSubscription`](/docs/api-reference/liveblocks-react#useThreadSubscription)
to replicate or customize this behavior.

### Thread subscription settings

By default, you’ll receive inbox notifications for threads you are participating
in. This setting can be customized for each user and per room:

- `"all"` to be notified about everything.
- `"replies_and_mentions"` for the default setting.
- `"none"` to mute the room.

You can use
[`useRoomSubscriptionSettings`](/docs/api-reference/liveblocks-react#useRoomSubscriptionSettings)
to build a settings picker in your app and allow users to change their own
subscription settings for the current room, or use
[`updateRoomSubscriptionSettings`](/docs/api-reference/liveblocks-node#post-rooms-roomId-users-userId-subscription-settings)
server-side to control them yourself: for example, to automatically make a
document’s author notified about everything in their document.

### Getting thread data

When using inbox notifications for threads, it can be useful to fetch the actual
thread data, and
[`useInboxNotificationThread`](/docs/api-reference/liveblocks-react#useInboxNotificationThread)
makes this easy.

```tsx
function Notification({ inboxNotification }) {
  const thread = useInboxNotificationThread(inboxNotification.id);

// { type: "thread", id: "th_sf8s6sh...", ... }
  console.log(thread);

// ...
}
```

## Hook types [#hook-types]

There are two different ways to use the
[notifications](#inbox-notifications-hook) and [user](#user-hook) hooks; with
[React Suspense](https://react.dev/reference/react/Suspense), and without it. We
recommend using the Suspense versions, as they often result in simpler code.

### Suspense hooks [#suspense-hooks]

Using Suspense hooks means that any data retrieved, for example
`inboxNotifications` from `useInboxNotifications`, will never be `undefined`,
and your component will never see an error.

```tsx
import { useInboxNotifications } from "@liveblocks/react/suspense";

// Suspense: `inboxNotifications` is always defined
function MyNotifications() {
  const { inboxNotifications } = useInboxNotifications();

// [{ type: "$myCustomNotification", id: "in_sf8s6sh...", ... }, ...]
  console.log(inboxNotifications);
}
```

```tsx highlight="7-11"
import { ClientSideSuspense } from "@liveblocks/react/suspense";
import { ErrorBoundary } from "react-error-boundary";

// Handle errors and loading state in the component above
function Component() {
  return (
    <ErrorBoundary fallback={<div>Error</div>}>
      <ClientSideSuspense fallback={<div>Loading...</div>}>
        <MyNotifications />
      </ClientSideSuspense>
    </ErrorBoundary>
  );
}
```

To use Suspense, make sure you’re exporting your hooks from
`@liveblocks/react/suspense`.

```tsx
// Suspense version of hooks
import { useInboxNotifications, useUser } from "@liveblocks/react/suspense";
//                                                                ^^^^^^^^
```

### Regular hooks [#regular-hooks]

The regular versions of Liveblocks hooks require you to check for `error` and
`isLoading` properties. You can then handle these states in the same component.

```tsx
import { useInboxNotifications } from "@liveblocks/react";

// Handle errors and loading state in the same component
function MyNotifications() {
  const { inboxNotifications, error, isLoading } = useInboxNotifications();

if (error) {
    return <div>Error</div>;
  }

if (isLoading) {
    return <div>Loading...</div>;
  }

// Non-Suspense: `inboxNotifications` is only defined AFTER the `if` checks
  // [{ type: "$myCustomNotification", id: "in_sf8s6sh...", ... }, ...]
  console.log(inboxNotifications);
}
```

To use the regular hooks, make sure you’re exporting from `@liveblocks/react`.

```tsx
// Regular version of hooks
import { useInboxNotifications, useUser } from "@liveblocks/react";
//                                              ^^^^^^^^^^^^^^^^^
```

---
meta:
  title: "Styling and customization"
  parentTitle: "Notifications"
  description: "CSS variables, dark mode, and more"
---

Styling Notifications
[default components](/docs/ready-made-features/notifications/default-components)
is enabled through a range of means, such as CSS variables, class names, and
more.

## Default components

To add the default components’ theme, import the
[default styles](/docs/api-reference/liveblocks-react-ui#Default-styles) CSS
file.

```ts
import "@liveblocks/react-ui/styles.css";
```

You can also import one of two CSS files to enable
[dark mode](/docs/api-reference/liveblocks-react-ui#Dark-mode), depending on how
you’d like to enable it.

```ts
// Dark mode using the system theme with `prefers-color-scheme`
import "@liveblocks/react-ui/styles/dark/media-query.css";
```

```ts
// Dark mode using `className="dark"`, `data-theme="dark"`, or `data-dark="true"`
import "@liveblocks/react-ui/styles/dark/attributes.css";
```

### CSS variables

```css
/* Styles all default components */
.lb-root {
  --lb-accent: purple;
  --lb-spacing: 1em;
  --lb-radius: 0;
}
```

### Class names

Should you need deeper customization,
[class names](/docs/api-reference/liveblocks-react-ui#Class-names) can be
styled, some of which provide contextual data attributes.

```css
.lb-notification {
  /* Customize notification */
}

.lb-avatar[data-loading] {
  /* Customize avatar loading state */
}
```

---
meta:
  title: "Agent skills"
  parentTitle: "Tools"
  description:
    "Use Liveblocks agent skills to help develop your Liveblocks and Yjs apps
    more easily."
---

Create your Liveblocks applications more easily with our agent skills, designed
to help AI coding assistants follow best practices for Liveblocks and Yjs. These
skills use the [Agent Skills](https://agentskills.io/home) format.

## Install

Install with the following command:

```bash
npx skills add liveblocks/skills
```

## Skills

### liveblocks-best-practices

Best practices for using Liveblocks. Contains 40+ comprehensive references
related to each feature of Liveblocks. Use it when building, debugging, or
answering questions about Liveblocks.

### yjs-best-practices

Best practices for using Yjs. Contains info on fixing common issues, structuring
your data efficiently, and avoiding bugs. Use it when building, debugging, or
answering questions about Yjs.

## Usage

After installation, skills are automatically available in your AI tool. Your
agent will use them when it judges they are relevant. For example, the following
questions will trigger skills:

```
How do I handle unstable Wi-Fi connections with Liveblocks?
```

```
How do I pass custom headers to my auth endpoint?
```

```
Why is my Y.Map growing so large?
```

## Source code

The source code is available in our
[GitHub repository](https://github.com/liveblocks/skills).

---
meta:
  title: "Dev server"
  parentTitle: "Tools"
  description:
    "Run a local Liveblocks dev server for multiplayer development and testing
    without hitting production."
---

The Liveblocks dev server is a local server that lets you develop and test
multiplayer features without connecting to Liveblocks production servers. It is
built on our open-source
[`@liveblocks/server`](https://github.com/liveblocks/liveblocks/tree/main/packages/liveblocks-server)
package internally.

## Features

The dev server fully supports all
[Multiplayer](/docs/ready-made-features/multiplayer) features, and partially
supports other APIs. [Learn more](#Partially-supported-features).

| Feature                                                                                                                            | Support |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------- |
| [Liveblocks Storage](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-storage) (LiveObject, Presence, Broadcast, etc.) | ✅      |
| [Liveblocks Yjs](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-yjs)                                                 | ✅      |
| [Text editors](/docs/ready-made-features/multiplayer/text-editor) (Tiptap, BlockNote, Lexical)                                     | ✅ ¹    |
| [Public key authentication](/docs/api-reference/liveblocks-react#LiveblocksProviderPublicKey)                                      | ✅      |
| [Access token authentication](/docs/authentication/access-token)                                                                   | ✅      |
| [ID token authentication](/docs/authentication)                                                                                    | ✅      |
| [Room Node.js methods](/docs/api-reference/liveblocks-node#Room)                                                                   | ✅      |
| [Room REST APIs](/docs/api-reference/rest-api-endpoints#Room)                                                                      | ✅      |
| [Comments](/docs/ready-made-features/comments)                                                                                     | ❌ ²    |
| [Notifications](/docs/ready-made-features/notifications)                                                                           | ❌ ²    |
| [AI Agents](/docs/ready-made-features/ai-agents)                                                                                   | ❌      |
| Other APIs                                                                                                                         | ❌      |

¹ <small>_Excluding features related to Comments and Notifications._</small>  
² <small>_Basic APIs will return dummy data, so you can still use the Liveblocks
dev server to test other features in your app._</small>

## Set up the dev server

The development server currently only supports connecting with
[public key](/docs/api-reference/liveblocks-client#createClientPublicKey) or
[access token](/docs/authentication/access-token) authentication. ID token
authentication will be supported in future.

<Steps>

<Step>
    <StepTitle>Install Bun</StepTitle>
    <StepContent>

The Liveblocks dev server requires [Bun](https://bun.sh/) to be installed.

```bash
      npm install -g bun
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Run the dev server</StepTitle>
    <StepContent>

Start the dev server from your project directory—it runs on [`http://localhost:1153`](http://localhost:1153).

```bash
      npx liveblocks dev
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Connect to the dev server</StepTitle>
    <StepContent>
      Point your client and auth endpoint to the dev server, and update your API
      keys. You must use `"sk_localdev"` instead of your secret key and 
      `"pk_localdev"` instead of your public key. 
      
      The easiest way to do this is to run the dev server and press `p`. It copies
      a prompt you can paste into your AI code editor, which will intelligently 
      make the changes for you.

If you don’t use the prompt, you can manually add `baseUrl` and change
      your API key:

```tsx
      import { LiveblocksProvider } from "@liveblocks/react";

function App() {
        return (
          <LiveblocksProvider
            // +++
            baseUrl="http://localhost:1153"
            // +++
            authEndpoint="/api/liveblocks-auth"
          >
            {/* Your app */}
          </LiveblocksProvider>
        );
      }
      ```

```ts
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        // +++
        baseUrl: "http://localhost:1153",
        secret: "sk_localdev",
        // +++
      });
      ```

```tsx isCollapsable isCollapsed title="Alternate snippet for public key"
      // Only edit this file for public key
      import { LiveblocksProvider } from "@liveblocks/react";

function App() {
        return (
          <LiveblocksProvider
            // +++
            baseUrl="http://localhost:1153"
            publicApiKey="pk_localdev"
            // +++
          >
            {/* Your app */}
          </LiveblocksProvider>
        );
      }
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Complete</StepTitle>
    <StepContent>

You're all set up, open your app and start building collaborative features
      using the local dev server, or [set up CI testing](/docs/guides/how-to-set-up-continuous-integration-ci-testing)
      with your application.

</StepContent>

</Step>
</Steps>

## Partially supported features

A number of unsupported features are partially implemented so you can run your
app without seeing errors. For example, `useThreads` is not supported yet, but
it will always return an empty array so you can still view your application.

```tsx title="React"
// ✅ Fully supported
const others = useOthers();
const shapes = useStorage((root) => root.shapes);

// ⚠️ Returns dummy data such as empty arrays
const { threads } = useThreads();
const { inboxNotifications } = useInboxNotifications();

// ⚠️ Nothing happens when calling unsupported functions
const createNewThread = useCreateThread();
createNewThread({ body: {}, attachments: [] });
```

```ts title="Node.js"
// ✅ Fully supported
const storage = await liveblocks.getStorageDocument("my-room-id");
await liveblocks.broadcastEvent("my-room-id", { type: "REFRESH" });

// ⚠️ Room APIs are supported but permissions and metadata are ignored
await liveblocks.createRoom("my-new-room-id", {
  defaultAccesses: ["room:write"],
  metadata: { title: "My title" },
});
// { metadata: {}, defaultAccesses: [], ... }
await liveblocks.getRoom("my-new-room-id");

// ⚠️ Returns dummy data such as empty arrays
const { data: threads } = await liveblocks.getThreads({
  roomId: "my-room-id",
});

// ⚠️ Nothing happens when calling unsupported functions
await liveblocks.createThread({
  roomId: "my-room-id",
  body: {},
});
```

In future, we plan to support more features in the dev server.

## REST API

The REST API supports the same set of features as the Node.js package. To use
it, point your requests to the dev server URL and use `sk_localdev` as the
secret key.

```bash
curl http://localhost:1153/v2/* \
  -H 'Authorization: Bearer sk_localdev'
```

## Quick local testing

When your unit tests need the Liveblocks dev server to be running, you can use
`--cmd "vitest run"` (or whichever test command you use) to run your tests in a
temporary, ephemeral, dev server instance.

This mode will:

1. Start a fresh, empty, dev server instance.
2. Run your unit tests.
3. Stop the dev server.

Example output:

```bash
npx liveblocks dev --cmd 'vitest run'
Starting the Liveblocks dev server...

Liveblocks dev server running at http://localhost:1153
Server logs: /tmp/liveblocks-dev-XXXXXX/server.log

✓ src/__tests__/your-unit-test.test.ts (28 tests) 40ms

Test Files  1 passed (1)
      Tests  28 passed (28)
   Start at  11:24:51
   Duration  0.5s

Liveblocks dev server shut down
```

You can also pass extra arguments after the command. They will be appended to
the end of the command string:

```bash
npx liveblocks dev --cmd 'vitest run' my-test.test.ts
# Runs: vitest run my-test.test.ts
```

If you need precise control over where the extra arguments are inserted, use
`{}` as a placeholder:

```bash
npx liveblocks dev --cmd 'vitest run {} --reporter=verbose' my-test.test.ts
# Runs: vitest run my-test.test.ts --reporter=verbose
```

Use `--` before any extra arguments that start with `-`:

```bash
npx liveblocks dev --cmd 'vitest run' -- --coverage my-test.test.ts
# Runs: vitest run --coverage my-test.test.ts
```

We recommend:

1. `npx liveblocks dev` for manual testing and development, which retains data
   between runs in the `.liveblocks/` folder.
2. `npx liveblocks dev --cmd "vitest run"` for locally running your unit tests
   against a fresh instance (your local data in `.liveblocks/` won't be affected
   by your unit tests).

## Continuous Integration (CI) testing

You can use the dev server in CI environments by setting up a test environment
file and running the dev server as a service container. Learn how do this in our
step-by-step guide.

<Button asChild>
  <a href="/docs/guides/how-to-set-up-continuous-integration-ci-testing">
    How to set up Continuous Integration (CI) testing
  </a>
</Button>

## End-to-End (E2E) testing

You can use the dev server to run end-to-end tests with tools such as
Playwright. Learn how to do this in our step-by-step guide.

<Button asChild>
  <a href="/docs/guides/how-to-set-up-end-to-end-e2e-testing-with-playwright">
    How to set up End-to-End (E2E) testing with Playwright
  </a>
</Button>

## Docker

You can run the dev server as a Docker container, which is useful for CI
environments where you may not have Bun installed.

```bash
docker run -p 1153:1153 ghcr.io/liveblocks/cli dev
```

To persist data between container restarts, mount a volume:

```bash
docker run -p 1153:1153 -v liveblocks-data:/app/.liveblocks ghcr.io/liveblocks/cli dev
```

## Source code

The source code is available in our
[GitHub repository](https://github.com/liveblocks/liveblocks/tree/main/tools/liveblocks-cli).

## Examples

The following examples fully support the dev server.

</ListGrid>

---
meta:
  title: "DevTools"
  parentTitle: "Tools"
  description:
    "Learn how to leverage Liveblocks DevTools to inspect and troubleshoot your
    collaborative application."
---

Our [DevTools](/devtools) is a browser-based extension that integrates with
Liveblocks and your local development environment. This allows you to easily
inspect, visualize, and troubleshoot your collaborative online experiences.

Our DevTools is currently only available if you are on Liveblocks 1.0 or later.
To view step-by-step instructions on how to upgrade your project to Liveblocks
1.0, check out our [upgrade guides](/docs/platform/upgrading/).

If you want to see how this works in action, check out this
[live demo](https://www.youtube.com/watch?v=-6Jxejp0iuw) recorded by
[Vincent](https://twitter.com/nvie) on YouTube.

</Banner>

## Install the browser extension

Our DevTools extension is available for all major web browsers:

- [Chrome](https://chrome.google.com/webstore/detail/liveblocks-devtools/iiagocfmmhknpdalddkbiejnfmbmlffk)
- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/liveblocks-devtools/)
- [Edge](https://microsoftedge.microsoft.com/addons/detail/liveblocks-devtools/hfecmmnilleegmjaegkjjklnjbgadikg)

Within the “Liveblocks” panel, you will see two panes: storage and presence. The
storage pane represents each object that you have defined in storage as a tree,
likewise, the presence pane represents each user that is connected to your
Liveblocks project.

## Trying our DevTools

### With our Starter Kit

The [Liveblocks Starter Kit](/starter-kit) is a great way to get started with
Liveblocks and learn how to use our DevTools.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/devtools/liveblocks-devtools-starter-kit.mp4"
      type="video/mp4"
    />
  </video>
</Figure>
To use the Starter Kit with DevTools, run the following command:

```bash
npx create-liveblocks-app@latest --next
```

You can then follow the guided prompts in the terminal to create your project.
For additional information on how to use the Starter Kit, see the
[Starter Kit guide](/docs/tools/nextjs-starter-kit).

Once you have completed the Starter Kit prompts and installed the extension, run
the Starter Kit with `npm run dev` and open your browser to `localhost:3000`.
You should authenticate, and then create a new draft document. Once you have
created a new document, open up the developer tools window. Find the newly
available “Liveblocks” panel there.

### With an example from our gallery

All of [our examples](/examples) hosted on Liveblocks.io are available for you
to run locally from the
[examples directory](https://github.com/liveblocks/liveblocks/tree/main/examples)
in the Liveblocks repo. For testing and reviewing how to use our DevTools, we
will use the
[Advanced Collaborative Spreadsheet](https://liveblocks.io/examples/collaborative-spreadsheet-advanced/nextjs).

To download this example, run the following command, and follow the guided
prompts to create your project:

```bash
npx create-liveblocks-app@latest --example nextjs-spreadsheet-advanced
```

Once you have completed the prompts and installed the extension, run the example
with `npm run dev` and open your browser to `localhost:3000`.

Open your browser and open up the developer tools window. Find the newly
available “Liveblocks” panel there, and you should see the values from the
spreadsheet examples populating storage.

## Features and tips

### Highlighting

When a value in storage changes, the DevTools will highlight the value to
indicate that it has changed.

### Search

Storage values are searchable by key and regex.

### Hover

Hovering over a value in storage or presence makes an eye icon appear. If
clicked, it displays the value of that key.

### Expand and collapse

- You can expand and collapse objects with one level of depth by using the arrow
  keys or spacebar
- You can quickly expand and collapse nested objects within storage by holding
  the alt/option key and clicking on the object

If you open the DevTools after a Liveblocks client has already been initialized,
you may see an empty page. This is because our DevTools is only able to retrieve
the current state of storage and presence. To fix this, you can refresh the page
or open the DevTools before initializing the Liveblocks client.

</Banner>

---
meta:
  title: "MCP server"
  parentTitle: "Tools"
  description:
    "Learn to use the official MCP server for Liveblocks, helpful for inspecting
    and modifying your project with AI in Cursor, VS Code, Claude Desktop, and
    more."
---

The Liveblocks MCP server allows you to inspect and modify your project with AI
in compatible apps such as Cursor, VS Code, Claude Desktop, and more.

## Features

Our MCP server features 39 different tools, enabling most features from our
[REST API](/docs/api-reference/rest-api-endpoints). You can use it to:

- Create and modify rooms, threads, comments, notifications, more.
- Read realtime Storage and Yjs values.
- Broadcast custom events to connected clients.
- Mark threads and notifications as read/unread.

AI will often string tool calls together—for example, if you ask it to fetch a
room that doesn’t exist, it will ask if you’d like to create the room first, and
then fetch it after.

## Automatic setup

To install automatically, use one of the following commands, making sure to
insert a secret key from your correct project in [your dashboard](/dashboard).

Don’t insert a secret key from your product application, as AI will have direct
access to modify it.

</Banner>

### Cursor

Run the following command to set up [Cursor](https://cursor.sh/):

```bash
npx -y @smithery/cli install @liveblocks/liveblocks-mcp-server --client cursor --key "{{SECRET_KEY}}"
```

### Claude

Run the following command to set up
[Claude Desktop](https://claude.ai/download):

```bash
npx -y @smithery/cli install @liveblocks/liveblocks-mcp-server --client claude --key "{{SECRET_KEY}}"
```

### VS Code

Run the following command to set up [VS Code](https://code.visualstudio.com/):

```bash
npx -y @smithery/cli install @liveblocks/liveblocks-mcp-server --client vscode --key "{{SECRET_KEY}}"
```

### Other clients

Find installation information for other clients on
[Smithery](https://smithery.ai/server/@liveblocks/liveblocks-mcp-server).

## Manual setup

1. Clone the
   [Liveblocks MCP server](https://github.com/liveblocks/liveblocks-mcp-server)
   repo.

```bash
git clone https://github.com/liveblocks/liveblocks-mcp-server.git
```

2. Build the project.

```bash
npm install
npm run build
```

### Cursor

3. Go to File → Cursor Settings → MCP → Add new server.

4. Add the following, with the full path to the repo and the correct secret key
   from [your dashboard](/dashboard):

```json
{
  "mcpServers": {
    "liveblocks-mcp-server": {
      "command": "node",
      "args": ["/full/path/to/the/repo/liveblocks-mcp-server/build/index.js"],
      "env": {
        "LIVEBLOCKS_SECRET_KEY": "{{SECRET_KEY}}"
      }
    }
  }
}
```

5. Check it's enabled in the MCP menu.

### Claude Desktop

3. Go to File → Settings → Developer → Edit Config.

4. Open the JSON file, `claude_desktop_config.json`.

5. Add the following, with the full path to the repo and the correct secret key
   from [your dashboard](/dashboard):

## Source code

The source code is available in our
[GitHub repository](https://github.com/liveblocks/liveblocks-mcp-server).

---
meta:
  title: "Next.js Starter Kit"
  parentTitle: "Tools"
  description:
    "Kickstart your collaborative SaaS product with the Liveblocks Next.js
    Starter Kit."
---

The Next.js Starter Kit is an open-source template that showcases all aspects of
Liveblocks in a single, modern application.

If you’d like to see how this works, make sure to
[check out this live demo video](https://www.youtube.com/watch?v=Lf7HQ4Z_Ovc) on
YouTube, or [try the project online](https://nextjs-starter-kit.liveblocks.app).

</Banner>

## Features

The Next.js Starter Kit includes the following

- Documents dashboard with pagination, organizations, auto-revalidation.
- Collaborative apps including a whiteboard, text documents, note editor,
  drawing canvas.
- Realtime presence with avatars, cursors, carets.
- Fully-featured share menu with users, organizations, public permissions.
- Authentication compatible with GitHub, Google, Auth0, and more.

## Set up the Next.js Starter Kit

### create-liveblocks-app

You can get started by running the following command:

```bash
npx create-liveblocks-app@latest --next
```

This will run an installer that allows you to download, configure, and deploy,
your project:

Give your project a name, and select the [authentication](#authentication)
method you’d like to use in your app. If you are trying to generate a proof of
concept quickly, opting to use demo authentication may be a great option—you can
still add other authentication providers later on.

#### Deploy with Vercel Integration

If you would like to set up CI/CD with your application, we’ve made that process
straightforward for you as well. When prompted, you can select "deploy to
Vercel" to enable building and deploying the starter kit. The Vercel Integration
will open in a new browser window for you to complete the process of adding your
repository.

If by clicking "Create" you receive "An unexpected internal error occurred" you
should validate within your code hosting platform of choice (GitHub, GitLab,
Bitbucket) that the Vercel integration has permission to access your repository.
In GitHub, permissions can be found can be found under Settings > Integrations >
Vercel.

#### Connect to Liveblocks and retrieve your secret key

If you prefer to work locally, you can tell the installer you would not like to
"deploy to Vercel". After declining the deployment option, the installer will
prompt adding your Liveblocks Key to the application automatically. If you
forwent deployment or indicated that you would like to get your Liveblocks
secret key automatically, the Liveblocks integration page will open in a new
browser tab. Once the integration page appears, you can sign up/sign in to
Liveblocks, create a new project, and import your API key into the installer.

After finishing up, check the installer and follow the commands recommended to
get you started.

### Authentication [#authentication]

The Liveblocks starter kit uses [NextAuth.js](https://next-auth.js.org/) for
authentication, meaning many authentication providers can be configured with
minimal code changes. A demo authentication system is used by default, but it’s
easy to add real providers, such as GitHub, Auth0, and more.

Take a look at the guide for your chosen authentication method:

- [GitHub authentication](#github-authentication)
- [Auth0 authentication](#auth0-authentication)
- [Demo authentication](#demo-authentication)

### GitHub authentication [#github-authentication]

To use GitHub auth, make sure you selected "GitHub authentication" when running
the installer (or you’ve set up the
[provider manually](#add-multiple-authentication-providers)). This is how to set
up your GitHub secret key and client id.

1. Go to [Developer Settings](https://github.com/settings/apps) on GitHub and
   click "New GitHub App".
2. Enter an app name (e.g. `Liveblocks Starter Kit (dev)`). You’ll need a new
   app for each environment, so it’s helpful to place "dev" in the name.
3. Add a homepage URL—this isn’t important now, so a placeholder will do.
4. Find the "Callback URL" input just below, and add your local development URL
   (e.g. `http://localhost:3000`).
5. Look for the "Webhook" section and make sure to uncheck "Active".
6. Use the remaining default settings and press "Create GitHub App".

7. On the next page under "Client secrets", press the "Generate a new client
   secret" button (note that this is different to generating a private key!).
8. Copy this secret into the `/.env.local` file as `GITHUB_CLIENT_SECRET`
9. Go back to the previous page and find the "Client ID" near the top. Copy this
   into your `.env.local` file as `GITHUB_CLIENT_ID`

Almost there! `.env.local` should now contain lines similar to this:

```env file=".env.local"
GITHUB_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
GITHUB_CLIENT_ID=XXXXXXXXXXXXXXXXXXXX
```

GitHub authentication is now complete! Next,
[add yourself as a user](#how-to-sign-up) to test out your authentication.

### Auth0 authentication [#auth0-authentication]

To use Auth0 auth, make sure you selected "Auth0 authentication" when running
the installer (or you’ve set up the
[provider manually](#add-multiple-authentication-providers)). This is how to set
up your Auth0 secret key and client information.

1. Go to your [Auth0 Dashboard](https://manage.auth0.com/dashboard) and click
   "Create Application".
2. Enter an app name (e.g. `Liveblocks Starter Kit (dev)`). You’ll need a new
   app for each environment, so it’s helpful to place "dev" in the name.
3. Select "Single Page Web Applications", and press "Create".
4. Copy your "Client ID" from the top of the page, and place it within
   `.env.local` as `AUTH0_CLIENT_ID`.
5. Click the "Settings" tab— we’ll be making a number of changes here.
6. Find the "Client Secret" input field, and copy the value into `.env.local` as
   `AUTH0_CLIENT_SECRET`.
7. Copy your "Domain" from the input field, add "https://" to the start, and
   place it within `.env.local` as `AUTH0_ISSUER_BASE_URL`.
8. Add the following to the "Allowed Callback URLs" textarea:
   `http://localhost:3000/api/auth/callback/auth0`.
9. Add the following to the "Allowed Logout URLs" textarea:
   `http://localhost:3000`.
10. Scroll to the bottom and press "Save changes".

`.env.local` should now contain these three lines, along with anything
previously there:

```env file=".env.local"
AUTH0_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AUTH0_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AUTH0_ISSUER_BASE_URL=https://XXXXXXXXXXXXXXXXXX.com
```

Auth0 authentication is now set up! Next, [add yourself a user](#how-to-sign-up)
to test out your authentication.

### Demo authentication [#demo-authentication]

For quickly testing out your app, the demo authentication method can be used.
This method uses a NextAuth
[`CredentialsProvider`](https://next-auth.js.org/providers/credentials) to
simulate a real sign in system. To replace it with your own authentication
method, you can add any other NextAuth
[`Provider`](https://next-auth.js.org/providers/) to
[`/auth.config.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/auth.config.ts).

Read the [next section](#how-to-sign-up) to learn how to add a new user to your
demo application.

### How to sign up - add yourself as a user [#how-to-sign-up]

We haven’t set up a database, so we’re temporarily using the
[`/data`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/data)
folder instead. Before any user can sign in, they need to be added to
[`/data/users.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/data/users.ts).
Navigate there and add your details, for example, if you’re signing in with
`yourname@example.com`:

```ts file="data/users.ts"
{
  id: "your.name@example.com",
  name: "Your Name",
  avatar: "https://liveblocks.io/avatars/avatar-0.png",
  organizationIds: ["liveblocks", "your.name@example.com"],
},
```

Note that this is replacing the sign-up process, so you must enter the email of
any new user. If, for example, you’re using GitHub authentication, you can enter
the email address of any valid GitHub account.

### Ready to go

The Next.js Starter Kit is now ready to use! After setting up authentication,
make sure to restart the dev server to see your authentication in action.

```bash
npm run dev
```

## Assorted info

### Structure

The
[starter kit](https://github.com/liveblocks/liveblocks/tree/main/starter-kits/nextjs-starter-kit)
has the following structure:

```
app
components
data
icons
layouts
lib
 └─ actions
 └─ database
 └─ hooks
 └─ utils
primitives
styles
types
utils
auth.ts
auth.config.ts
constants.ts
liveblocks.config.ts
liveblocks.server.config.ts
package.json
```

The important thing to note is that there are primitives, which are base level
components such as buttons (think of these as the small building blocks of a
page), components, which you can think of as multiplayer implementations
(cursors, badges, etc), app, which renders document level experiences and a
library (lib) of both server side and client side methods which contain the
logic to create and modify documents.

<br />
<details>
  <summary>More info about the structure</summary>
  <br />
  <dl>
    <dt>`/app/`</dt>
    <dd>Next.js app folder.</dd>
    <dt>`/components/`</dt>
    <dd>Components used in the app.</dd>
    <dt>`/data/`</dt>
    <dd>A demo database.</dd>
    <dt>`/icons/`</dt>
    <dd>Every icon component.</dd>
    <dt>`/layouts/`</dt>
    <dd>Page layout components.</dd>
    <dt>`/lib/actions/`</dt>
    <dd>
      Server actions that can be used on both client and server, used for
      accessing and modifying documents.
    </dd>
    <dt>`/lib/database/`</dt>
    <dd>Server functions used for getting database information.</dd>
    <dt>`/lib/hooks/`</dt>
    <dd>A set of React hooks that are used on the client.</dd>
    <dt>`/lib/utils/`</dt>
    <dd>Assorted document-related utilities.</dd>
    <dt>`/primitives/`</dt>
    <dd>Generic reusable components.</dd>
    <dt>`/types/`</dt>
    <dd>All reusable TypeScript types.</dd>
    <dt>`/auth.ts`</dt>
    <dd>File that links NextAuth to your database.</dd>
    <dt>`/auth.config.ts`</dt>
    <dt>File where NextAuth providers are set up.</dt>
    <dt>`/constants.ts`</dt>
    <dd>Constant strings used in the app, such as URLs and global IDs.</dd>
    <dt>`/liveblocks.config.ts`</dt>
    <dd>Liveblocks config file.</dd>
    <dt>`/liveblocks.server.config.ts`</dt>
    <dd>Server-side Liveblocks config file.</dd>
  </dl>
</details>

### Async fetching and error handling

This starter kit makes extensive use of the following programming pattern for
fetching async resources:

```ts
const { data, error } = await getDocument({
  /* ... */
});

// An error has occured
if (error) {
  // { code: 400, message: "Document not found", suggestion: "Please check the URL is..." }
  console.log(error);
  return;
}

// Success, but result is empty
if (!data) {
  return;
}

// Success
// { name: "my-document", id: "hIas7GuihgHF8Fhv8Sskg",  ... }
console.log(data);
```

### Document functions

Much of the starter kit’s power is in the
[`/lib/actions`](https://github.com/liveblocks/liveblocks/tree/main/starter-kits/nextjs-starter-kit/lib/actions)
directory. The functions in these files allow you to edit your documents easily
and return type-safe objects. For example in an API endpoint:

```ts
import { createDocument } from "@/lib/actions";

export async function POST() {
  // Create a new document
  const { data, error } = await createDocument({
    name: "My document",
    type: "whiteboard",
    userId: "charlie.layne@example.com",
  });

// ...
}
```

Because these functions are server actions, they can be leveraged on both client
and server.

```tsx
import { createDocument } from "@/lib/actions";

export function CreateDocumentButton() {
  async function handleCreateDocument() {
    // Create a new document
    const { data, error } = await createDocument({
      name: "My document",
      type: "whiteboard",
      userId: "charlie.layne@example.com",
    });
  }

return <button onClick={handleCreateDocument}>New document</button>;
}
```

Functions that return data can be used with [SWR hooks](https://swr.vercel.app/)
that automatically update your data in components. For example,
`getDocumentUsers` returns a list of users with access to the room:

```tsx
// Convert from this
const { data, error } = await getDocumentUsers({
  documentId: "my-document-id",
});

// To this
const { data, error } = useDocumentsFunctionSWR([
  getDocumentUsers,
  {
    documentId: "my-document-id",
  },
]);
```

Here’s a working example:

```tsx
import { getDocumentUsers, useDocumentsFunctionSWR } from "../../lib/client";

export function ListUsers() {
  // Get users attached to a document and update every 1000ms
  const { data: users, error: usersError } = useDocumentsFunctionSWR(
    [
      getDocumentUsers,
      {
        documentId: "my-document-id",
      },
    ],
    { refreshInterval: 1000 }
  );

if (usersError) {
    return <div>Error</div>;
  }

if (!users) {
    return <div>Loading...</div>;
  }

return (
    <ul>
      {users.map((user) => (
        <li>user.name</li>
      ))}
    </ul>
  );
}
```

### How to extend the Document type

If you’d like to add a new property to `Document`, it’s simple. First, edit the
`Document` type in
[`/types/documents.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/types/document.ts):

```ts file="types/documents.ts"
export type Document = {
  // Your new property
  randomNumber: number;
  //...
};
```

Then modify the return value in
[`/lib/utils/buildDocuments.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/utils/buildDocuments.ts).
This is a function that converts a Liveblocks room into your custom document
format:

```ts file="lib/utils/buildDocuments.ts"
// Return our custom Document format
const document: Document = {
  randomNumber: Math.random(),
  // ...
};
```

Next, run the following command to check for problems:

```bash
npm run typecheck
```

If no errors are returned, the document properties were successfully extended.

### How to extend the User & Session type

Similar to the way we extend the `Document` type, we can also extend the `User`
and `Session` type.

Adding a new property to `User`/`Session` is simple. First, edit the `User` type
in
[`/types/data.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/types/data.ts).

```ts file="types/data.ts"
export type User = {
  // Your new property
  randomNumber: number;
  // ...
};
```

Then make sure to return this new property in
[`/lib/database/getUser.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/database/getUser.ts).

```ts file="lib/database/getUser.ts"
return { randomNumber: Math.random() /* ... */ };
```

The new property will now be available to use in your app:

```ts
// randomNumber: Math.random(),
console.log(session.user.info.randomNumber);
```

#### Adding this to your Liveblocks app (optional)

Liveblocks presence is a way of displaying online presence between users,
helpful for live avatars, realtime cursors, etc., and it’s possible to attach a
properties to it for each user. To make a property accessible in presence (and
within the React hooks used in whiteboard), you must modify `UserInfo` in
[`/liveblocks.config.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/liveblocks.config.ts).

```ts file="liveblocks.config.ts"
export type UserInfo = Pick<User, "randomNumber" /* ... */>;
```

In this example
[Pick](https://www.typescriptlang.org/docs/handbook/utility-types.html) creates
the UserInfo type based off of the User type and adds additional keys based on
the properties you provide. After this, modify
[`/lib/actions/authorizeLiveblocks.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/actions/authorizeLiveblocks.ts).
First, we’ll give an anonymous user a property:

```ts file="lib/actions/authorizeLiveblocks.ts"
// Anonymous user info
const anonymousUser: User = {
  randomNumber: Math.random(),
  // ...
};
```

Next, we’ll get the signed-in user’s property:

```ts file="lib/actions/authorizeLiveblocks.ts"
// Get current user info from session (defined in /auth.config.ts)
// If no session found, this is a logged out/anonymous user
const {
  randomNumber,
  // ...
} = session?.user.info ?? anonymousUser;
```

And then pass this info to `authorize`:

```ts file="lib/actions/authorizeLiveblocks.ts"
// Get Liveblocks access token
const { data, error } = await authorize({
  userInfo: { randomNumber /* ... */ },
  // ...
});
```

To make sure to check everything’s hooked up correctly:

```bash
npm run typecheck
```

Once that’s working, the new property can then be used in your app:

```tsx
// My random number
const myRandomNumber = useSelf((me) => me.info.randomNumber);

// An array of everyone else’s random numbers
const everyonesRandomNumbers = useOthersMapped(
  (other) => other.info.randomNumber
);
```

### Adding multiple authentication providers [#add-multiple-authentication-providers]

It’s possible to add multiple authentication providers to the starter kit using
[NextAuth Providers](https://next-auth.js.org/providers/). Open
[`/auth.config.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/auth.config.ts)
and place your providers in the object:

```ts
import GithubProvider from "next-auth/providers/github";
import Auth0Provider from "next-auth/providers/auth0";

export const authOptions = {
  // ...
  providers: {
    GithubProvider({
      clientId: process.env.GITHUB_CLIENT_ID as string,
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
    }),
    Auth0Provider({
      clientId: process.env.AUTH0_CLIENT_ID as string,
      clientSecret: process.env.AUTH0_CLIENT_SECRET as string,
      issuer: process.env.AUTH0_ISSUER_BASE_URL as string,
    }),
  }
};
```

It’s not only possible with GitHub and Auth0, any
[NextAuth provider](https://next-auth.js.org/providers/) will work, such as
Google, X, Reddit, or more. You can find more information about getting the
necessary secrets on the NextAuth documentation, or on the provider’s website.

Note that if you’re using `CredentialsProvider` (for example, as used in the
demo authentication), `CredentialsProvider` must be removed before any other
authentication methods will appear.

### Switching themes

The starter kit comes with both a dark mode and light mode. By default, the user
sees the theme that corresponds to their system setting, but it’s easy to switch
your whole app to just dark or light mode by modifying
[`styles/globals.css`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/styles/globals.css).

- To use only light mode, remove the entire
  `@media (prefers-color-scheme: dark)` media query.
- To use only dark mode, copy the "Dark mode" CSS variables into the "Light
  mode" section, then remove the entire `@media (prefers-color-scheme: dark)`
  media query.

### Adding a database

To add a database you need to modify the following async functions to return the
correct properties:

- [`/lib/database/getGroup.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/database/getGroup.ts)
- [`/lib/database/getGroups.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/database/getGroups.ts)
- [`/lib/database/getOrganization.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/database/getOrganization.ts)
- [`/lib/database/getUser.ts`](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/lib/database/getUser.ts)

You can then remove the `/data` folder. Everything else should work as expected.

---
meta:
  title: "Upgrading Liveblocks"
  description: "Select the Liveblocks version you’d like to update to"
---

Select the version you’d like to update to. When upgrading, please note that all
packages should be upgraded to the same version. If a version isn’t mentioned,
there are no breaking changes.

---
meta:
  title: "Upgrading to 0.17"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 0.17"
---

```bash
npm install @liveblocks/client@0.17 @liveblocks/react@0.17
```

With the release of 0.17 we’re making a big investment in the stability and
reliability of Liveblocks. Our long term goal is to empower you to write and
help evolve your apps in the best way possible, and at enterprise scale. It
already was easy to get started with Liveblocks, and with these changes we want
to make _evolving_ your app just as easy.

The first step towards this goal is to take TypeScript support to the next level
for [`@liveblocks/client`][] and [`@liveblocks/react`][] (but our other packages
will soon follow suit). This will help you write code with confidence and catch
bugs as soon as possible in the development process. We have strictened our type
definitions to be more accurate and will recommend some new usage patterns, so
it will be easier for you to create _bug free_ collaborative apps.

To upgrade [`@liveblocks/client`][] and [`@liveblocks/react`][], run the
following command.

```bash
npm install @liveblocks/client@0.17 @liveblocks/react@0.17
```

With these changes, we’re clearing the path to enable schema validation per
room, automatic data migrations, more powerful data selector APIs, and other
enterprise-level features.

Let’s dive in and take a look!

## Changes in @liveblocks/react [#react]

### Lifting up your state to the room level [#lifting-state-to-room]

With 0.16, it was possible to initialize a storage key with [`useObject`][],
[`useList`][], [`useMap`][].

Even if handy, we realized that it introduced confusion and unpredictable
behavior for most users. Imagine a scenario where you have two components
initializing the same storage key.

```tsx
function ComponentA() {
  const author = useObject("author", {
    firstName: "Ada",
    lastName: "Lovelace",
  });

/* ... */
}

function ComponentB() {
  const author = useObject("author", {
    firstName: "Margaret",
    lastName: "Hamilton",
  });

/* ... */
}
```

Depending on which component renders first, `author` will be Margaret Hamilton
or Ada Lovelace. To make this more predictable, we’re deprecating this and
recommend initializing the storage at the [`RoomProvider`][] level.

#### Before ❌ [@hidden]

```tsx
function ComponentA() {
  const author = useObject(
    "author",

// ⚠️ Don’t initialize your data here anymore!
    { firstName: "Ada", lastName: "Lovelace" }
  );

/* ... */
}
```

#### After ✅ [@hidden]

```tsx highlight="5-10,13,20"
import { LiveObject } from "@liveblocks/client";

function Root() {
  // Instead, initialize it at the RoomProvider level to remove all ambiguity
  const initialStorage = {
    author: new LiveObject({
      firstName: "Ada",
      lastName: "Lovelace",
    }),
  };

return (
    <RoomProvider id="my-room-id" initialStorage={initialStorage}>
      <ComponentA />
    </RoomProvider>
  );
}

function ComponentA() {
  const author = useObject("author");

/* ... */
}
```

Notice the explicit use of LiveObject here now. Before, when using useObject (or
useList, useMap), the data you passed to initialize it would automatically get
wrapped in LiveObject for you. This seemed convenient at first, but it also
caused confusion about which Storage keys were Live structures and which ones
were “normal” values. By opting in to which keys you want to be Live structures,
you now get full control over your storage data.

</Banner>

If you run into issues with these new patterns and you need help, please
[let us know](https://github.com/liveblocks/liveblocks/discussions/359). We’re
here to help!

### A better way to annotate your own types [#react-better-type-annotations]

In 0.16, most of our hooks accepted generic parameters that let you explicitly
provide your own types. For example:

```tsx highlight="3-5,11,19"
import { useMyPresence, RoomProvider } from "@liveblocks/react";

type Presence = {
  cursor: { x: number; y: number };
};

function Root() {
  return (
    <RoomProvider
      id="my-room-id"
      initialPresence={{ cursor: { x: 100, y: 100 } }}
    >
      <Component />
    </RoomProvider>
  );
}

function Component() {
  const [myPresence] = useMyPresence<Presence>();

const cursor = myPresence.cursor; // Valid

/* ... */
}
```

One issue with this API was that there was no good way to make sure that
`RoomProvider.initialPresence` and [`useMyPresence`][] types remain
synchronized, as there was no inherent connection between these.

If we added a `color` property to the `Presence` type, it would still be missing
from the `initialPresence` at the `RoomProvider` level, and TypeScript would not
be able to catch that bug. The opposite would also fail; omitting the `cursor`
property on the `initialPresence` would break at runtime but TypeScript would
not be able to catch this issue for you!

Another issue is that there could be many places where you’d have to provide
those extra type annotations.

With 0.17, we’re fixing all of this!

To do so, we’re introducing a new API called [`createRoomContext`][]. It lets
you type your `RoomProvider` and make sure that all your hooks types are
synchronized with the `RoomProvider`. Besides this initial setup, you will no
longer have to provide any type annotations elsewhere anymore.

```tsx
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  /* client options */
});

type Presence = {
  cursor: { x: number; y: number };
};

// This is just to illustrate the API - read on for tips on where to put this!
const { RoomProvider, useMyPresence } = createRoomContext<Presence>(client);

function Root() {
  return (
    <RoomProvider
      id="my-room-id"
      initialPresence={{ cursor: { x: 100, y: 100 } }}
    >
      <Component />
    </RoomProvider>
  );
}

function Component() {
  const [myPresence] = useMyPresence();

// We can now be sure that cursor is a valid property without any generic typed param
  const cursor = myPresence.cursor;

/* ... */
}
```

As you can see, `createRoomContext` optionally takes type parameters that let
you specify the shape of your app’s data (by specifying your own `Presence`,
`Storage`, `UserMeta`, `Event` types). Depending on the complexity of your app,
you may only need to use one or more of these.

Take a look at these examples to better see how to use and configure it:

- Our live-cursors-chat example app uses
  [`Presence`](https://github.com/liveblocks/liveblocks/blob/a11e5744531a21201ae9f9f9ad4f1aa5e74e141e/examples/nextjs-live-cursors-chat/liveblocks.config.ts#L8-L25)
  only
- Our live-avatars example app uses
  [`UserMeta`](https://github.com/liveblocks/liveblocks/blob/a11e5744531a21201ae9f9f9ad4f1aa5e74e141e/examples/nextjs-live-avatars/liveblocks.config.ts#L8-L26)
  only
- Our logo-builder example app uses
  [`Presence`](https://github.com/liveblocks/liveblocks/blob/a11e5744531a21201ae9f9f9ad4f1aa5e74e141e/examples/nextjs-logo-builder/liveblocks.config.ts#L8-L31),
  [`Storage`](https://github.com/liveblocks/liveblocks/blob/a11e5744531a21201ae9f9f9ad4f1aa5e74e141e/examples/nextjs-logo-builder/liveblocks.config.ts#L8-L31),
  and
  [`UserMeta`](https://github.com/liveblocks/liveblocks/blob/a11e5744531a21201ae9f9f9ad4f1aa5e74e141e/examples/nextjs-logo-builder/liveblocks.config.ts#L8-L31)

### Recommended upgrade steps

To make this refactoring as easy as possible, follow the steps below.

#### Step 1 - Upgrade `@liveblocks/client` and `@liveblocks/react` [@hidden]

To upgrade [`@liveblocks/client`][] and [`@liveblocks/react`], run the following
command.

```bash
npm install @liveblocks/client@0.17 @liveblocks/react@0.17
```

#### Step 2 - Create a new file called `liveblocks.config.ts` where you will create your Liveblocks client, provider and hooks and re-export them. [@hidden]

```tsx file="liveblocks.config.ts"
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  /* client options */
});

// Presence represents the properties that will exist on every User in the Room
// and that will automatically be kept in sync. Accessible through the
// `user.presence` property. Must be JSON-serializable.
type Presence = {
  // cursor: { x: number, y: number } | null,
  // ...
};

// Optionally, Storage represents the shared document that persists in the
// Room, even after all Users leave. Fields under Storage typically are
// LiveList, LiveMap, LiveObject instances, for which updates are
// automatically persisted and synced to all connected clients.
type Storage = {
  // author: LiveObject<{ firstName: string, lastName: string }>,
  // ...
};

// Optionally, UserMeta represents static/readonly metadata on each User, as
// provided by your own custom auth backend (if used). Useful for data that
// will not change during a session, like a User's name or avatar.
// type UserMeta = {
//   id?: string,  // Accessible through `user.id`
//   info?: Json,  // Accessible through `user.info`
// };

// Optionally, the type of custom events broadcasted and listened for in this
// room. Must be JSON-serializable.
// type RoomEvent = {};

export const {
  RoomProvider,
  useMyPresence,
  useObject,
  /* ...all the other hooks you’re using... */
} = createRoomContext<Presence, Storage /* UserMeta, RoomEvent */>(client);
```

#### Step 3 - Replace all the direct hook imports from `@liveblocks/react` by your path to `liveblocks.config.ts` and remove all generic params. [@hidden]

##### Before ❌ [@hidden]

```tsx
import { useMyPresence, useOthers, useObject } from "@liveblocks/react";
import { Author } from "./types";

type MyPresence = {
  cursor: { x: number; y: number } | null;
};

function Component() {
  const author = useObject<Author>("author");
  const [{ cursor }] = useMyPresence<MyPresence>();
  const others = useOthers<Presence>();
}
```

##### After ✅ [@hidden]

```tsx
import { useMyPresence, useOthers, useObject } from "./liveblocks.config";

function Component() {
  const author = useObject("author");
  const [{ cursor }] = useMyPresence();
  const others = useOthers();
}
```

#### Step 4 - Remove your [`LiveblocksProvider`][] at the top of your react tree. It’s not needed anymore! [@hidden]

##### Before ❌ [@hidden]

```tsx
import { createClient } from "@liveblocks/client";
import { LiveblocksProvider, RoomProvider } from "@liveblocks/react";

const client = createClient({
  /* ... */
});

ReactDOM.render(
  <LiveblocksProvider client={client}>
    <RoomProvider id="my-room-id">
      <App />
    </RoomProvider>
  </LiveblocksProvider>,
  document.getElementById("root")
);
```

##### After ✅ [@hidden]

```tsx
import { RoomProvider } from "./liveblocks.config";

ReactDOM.render(
  <RoomProvider id="my-room-id">
    <App />
  </RoomProvider>,
  document.getElementById("root")
);
```

If you run into issues with these new patterns and you need help, please
[let us know](https://github.com/liveblocks/liveblocks/discussions/360). We’re
here to help!

## Changes in @liveblocks/client [#client]

### Removed dangerous default type params [#no-more-default-type-params]

In 0.16, while [`LiveList`][], [`LiveMap`][], [`LiveObject`][] were generics,
they also took default type params, which made them a footgun. It was easy to
accidentally use them in a way that would discard useful type information and
hinder inference.

For example:

```ts
// ✅ Inferred
let list = new LiveList([1, 2, 3]);

// ✅ Explicit
let list: LiveList<number> = new LiveList([1, 2, 3]);

// ☢️ 0.16: Dangerous footgun: discards useful type information!
// 🚫 0.17: No longer possible
let list: LiveList = new LiveList([1, 2, 3]);
```

They now mimic their equivalent built-in TypeScript generics, so:

- `LiveList<T>` is now just like `Array<T>`
- `LiveMap<K, V>` is now just like `Map<K, V>`
- `LiveObject<{ a: number, b: string }>` is now just like
  `{ a: number, b: string }`

### No longer import Presence [#define-dont-import-presence]

In 0.16, we exposed a `Presence` type that you could import, which was just an
alias for “any JSON object”—not that useful! Importing Presence from Liveblocks
made no sense. By definition, Presence is data owned and defined by your
application after all.

You should no longer need to _import_ this type.

```tsx
// ❌ No longer need to _import_ Presence
import type { Presence } from "@liveblocks/client";

client.enter<Presence>("myRoom");
```

Instead, just _define_ it:

```tsx
// ✅ Just define the shape your app needs
type Presence = {
  cursor: { x: number; y: number } | null;
};

client.enter<Presence>("myRoom");
```

### A better way to annotate your own types [#client-better-type-annotations]

We already talked about why, in React, we
[improved the way you can annotate your own app’s data](#react-better-type-annotations),
by annotating the types only once, at the “top” of your app.

For the same reason, we’re doing a similar thing in the client package.

This section only applies if you’re not using the React package.

</Banner>

```tsx highlight="18-21,24"
import { createClient } from "@liveblocks/client";
import { Author } from "./types";

const client = createClient({
  /* client options */
});

type Presence = {
  cursor: { x: number; y: number } | null;
};

type Storage = {
  author: LiveObject<Author>;
};

// ❌ In 0.16, you had to annotate each method separately
const room = client.enter("myRoom");
const { root } = await room.getStorage<Storage>();
const author = root.get<Author>("author");
const me = room.getPresence<Presence>();
const others = room.getOthers<Presence>();

// ✅ In 0.17, you can simply annotate it once, at the "top"
const room = client.enter<Presence, Storage>("myRoom");
const { root } = await room.getStorage();
const author = root.get("author");
const me = room.getPresence();
const others = room.getOthers();
```

If you run into issues with these new patterns and you need help, please let us
know. We’re here to help!

---
meta:
  title: "Upgrading to 0.18"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 0.18"
---

```bash
npm install @liveblocks/client@0.18 @liveblocks/react@0.18
```

With the release of 0.18 we’re bringing some exciting and pretty major
improvements to our React hooks, letting you build apps with ease and with more
control over the exact behavior.

The new APIs we’re introducing here solve many subtle and not-so-subtle pain
points. We heard your feedback, and think we have shipped something awesome that
you’ll love.

This guide consists of two sections:

1. Introduction of the new APIs to get a taste of the new features
2. Recommended upgrade steps to get the most out of it for your app
   ([jump straight to it](#upgrade-steps))

Let’s dive right in!

## Changes in @liveblocks/react [#react]

With 0.18, the biggest conceptual shift is that our hooks to consume data from
Liveblocks now return normal JavaScript data structures (objects, arrays, maps)
that are _immutable_ by default.

Suppose you have initialized your room with:

```tsx highlight="5-9"
<RoomProvider
  id="my-room"
  initialPresence={/* ... */}
  initialStorage={{
    scientist: new LiveObject({
      firstName: "Ada",
      lastName: "Lovelace",
      pets: new LiveList(["🐶", "🐈"]),
    }),
  }}
>
  <App />
</RoomProvider>
```

### Accessing nested data [#nested-data]

Reading nested data from there is now much easier:

#### Previously ❌ [@hidden]

```tsx
function Component() {
  const scientist = useObject("scientist");
  if (scientist == null) {
    return null;
  }

const pets = scientist.get("pets").toArray();
  // ["🐶", "🐈"]
}
```

#### Now ✅ [@hidden]

```tsx
function Component() {
  const pets = useStorage((root) => root.scientist.pets);
  // ["🐶", "🐈"]
}
```

As you can see, because we can read data with normal JavaScript data structures,
accessing nested data is now straightforward.

### Subscribing to updates is automatic now [#subscriptions]

Rerendering your components when nested data—like our scientist’s pets
list—changes was a true head breaker before. This required extra helper
components, manual subscriptions, and manual conversion to “normal” JavaScript
arrays.

Now, rerendering your component when data changes is automatic, even for deeply
nested data.

#### Previously ❌ [@hidden]

```tsx
function Component() {
  const scientist = useObject("scientist");
  if (scientist == null) {
    return null;
  }

return <Pets livePets={scientist.get("pets")} />;
}

function Pets({ livePets }) {
  const room = useRoom();
  const [pets, setPets] = useState(livePets.toArray());

useEffect(() => {
    return room.subscribe(livePets, () => {
      setPets(livePets.toArray());
    });
  }, [room, livePets]);
}
```

#### Now ✅ [@hidden]

```tsx
function Component() {
  const pets = useStorage((root) => root.scientist.pets);
  // ["🐶", "🐈"]
}
```

There is no typo in this example. This is the actual code.

### Multiple subscriptions are just as easy [#multi-subscriptions]

Previously, if you wanted to derive a computed value from multiple storage
values, it took some manual setup to ensure the component would automatically
rerender when either of those values changed.

Now, this is fully automatic. Or should we say, automagic?

#### Previously ❌ [@hidden]

```tsx highlight="11"
function Component() {
  const objA = useObject("a");
  const objB = useObject("b");

const room = useRoom();
  const [sum, setSum] = useState();
  //     ^^^ We’re trying to compute the result of a.x + b.x in here

useEffect(() => {
    function onChange() {
      setSum(objA.get("x") + objB.get("x"));
    }

const unsubA = room.subscribe(objA, onChange);
    const unsubB = room.subscribe(objB, onChange);

return () => {
      unsubA();
      unsubB();
    };
  }, [room, objA, objB]);
}
```

#### Now ✅ [@hidden]

```tsx
function Component() {
  const sum = useStorage((root) => root.a.x + root.b.x);
}
```

This component will rerender automatically any time `a.x` or `b.x` changes, but
not more often.

### Guaranteed referential equality [#referential-equality]

Previously we returned mutable Live structures for performance reasons because
converting live changing data to JavaScript data structures constantly (and
recursively) was previously too slow to do on every render. This led to
unintuitive behavior when used with React hooks dependencies.

Not anymore! Due to a technique called structural sharing, we’re now able to
_guarantee_ for nodes in the Storage tree that as long as their (direct or
nested) contents haven’t changed in Storage, their immutable representation will
remain to be the same object references on the next render. This means that you
can rely on referential equality, as you may have expected in the first place.

#### Previously ❌ [@hidden]

```tsx
function Component() {
  const scientist = useObject("scientist");

useEffect(() => {
    // Effect never triggered when scientist (or their pets list) changes! :(
  }, [scientist]);
}
```

#### Now ✅ [@hidden]

```tsx
function Component() {
  const scientist = useStorage((root) => root.scientist);

useEffect(() => {
    // Effect triggered every time scientist (or their pets list) changes! :)
    // But not more often than that!
  }, [scientist]);
}
```

### Suspense support

Starting with 0.18, all hooks that read data from Liveblocks come with a
Suspense version of the hook which will never return `null` to indicate the
“still loading” state. Instead, they will suspend the rendering of the component
tree until Liveblocks has finished loading.

We recommend you to adopt Suspense if you can because it lets you get rid of the
ugly `null` checks, helper components to “eat off” those null cases, and the
prop drilling that necessarily comes with all that.

#### Previously ❌ [@hidden]

```tsx
function Component() {
  const camera = useObject("camera");
  const items = useList("items");

// 👎
  if (camera == null || items == null) {
    return <div>Still loading...</div>;
  }

return <MyRealComponent camera={camera} items={items} />;
}
```

#### Now ✅ [@hidden]

Set up a Suspense boundary once:

```tsx file="App.tsx" highlight="6"
import { Suspense } from "react";

function Setup() {
  return (
    // Once
    <Suspense fallback={<Loading />}>
      <App />
    </Suspense>
  );
}
```

Switch to use the Suspense versions of our hooks instead of the “normal” ones:

```tsx file="liveblocks.config.ts" highlight="2"
export const {
  suspense: {
    RoomProvider,
    useStorage,
    /* etc. */
  },
} = createRoomContext(client);
```

Then, enjoy no more null checks everywhere in your app:

```tsx file="Component.tsx"
function Component() {
  const camera = useStorage((root) => root.camera);
  const items = useStorage((root) => root.items);
  // No more null checking! :)
}
```

## Recommended upgrade steps [#upgrade-steps]

To get the most out of the new hooks, we recommend following the steps below to
gradually upgrade your app to make use of the new hooks.

### Step 1: Install the latest package [@hidden]

```bash
npm install @liveblocks/client@0.18 @liveblocks/react@0.18
```

### Step 2: Make sure you’re setting initial presence [@hidden]

We now require setting an initial presence value when you connect to a room
explicitly. This ensures that every user is guaranteed to always have a known
presence value.

Check that you have this in your config file:

```tsx file="liveblocks.config.ts" highlight="3"
<RoomProvider
  id="my-room"
  initialPresence={{}}
  //              ^^^^ No longer optional
>
  <App />
</RoomProvider>
```

If your app somehow doesn’t use Presence, you can just set an empty object
(`{}`) here.

### Step 3: You can remove some uncertainty from user instances [@hidden]

If you have expressions in your code that look like...

```tsx
user.info?.avatar;
//       ^
user.presence?.cursor.x;
//           ^
```

You can now remove these optional chainings. The fields `info` and `presence`
will now always be set on `User` instances.

### Step 4: Adopt Suspense (optional) [@hidden]

Now is a great moment to opt-in to Suspense (see the
[React docs](https://reactjs.org/docs/react-api.html#suspense)) with Liveblocks,
if you can or want to use it in your app. We recommend it for most apps because
it makes working with the new hooks even nicer.

To avoid repeating ourselves, please follow the instruction below.

Follow
[these instructions to adopt Suspense](/docs/api-reference/liveblocks-react#suspense).
Don’t worry, we’ll wait.

</Banner>

Now that you have updated your app to Suspense, you should be able to remove all
these pesky `null` checks from your code.

```tsx highlight="6-8"
function Component() {
  const a = useMap("a");
  const b = useList("b");
  const c = useObject("c");

if (a == null || b == null || c == null) {
    return <Loading />;
  }

/* ... */
}
```

Afterward, please verify that your app still works like normal.

### Step 5a: Replace reads with `useStorage` [@hidden]

We recommend rewriting all usages of `useList`, `useObject` and `useMap` if
those are used for _reading_ data only. If used only for reading values from
Storage, you could turn these into an equivalent `useStorage` call, which has
fewer gotchas.

For example, change:

```tsx
// ❌
const obj = useObject("a");
const list = useObject("b");
const map = useMap("c");
```

to:

```tsx
// ✅
const obj = useStorage((root) => root.a);
const list = useStorage((root) => root.b);
const map = useStorage((root) => root.c);
```

Note that the `root` argument you receive here is the immutable normal
JavaScript equivalent of your entire Storage tree, as returned by calling
[`.toImmutable`][].

So this means that if you have been manually converting the mutable Live
structures to normal data structures, you no longer have to do this:

```tsx
// ❌
obj.toObject();
list.toArray();
```

```tsx
// ✅
obj; // Already a normal JS object
list; // Already a normal JS array
```

Please note that `useList`, `useObject`, or `useMap` are not deprecated and
still work with the same behavior as before. We just no longer recommend their
use.

### Step 5b: Replace mutations with useMutation [@hidden]

If you are (also) using `useList`, `useObject` or `useMap` to obtain a mutable
reference to the Live structure to _mutate_ it, you can rewrite those use cases
to use the new `useMutation` hook instead.

For example:

```tsx
// ❌
const obj = useObject("a");

return (
  <input
    value={obj.get("name")}
    //         ^^^ Live object used for reading
    onClick={() => {
      obj.set("name", e.currentTarget.value);
      //  ^^^ Live object used for mutating
    }}
  />
);
```

The idiomatic way to deal with Storage is to _consume_ data using simple/normal
JS data structures and to _mutate_ data using a callback function that you can
create with `useMutation`, which provides access to the mutable Live structures.

```tsx
// ✅
const name = useStorage((root) => root.a.name);

const setName = useMutation(({ storage }, newName) => {
  storage.get("a").set("name", newName);
  //               ^^^ Mutation goes here
}, []);

return (
  <input
    value={name}
    //     ^^^^ Reading uses simple values
    onClick={(e) => setName(e.currentTarget.value)}
  />
);
```

Even though in this contrived example it may look more complicated, in large
apps this pattern will vastly simplify your app’s complexity.

See the [`useMutation`][] documentation to learn all the details, because it has
a lot more in store.

</Banner>

### Step 6: Get rid of `room.subscribe()` calls [@hidden]

Historically the only way to get full control over exactly when and how your
components would rerender was to use the low-level `room.subscribe()` API.

Most, if not all, of these use cases can be replaced by an equivalent, yet much
simpler call to `useStorage` with a selector function that does an equivalent
thing.

**Common use case: subscribing to nested data**  
If you are using `room.subscribe` to manually rerender components when nested
data changes, you can replace it by “just” selecting the nested fields you’re
interested in. See [this example](#subscriptions).

```tsx
// ✅ Automatically rerenders if pets changes (but not more often)
const nested = useStorage((root) => root.scientist.pets);
```

**Common use case: subscribing to a computed value**  
If you are using `room.subscribe` to synchronize a computation based on multiple
storage values, you can replace it by “just” doing the computation in See
[this example](#multi-subscriptions).

```tsx
// ✅ Automatically rerenders if computed value changes
const sum = useStorage((root) => root.a + root.b);
```

If you have another use case for `room.subscribe` that you think isn’t possible
to express in an equivalent `useStorage` call, please
[let us know about it](https://github.com/liveblocks/liveblocks/discussions/504).
We’re happy to help!

### Step 7: Get rid of manual batch calls [@hidden]

Most, if not all, cases of manually calling `useBatch` or `room.batch` should no
longer be needed and can be replaced by `useMutation`, which automatically
batches already!

That’s it!

If you run into issues with these new patterns and you need help, please
[let us know](https://github.com/liveblocks/liveblocks/discussions/504). We’re
here to help!

[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation
[`.toimmutable`]: /docs/api-reference/liveblocks-client#LiveObject.toImmutable

---
meta:
  title: "Upgrading to 0.19"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 0.19"
---

In the Liveblocks 0.19 release, we’re adding support for Zustand v4 to
`@liveblocks/zustand`. Zustand v4 brings greatly improved TypeScript types to
its APIs, enabling us to enhance the quality of our types, bringing it in line
with our React package.

Let’s take a look!

## Upgrading steps by package

### @liveblocks/react [#react]

To update `@liveblocks/react` to 0.19, run the following command using your
preferred package manager:

```bash
npm install @liveblocks/client@0.19 @liveblocks/react@0.19
```

#### useOther now requires a selector argument [@hidden]

`useOther` now requires a
[selector](/docs/api-reference/liveblocks-react#selectors-receive-immutable-data)
function argument. You will need to replace instances of `useOther` that do not
use a selector in your codebase.

#### Previously ❌ [@hidden]

```tsx
const other = useOther(id); // 👈 does not include a selector
```

#### Now ✅ [@hidden]

```tsx
const other = useOther(id, (other) => other); // 👈 requires a selector
```

#### Include unstable_batchedUpdates if you use React 17 [@hidden]

We’ve added support to prevent the stale props/zombie child scenario. To avoid
this issue, we enforce passing the `unstable_batchedUpdates` prop to
`RoomProvider`.

This section only applies if you are using React 17 or lower. You do not need to
do anything if you are using React 18 or higher.

</Banner>

```tsx highlight="2,8"
// ⚠️ Only if you’re using React 17 or lower
import { unstable_batchedUpdates } from "react-dom"; // 👈
<RoomProvider
  id="my-room"
  initialPresence={...}
  initialStorage={...}
  unstable_batchedUpdates={unstable_batchedUpdates}
>
  <App />
</RoomProvider>
```

For additional context, see the
[troubleshooting guide](/docs/platform/troubleshooting#stale-props-zombie-child)

### @liveblocks/redux [#redux]

To update `@liveblocks/redux` to 0.19, run the following command using your
preferred package manager:

```bash
npm install @liveblocks/client@0.19 @liveblocks/redux@0.19
```

#### Update use of default export liveblocksEnhancer [@hidden]

The main export has been renamed, so you will need to update your imports and
use of the enhancer:

#### Previously ❌ [@hidden]

```ts
import { enhancer } from "@liveblocks/redux";
```

#### Now ✅ [@hidden]

```ts
import { liveblocksEnhancer } from "@liveblocks/redux";
```

#### Remove the second argument to state.liveblocks.enterRoom [@hidden]

When calling `state.liveblocks.enterRoom()`, you should not pass an explicit
initial state. It will use the state in your Redux store, for consistency and
ease of use. To migrate, make the following code changes:

#### Previously ❌ [@hidden]

```ts
useEffect(() => {
  enterRoom("room-id", {
    todos: [], // 👈 remove explicit initial state
  });
});
```

#### Now ✅ [@hidden]

```ts
useEffect(() => {
  enterRoom("room-id");
});
```

### @liveblocks/zustand [#zustand]

In 0.19 we added support for Zustand v4 (specifically v4.1.3 or higher) and will
no longer support Zustand v4.1.2 or lower. This is because Zustand v4.1.3 brings
greatly improved TypeScript types to its APIs, and consequently, we can improve
our internal types. To migrate, make the following code changes:

To update `@liveblocks/zustand` to 0.19, run the following command using your
preferred package manager:

```bash
npm install @liveblocks/client@0.19 @liveblocks/zustand@0.19
```

- Change these imports, if applicable, and rename accordingly:

#### Previously ❌ [@hidden]

```ts
import { middleware } from "@liveblocks/zustand";
import type { LiveblocksState } from "@liveblocks/zustand";
```

#### Now ✅ [@hidden]

```ts
import { liveblocks } from "@liveblocks/zustand";
import type { WithLiveblocks } from "@liveblocks/zustand";
```

- Update to the Zustand v4 recommended pattern:

#### Previously ❌ [@hidden]

```ts
create(liveblocks<MyState, ...>(...))
```

#### Now ✅ [@hidden]

```ts
create<WithLiveblocks<MyState, ...>>()(liveblocks(...))
```

To be clear:

1. First, move the type annotation away from the `liveblocks` middleware call,
   and onto the `create` call.
2. Next, wrap your `MyState` type in a `WithLiveblocks<...>` wrapper. This will
   make sure the injected `liveblocks` property on your Zustand state will be
   correctly typed.
3. Finally, make sure to add the extra call `()` wrapper, needed by Zustand v4
   now:
   ```ts
   create<WithLiveblocks<MyState, ...>>()(liveblocks(...))
   //                                  ^^ Not a typo
   ```

- Remove the second argument to `state.liveblocks.enterRoom()`: it no longer
  takes an explicit initial state. Instead, it’s automatically be populated from
  your Zustand state.

## Improvements [#improvements]

This release brings several changes to `@liveblocks/react`, which improve
rendering performance and stability. Additionally, we have refactored our
internal packages to increase code sharing. You can review the
[release notes](https://github.com/liveblocks/liveblocks/releases) for more
details.

### @liveblocks/react [#react-improvements]

#### New shouldInitiallyConnect prop [@hidden]

We added a new property `shouldInitiallyConnect` to `RoomProvider`, which lets
you control whether or not the room connects to Liveblock servers. By default,
it will check the `typeof window` to determine if it should connect. When using
SSR, you can set it to `false` to prevent the room from connecting to Liveblocks
servers.

```tsx highlight="4"
<RoomProvider
  id="room"
  initialPresence={{}}
  shouldInitiallyConnect={false} // 👈 control initial connection to Liveblocks
>
  <App />
</RoomProvider>
```

#### Addition of @liveblocks-core package [@hidden]

We restructured our internal packages to increase code sharing. You may notice a
new dependency in your dependency tree: `@liveblocks/core`. It contains private
APIs that aren’t intended for direct consumption.

### @liveblocks/client [#client-improvements]

#### New shouldInitiallyConnect option [@hidden]

Similar to the [`shouldInitiallyConnect`](#react-shouldInitiallyConnect) prop in
`@liveblocks/react`, we added a `shouldInitiallyConnect` option to
`client.enter`. The default value is `true`. You may want to set it to `false`
when using SSR, or if you would prefer to establish the WebSocket connection
later.

```tsx
client.enter("room", {
  initialPresence: {},
  shouldInitiallyConnect: false, // 👈 for SSR using the @liveblocks/client package
});
```

### @liveblocks/\* [#all]

All packages now provide an `isReadOnly` flag on user instances. It is available
by calling `getSelf()` and `getOthers`. `isReadOnly` is true when storage is
read-only, as well as when a user has `read` permission to the `room` and
`write` permission to `presence`.

```ts highlight="3,5"
const me = room.getSelf();

me.isReadOnly; // boolean

const others = room.getOthers();
for (const other of others) {
  other.isReadOnly; // boolean
}
```

You can learn more about room permissions under
[authentication](/docs/authentication).

That’s it!

If you run into issues with these new patterns and you need help, please let us
know [by email](mailto:support@liveblocks.io) or by joining our
[Discord community](/discord)! We’re here to help!

---
meta:
  title: "Upgrading to 1.0"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 1.0"
---

Liveblocks 1.0 is our first major release, marking the end of the beta period
for storage and conflict-free data types. This release includes improvements to
our pricing model that make billing more predictable. Additionally, we have
vastly improved the ability to animate cursors at up to 60fps by updating the
throttle option in `createClient`. The primary change you should note is the
transition to making the `userId` mandatory in the `authorize` option. This
change is in line with our [new pricing model](https://liveblocks.io/pricing).

Let’s take a look!

## Upgrading steps by package

### @liveblocks/node [#node]

To update `@liveblocks/node` to 1.0, run the following command using your
preferred package manager:

```bash
npm install @liveblocks/node@1.0.0
```

#### Update the authorize option [@hidden]

We have updated the `authorize` method to make `userId` mandatory. This change
ties into our new [pricing model](https://liveblocks.io/pricing), which is based
on Monthly Active Users (MAU) instead of connections. We use `userId` to track
MAU associated with a Liveblocks account.

```ts highlight="20"
import { authorize } from "@liveblocks/node";

// Replace this key with your secret key provided at
// https://liveblocks.io/dashboard/projects/{projectId}/apikeys
const secret = "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx";

export default async function auth(req, res) {
  /**
   * Implement your own security here.
   *
   * It’s your responsibility to ensure that the caller of this endpoint
   * is a valid user by validating the cookies or authentication headers
   * and that it has access to the requested room.
   */
  const room = req.body.room;
  const response = await authorize({
    room,
    secret,
    // Corresponds to the UserMeta[id] type defined in liveblocks.config.ts
    userId: "123", // Required
    groupIds: ["456"], // Optional
    userInfo: {
      // Optional, corresponds to the UserMeta[info] type defined in liveblocks.config.ts
      name: "Ada Lovelace",
      color: "red",
    },
  });
  return res.status(response.status).end(response.body);
}
```

If you do not use the `authorize` function because you are using the public API
key method, a cookie will be set in the browser when a user connects to a room.
This cookie will be used to track MAU associated with a Liveblocks account and
will expire after 30 days.

### Authorize endpoint [#authorize-endpoint]

If you do not use the `authorize` function, but call the `authorize` endpoint
with a secret key instead, you should pass the `userId` even though it is not
mandatory on the API level because the userID will be used for MAU. Set the
`Authorization: Bearer` header to your secret key.

```ts
POST https://api.liveblocks.io/v2/rooms/{roomId}/authorize
```

Set the following the request body:

```ts highlight="3"
{
  "userId": "user123",
  "groupIds": [
    "g1",
    "g2"
  ],
  "userInfo": {
    "name": "bob",
    "colors": [
      "blue",
      "red"
    ]
  }
}
```

## Improvements [#improvements]

We added additional features to [Webhooks](/docs/platform/webhooks),
enhancements to the `Room` class, and more. You can review the
[release notes](https://github.com/liveblocks/liveblocks/releases) for more
details.

### @liveblocks/client [#client-improvements]

To update `@liveblocks/client` to 1.0, run the following command using your
preferred package manager:

```bash
npm install @liveblocks/client@1.0.0
```

#### Improvements to throttle allow animation of up to 60fps [@hidden]

You can now specify the `throttle` option in
[`createClient`](https://liveblocks.io/docs/api-reference/liveblocks-client#createClientThrottle)
that can go as low as 16ms. If not set, the default value is 100ms.

```ts highlight="5"
import { createClient } from "@liveblocks/client";

const client = createClient({
  /* ... other options ... */
  throttle: 16,
});
```

You can see the marked improvement in the animation from 80ms (original limit)
to 16ms in this
[tweet](https://twitter.com/ctnicholasdev/status/1622656511758700546). If you
want to try it out for yourself, check out
[live cursors example](https://liveblocks.io/examples/live-cursors/nextjs).

#### New methods available on the Room class [@hidden]

We added new methods to the `Room` class that you can use to obtain the storage
status of a room, subscribe to storage status changes, or reconnect to a room
whenever necessary. You can also use the
[Liveblocks DevTools extension](/devtools) to visualize realtime changes to
storage while implementing these changes.

Use `room.getStorageStatus` to retrieve the storage status of a room. The
statuses are:

- `not-loaded`: Initial state when entering the room.
- `loading`: Once the storage has been requested via room.getStorage().
- `synchronizing`: When some local updates have not been acknowledged by
  Liveblocks servers.
- `synchronized`: Storage is in sync with Liveblocks servers.

Use `room.subscribe` to subscribe to storage status changes. This method returns
an unsubscribe function.

```ts
room.subscribe("storage-status", (status) => {
  // Implement your logic here
  switch (status) {
    case "not-loaded":
      break;
    case "loading":
      break;
    case "synchronizing":
      break;
    case "synchronized":
      break;
    default:
      break;
  }
});
```

You can use `room.reconnect()` to close the room connection and try to
[reconnect](/docs/api-reference/liveblocks-client#Room.reconnect).

### @liveblocks/node [#node-improvements]

#### Webhooks enhancements [@hidden]

We have added two new events to our Webhooks functionality: `RoomCreatedEvent`
and `RoomDeletedEvent`. We have also added a `WebhookHandler` class to make it
easier to verify event requests from Liveblocks’ Webhooks functionality. It also
provides fully typed `WebhookEvents`.

```ts
import { WebhookHandler } from "@liveblocks/node";

const webhookHandler = new WebhookHandler(process.env.SECRET);

const event = webhookHandler.verifyRequest({
  headers: req.headers,
  rawBody: req.body,
});
```

Verification of events is critical to ensure that the events are coming from
Liveblocks and not from a malicious source. Check out our
[Webhooks guide](https://liveblocks.io/docs/platform/webhooks) for more details.

That’s it!

If you have issues with these new patterns and need help, please let us know
[by email](mailto:support@liveblocks.io) or by joining our
[Discord community](/discord)! We’re here to help!

---
meta:
  title: "Upgrading to 1.10"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 1.10"
---

Notifications is the first Liveblocks product that works across multiple rooms,
and this has required us to introduce breaking changes to ensure a consistent
API for Comments and Notifications.

## How to upgrade? [#how]

You can upgrade to 1.10 by downloading the latest version of each Liveblocks
package you’re using, for example in a React app:

```bash
npm install @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-ui@latest @liveblocks/node@latest
```

If you’re using any other Liveblocks packages make sure to update those too.

</Banner>

## All changes are for Comments and Notifications

If you’re not using Comments or Notifications, there are no breaking changes for
you! However, if you are using these, or intend to use them in future, keep
reading.

## Security

Users must see the notifications across multiple rooms when they open their
inbox. This is the first time we must expose an API not associated with a single
room. It forced us to introduce a minor breaking change in our authentication
mechanism. Using
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
will call your authentication endpoint without a `room`.

### createClient with callback

If you use `createClient` with `authEndpoint`
[as a callback](/docs/api-reference/liveblocks-client#createClientCallback),
`room` is now optional.

```typescript
const client = createClient({
  authEndpoint: (room) => {
    // The `room` argument will be `undefined` if you're using `useInboxNotifications`
  },
});
```

## Comments resolver functions

Notifications needs to resolve users, as well as Comments, so we’ve lifted the
resolver functions from `createRoomContext` to `createClient`.

Before:

```tsx file="liveblocks.config.ts" highlight="7-12"
// ❌ Before - Liveblocks 1.9
const client = createClient({
  authEndpoint: "/api/liveblocks-auth",
});

const { RoomProvider } = createRoomContext({
  async resolveUsers({ userIds, roomId }) {
    // ...
  },
  async resolveMentionSuggestions({ text, roomId }) {
    // ...
  },
});
```

After:

```tsx file="liveblocks.config.ts" highlight="4-9"
// ✅ After - Liveblocks 1.10
const client = createClient({
  authEndpoint: "/api/auth/liveblocks-auth",
  async resolveUsers({ userIds }) {
    // ...
  },
  async resolveMentionSuggestions({ text }) {
    // ...
  },
});

const { RoomProvider } = createRoomContext();
```

Because the resolvers are no longer room-based, you’ll notice that `roomId` is
no longer in the parameters.

### Resolver types

Because the resolvers have moved to the `client`, the `ResolveUsersArgs` and
`ResolveMentionSuggestionsArgs` types are now exported from `@liveblocks/client`
instead of `@liveblocks/react`.

```tsx highlight="5,11"
// ❌ Before - Liveblocks 1.9
import {
  ResolveUsersArgs,
  ResolveMentionSuggestionsArgs,
} from "@liveblocks/react";

// ✅ After - Liveblocks 1.10
import {
  ResolveUsersArgs,
  ResolveMentionSuggestionsArgs,
} from "@liveblocks/client";
```

Relatedly,
[`stringifyCommentBody`](/docs/api-reference/liveblocks-node#stringify-comment-body)’s
`CommentBodyResolveUsersArgs` no longer exists, and you should use
`ResolveUsersArgs` instead.

```tsx highlight="5,11"
// ❌ Before - Liveblocks 1.9
import { CommentBodyResolveUsersArgs } from "@liveblocks/node";

// ✅ After - Liveblocks 1.10
import { ResolveUsersArgs } from "@liveblocks/node";
```

## Comments CSS variables

Some `elevation` and `tooltip`
[CSS variables](/docs/api-reference/liveblocks-react-ui#CSS-variables) have been
removed:

- `--lb-tooltip-background`
- `--lb-tooltip-foreground`
- `--lb-tooltip-foreground-contrast`
- `--lb-elevation-background`
- `--lb-elevation-foreground`
- `--lb-elevation-foreground-contrast`

Because these no longer exist, we recommend using the basic `--lb-*` variables
directly on `.lb-elevation` or `.lb-tooltip `.

Before:

```css
/* ❌ Before - Liveblocks 1.9 */
:root {
  --lb-tooltip-foreground: white;
  --lb-elevation-background: red;
}
```

After:

```css
/* ✅ After - Liveblocks 1.10 */
.lb-tooltip {
  --lb-foreground: white;
}

.lb-elevation {
  --lb-background: red;
}
```

## Comments overrides

Comments overrides allows you to replace a string or node in default components,
with another that you’ve specified. Some overrides have been changed.

- `SELF` is now `USER_SELF`.
- `UNKNOWN_USER` is now `USER_UNKNOWN`.
- `COMMENT_REACTION_REMAINING` no longer exists, and you should use the
  `LIST_REMAINING_USERS` instead.
- `COMMENT_REACTION_TOOLTIP` is now `COMMENT_REACTION_LIST`, and its arguments
  have been changed to `(list, emoji, count)`.

Before:

```tsx highlight="4-7"
// ❌ Before - Liveblocks 1.9
<CommentsConfig
  overrides={{
    SELF: "you",
    UNKNOWN_USER: "Anon",
    COMMENT_REACTION_REMAINING: (others) => `${others} people`,
    COMMENT_REACTION_TOOLTIP: (emoji, list) => (
      <>
        {list} reacted with {emoji}
      </>
    ),
  }}
/>
```

After:

```tsx highlight="4-7"
// ✅ After - Liveblocks 1.10
<CommentsConfig
  overrides={{
    USER_SELF: "you",
    USER_UNKNOWN: "Anon",
    LIST_REMAINING_USERS: (others) => `${others} people`,
    COMMENT_REACTION_LIST: (list, emoji, count) => (
      <>
        {list} reacted with {emoji}
      </>
    ),
  }}
/>
```

When upgrading, remember that overrides can be applied both globally with
`<CommentsConfig>`, and per component, e.g. `<Composer>`. Learn more in the
[overrides API reference](/docs/api-reference/liveblocks-react-ui#Overrides).

---
meta:
  title: "Upgrading to 1.2"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 1.2"
---

There are no breaking changes in this update, however we are introducing a new
authentication method. If you’re currently using `createClient()` with the
`authEndpoint` option, we recommend you read on.

Liveblocks 1.2 provides new ways to specify who can access certain rooms, and
with which permissions they can enter. Our new-style security tokens also bring
speed improvements, allowing clients to connect Liveblocks rooms even quicker,
as well as permitting authorization tokens that can be used for multiple rooms.

## Public key authentication changes [#public-auth-changes]

<Banner type="success" title="No changes required">
  If you’re currently using Liveblocks **public keys**, no changes are required.
</Banner>

With Liveblocks 1.2, entering rooms with your public key will be noticeably
quicker. If you’re currently using Liveblocks public keys, no changes are
required to your application.

## Private key authentication changes [#private-auth-changes]

<Banner type="warning" title="We recommend changing your auth back end">
  If you’re currently using Liveblocks **private keys** we **highly recommend**
  you upgrade your auth back end.
</Banner>

Upgrading your existing auth back end will opt you in to using our new-style
auth tokens, which offer the following benefits:

- Grant users permission to multiple rooms in one transaction, meaning fewer
  requests on your back end.
- Much quicker to join rooms, particularly any after the first.
- Unlock access to upcoming features, such as [Comments](/comments).

If you’re currently using Liveblocks private keys, no changes are strictly
necessary, but we do highly recommend you upgrade your application’s back end.

## How to upgrade? [#how]

You can upgrade to 1.2 by downloading the latest version of each Liveblocks
package you’re using, for example in a React app:

```bash
npm install @liveblocks/client@latest @liveblocks/node@latest @liveblocks/react@latest
```

If you’re using any other Liveblocks packages make sure to update those too.

</Banner>

We’ll walk you through the necessary changes below, but first, if you currently
have a Liveblocks application in production, we recommend following a rollout
plan, to prevent any users running an old Liveblocks client, during the upgrade,
from having issues.

### Rollout plan

<Steps>
  <StepCompact>
    Keep your existing back end endpoint (e.g. `/api/auth`).
  </StepCompact>

<StepCompact>
  Create a new authentication endpoint for the upgrade (e.g.
  `/api/liveblocks-auth`).
</StepCompact>

<StepCompact>
  In your front end, point `createClient()`’s `authEndpoint` URL to the new
  endpoint.
</StepCompact>

<StepCompact>Done! You can deploy your application now.</StepCompact>

<StepCompact lastStep>
    Later, when all your application’s clients have been upgraded to the latest version, you can safely remove the old endpoint.
  </StepCompact>
</Steps>

## Deciding which token to use [#deciding]

In Liveblocks 1.2 there are two new ways to authenticate with
`@liveblocks/node`.

- [Access tokens](#access-tokens) are recommend for most applications.
- [ID tokens](#id-tokens) are best if you’re using fine-grained permissions with
  our REST API.

Access tokens and ID tokens both allow for multiple room support, but have
different sources of truth. The old authentication method, single-room tokens
with `authorize`, is still supported but will eventually be deprecated.

## Access tokens [#access-tokens]

Access tokens are the new recommended way to authenticate, because they’re easy
to manage from your custom back end. They follow the analogy of a _hotel key
card_. Anyone that has a key card can enter any room that the card gives access
to. It’s easy to give out these key cards right from your back end.

### Upgrading to access tokens [#upgrade-to-access-tokens]

First, create a new endpoint in your back end, next to your existing `/api/auth`
endpoint. We recommend going with `/api/liveblocks-auth`.

Let’s implement it to issue tokens that would be equivalent to your current
single-room token based setup.

<Steps>

<Step>
    <StepTitle>Create a client</StepTitle>
    <StepContent>
    Create a Node.js client that allows you to interact with our REST API.
      ```tsx
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });
      ```
    </StepContent>

</Step>

<Step>
    <StepTitle>Start an auth session inside your endpoint</StepTitle>
    <StepContent>
    Every session should have a unique user ID, which is typically the ID of the user in your database.
      ```tsx highlight="10-13"
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

export async function POST(request) {
        const user = { id: "olivier@example.com", info: { name: "Olivier" }};

const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.info } // Optional
        );
      }
      ```
    </StepContent>

</Step>

<Step>
    <StepTitle>Give the user access to the room</StepTitle>
    <StepContent>
    Give if the current user access to the room, with either `session.FULL_ACCESS`, or `session.READ_ACCESS`.
      ```tsx highlight="15,16"
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

export async function POST(request) {
        const user = { id: "olivier@example.com", info: { name: "Olivier" }};

const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.info } // Optional
        );

const { room } = await request.json();
        session.allow(room, session.FULL_ACCESS);
      }
      ```
    </StepContent>

</Step>

<Step>
    <StepTitle>Authorize the user and return the result</StepTitle>
    <StepContent>
    Give if the current user access to the room, with either `session.FULL_ACCESS`, or `session.READ_ACCESS`.
      ```tsx highlight="18,19"
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

export async function POST(request) {
        const user = { id: "olivier@example.com", info: { name: "Olivier" }};

const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.info } // Optional
        );

const { room } = await request.json();
        session.allow(room, session.FULL_ACCESS);

const { status, body } = await session.authorize();
        return new Response(body, { status });
      }
      ```
    </StepContent>

</Step>

<Step>
    <StepTitle>Point to the new endpoint</StepTitle>
    <StepContent>
    In the front end of your app, update your `liveblocks.config.ts` file to connect to the new endpoint.
    ```ts file="liveblocks.config.ts" highlight="4"
      import { createClient } from "@liveblocks/client";

const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```
    </StepContent>

</Step>

<Step>
  <StepTitle>You’re migrated!</StepTitle>
  <StepContent>
    You’ve successfully migrated, and now have a similar authentication set up
    as before! However, there are other new features we can take advantage of.
  </StepContent>
</Step>

<Step lastStep>
    <StepTitle>Bonus: Issue access to multiple rooms</StepTitle>
    <StepContent>
    With Liveblocks 1.2, you can also issue access to multiple rooms, or even use a prefix-based wildcard in the room name, enabling any amount of rooms! You can learn more about this in our [access token](/docs/authentication/access-token#permissions) guide.
      ```tsx highlight="15-18"
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

export async function POST(request) {
        const user = { id: "olivier@example.com", info: { name: "Olivier" }};

const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.info } // Optional
        );

const { room } = await request.json();
        session.allow(room, session.FULL_ACCESS);
        session.allow("my-room-*", session.READ_ACCESS);
        session.allow("my-other-room", session.READ_ACCESS);

const { status, body } = await session.authorize();
        return new Response(body, { status });
      }
      ```
    </StepContent>

</Step>

</Steps>

### Learn more about access tokens

You can find guides for your specific framework and learn more about permissions
in our [access tokens authentication guides](/docs/authentication/access-token).

Here’s a full working example of access tokens in a Next.js endpoint.

```ts file="app/api/liveblocks-auth/route.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";

// Create a client
const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST(request: Request) {
  const user = __getUserFromDB__(request);

// Start an auth session inside your endpoint
  const session = liveblocks.prepareSession(
    user.id,
    { userInfo: user.metadata } // Optional
  );

// Give the user access to the room
  const { room } = await request.json();
  if (room && __shouldUserHaveAccess__(user, room)) {
    // e.g. session.allow("my-room", ["room:write"])
    session.allow(room, session.FULL_ACCESS);
  }

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  return new Response(body, { status });
}
```

## ID tokens [#id-tokens]

Are you already using our REST API to assign fine-grained permissions to each
room, via [Create room](/docs/api-reference/rest-api-endpoints#post-rooms) or
[Update room](/docs/api-reference/rest-api-endpoints#post-rooms-roomId) APIs? If
so, ID tokens may work best for you.

ID tokens follow the analogy of a _membership card_. Anyone with that membership
card can try to enter a room, but your permissions will be checked at the door.
This approach to permissions is most powerful because it can be set up very
finely, but it comes at the cost of having to keep those permissions
programmatically in sync with Liveblocks. We recommend it for advanced use cases
only.

### Upgrading to ID tokens [#upgrade-to-id-tokens]

If you’ve already set up room permissions using our REST API, then this should
be easy!

First, let’s create a new endpoint in your back end, next to your existing
`/api/auth` endpoint. We recommend going with `/api/liveblocks-auth`.

All you have to do now is implement it as follows:

<Steps>

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });
      ```
    </StepContent>

</Step>

<Step>
    <StepTitle>Identify the user and return the result</StepTitle>
    <StepContent>
    Whichever `userId` (or `groupIds`) you pass will be used to check the permissions you configured in your Liveblocks account already.
      ```tsx highlight="10-15"
      import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
        secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

export async function POST(request) {
        const user = { id: "olivier@example.com", info: { name: "Olivier" }};

const { status, body } = await liveblocks.identifyUser({
          userId: user.id,
          groupIds, // Optional
        });

return new Response(body, { status });
      }
      ```
    </StepContent>

</Step>

const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```
    </StepContent>

</Step>

<Step>
  <StepTitle>You’re migrated!</StepTitle>
  <StepContent>You’ve successfully migrated to id tokens!</StepContent>
</Step>

<Step lastStep>
    <StepTitle>Bonus: Use our REST API to handle permissions</StepTitle>
    <StepContent>
    ID tokens use permissions set with our [REST API](/docs/api-reference/rest-api-endpoints).
    For example, this is how you [create a room](/docs/api-reference/rest-api-endpoints#post-rooms),
    and give a user full access.

```ts highlight="6-8"
    fetch("https://api.liveblocks.io/v2/rooms", {
      method: "POST",
      body: JSON.stringify({
        id: "my-room-name",
        defaultAccesses: [],
        usersAccesses: {
          "olivier@example.com": ["room:write"]
        }
      }),
    });
    ```
    </StepContent>

</Step>
</Steps>

### Learn more about ID tokens

You can find guides for your specific framework and learn more about permissions
in our [ID tokens authentication guides](/docs/authentication/id-token).

Here’s a full working example of ID tokens in a Next.js endpoint.

```ts file="app/api/liveblocks-auth/route.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";

// Create a client
const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST(request: Request) {
  const user = __getUserFromDB__(request);

// Identify the user and return the result
  const { status, body } = await liveblocks.identifyUser({
    userId: user.id,
    groupIds, // Optional
  });

return new Response(body, { status });
}
```

If you have issues with these new patterns and need help, please let us know
[by email](mailto:support@liveblocks.io) or by joining our
[Discord community](/discord)! We’re here to help!

---
meta:
  title: "Upgrading to 1.5"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 1.5"
---

There’s a small breaking changes in this update, as we’re introducing a better
API to enter and leave rooms. If you’re calling `client.enter()` or
`client.leave()` in your application, or using our Zustand or Redux packages, we
recommend you read on.

## How to upgrade? [#how]

You can upgrade to 1.5 by downloading the latest version of each Liveblocks
package you’re using, for example in a React app:

```bash
npm install @liveblocks/client@latest @liveblocks/node@latest @liveblocks/react@latest
```

If you’re using any other Liveblocks packages make sure to update those too.

</Banner>

## Recommended: new enter/leave API

Until now, the API to manually enter a Room using the client looked like the
following:

```tsx
// ❌ We recommend you stop using this API
const room = client.enter("my-room", options);

// Then later, when unmounting
client.leave("my-room");
```

These APIs will remain supported and unchanged, but starting with Liveblocks
1.5, there is a new preferred API, which we recommend you switch to:

```tsx
// ✅ Prefer this API instead
const { room, leave } = client.enterRoom("my-room", options);

// Then later, when unmounting
leave();
```

We’ve changed this API to return a new “leave” function every time a room
reference is requested. This allows sharing the same room connection with two or
more parts of your application, without those parts competing for control of the
room connection. The room connection will only be terminated after every `leave`
function has been called.

This enables more advanced use cases such as supporting multiple `RoomProvider`
instances for the same room ID, in different parts of your application, or using
our React package for one part of your application, while using a Zustand store
for another.

## Upgrading for Zustand users

If you’re using our Zustand package, there’s a breaking change—you no longer
need to pass the room ID to leave the room:

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

// ❌ Before
leaveRoom("my-room-name");

// ✅ After
leaveRoom();
```

## Upgrading for Redux users

If you’re using our Redux package, there’s a similar breaking change—you no
longer need to pass the room ID to leave the room:

```tsx
const dispatch = useDispatch();

// ❌ Before
dispatch(actions.leaveRoom("my-room-name"));

// ✅ After
dispatch(actions.leaveRoom());
```

---
meta:
  title: "Upgrading to 1.9"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 1.9"
---

There’s a tiny breaking change related to Comments in this update. Each date
returned is now a `Date` object, whereas previously each was a `string`.

## How to upgrade? [#how]

You can upgrade to 1.9 by downloading the latest version of each Liveblocks
package you’re using, for example in a React app:

```bash
npm install @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-comments@latest @liveblocks/node@latest
```

If you’re using any other Liveblocks packages make sure to update those too.

</Banner>

## Dates are no longer strings

Each date returned from Comments is now a `Date` object, whereas previously each
was a `string`. An example of this is `createdAt`, a value attached to each
thread.

Before:

```tsx
// ❌ Before - Liveblocks 1.8
const { threads } = useThreads();

// "2023-12-15T14:15:22Z"
console.log(threads[0].createdAt);
```

After:

```tsx
// ✅ After - Liveblocks 1.9
const { threads } = useThreads();

// Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>
console.log(threads[0].createdAt);
```

Every Comments-related date has been updated, such as `createdAt`, `updatedAt`
properties in threads, and `editedAt`, `deletedAt` in comments, so take care to
check every date instance you’re using. It’s likely that no changes are required
after this update.

---
meta:
  title: "Upgrading to 2.0"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.0"
---

Liveblocks 2.0 is our second major release, and focuses on removing any rough
edges and smoothening the developer experience. It makes Liveblocks simpler to
set up for new users as well as for existing users. Our long term goal is to
empower you to write and evolve your apps in the best way possible, and at
enterprise scale.

Skip ahead to the [how to upgrade](#how-to-upgrade) section.

</Banner>

## Rationale

Liveblocks has always embraced the benefits of static typing with TypeScript.
Roughly two years ago, we published 0.17, which
[introduced](/blog/whats-new-in-v0-17) the pattern of calling
`createRoomContext()` and returning a “bundle” of type-safe hooks that you could
then use in your application. This pattern worked nicely because all the hooks
were bound to your custom type definitions for `Presence`, `Storage`, etc. in
one single place, and every Liveblocks API would deeply know about it. No need
for manual type annotations anywhere else in your codebase.

### Downsides to this approach

There were, however, a couple of downsides to this approach that have always
kept itching:

- Importing hooks from a local config file was a little bit awkward. It wasn’t
  an all too familiar pattern for most users.
- Re-exporting the list of hooks took maintenance. If we added a new hook, you’d
  have to also re-export it manually.
- Due to how TypeScript works, the type params you’d provide to
  `createRoomContext()` had a fixed ordering to them. If you wanted to specify
  only `Presence` and `RoomEvent`, you’d have to “skip” some type params, by
  doing `createRoomContext<Presence, {}, {}, RoomEvent>()` or similar.

### Introducing Liveblocks 2.0

With 2.0, this all becomes a lot simpler. We’ve done a lot of internal
refactoring to make this possible. We’ll dive in soon, but here is a sneak peek:

```tsx showLineNumbers={false} file="liveblocks.config.ts"
// ❌ This pattern is no longer recommended unless you need multiple room types
export const {
  suspense: { RoomProvider, useRoom, useThread },
} = createRoomContext<
  MyPresence,
  MyStorage,
  MyUserMeta,
  MyRoomEvent,
  MyThreadMetadata
>(client);

// ✅ After
declare global {
  // These custom types are all optional, just define the ones you want/need
  interface Liveblocks {
    Presence: MyPresence;
    Storage: MyStorage;
    UserMeta: MyUserMeta;
    RoomEvent: MyRoomEvent;
    ThreadMetadata: MyThreadMetadata;
  }
}
```

```tsx showLineNumbers={false} file="Component.tsx"
// ❌ Before
import { RoomProvider, useRoom, useThreads } from "./liveblocks.config.ts";

// ✅ After
import { RoomProvider, useRoom, useThreads } from "@liveblocks/react/suspense";
// or
import { RoomProvider, useRoom, useThreads } from "@liveblocks/react";
```

We’ll first go over all the breaking changes, then we’ll show you how to
simplify your codebase.

## How to upgrade [#how-to-upgrade]

First of all, let’s upgrade all Liveblocks dependencies to their latest
versions. The easiest way to do that is to run the following command:

```bash
npx liveblocks@latest upgrade
```

There are also some **breaking changes** in this update. **Most users will not
run into any of these**, but there is a chance that some of these will affect
your situation. Making the necessary code adjustments should however be easy. In
many cases, we provide a codemod that makes the actual change for you, so you
don’t have to do so manually.

### Breaking change 1: renamed package [#bc1]

This breaking change only affects users of `@liveblocks/react-comments`.

</Banner>

We’ve renamed our package `@liveblocks/react-comments` to
`@liveblocks/react-ui`, because our library of pre-built UI components now
contains more than just Comments-related components. Please adjust your imports.

Run the following **codemod** or manually make the changes:

```bash
npx @liveblocks/codemod@latest react-comments-to-react-ui
```

This will change your imports like this:

```tsx showLineNumbers={false}
// ❌ Before
import { Thread } from "@liveblocks/react-comments";

// ✅ After
import { Thread } from "@liveblocks/react-ui";
```

And also:

```tsx showLineNumbers={false}
// ❌ Before
<CommentsConfig />

// ✅ After
<LiveblocksUIConfig />
```

### Breaking change 2: renamed exports in our Node package [#bc2]

This breaking change only affects users of `@liveblocks/node`.

</Banner>

To avoid confusion with the newly introduced custom
[`RoomInfo`](#New-custom-type-RoomInfo) type, we’ve renamed the `RoomInfo` type
in our `@liveblocks/node` package.

Run the following **codemod** or manually make the changes:

```bash
npx @liveblocks/codemod@latest room-info-to-room-data
```

This will change:

```tsx showLineNumbers={false}
// ❌ Before
import { RoomInfo } from "@liveblocks/node";
const rooms: RoomInfo[] = [];

// ✅ After
import { RoomData } from "@liveblocks/node";
const rooms: RoomData[] = [];
```

### Breaking change 3: client methods from our Node package no longer take type params [#bc3]

This breaking change only affects users of `@liveblocks/node`.

</Banner>

In `@liveblocks/node`, none of the client methods, like
`liveblocks.getThread()`, take type params any longer.

Make the following changes:

```tsx showLineNumbers={false}
// ❌ Before
await liveblocks.createThread<MyThreadMetadata>();
await liveblocks.editThreadMetadata<MyThreadMetadata>();
await liveblocks.getThreads<MyThreadMetadata>();
await liveblocks.getThread<MyThreadMetadata>();
//                         ^^^^^^^^^^^^^^^^ No longer possible

// ✅ After
await liveblocks.createThread();
await liveblocks.editThreadMetadata();
await liveblocks.getThreads();
await liveblocks.getThread();

// In liveblocks.config.ts
declare global {
  interface Liveblocks {
    ThreadMetadata: MyThreadMetadata;
  }
}
```

You should use global type augmentation instead. Please see
[“Simplifying your Liveblocks application”](#simplifying) below for a lot more
detail on this transition.

### Breaking change 4: changed default export to named export in Yjs package [#bc4]

This breaking change only affects users of `@liveblocks/yjs`.

</Banner>

To make discoverability and refactorings easier, and to avoid confusion with the
newly introduced [`LiveblocksProvider`][] in our React package, we’re no longer
using default exports, but named exports only.

Run the following **codemod** or manually make the changes:

```bash
npx @liveblocks/codemod@latest remove-yjs-default-export
```

This will change your import (and its usage) like this:

```tsx showLineNumbers={false}
// ❌ Before
import LiveblocksProvider from "@liveblocks/yjs";
const yDoc = new Y.Doc();
const yProvider = new LiveblocksProvider(room, yDoc);
```

```tsx showLineNumbers={false}
// ✅ After
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, yDoc);
```

### Breaking change 5: minor LiveList constructor change [#bc5]

This breaking change only affects users of Storage.

</Banner>

The `LiveList()` constructor’s argument is no longer optional, because it causes
unneeded but confusing type inference issues.

Run the following **codemod** or manually make the changes:

```bash
npx @liveblocks/codemod@latest live-list-constructor
```

This will add an array to empty `LiveList` constructors:

```tsx showLineNumbers={false}
// ❌ Before
const mylist = new LiveList();

// ✅ After
const mylist = new LiveList([]);
```

### Breaking change 6: new webhook event types [#bc6]

This breaking change only affects users of webhooks.

</Banner>

The webhook event `NotificationEvent`’s type can represent multiple kinds of
notifications: `"thread"`, `"textMention"`, and custom ones (e.g.
`"$myNotification"`).

If you were using properties only available on the `"thread"` kind (e.g.
`threadId`), you will need to first check for the kind of notification before
accessing them.

```ts showLineNumbers={false}
// ❌ Before
const threadId = event.data.threadId;

// ✅ After
if (event.data.kind === "thread") {
  const threadId = event.data.threadId;
}
```

### Breaking change 7: removed deprecated APIs [#bc7]

All of the following APIs have been removed in 2.0, as they were deprecated
multiple versions ago.

**Affecting `@liveblocks/client`:**

- `Client.enter()` has been replaced by `Client.enterRoom()`
- `Client.leave()` has been replaced by `Client.enterRoom()`, which returns a
  `leave` function
- Client option `fetchPolyfill`, `WebSocketPolyfill`, are replaced by
  `polyfills: { fetch, WebSocket }`
- Legacy option `shouldInitiallyConnect` is now renamed to `autoConnect`
- Legacy connection status APIs, e.g. `room.getConnectionState()` and
  `.subscribe("connection")`. You can use `.getStatus()` or
  `.subscribe("status")` instead.
- `user.isReadOnly` field is replaced by `!user.canWrite` (note the negation
  here)
- The `Others<P, U>` type. Please change to `readonly User<P, U>[]`.

**Affecting `@liveblocks/react`:**

- The `useMap`, `useList`, and `useObject` hooks. These have been deprecated
  since the release of 0.18 (more than two years ago). Please see
  [the 0.18 upgrade guide](/docs/platform/upgrading/0.18#Step-5a:-Replace-reads-with-useStorage)
  for tips on how to rewrite these hooks to `useStorage`.
- The second argument `options` to `createRoomContext(client, options)` has been
  removed. These options have been moved to the client.

**Affecting `@liveblocks/node`:**

- Remove legacy `authorize` method from `@liveblocks/node`. Please refer to
  [the 1.2 upgrade guide](/docs/platform/upgrading/1.2#how) to learn how to
  upgrade your auth endpoint.

**Affecting `@liveblocks/redux` and `@liveblocks/zustand`:**

- Legacy aliased exports in Zustand/Redux packages are removed

## Simplifying your Liveblocks application (optional) [#simplifying]

This section is optional, but highly recommended. You can do it now, or come
back to do it later.

</Banner>

If you have dealt with the breaking changes above, or concluded they they don’t
apply to your situation, we can go a step further and really simplify your
Liveblocks setup.

If your Liveblocks application has multiple room types, and therefore you have
multiple Liveblocks config files—one for each room type—then you cannot switch
to a single global type definition. In that advanced case, the following
simplifications do not apply to you. We will keep supporting the
`createRoomContext` API for these advanced use cases, but no longer recommend it
for the more common case of having just a single room type.

</Banner>

### Step 1: Use the new global Liveblocks custom types [#step1]

Go to your `liveblocks.config.ts`, find your `createRoomContext()` call. Now
decide which codemod to run.

**Option 1: You are using Suspense hooks.**
(`const { suspense: { useRoom, ... } }`)

```bash
npx @liveblocks/codemod@latest remove-liveblocks-config-contexts --suspense
```

**Option 2: You are using classic hooks.** (`const { useRoom, ... }`)

```bash
npx @liveblocks/codemod@latest remove-liveblocks-config-contexts
```

Running either of these will make the following changes.

```tsx showLineNumbers={false}
// ❌ Before
export const {
  ...
} = createRoomContext<MyPresence, MyStorage, MyUserMeta, MyRoomEvent, MyThreadMetadata>(client);
```

```tsx showLineNumbers={false}
// ✅ After
declare global {
  interface Liveblocks {
    Presence: MyPresence;
    Storage: MyStorage;
    UserMeta: MyUserMeta;
    RoomEvent: MyRoomEvent;
    ThreadMetadata: MyThreadMetadata;
  }
}
```

Secondly, it will change all imports in your code base to import the hooks
directly instead:

```tsx showLineNumbers={false}
// ❌ Before
import { RoomProvider, useRoom, ... } from "./liveblocks.config.ts";
```

```tsx showLineNumbers={false}
// ✅ After
import { RoomProvider, useRoom, ... } from "@liveblocks/react/suspense";  // Option 1
import { RoomProvider, useRoom, ... } from "@liveblocks/react";           // Option 2
```

### Step 2: Set up a LiveblocksProvider [#step2]

At this point, there should not be any new TypeScript issues. However, running
the code will not yet work. This is because previously the hooks were bound to
the `client` instance by passing it to the `createRoomContext()` factory, which
we now removed. When using the global types, we’ll have to provide the
Liveblocks client otherwise.

The way to do it is to use a pretty standard React provider. Make the following
change:

```tsx showLineNumbers={false} file="liveblocks.config.ts"
// ❌ Before, you no longer have to use createClient()
import { createClient } from "@liveblocks/client";

const client = createClient({
  authEndpoint: "/api/liveblocks-auth",
  throttle: 16,
  /* etc */
);
```

```tsx showLineNumbers={false} file="layout.tsx"
// ✅ After
"use client";

import { LiveblocksProvider } from "@liveblocks/react";

export function Layout({ children }) {
  return (
    // Move options here, client will be created for you
    <LiveblocksProvider
      authEndpoint="/api/liveblocks-auth"
      throttle={16}
      /* etc */
    >
      {children}
    </LiveblocksProvider>
  );
}
```

We recommend placing the `LiveblocksProvider` as high up your component tree as
you can, preferably in your `_app.tsx` or `layout.tsx` (or equivalent for your
React framework of choice). Unfortunately, we cannot provide a codemod for this
step, because we cannot mechanically decide where exactly to inject the
Liveblocks provider in your application.

</Banner>

If you were exporting the `client` instance before and have components that
directly accessed it before, you can now obtain a reference to the `client`
instance that the `LiveblocksProvider` creates for you using the `useClient`
hook:

```tsx showLineNumbers={false}
// ❌ Before
import { client } from "./liveblocks.config";

function MyComponent() {
  doSomethingWith(client);
}
```

```tsx showLineNumbers={false}
// ✅ After
import { useClient } from "@liveblocks/react"; // or
import { useClient } from "@liveblocks/react/suspense";

function MyComponent() {
  const client = useClient();
  doSomethingWith(client);
}
```

### Step 3: Optional cleanup of type params [#step3]

If you also exported your `Presence`, `Storage`, etc types from
`liveblocks.config.ts` before, you no longer have to. The main reason to export
these before was to use them in helper functions that used some of the
Liveblocks types, like `User`, or `Room`.

```bash
npx @liveblocks/codemod@latest remove-unneeded-type-params
```

For example:

```tsx showLineNumbers={false}
import type { Room, User } from "@liveblocks/client";
import type { MyPresence, MyStorage } from "./liveblocks.config";

// ❌ Before
function isAdult(user: User<MyPresence, MyUserMeta>) {
  //                        ^^^^^^^^^^^^^^^^^^^^^^
  return user.info.age >= 18;
  //               ^^^ Coming from MyUserMeta
}

// ❌ Before
function doSomethingWithRoom(
  room: Room<MyPresence, MyStorage, MyUserMeta, never>
  //         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
) {
  /* ... */
}
```

This is no longer needed. You can simply remove them. TypeScript will still know
about your custom `age` property on `user.info`.

```tsx showLineNumbers={false}
import type { Room, User } from "@liveblocks/client";

// ✅ After
function isAdult(user: User) {
  return user.info.age >= 18;
  //               ^^^ Still coming from configured UserMeta custom type
}

// ✅ After
function doSomethingWithRoom(room: Room) {
  /* ... */
}
```

## Improvements

Furthermore, the following miscellaneous quality-of-life improvements have been
made that are non-breaking changes.

### `ClientSideSuspense` no longer needs a function

Previously, the `ClientSideSuspense` helper needed a function as its `children`
prop, but it no longer has to.

```bash
npx @liveblocks/codemod@latest simplify-client-side-suspense-children
```

This will change:

```tsx showLineNumbers={false}
// ❌ Before
<ClientSideSuspense fallback={<Loading />}>
  {() => <MyApp />}
</ClientSideSuspense>
```

```tsx showLineNumbers={false}
// ✅ After
<ClientSideSuspense fallback={<Loading />}>
  <MyApp />
</ClientSideSuspense>
```

### Improved `InboxNotification` props types

When passing custom components to the `kinds` prop of [`InboxNotification`][],
you could use types like `InboxNotificationThreadProps` for the props. But this
wasn’t always true for all notification kinds, so now you can use types named
`InboxNotificationThreadKindProps` for your components, while
`InboxNotificationThreadProps` describes the props of our own
`InboxNotification.Thread`.

```tsx showLineNumbers={false}
// ❌ Before
function MyThreadNotification(props: InboxNotificationThreadProps) {
  return <InboxNotification.Thread {...props} />;
}

<InboxNotification kinds={{ thread: MyThreadNotification }} />;
```

```tsx showLineNumbers={false}
// ✅ After
function MyThreadNotification(props: InboxNotificationThreadKindProps) {
  //                                                        ^^^^
  return <InboxNotification.Thread {...props} />;
}

<InboxNotification kinds={{ thread: MyThreadNotification }} />;
```

### New custom type `RoomInfo`

By using the [`resolveRoomsInfo`][] callback from [`createClient`][] or the new
[`LiveblocksProvider`][], you can attach arbitrary room data to a room, which
you can retrieve with the [`useRoomInfo`][] hook.

Both of these APIs will now respect the type you provide via:

```tsx showLineNumbers={false}
declare global {
  interface Liveblocks {
    RoomInfo: {
      /* your custom type definition here */
    };
  }
}
```

### New custom type `ActivitiesData`

By providing a custom `ActivitiesData` type, you can improve how your custom
notifications and their activities’ data are typed.

```tsx showLineNumbers={false}
declare global {
  interface Liveblocks {
    // Custom activities data for custom notification kinds
    ActivitiesData: {
      // Example, a custom $alert kind
      $alert: {
        title: string;
        message: string;
      };
    };

// Other kinds
    // ...
  }
}
```

That’s it!

## Questions? Please ask!

If you have any trouble with these new patterns, run into a bug with one of the
codemods, or otherwise need help, please let us know
[by email](mailto:support@liveblocks.io) or by joining our
[Discord community](/discord)! We’re here to help!

[`createClient`]: /docs/api-reference/liveblocks-client#createClient
[`LiveblocksProvider`]: /docs/api-reference/liveblocks-react#LiveblocksProvider
[`InboxNotification`]: /docs/api-reference/liveblocks-react-ui#InboxNotification
[`resolveRoomsInfo`]:
  /docs/api-reference/liveblocks-client#createClientResolveRoomsInfo
[`useRoomInfo`]: /docs/api-reference/liveblocks-react#useRoomInfo

---
meta:
  title: "Upgrading to 2.15"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.15"
---

This version of Liveblocks drops support for React versions below 18.

## Does this affect you? [#does-this-affect-you]

If you are **already on React 18 or above**, you do not have to do anything.
Just enjoy the smaller bundle size and performance improvements!

If **you are on React 16 or 17**, you should upgrade React before upgrading
Liveblocks to 2.15. See the [instructions below](#how-to-upgrade).

If **you cannot upgrade to React 18 yet** for whatever reason, you can still
keep using Liveblocks 2.14 which is the last version to support React 17 and
below.

## How to upgrade? [#how-to-upgrade]

To upgrade Liveblocks to 2.15, first upgrade React to 18 by following the
[How to Upgrade to React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide).

Then, upgrade all Liveblocks packages by running:

```bash
npx liveblocks@latest upgrade
```

You can now safely remove this line from your codebase:

```diff
-import { unstable_batchedUpdates } from "react-dom";
 //                                      ^^^^^^^^^^^ ...or "react-native"!

<RoomProvider
   id="my-room"
   initialPresence={/* ... */}
   initialStorage={/* ... */}
-  unstable_batchedUpdates={unstable_batchedUpdates}
 >
   <App />
 </RoomProvider>
```

That’s it!

---
meta:
  title: "Upgrading to 2.16"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.16"
---

We’ve made React changes, affecting how our error listener hook works, and how
undefined metadata is filtered in Comments.

## How to upgrade

Upgrade to 2.16 by downloading the latest version of each Liveblocks package
you’re using. The easiest way to do this is to run the following command:

```bash
npx liveblocks@latest upgrade
```

## Does this affect you? [#does-this-affect-you]

**If you’re using the [`useErrorListener`][] hook**, please read about
[a behavior change](#change-1).

**If you’re using Comments in React**, please read about
[the change to metadata filtering](#change-2).

Otherwise, no changes will affect you.

## New errors can appear in `useErrorListener` [#change-1]

From 2.16, [`useErrorListener`][] will notify you about new errors. Previously,
only room connection errors were previously reported, possible if you were using
Presence, Storage, or Yjs. After upgrading, you can also receive a number of
errors from Comments and Notifications.

```tsx
import { useErrorListener } from "@liveblocks/react";

useErrorListener((error) => {
  switch (error.context.type) {
    // +++
    case "CREATE_THREAD_ERROR":
      const { roomId, threadId, commentId, body, metadata } = error.context;
      break;
    // +++

// +++
    case "MARK_INBOX_NOTIFICATION_AS_READ_ERROR":
      const { inboxNotificationId, roomId } = error.context;
      break;
    // +++

// Many other new errors
    // ...
  }
});
```

For a full list of possible errors, see the [`useErrorListener`][]
documentation.

We have also decoupled [`useErrorListener`][] from the current room. Previously
it required to be nested under a
[`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider). Now, you
can use it anywhere under
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
and it will notify you about errors from all rooms.

### To upgrade [#upgrade-change-1]

No changes are necessary to upgrade, however **if you would like to keep the old
behavior** and only show room connection errors, you can filter out all new
errors with an early return:

```ts
import { useErrorListener, useRoom } from "@liveblocks/react";

function App() {
  // +++
  const room = useRoom();
  // +++

useErrorListener((error) => {
    // +++
    if (
      error.context.roomId !== room.id &&
      error.context.type !== "ROOM_CONNECTION_ERROR"
    ) {
      return;
    }
    // +++

// Your previous logic
  });
}
```

## Ability to filter threads by absence of metadata [#change-2]

From 2.16, the [`useThreads`][] (and `useUserThreads_experimental`) hooks
supports filtering by _absence_ of a metadata field using `null`.

```ts
// ✅ Will now return "important" threads without a `color` field
const threads = useThreads({
  query: {
    metadata: {
      // +++
      color: null,
      // +++
      label: "important",
    },
  },
});
```

Previously this was not supported, but due to a bug, using an explicit
`undefined` would already allow you to do this. However, threads weren’t
filtered correctly in our back end causing over-fetches.

### To upgrade [#upgrade-change-2]

If you relied on this bug, change `undefined` to `null` in any metadata
properties. **This will keep behavior the same**—if you don’t make this change,
then your previous filtering will no longer work.

```ts title="Before"
const threads = useThreads({
  query: {
    metadata: {
      // ❌ Before - Will have no effect in 2.16
      // +++
      color: undefined,
      // +++
      label: "important",
    },
  },
});
```

```ts title="After"
const threads = useThreads({
  query: {
    metadata: {
      // ✅ After - Will now find threads without a `color`
      // +++
      color: null,
      // +++
      label: "important",
    },
  },
});
```

That’s it for 2.16!

[`useerrorlistener`]: /docs/api-reference/liveblocks-react#useErrorListener
[`usethreads`]: /docs/api-reference/liveblocks-react#useThreads

---
meta:
  title: "Upgrading to 2.2"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.2"
---

You must upgrade to 2.0 first, please follow the
[2.0 upgrade guide](/docs/platform/upgrading/2.0).

</Banner>

We are making `resolved` a first-class citizen property on
[threads](/docs/ready-made-features/comments/concepts#Threads). You don’t have
to use a thread’s metadata to set a thread as resolved anymore.

## How to upgrade? [#how]

You can upgrade to 2.2 by downloading the latest version of each Liveblocks
package you’re using. The easiest way to do that is to run the following
command:

```bash
npx liveblocks@latest upgrade
```

## All changes are for Comments

If you are not using Comments or are not using the `resolved` metadata property,
there are no breaking changes for you! However, if you are and have logic based
on the webhook event `threadMetadataUpdated`, keep reading.

### Webhook events

When you upgrade to 2.2, the default
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component will update
the thread’s first-class citizen property instead of the metadata. When a thread
is marked as resolved or unresolved, we will send the events
[`threadMarkedAsResolved`](/docs/platform/webhooks#ThreadMarkedAsResolvedEvent)
and
[`threadMarkedAsUnresolved`](/docs/platform/webhooks#ThreadMarkedAsUnresolvedEvent)
instead of
[`threadMetadataUpdated`](/docs/platform/webhooks#ThreadMarkedAsUnresolvedEvent).

Before upgrading to 2.2, you should update your webhook endpoint to process
those new events accordingly.

### REST API endpoints

If you use the REST endpoint
[`Edit thread metadata`](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-metadata)
to update the metadata `resolved`, you should instead use the endpoints
[`Mark thread as resolved`](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-mark-as-resolved)
and
[`Mark thread as unresolved`](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-mark-as-unresolved).

Note that updating the `resolved` metadata property automatically updates the
first-class citizen one.

---
meta:
  title: "Upgrading to 2.24"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.24"
---

We’ve renamed some of the concepts around notifications and notification
settings to improve clarity.

## How to upgrade

Upgrade to 2.24 by downloading the latest version of each Liveblocks package
you’re using. The easiest way to do this is to run the following command:

```bash
npx liveblocks@latest upgrade
```

## Does this affect you? [#does-this-affect-you]

If you are using notification settings in any way—with [`@liveblocks/client`][],
[`@liveblocks/react`][], [`@liveblocks/node`][], or
[the REST API](/docs/api-reference/rest-api-endpoints)—continue reading to see
the changes. The naming changes are **backwards compatible**.

Otherwise, no changes will affect you.

## Naming changes

### Rationale

Historically, we used the term “notification settings” to refer to
**room-level** settings that control the
[inbox notifications](/docs/ready-made-features/notifications/concepts#Inbox-Notifications)
received by a user (e.g. setting `"threads"` to `"all"` would make the user
receive inbox notifications for any threads activity in the room, not just the
ones where they participate).

With 2.18, we introduced the concept of “**user** notification settings”, which
are **project-level** settings that control the notifications (
[`"notification"` webhook events](/docs/platform/webhooks#NotificationEvent),
not "inbox notifications") received by a user (e.g. setting
`email.$myCustomNotification` to `false` would disable `"notification"` webhook
events for the `$myCustomNotification` kind and the `email` channel).

To improve clarity, we’re renaming these concepts:

- “room **notification** settings” → “room **subscription** settings”: they
  control which things a user is subscribed to in a room
- “**user** notification settings” → “notification settings”: they control which
  notifications a user receives

### What changed

All methods, hooks, types, and REST API endpoints that were using these terms
have been renamed to use the new naming, see the examples below.

We provide a codemod to automatically update your codebase to the new naming.

```bash
npx @liveblocks/codemod@latest rename-notification-settings
```

#### `@liveblocks/react`

```tsx
// ❌ Before
import {
  // +++
  useRoomNotificationSettings,
  useUpdateRoomNotificationSettings,
  // +++
} from "@liveblocks/react";

// ✅ After
import {
  // +++
  useRoomSubscriptionSettings,
  useUpdateRoomSubscriptionSettings,
  // +++
} from "@liveblocks/react";
```

```tsx
// ❌ Before
useErrorListener((error) =>
  // +++
  if (error.context.type === "UPDATE_NOTIFICATION_SETTINGS_ERROR") {
    // +++
    /* ... */
  }
);

// ✅ After
useErrorListener((error) =>
  // +++
  if (error.context.type === "UPDATE_ROOM_SUBSCRIPTION_SETTINGS_ERROR") {
    // +++
    /* ... */
  }
);
```

#### `@liveblocks/client`

```tsx
// ❌ Before
import type { RoomNotificationSettings } from "@liveblocks/client";

// ✅ After
import type { RoomSubscriptionSettings } from "@liveblocks/client";
```

```tsx
// ❌ Before
const { room, leave } = client.enterRoom("my-room-id");

// +++
room.getNotificationSettings();
room.updateNotificationSettings(/* ... */);
// +++

// ✅ After
const { room, leave } = client.enterRoom("my-room-id");

// +++
room.getSubscriptionSettings();
room.updateSubscriptionSettings(/* ... */);
// +++
```

```tsx
// ❌ Before
import type { UserNotificationSettings } from "@liveblocks/client";

// ✅ After
import type { NotificationSettings } from "@liveblocks/client";
```

#### `@liveblocks/node`

```tsx
// ❌ Before
const liveblocks = new Liveblocks({
  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});

// +++
await liveblocks.getRoomNotificationSettings(/* ... */);
await liveblocks.updateRoomNotificationSettings(/* ... */);
await liveblocks.deleteRoomNotificationSettings(/* ... */);
// +++

// ✅ After
const liveblocks = new Liveblocks({
  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});

// +++
await liveblocks.getRoomSubscriptionSettings(/* ... */);
await liveblocks.updateRoomSubscriptionSettings(/* ... */);
await liveblocks.deleteRoomSubscriptionSettings(/* ... */);
// +++
```

#### REST API

```shell
# ❌ Before
https://api.liveblocks.io/v2/rooms/:roomId/users/:userId/notification-settings

# ✅ After
https://api.liveblocks.io/v2/rooms/:roomId/users/:userId/subscription-settings
```

That’s it for 2.24!

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`@liveblocks/node`]: /docs/api-reference/liveblocks-node

---
meta:
  title: "Upgrading to 2.8"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.8"
---

We are introducing attachments to allow users to add files to their comments.

## How to upgrade? [#how]

You can upgrade to 2.8 by downloading the latest version of each Liveblocks
package you’re using. The easiest way to do that is to run the following
command:

```bash
npx liveblocks@latest upgrade
```

## All changes are for Comments

If you are not using Comments or are not using
[the default Comments components](/docs/ready-made-features/comments/default-components),
there are no breaking changes for you! However, if you are, or intend to use
them later, keep reading.

## Attachments

Liveblocks 2.8 adds attachments to Comments, and while not a breaking change, it
is mostly enabled by default in the default components. We recommend you either
[enable attachments](#enable-attachments) or
[disable attachments](#disable-attachments) when you upgrade.

### Enable attachments [#enable-attachments]

Attachments are enabled by default, but if you’re using
[`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread),
[`useCreateComment`](/docs/api-reference/liveblocks-react#useCreateComment), or
[`useEditComment`](/docs/api-reference/liveblocks-react#useEditComment), you can
now pass these an attachments array.

```tsx
const createThread = useCreateThread();

// ❌ Before - Liveblocks 2.7
createThread({ body: {}, metadata: {} });

// ✅ After - Liveblocks 2.8
createThread({ body: {}, attachments: [], metadata: {} });
```

These hooks are most commonly used to enable
[custom Composer behavior](/docs/api-reference/liveblocks-react-ui#Custom-behavior)
with `onComposerSubmit`, which now provides the `attachments` array for you. You
must pass this to your mutations for attachments to work correctly.

```tsx
const createThread = useCreateThread();

// ❌ Before - Liveblocks 2.7
<Composer
  onComposerSubmit={({ body }, event) => {
    event.preventDefault();
    createThread({ body, metadata: {} });
  }}
/>

// ✅ After - Liveblocks 2.8
<Composer
// +++
  onComposerSubmit={({ body, attachments }, event) => {
    // +++
    event.preventDefault();
    // +++
    createThread({ body, attachments, metadata: {} });
    // +++
  }}
/>
```

Remember that this applies to
[`useCreateComment`](/docs/api-reference/liveblocks-react#useCreateComment) and
[`useEditComment`](/docs/api-reference/liveblocks-react#useEditComment) too, not
just [`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread).
No further changes are necessary to enable attachments in the default
components.

{/* TODO If you’re using primitives you must ... */}

### Disable attachments [#disable-attachments]

If you’d prefer to disable attachments, you can do so by setting the
`showAttachments` prop to `false` on each of the following components:
[`Composer`](/docs/api-reference/liveblocks-react-ui#Composer),
[`Comment`](/docs/api-reference/liveblocks-react-ui#Comment),
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread), and
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification.Thread).

```tsx
// Disable attachments
<Composer showAttachments={false} ... />
<Comment showAttachments={false} ... />
<Thread showAttachments={false} ... />
<InboxNotification showAttachments={false} ... />
```

## Default Composer component structure

The default [`Composer`](/docs/api-reference/liveblocks-react-ui#Composer)
component’s structure has slightly changed, so if you customized its styles:
make sure to check if and how the new structure affects your changes.

```html

<form class="lb-root lb-composer lb-composer-form">
  
</form>

<form class="lb-root lb-composer lb-composer-form">
  <div class="lb-composer-editor-container">
    
  </div>
</form>
```

---
meta:
  title: "Upgrading to 2.9"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 2.9"
---

We are introducing pagination to Comments and Notifications as default. You need
to upgrade your app to handle this.

## How to upgrade? [#how]

You can upgrade to 2.9 by downloading the latest version of each Liveblocks
package you’re using. The easiest way to do that is to run the following
command:

```bash
npx liveblocks@latest upgrade
```

## All changes are for Comments & Notifications

If you’re not using
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads) or
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
there are no breaking changes for you! However, if you are using them, keep
reading.

## Pagination

[`useThreads`](/docs/api-reference/liveblocks-react#useThreads) and
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
now only fetch the **latest 50 threads/notifications**, and you must use
paginate to retrieve more. Previously, these two functions would fetch every
single thread/notification, but this is no longer possible.

<Banner type="warning">
  If your rooms have fewer than 50 threads, and your users fewer than 50
  notifications, there will be no visible difference when upgrading. Pagination
  is only used after 50.
</Banner>

### Threads

Here’s a before and after example with
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads), adding
pagination.

```tsx title="Before"
import { useThreads } from "@liveblocks/react/suspense";

function Threads() {
  const { threads } = useThreads();

return (
    <div>
      {threads.map((thread) => (
        <Thread key={thread.id} thread={thread} />
      ))}
    </div>
  );
}
```

```tsx title="After"
import { useThreads } from "@liveblocks/react/suspense";

function Threads() {
  const {
    threads,
    // +++
    fetchMore,
    isFetchingMore,
    hasFetchedAll,
    fetchMoreError,
    // +++
  } = useThreads();

// +++
  const loadMore = fetchMoreError ? (
    <>
      <p>Error loading more threads: {fetchMoreError.message}</p>
      <button onClick={fetchMore} disabled={isFetchingMore}>
        Retry
      </button>
    </>
  ) : (
    <button onClick={fetchMore} disabled={isFetchingMore}>
      Load more
    </button>
  );
  // +++

return (
    <div>
      {threads.map((thread) => (
        <Thread key={thread.id} thread={thread} />
      ))}
      // +++
      {hasFetchedAll ? <div>🎉 You're all caught up!</div> : loadMore}
      // +++
    </div>
  );
}
```

### Notifications

Here’s a before and after example with
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications),
adding pagination.

```tsx title="Before"
import { useInboxNotifications } from "@liveblocks/react/suspense";

function Notifications() {
  const { inboxNotifications } = useInboxNotifications();

return (
    <div>
      {inboxNotifications.map((notification) => (
        <InboxNotification key={notification.id} inboxNotification={no†ification} />
      ))}
    </div>
  );
}
```

```tsx title="After"
import { useInboxNotifications } from "@liveblocks/react/suspense";

function Notifications() {
  const {
    inboxNotifications,
    // +++
    fetchMore,
    isFetchingMore,
    hasFetchedAll,
    fetchMoreError,
    // +++
  } = useInboxNotifications();

// +++
  const loadMore = fetchMoreError ? (
    <>
      <p>Error loading more notifications: {fetchMoreError.message}</p>
      <button onClick={fetchMore} disabled={isFetchingMore}>
        Retry
      </button>
    </>
  ) : (
    <button onClick={fetchMore} disabled={isFetchingMore}>
      Load more
    </button>
  );
  // +++

return (
    <div>
      {inboxNotifications.map((notification) => (
        <InboxNotification key={notification.id} inboxNotification={no†ification} />
      ))}
      // +++
      {hasFetchedAll ? <div>🎉 You're all caught up!</div> : loadMore}
      // +++
    </div>
  );
}
```

### Learn more

Learn more about pagination under
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads) and
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications).

---
meta:
  title: "Upgrading to 3.0"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 3.0"
---

Liveblocks 3.0 is our third major release, focusing on our newest product,
[AI Copilots](https://liveblocks.io/blog/meet-liveblocks-3-0-the-fastest-way-to-let-your-users-collaborate-with-ai-in-your-product).
We’ve used this as an opportunity to tidy up some of our existing APIs, ensuring
consistency throughout our offering.

## How to upgrade [#how-to-upgrade]

First of all, let’s upgrade all Liveblocks dependencies to their latest
versions. The easiest way to do that is to run the following command:

```bash
npx liveblocks@latest upgrade
```

There are some **breaking changes** in this update.

## Does this affect you? [#does-this-affect-you]

**If you’re using TypeScript 4.9 or lower**, TypeScript 5.0 is now the minimum
supported version.

**If you’re using [Comments](/docs/ready-made-features/comments) and/or
[Text Editor](/docs/ready-made-features/text-editor)**, please read about
[changes to mentions](#mentions).

**If you’re using [Notifications](/docs/ready-made-features/notifications)**,
please read about
[a change related to notification settings](#notification-settings).

**If you’re using
[`@liveblocks/emails`](/docs/api-reference/liveblocks-emails)**, please read
about [changes to its returned values](#liveblocks-emails).

**If you’re using
[`LiveblocksUIConfig`](/docs/api-reference/liveblocks-react-ui#LiveblocksUiConfig)**,
please read about [its renaming](#liveblocks-ui-config).

**If you’re using any deprecated APIs** (e.g. `useBatch`, `useStorageStatus`,
`useEditorStatus`…), please read about [the ones being removed](#deprecated).

Otherwise, you can simply upgrade your packages and no changes will affect you.

## Mentions [#mentions]

We’re making some changes to mentions in Comments and Text Editor to support
different mention kinds in future releases: user mentions, group mentions, etc.

### Components [#mentions-components]

The `onMentionClick` prop on [`Thread`][] and [`Comment`][] now receives a
`MentionData` object as its first argument instead of a `userId` string.

```tsx
// ❌ Before
onMentionClick(userId: string, event: MouseEvent<HTMLElement>) => void;
// userId: "user-0"

// ✅ After
onMentionClick(mention: MentionData, event: MouseEvent<HTMLElement>) => void;
// mention: { kind: "user", id: "user-0" }
```

### Primitives [#mentions-primitives]

When customizing the
[`Mention`](/docs/api-reference/liveblocks-react-ui#primitives-Comment.Body-Mention)
component on the [`Comment.Body`][] and [`Composer.Editor`][] primitives, the
`userId` prop has been replaced by a `mention` one which is a `MentionData`
object.

```tsx
import { Comment, Composer } from "@liveblocks/react-ui/primitives";

// ❌ Before
<Comment.Body
  components={{
    // +++
    Mention: ({ userId }) => <Comment.Mention>@{userId}</Comment.Mention>,
    // +++
  }}
/>;
<Composer.Editor
  components={{
    // +++
    Mention: ({ userId, isSelected }) => (
      <Composer.Mention>@{userId}</Composer.Mention>
    ),
    // +++
  }}
/>;

// ✅ After
<Comment.Body
  components={{
    // +++
    Mention: ({ mention }) => <Comment.Mention>@{mention.id}</Comment.Mention>,
    // +++
  }}
/>;
<Composer.Editor
  components={{
    // +++
    Mention: ({ mention, isSelected }) => (
      <Composer.Mention>@{mention.id}</Composer.Mention>
    ),
    // +++
  }}
/>;
```

When customizing the
[`MentionSuggestions`](/docs/api-reference/liveblocks-react-ui#primitives-Composer.Editor-MentionSuggestions)
component on the [`Composer.Editor`][] primitive, the `userIds` prop has been
replaced by a `mentions` one which is an array of `MentionData` objects, and the
`selectedUserId` prop has been renamed to `selectedMentionId`.

```tsx
import { Composer } from "@liveblocks/react-ui/primitives";

// ❌ Before
<Composer.Editor
  components={{
    // +++
    MentionSuggestions: ({ userIds, selectedUserId }) => (
      // +++
      <Composer.Suggestions>
        <Composer.SuggestionsList>
          // +++
          {userIds.map((userId) => (
            <Composer.SuggestionsListItem key={userId} value={userId}>
              {userId}
            </Composer.SuggestionsListItem>
          ))}
          // +++
        </Composer.SuggestionsList>
      </Composer.Suggestions>
    ),
  }}
/>;

// ✅ After
<Composer.Editor
  components={{
    // +++
    MentionSuggestions: ({ mentions, selectedMentionId }) => (
      // +++
      <Composer.Suggestions>
        <Composer.SuggestionsList>
          // +++
          {mentions.map((mention) => (
            <Composer.SuggestionsListItem key={mention.id} value={mention.id}>
              {mention.id}
            </Composer.SuggestionsListItem>
          ))}
          // +++
        </Composer.SuggestionsList>
      </Composer.Suggestions>
    ),
  }}
/>;
```

### `@liveblocks/emails` [#mentions-liveblocks-emails]

The [`prepareTextMentionNotificationEmailAsReact`][] and
[`prepareTextMentionNotificationEmailAsHtml`][] functions’ returned data changed
slightly:

- The `id` property is now named `textMentionId`, it refers to the mention’s
  Text Mention ID, not the user ID used for the mention
- The `id` property now refers to the mention’s ID, as in the user ID used for
  the mention
- The `kind` property now indicates the mention’s kind (e.g. `"user"`,
  `"group"`, etc.)

```tsx
await prepareTextMentionNotificationEmailAsReact(liveblocks, event);

// ❌ Before
// {
//   mention: {
// +++
//     id: "in_xxx",
// +++
//     roomId: "123",
//     createdAt: new Date(),
//     author: {
//       id: "user-who-created-the-mention",
//       info: {
//         name: "Aurélien",
//       },
//     },
//     content: /* The rendered content */,
//   },
//   ...
// }

// ✅ After
// {
//   mention: {
// +++
//     textMentionId: "in_xxx",
//     id: "user-who-is-mentioned",
//     kind: "user",
// +++
//     roomId: "123",
//     createdAt: new Date(),
//     author: {
//       id: "user-who-created-the-mention",
//       info: {
//         name: "Aurélien",
//       },
//     },
//     content: /* The rendered content */,
//   },
//   ...
// }
```

When customizing the
[`Mention`](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react-customizing-components)
component in the [`prepareTextMentionNotificationEmailAsReact`][] function, the
`element` prop’s `userId` property has been renamed to `id`, and `element.kind`
now indicates the mention’s kind.

```tsx
await prepareThreadNotificationEmailAsReact(liveblocks, webhookEvent, {
  components: {
    // ❌ Before
    Mention: ({ element, user }) => (
      // +++
      <span style={{ color: "red" }}>@{element.userId}</span>
      // +++
    ),

// ✅ After
    Mention: ({ element, user }) => (
      // +++
      <span style={{ color: "red" }}>@{element.id}</span>
      // +++
    ),
  },
});
```

### Utilities [#utilities]

The `getMentionedIdsFromCommentBody` utility (from
[`@liveblocks/client`](/docs/api-reference/liveblocks-client) and
[`@liveblocks/node`](/docs/api-reference/liveblocks-node)) has been replaced by
[`getMentionsFromCommentBody`](/docs/api-reference/liveblocks-client#get-mentions-from-comment-body).

```tsx
// ❌ Before
getMentionedIdsFromCommentBody(commentBody);
// ["user-1", "user-2"]

// ✅ After
getMentionsFromCommentBody(commentBody, (mention) => mention.kind === "user");
// [{ type: "mention", kind: "user", id: "user-1" }, { type: "mention", kind: "user", id: "user-2" }]
```

By default, if the optional second argument is not provided, all mentions are
returned, including future mention kinds (e.g. group mentions in the future).

```tsx
// All mentions
getMentionsFromCommentBody(commentBody);

// Only user mentions
getMentionsFromCommentBody(commentBody, (mention) => mention.kind === "user");
```

## Notification settings [#notification-settings]

2.24 [introduced a few naming changes](/docs/platform/upgrading/2.24) around the
concepts of “notification settings” and “subscription settings” to improve
clarity. 3.0 [removes the aliases for the previous names](#deprecated) but it
also introduces one change that we couldn’t make in 2.24:

The `UPDATE_USER_NOTIFICATION_SETTINGS_ERROR` error has been renamed to
`UPDATE_NOTIFICATION_SETTINGS_ERROR`.

```tsx
// ❌ Before
useErrorListener((error) =>
  // +++
  if (error.context.type === "UPDATE_USER_NOTIFICATION_SETTINGS_ERROR") {
    // +++
    /* ... */
  }
);

// ✅ After
useErrorListener((error) =>
  // +++
  if (error.context.type === "UPDATE_NOTIFICATION_SETTINGS_ERROR") {
    // +++
    /* ... */
  }
);
```

## `@liveblocks/emails` [#liveblocks-emails]

The functions to prepare HTML/React emails are now more consistent, using the
same `body` and `content` properties instead of `reactBody`/`htmlBody` and
`reactContent`/`htmlContent`.

```tsx
// ❌ Before
prepareThreadNotificationEmailAsReact(liveblocks, event); // { comment: { reactBody: ReactNode, ... }, ... }
prepareThreadNotificationEmailAsHtml(liveblocks, event); // { comment: { htmlBody: string, ... }, ... }
prepareTextMentionNotificationEmailAsReact(liveblocks, event); // { mention: { reactContent: ReactNode, ... }, ... }
prepareTextMentionNotificationEmailAsHtml(liveblocks, event); // { mention: { htmlContent: string, ... }, ... }

// ✅ After
prepareThreadNotificationEmailAsReact(liveblocks, event); // { comment: { body: ReactNode, ... }, ... }
prepareThreadNotificationEmailAsHtml(liveblocks, event); // { comment: { body: string, ... }, ... }
prepareTextMentionNotificationEmailAsReact(liveblocks, event); // { mention: { content: ReactNode, ... }, ... }
prepareTextMentionNotificationEmailAsHtml(liveblocks, event); // { mention: { content: string, ... }, ... }
```

## `LiveblocksUiConfig` [#liveblocks-ui-config]

The
[`LiveblocksUIConfig`](/docs/api-reference/liveblocks-react-ui#LiveblocksUiConfig)
utility has been renamed to `LiveblocksUiConfig` (`UI` → `Ui`) for consistency
with other Liveblocks APIs.

Run the following **codemod** or manually make the changes:

```bash
npx @liveblocks/codemod@latest liveblocks-ui-config
```

## Removed deprecated APIs [#deprecated]

All of the following APIs have been removed in 3.0, as they were deprecated
multiple versions ago.

**Affecting all packages:**

- The `code` property has been removed from `LiveblocksError`, use
  `LiveblocksError.context.code` instead for better TypeScript support.
- The deprecated aliases from the
  [2.24 naming changes](/docs/platform/upgrading/2.24) have been removed, use
  their new names instead. There’s a codemod available to automatically use the
  new names: `npx @liveblocks/codemod@latest rename-notification-settings`.

**Affecting `@liveblocks/client`:**

- The `unstable_fallbackToHTTP` client option has been removed, set
  `largeMessageStrategy` to `"experimental-fallback-to-http"` instead.

**Affecting `@liveblocks/node`:**

- The `metadata` option has been removed from the [`getRooms`][] method, use
  `query.metadata` instead.
- The `nextPage` property has been removed from the [`getRooms`][] method’s
  response, use `query.nextPage` instead.
- The `RoomData` type has been removed, use `RoomInfo` instead. There’s a
  codemod available to automatically use the new type:
  `npx @liveblocks/codemod@latest room-info-to-room-data`.

**Affecting `@liveblocks/react`:**

- The `useBatch` hook has been removed, use [`useMutation`][] instead for
  writing to Storage, which will automatically batch all mutations.
- The `useStorageStatus` hook has been removed, use [`useSyncStatus`][] instead
  for tracking sync status, it reflects the sync status of all parts of
  Liveblocks.

**Affecting `@liveblocks/react-lexical`:**

- The `useEditorStatus` hook has been removed, use [`useSyncStatus`][] instead
  for tracking sync status, it reflects the sync status of all parts of
  Liveblocks.

[`Thread`]: /docs/api-reference/liveblocks-react-ui#Thread
[`Comment`]: /docs/api-reference/liveblocks-react-ui#Comment
[`Comment.Body`]:
  /docs/api-reference/liveblocks-react-ui#primitives-Comment.Body
[`Composer.Editor`]:
  /docs/api-reference/liveblocks-react-ui#primitives-Composer.Editor
[`prepareTextMentionNotificationEmailAsReact`]:
  /docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react
[`prepareTextMentionNotificationEmailAsHtml`]:
  /docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-html
[`getRooms`]: /docs/api-reference/liveblocks-node#get-rooms
[`useSyncStatus`]: /docs/api-reference/liveblocks-react#useSyncStatus
[`useMutation`]: /docs/api-reference/liveblocks-react#useMutation

---
meta:
  title: "Upgrading to 3.10"
  parentTitle: "Upgrading"
  description: "Guide to upgrade to Liveblocks version 3.10"
---

Liveblocks 3.10 releases breaking changes for [Tiptap](#Upgrade-Tiptap) and
[BlockNote](#Upgrade-BlockNote) users, as it requires at least Tiptap 3.0 or
BlockNote 0.39. No other parts of Liveblocks are affected by breaking changes.

## Not using Tiptap or BlockNote?

**If you’re not using Tiptap or BlockNote, there are no breaking changes**,
simply upgrade all Liveblocks dependencies to their latest versions. The easiest
way to upgrade is to run the following command:

```bash
npx liveblocks@latest upgrade
```

## Upgrade Tiptap

Tiptap v3 is a major update with breaking changes, but the migration process is
quite simple. First, you _must_ uninstall all Tiptap and Liveblocks dependencies
to avoid future version conflicts as we upgrade. This includes any extra Tiptap
extensions you may have installed or anything else with a dependency on Tiptap.

### AI-assisted upgrade

The easiest way to upgrade is to use our AI assistant to generate the uninstall
and install commands for you. Make sure you’re signed in, paste your
`package.json` into the following input, and generate the commands.

<AskAiInput 
  placeholder="Paste package.json here" 
  prompt={`Write two **multi-line** npm commands for me:
1. Uninstall all Tiptap and Liveblocks packages. 
2. Install all the same packages with @latest on Liveblocks and @3 on Tiptap.

Here is my package.json:

\`\`\`json

\`\`\`

Offer to rewrite the multi-line commands if I'm on Windows.

`}>

Generate commands

</AskAiInput>

Run the two commands then skip to
[Critical changes for Liveblocks users](#Critical-changes-for-Liveblocks-Tiptap-users).

### Manual upgrade

If you’d like to upgrade manually, you need to run the npm command to uninstall
all Tiptap and Liveblocks packages. Note that you are likely using more package
than are listed here, such as Tiptap extensions.

```bash
npm uninstall @tiptap/react @tiptap/starter-kit @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-tiptap @liveblocks/node
```

Next re-install all Tiptap and Liveblocks packages. If you see a peer dependency
issue during this install, you may have missed something during the previous
uninstall step.

```bash
npm install @tiptap/react@3 @tiptap/starter-kit@3 @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-ui@latest @liveblocks/react-tiptap@latest @liveblocks/node@latest
```

This will ensure that all packages are compatible with each other and prevent
version conflicts.

### Critical changes for Liveblocks Tiptap users

While Tiptap 3 includes many changes, there are two particularly critical
changes that affect Liveblocks integration:

#### StarterKit configuration change

Liveblocks provides its own undo/redo functionality for collaborative editing.
In Tiptap 2, you disabled this by setting `history: false` in the StarterKit
extension. In Tiptap 3, this option has been renamed to `undoRedo`:

```diff
const editor = useEditor({
  extensions: [
    StarterKit.configure({
-      history: false,
+      undoRedo: false,
    }),
    // Other extensions...
  ],
});
```

#### Set `immediatelyRender: false` for SSR

If you're using server-side rendering (such as with Next.js), it's now more
critical to set `immediatelyRender: false` in your editor configuration to
prevent hydration issues:

```tsx highlight="3"
const editor = useEditor(
  {
    immediatelyRender: false,
    extensions: [
      StarterKit.configure({
        undoRedo: false,
      }),
      // Other extensions...
    ],
  },
  []
);
```

This ensures the editor doesn't render on the server, which can cause mismatches
between server and client rendering.

#### Style Changes

If you have your own styles for collaboration cursors, the default CSS classes
prefix changed from `.collaboration-cursor` to `.collaboration-carets`.

```diff
- .collaboration-cursor__caret {
+ .collaboration-carets__caret {
  /* Your caret styles */
}

- .collaboration-cursor__label {
+ .collaboration-carets__label {
  /* Your label styles */
}
```

### Full migration guide

For a complete list of breaking changes and new features in Tiptap 3, refer to
the
[official Tiptap upgrade guide](https://tiptap.dev/docs/guides/upgrade-tiptap-v2).

## Upgrade BlockNote

BlockNote 0.39 has upgraded to use Tiptap 3.0 under the hood, which requires a
simple upgrade. First, you _must_ uninstall all BlockNote, Tiptap, and
Liveblocks dependencies to avoid future version conflicts as we upgrade. This
includes any extra Tiptap extensions you may have installed or anything else
with a dependency on Tiptap.

### AI-assisted upgrade

<AskAiInput 
  placeholder="Paste package.json here" 
  prompt={`Write two **multi-line** npm commands for me:
1. Uninstall all BlockNote, Tiptap, and Liveblocks packages. 
2. Install all the same packages with @latest on Liveblocks and BlockNote, and @3 on Tiptap.

Here is my package.json:

\`\`\`json

\`\`\`

Offer to rewrite the multi-line commands if I'm on Windows.

`}>

Generate commands

</AskAiInput>

Run the two commands then skip to
[Critical changes for Liveblocks BlockNote users](#Critical-changes-for-Liveblocks-BlockNote-users).

### Manual upgrade

If you’d like to upgrade manually, you need to run the npm command to uninstall
all BlockNote, Tiptap, and Liveblocks packages. Note that you are likely using
more package than are listed here, such as text editor extensions.

```bash
npm uninstall @blocknote/core @blocknote/mantine @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-blocknote @liveblocks/node
```

Next re-install all BlockNote, Tiptap, and Liveblocks packages. If you see a
peer dependency issue during this install, you may have missed something during
the previous uninstall step.

```bash
npm install @blocknote/core@latest @blocknote/mantine@latest @liveblocks/client@latest @liveblocks/react@latest @liveblocks/react-ui@latest @liveblocks/react-blocknote@latest @liveblocks/node@latest
```

This will ensure that all packages are compatible with each other and prevent
version conflicts.

### Critical changes for Liveblocks BlockNote users

#### Style Changes

If you have your own styles for collaboration cursors, the default CSS classes
prefix changed from `.collaboration-cursor` to `.collaboration-carets`.

```diff
- .collaboration-cursor__caret {
+ .collaboration-carets__caret {
  /* Your caret styles */
}

- .collaboration-cursor__label {
+ .collaboration-carets__label {
  /* Your label styles */
}
```

### BlockNote release notes

To learn more about the changes in BlockNote 0.39, please refer to the
[BlockNote 0.39 release notes](https://github.com/TypeCellOS/BlockNote/releases/tag/v0.39.0).

---
meta:
  title: "The new realtime data storage engine and its benefits"
  description:
    "Learn about our improved v2 realtime data storage engine and its benefits"
---

Since v3.14, rooms can be powered by our new v2 realtime data storage engine—a
ground-up rearchitecture that removes server-side memory limits, enabling faster
initial loads and support for much larger documents. Switching is **seamless and
requires no code changes**. Rooms on v1 or v2 behave identically from your app’s
perspective—the two sync engines we
support—[Liveblocks Storage](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-storage)
and [Yjs](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-yjs) all
work the same way.

Since March 10, 2026, the v2 engine is the default for all newly created rooms.
Existing rooms remain on v1 for now.

## What are the benefits?

The main architectural leap of v2 is that the Liveblocks server no longer needs
to keep the entire document in memory. In v1, large documents put memory
pressure on our edge workers, which are limited in capacity. A 50 MiB document,
including its overhead, could easily cause an OOM crash in an edge worker on the
v1 engine, in turn causing the room to become inaccessible.

Rooms on the v2 realtime data storage engine now stream their document data
directly from our persisted storage layer, keeping only minimal data in memory.
Conflict resolution and mutations happen directly in the storage layer too.

This enables arbitrarily large documents—server memory is no longer the
bottleneck (browser memory, network speed, or your app’s rendering performance
might now be).

Initial load time will be faster, especially for larger documents: the server
can start streaming immediately without buffering, and our wire protocol has
been compacted to reduce transmission overhead.

Several [previously documented platform limits](/docs/platform/limits) have been
raised significantly for rooms on the v2 engine:

| Item                    | v1 limit | v2 limit |
| ----------------------- | -------- | -------- |
| Broadcast event message | 1 MB     | 32 MB    |
| `LiveObject`            | 128 kB   | 2 MB     |
| `LiveMap` value         | 128 kB   | 2 MB     |
| `LiveList` value        | 128 kB   | 2 MB     |

## How it works

The engine version is assigned at room creation time and cannot be changed
afterward. Since March 10, 2026, all newly created rooms automatically use the
v2 engine. No opt-in or code changes are required.

If you're on an older SDK version, we recommend upgrading to v3.14+ to take full
advantage of the v2 engine: `npx liveblocks@latest upgrade`

### Migrating existing rooms

Existing rooms that were created before this change remain on the v1 engine.
Eventually, we will transparently migrate all existing room data from the v1 to
the v2 engine. This process will be seamless and require no action on your part.
We will announce this ahead of time.

---
meta:
  title: "Adding Liveblocks to existing useState hooks"
  description: "Learn how to add Liveblocks to your existing useState hooks"
---

<Banner title="Not recommended" type="warning">
  Note that this is not the recommended way to build your app. We recommend
  using conflict-free data types and the `useStorage` and `useMutation` hooks,
  to take full advantage of our features.
</Banner>

You can easily add Liveblocks to an existing `useState` hook by broadcasting and
listening to events.

```ts
import { useState } from "react";
import { useBroadcastEvent, useEventListener } from "./liveblocks.config";

function useCustomState() {
  const [state, setState] = useState();
  const broadcast = useBroadcastEvent();

// Update useState and broadcast an event
  const setStateAndBroadcast = (newValue) => {
    setState(newValue);
    broadcast({ type: "STATE_UPDATE", data: newValue });
  };

// Listen for the broadcast event
  useEventListener(({ event }) => {
    if (event.type === "STATE_UPDATE") {
      setState(event.data);
    }
  });

return [state, setStateAndBroadcast];
}
```

---
meta:
  title: "Can I use my own database with Yjs?"
  description:
    "Learn how to use webhooks to duplicate Yjs document data to your own
    database"
---

When building collaborative applications with Yjs and Liveblocks, you may wish
to store document data in your own database alongside Liveblocks. While
Liveblocks needs to store Yjs document data to handle realtime collaboration,
you can use webhooks to duplicate this data to your own database whenever
changes occur.

## Why Liveblocks stores Yjs data

Liveblocks must store Yjs document data to provide realtime collaboration
features. This storage is essential for:

- **Realtime synchronization**: Distributing changes to all connected users
  instantly.
- **Conflict resolution**: Merging changes from multiple users working
  simultaneously.
- **Offline support**: Syncing changes when users reconnect after being offline.
- **Document loading**: Loading the current document state when a user
  enters the room.

Without storing this data, Liveblocks wouldn't be able to provide the realtime
collaboration features that make Yjs powerful. However, you can still maintain
your own copy of the data for additional purposes like backups, analytics, or
creating full-text search.

## Duplicating data with webhooks

The best way to keep your own database in sync with Liveblocks is to use the
[`YDocUpdated`](/docs/platform/webhooks#YDocUpdatedEvent) webhook event. This
event fires whenever a Yjs document changes, allowing you to copy the updated
data to your database. Your server can then:

1. Receive the webhook event.
2. Fetch the latest document data from Liveblocks.
3. Store it in your database.

This approach ensures your database stays synchronized with Liveblocks without
interfering with realtime collaboration.

### Webhook throttling

Yjs documents can update up to 60 times per second during active collaboration,
so the `YDocUpdated` webhook is throttled to prevent overwhelming your server.
The webhook event will run no more than once every 60 seconds by default, but on
Enterprise plans, you can configure this throttle to be as low as every 5
seconds, giving you near realtime synchronization to your database.

If you’re interested in lowering the throttle value,
[reach out to our team](/contact/sales) to discuss your needs.

</Banner>

## Setting up database synchronization

We have detailed guides that walk you through how to set up your webhooks and
store the Yjs data in your database.

- [How to synchronize your Liveblocks Yjs document data to a Vercel Postgres database](/docs/guides/how-to-synchronize-your-liveblocks-yjs-document-data-to-a-vercel-postgres-database)
- [How to synchronize your Liveblocks Yjs document data to a Supabase Postgres database](/docs/guides/how-to-synchronize-your-liveblocks-yjs-document-data-to-a-supabase-postgres-database)
- [How to synchronize your Liveblocks Yjs document data to a PlanetScale MySQL database](/docs/guides/how-to-synchronize-your-liveblocks-yjs-document-data-to-a-planetscale-mysql-database)

If your database isn’t mentioned in these guides, the process is still similar,
so we recommend following the general steps outlined in the guides. The guides
above detail fetching your Yjs data, however if you’re using one of our text
editor extensions, you can use our server packages to fetch the Tiptap or
Lexical data instead.

### Tiptap

If you’re using Tiptap,
[`withProsemirrorDocument`](/docs/api-reference/liveblocks-node-prosemirror#withProsemirrorDocument)
can be used to fetch the Tiptap data, as text, markdown, JSON, and more, when
receiving the webhook event.

```ts
const textContent = await withProsemirrorDocument(
  { roomId: "my-room-id", client: liveblocks },
  async (api) => {
    return api.toMarkdown();
  }
);

// "# Hello world"
console.log(textContent);
```

Additionally you can modify the live document with
[`setContent`](/docs/api-reference/liveblocks-node-prosemirror#api.setContent).

### Lexical

If you’re using Lexical,
[`withLexicalDocument`](/docs/api-reference/liveblocks-node-lexical#withLexicalDocument)
can be used to fetch the Lexical data, as text, markdown, JSON, and more, when
receiving the webhook event.

```ts
const textContent = await withLexicalDocument(
  { roomId: "my-room-id", client: liveblocks },
  async (doc) => {
    return doc.toMarkdown();
  }
);

// "# Hello world"
console.log(textContent);
```

Additionally you can modify the live document with
[`update`](/docs/api-reference/liveblocks-node-lexical#doc.update).

## Learn more

For more information about data storage and webhooks, check out these resources:

### API documentation

Learn more about the APIs for working with Yjs data:

- [YDocUpdated webhook event](/docs/platform/webhooks#YDocUpdatedEvent)
- [@liveblocks/node-prosemirror](/docs/api-reference/liveblocks-node-prosemirror)
- [@liveblocks/node-lexical](/docs/api-reference/liveblocks-node-lexical)
- [Data storage](/docs/platform/data-storage)

---
meta:
  title: "Enabling agentic workflows with Liveblocks"
  parentTitle: "Guides"
  description:
    "Use Liveblocks REST APIs to let AI agents show presence, modify storage,
    and participate as collaborators in your rooms."
---

AI agents can participate as first-class collaborators inside Liveblocks rooms.
Two REST API capabilities make this possible:

- **Ephemeral Presence** (`POST /v2/rooms/{roomId}/presence`): Lets an agent
  appear in a room with a name, avatar, and custom presence data, with an
  auto-expiring TTL.
- **JSON Patch** (`PATCH /v2/rooms/{roomId}/storage/json-patch`): Lets an agent
  modify
  [Storage](/docs/ready-made-features/multiplayer/sync-engine/liveblocks-storage)
  using the RFC 6902 standard, which is well understood by LLMs, making it
  straightforward for AI models to generate patch operations directly from
  natural language instructions.

Both are language-agnostic HTTP endpoints, so agents built in Python,
TypeScript, or any other language can use them without a native Liveblocks
client.

## Making your agent visible with ephemeral presence [#ephemeral-presence]

The
[`POST /v2/rooms/{roomId}/presence`](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-presence)
endpoint lets your agent set presence in a room just like a connected user
would. The presence expires automatically once the TTL elapses, so the agent
never lingers after it’s done.

```shell title="Endpoint"
POST https://api.liveblocks.io/v2/rooms/{roomId}/presence
```

Authenticate with your project’s **secret key** in the `Authorization` header.

```shell
"Authorization: Bearer {{SECRET_KEY}}"
```

The request body accepts:

- `userId`: The agent’s stable identifier.
- `data`: Any presence object you want connected clients to see.
- `userInfo`: Optional name, avatar URL, and color for the agent.
- `ttl`: How long (in seconds) the presence should live (minimum: 2, maximum:
  3599).

```bash
curl -X POST "https://api.liveblocks.io/v2/rooms/my-room/presence" \
  -H "Authorization: Bearer {{SECRET_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "ai-agent",
    "data": { "status": "thinking", "focusedField": "email" },
    "userInfo": {
      "name": "AI Agent",
      "avatar": "https://example.com/ai-agent-avatar.png",
      "color": "#6366f1"
    },
    "ttl": 60
  }'
```

A `204` response means the presence was set successfully.

### Rendering the agent as an avatar [#agent-avatar]

Because the agent’s presence is set server-side, it flows to all connected
clients through the normal Liveblocks presence system. The agent appears in
[`useOthers`](/docs/api-reference/liveblocks-react#useOthers) alongside real
users, so existing avatar stack components work without any changes.

```tsx
import { useOthers, useSelf } from "@liveblocks/react/suspense";

function AvatarStack() {
  const others = useOthers();
  const self = useSelf();

return (
    <div className="avatar-stack">
      {others.map(({ connectionId, info }) => (
        <img key={connectionId} src={info.avatar} alt={info.name} />
      ))}
      {self && <img src={self.info.avatar} alt={self.info.name} />}
    </div>
  );
}
```

The `userInfo.avatar` you pass to the presence endpoint populates `info.avatar`
here, so the agent shows up with its own avatar.

### Highlighting form fields [#highlight-fields]

Presence `data` can carry any shape you choose. A `focusedField` property, for
example, lets the frontend highlight which input the agent is currently working
on, giving users real-time insight into what the agent is doing.

```tsx
import { useOthers } from "@liveblocks/react/suspense";

function FormField({ name, label }: { name: string; label: string }) {
  const agentFocus = useOthers((others) =>
    others.find((o) => o.presence.focusedField === name)
  );

return (
    <div className={agentFocus ? "ring-2 ring-indigo-500" : ""}>
      <label htmlFor={name}>{label}</label>
      <input id={name} name={name} />
      {agentFocus && (
        <span className="text-sm text-indigo-600">
          {agentFocus.info.name} is reviewing…
        </span>
      )}
    </div>
  );
}
```

As the agent moves between fields, call the presence endpoint again with an
updated `focusedField` value. Each call resets the TTL, so the presence stays
alive as long as the agent keeps working.

## Modifying Storage with JSON Patch [#json-patch]

The
[`PATCH /v2/rooms/{roomId}/storage/json-patch`](/docs/api-reference/rest-api-endpoints#patch-rooms-roomId-storage-json-patch)
endpoint lets an agent write directly to a room’s Storage document over HTTP.
The body is a JSON array of operations following the
[RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) specification.

```shell title="Endpoint"
PATCH https://api.liveblocks.io/v2/rooms/{roomId}/storage/json-patch
```

JSON Patch is a well-established standard that LLMs already understand, which
means you can ask a model to produce the patch operations directly from a
natural language instruction without writing custom tooling or prompt
engineering.

Supported operations are `add`, `remove`, `replace`, `move`, `copy`, and `test`.
If any operation fails, the whole patch is rejected and the document is left
unchanged.

For a full reference of all operations and error handling, see the
[Modifying Storage via REST API with JSON Patch](/guides/modifying-storage-via-rest-api-with-json-patch)
guide.

The example below uses Python, which is common in agentic pipelines:

```python
import requests

ROOM_ID = "my-room"
SECRET_KEY = "sk_prod_..."

operations = [
    {"op": "replace", "path": "/formData/email", "value": "verified@example.com"},
    {"op": "add",     "path": "/formData/status", "value": "reviewed"},
]

response = requests.patch(
    f"https://api.liveblocks.io/v2/rooms/{ROOM_ID}/storage/json-patch",
    json=operations,
    headers={"Authorization": f"Bearer {SECRET_KEY}"},
)

response.raise_for_status()  # raises on 4xx / 5xx
```

A `200` response means all operations were applied. A `422` response means the
patch failed; the response body includes an `error` code, a human-readable
`message`, and an optional `suggestion`.

## End-to-end example: agent reviews a form [#end-to-end]

The following example walks through an agent that reviews a multi-field form. It
uses ephemeral presence to show users what it’s doing in real time, and JSON
Patch to commit its changes to Storage.

```python
import requests

BASE = "https://api.liveblocks.io/v2"
ROOM  = "my-room"
AGENT_ID = "ai-agent"
HEADERS  = {"Authorization": "Bearer sk_prod_...", "Content-Type": "application/json"}

def set_presence(focused_field: str, status: str, ttl: int = 30):
    requests.post(
        f"{BASE}/rooms/{ROOM}/presence",
        json={
            "userId": AGENT_ID,
            "data": {"focusedField": focused_field, "status": status},
            "userInfo": {
                "name": "AI Agent",
                "avatar": "https://example.com/ai-agent-avatar.png",
            },
            "ttl": ttl,
        },
        headers=HEADERS,
    )

def patch_storage(ops: list):
    requests.patch(
        f"{BASE}/rooms/{ROOM}/storage/json-patch",
        json=ops,
        headers=HEADERS,
    ).raise_for_status()

# Step 1 — signal intent on the "email" field
set_presence("email", "reviewing")

# Step 2 — validate and update email in Storage
patch_storage([
    {"op": "replace", "path": "/formData/email", "value": "verified@example.com"},
])

# Step 3 — move to the "name" field
set_presence("name", "reviewing")

patch_storage([
    {"op": "replace", "path": "/formData/name", "value": "Jane Doe"},
])

# Step 4 — mark the review as complete
# Set a short TTL so presence expires soon after we're done
set_presence("", "done", ttl=5)
patch_storage([
    {"op": "add", "path": "/formData/reviewedAt", "value": "2026-02-20T12:00:00Z"},
    {"op": "add", "path": "/formData/reviewedBy", "value": AGENT_ID},
])
```

On the frontend, the `FormField` component from the
[section above](#highlight-fields) will highlight each field as the agent
focuses on it, and `useStorage` will reflect the patched values as they arrive
in real time, no extra wiring required.

## Triggering agentic workflows [#triggers]

There are several natural places to start an agent workflow. Choose the one that
fits your product best, or combine multiple triggers.

### Comments webhooks—mentioning an AI agent [#comments-webhook]

Users can invoke an agent by mentioning it in a comment (e.g.
`@AI Agent, please review this form`). The
[`commentCreated`](/docs/platform/webhooks#CommentCreatedEvent) webhook fires
for every new comment, giving you a place to detect the mention and dispatch the
agent.

<Steps>
  <Step>
    <StepTitle>Register the agent as a mentionable user</StepTitle>
    <StepContent>
      Add the agent’s ID to [`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers)
      and [`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveMentionSuggestions)
      in your [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider) 
      so it appears in the `@` mention picker alongside real users.

```tsx
      <LiveblocksProvider
        authEndpoint="/api/liveblocks-auth"
        resolveUsers={async ({ userIds }) => {
          const users = await fetchUsersFromDB(userIds);
          return userIds.map((id) => {
            if (id === "ai-agent") {
              return { name: "AI Agent", avatar: "/ai-agent-avatar.png" };
            }
            return users.find((u) => u.id === id);
          });
        }}
        resolveMentionSuggestions={async ({ text }) => {
          const userIds = await searchUsers(text);
          // Include the AI agent whenever "ai agent" matches the search text
          if ("ai agent".includes(text.toLowerCase())) {
            userIds.unshift("ai-agent");
          }
          return userIds;
        }}
      >
        {/* ... */}
      </LiveblocksProvider>
      ```

For more information on `resolveUsers` and `resolveMentionSuggestions`, see
      [Users and mentions](/docs/ready-made-features/comments/users-and-mentions).
    </StepContent>

</Step>

<Step lastStep>
    <StepTitle>Handle the `commentCreated` webhook</StepTitle>
    <StepContent>
      When a comment is created, the webhook payload contains `roomId`, `threadId`,
      and `commentId`. Fetch the full comment using the Liveblocks Node SDK, then use
      [`getMentionsFromCommentBody`](/docs/api-reference/liveblocks-node#getMentionsFromCommentBody)
      to extract all mentions and check whether the agent’s ID is among them.

```ts file="app/api/liveblocks-webhook/route.ts"
      import { Liveblocks, getMentionsFromCommentBody } from "@liveblocks/node";

const liveblocks = new Liveblocks({ secret: process.env.SECRET_KEY! });

export async function POST(req: Request) {
        const event = await req.json();

if (event.type === "commentCreated") {
          const { roomId, threadId, commentId } = event.data;

// Fetch the full comment to inspect its body
          const comment = await liveblocks.getComment({
            roomId,
            threadId,
            commentId,
          });

// Extract all mentions from the comment body
          const mentions = getMentionsFromCommentBody(comment.body);
          const mentionsAgent = mentions.some(
            (mention) => mention.kind === "user" && mention.id === "ai-agent"
          );

if (mentionsAgent) {
            // Trigger your agent workflow with the relevant context
            await triggerAgentWorkflow({ roomId, threadId, commentId });
          }
        }

return new Response(null, { status: 200 });
      }
      ```

`triggerAgentWorkflow` is where you kick off your agent — call an n8n webhook,
      invoke a CrewAI crew, hit an LLM API, or run any other pipeline you've built.

Always verify the webhook signature before processing events. See the
      [Webhooks documentation](/docs/platform/webhooks) for verification examples.

</Banner>
    </StepContent>

</Step>
</Steps>

### Storage webhooks [#storage-webhook]

The `storageUpdated` event fires whenever Storage is written to. This is useful
for agents that react to user edits, for example auto-validation,
auto-summarization, or data enrichment.

```ts file="app/api/liveblocks-webhook/route.ts"
export async function POST(req: Request) {
  const event = await req.json();

if (event.type === "storageUpdated") {
    const { roomId } = event.data;
    await triggerAgentWorkflow({ roomId });
  }

return new Response(null, { status: 200 });
}
```

### Direct API call or button [#direct-trigger]

The simplest trigger of all: a user clicks a button in your UI, which calls your
backend endpoint, which runs the agent. This gives you full control over when
and how the agent is invoked.

```tsx
async function handleReviewClick() {
  await fetch("/api/run-agent", {
    method: "POST",
    body: JSON.stringify({ roomId: "my-room" }),
  });
}
```

A scheduled job (CRON) is another variant which can run the agent periodically
to batch process rooms or perform maintenance tasks.

### Other triggers

- **Notification webhooks**: Fire when a user receives an inbox notification,
  which can be a signal to summarize unread activity or draft a reply.
- **External events**: Slack messages, GitHub PR events, email, Zapier triggers,
  or any inbound webhook that carries a `roomId` can start an agent run.
- **Scheduled / CRON jobs**: Poll rooms on a fixed schedule to run quality
  checks, generate reports, or clean up stale data.

## Integrating with agentic frameworks [#frameworks]

Because both APIs are plain HTTP endpoints, Liveblocks works with any agent
framework that can make HTTP requests.

- **n8n**: Add an HTTP Request node to call the presence and JSON Patch
  endpoints. Use a Liveblocks webhook as the workflow trigger so agents fire
  automatically on comment or storage events.
- **CrewAI** :Wrap the REST calls in a custom `Tool` and pass it to your agents.
  Agents can then set presence or patch storage as part of a multi-step task.
- **LangChain / LangGraph**: Define Liveblocks tools for function-calling
  models. The LLM can generate JSON Patch operations directly — the RFC 6902
  format is part of many models' training data, so no custom schema or special
  prompting is needed.
- **Any HTTP-capable framework**: fetch, axios, Python `requests`, Go
  `net/http`, cURL—if it can make a `POST` or `PATCH` request it can drive
  Liveblocks.

## Next steps

- [Modifying Storage via REST API with JSON Patch](/guides/modifying-storage-via-rest-api-with-json-patch):
  Full reference for all JSON Patch operations.
- [Webhooks](/docs/platform/webhooks): All available webhook events and
  signature verification.
- [REST API reference](/docs/api-reference/rest-api-endpoints): Complete request
  and response schemas for all endpoints.
- [Users and mentions](/docs/ready-made-features/comments/users-and-mentions):
  Setting up `resolveUsers` and `resolveMentionSuggestions`.

---
meta:
  title: "Fixing Next.js server component errors"
  description: "Learn how to fix Next.js server component problems"
---

## Fixing the warning: "Only plain objects can be passed to Client Components from Server Components"

This error occurs when you create a Liveblocks data structure (`LiveObject`,
`LiveList`, or `LiveMap`) within a server component. This is often occurs when
creating a room with `RoomProvider`, for example:

```tsx file="layout.tsx"
import { ReactNode } from "react";
import { RoomProvider } from "../liveblocks.config";
import { LiveObject } from "@liveblocks/client";

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <RoomProvider
          id="my-room-name"
          initialStorage={{
            // ❌ This line causes the error
            session: new LiveObject(),
          }}
        >
          {children}
        </RoomProvider>
      </body>
    </html>
  );
}
```

This can be fixed by turning the file into a client file with `"use client";` at
the top of the file. However, if your need a server component, you can extract
the provider to a different file.

## Structuring your app

To take this further, and to learn how to structure your Next.js app in the best
possible way, make sure to read our
[How to use Liveblocks with Next.js /app directory](/docs/guides/how-to-use-liveblocks-with-nextjs-app-directory)
guide.

---
meta:
  title: "Getting ProseMirror state on the server"
  description:
    "Learn how to retrieve your document’s ProseMirror state on the server"
---

Using
[`@liveblocks/node-prosemirror`](/docs/api-reference/liveblocks-node-prosemirror),
it’s possible to retrieve the state of your ProseMirror document on the server.

## Getting document state

To get your document state, you can use
[`withProsemirrorDocument`](/docs/api-reference/liveblocks-node-prosemirror#withProsemirrorDocument)
and
[`api.getText`](/docs/api-reference/liveblocks-node-prosemirror#api.getText).

```ts
import { Liveblocks } from "@liveblocks/node";
import { withProsemirrorDocument } from "@liveblocks/node-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

// +++
const textContent = await withProsemirrorDocument(
  { roomId: "your-room-id", client: liveblocks, field: "prosemirror" },
  async (api) => {
    return api.getText();
  }
);
// +++

// "My content"
console.log(textContent);
```

## Modifying document state

To modify document state with transactions, use
[`api.update`](/docs/api-reference/liveblocks-node-prosemirror#api.update). On
the ProseMirror website you can find a full list of
[transforms](https://prosemirror.net/docs/ref/#transform.Document_transforms)
and
[transactions functions](https://prosemirror.net/docs/ref/#state.Transaction).

```ts
import { Liveblocks } from "@liveblocks/node";
import { withProsemirrorDocument } from "@liveblocks/node-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

await withProsemirrorDocument(
  { roomId: "your-room-id", client: liveblocks, field: "prosemirror" },
  // +++
  async (api) => {
    await api.update((_, tr) => {
      // Transaction example
      return tr.insertText("Hello world");
    });
  }
  // +++
);
```

## Using Yjs APIs instead

We don’t generally recommend it, but it’s also possible to use
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) to retrieve the state
of your ProseMirror document, and its [`Y.Doc`](https://docs.yjs.dev/api/y.doc),
on the server. This may give you more control in some cases.

Using
[`Liveblocks.getYjsDocumentAsBinaryUpdate`](/docs/api-reference/liveblocks-node#get-rooms-roomId-ydoc-binary)
you can fetch your Yjs data, and place it inside a `Y.Doc`. We can then call
`yDocToProseMirror` from [`y-prosemirror`](https://github.com/yjs/y-prosemirror)
to retrieve the ProseMirror editor’s state.

```ts
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";
import { yDocToProsemirrorJSON } from "y-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST() {
  // Get your Yjs data as a binary update
  const update = await liveblocks.getYjsDocumentAsBinaryUpdate("my-room-name");

// Create a Yjs document
  const yDoc = new Y.Doc();

// Apply the binary update to `yDoc`
  Y.applyUpdate(yDoc, new Uint8Array(update));

// Get ProseMirror state from the default Yjs property it uses, "prosemirror"
  const prosemirrorState = yDocToProsemirrorJSON(yDoc, "prosemirror");

// { type: "doc", content: [{ type: "paragraph", content: [...] }] }
  console.log(prosemirrorState);
}
```

If you’d like to edit your `Y.Doc`, make sure to read
[how to use your `Y.Doc` on the server](/docs/guides/how-to-use-your-ydoc-on-the-server).

---
meta:
  title: "Getting Tiptap state on the server"
  description:
    "Learn how to retrieve your document’s Tiptap state on the server"
---

Using
[`@liveblocks/node-prosemirror`](/docs/api-reference/liveblocks-node-prosemirror),
it’s possible to retrieve the state of your Tiptap document on the server.
Tiptap is not easy to edit on the server directly, which is why it’s necessary
to use the ProseMirror package. Tiptap is an extension of ProseMirror.

## Getting document state

```ts
import { Liveblocks } from "@liveblocks/node";
import { withProsemirrorDocument } from "@liveblocks/node-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

// +++
const textContent = await withProsemirrorDocument(
  { roomId: "your-room-id", client: liveblocks },
  async (api) => {
    return api.getText();
  }
);
// +++

// "My content"
console.log(textContent);
```

## Modifying document state

```ts
import { Liveblocks } from "@liveblocks/node";
import { withProsemirrorDocument } from "@liveblocks/node-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

await withProsemirrorDocument(
  { roomId: "your-room-id", client: liveblocks },
  // +++
  async (api) => {
    await api.update((_, tr) => {
      // Transaction example
      return tr.insertText("Hello world");
    });
  }
  // +++
);
```

You’ve now learned to fetch and modify document state!

## Using Yjs APIs instead

We don’t generally recommend it, but it’s also possible to use
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) to retrieve the state
of your Tiptap document, and its [`Y.Doc`](https://docs.yjs.dev/api/y.doc), on
the server. This may give you more control in some cases.

With
[`Liveblocks.getYjsDocumentAsBinaryUpdate`](/docs/api-reference/liveblocks-node#get-rooms-roomId-ydoc-binary)
you can fetch your Yjs data, and place it inside a `Y.Doc`. Because Tiptap is a
wrapper around ProseMirror, we can then call `yDocToProseMirror` from
[`y-prosemirror`](https://github.com/yjs/y-prosemirror) to retrieve the Tiptap
editor’s state.

```ts
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";
import { yDocToProsemirrorJSON } from "y-prosemirror";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST() {
  // Get your Yjs data as a binary update
  const update = await liveblocks.getYjsDocumentAsBinaryUpdate("my-room-name");

// Create a Yjs document
  const yDoc = new Y.Doc();

// Apply the binary update to `yDoc`
  Y.applyUpdate(yDoc, new Uint8Array(update));

// Get Tiptap state from the Yjs property it uses, "default"
  const tiptapState = yDocToProsemirrorJSON(yDoc, "default");

// { type: "doc", content: [{ type: "paragraph", content: [...] }] }
  console.log(tiptapState);
}
```

If you’d like to edit your `Y.Doc`, make sure to read
[how to use your `Y.Doc` on the server](/docs/guides/how-to-use-your-ydoc-on-the-server).

---
meta:
  title: "How to add users to Liveblocks Comments"
  description:
    "Learn how to add your user’s avatars and names to Liveblocks Comments using
    the resolver functions."
---

After following the get started guide for Comments, you’ll notice that each user
is currently “Anonymous”, and that there’s no way to mention or tag other users.
To enable these features, we need to tell Comments where to find your users’
information.

## What we’re learning

In this guide we’ll be modifying
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
learning how to:

- Add names and avatars to threads and comments with
  [`resolveUsers`](/docs/api-reference/liveblocks-react#resolveUsers).
- Create user mention suggestions in the composer using
  [`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#resolveMentionSuggestions).

## Authenticate your application

The first step is to find an
[authentication guide for your framework](/docs/authentication) and authenticate
your app, as this is necessary for Comments.

Make sure to follow the metadata step in the guide, and attach the name of your
user, along with the URL of their avatar, as these properties will both be used
in the [default components](/docs/ready-made-features/comments#Components).
Here’s an example using ID token authentication, our recommended method, with an
email address as a user’s ID.

```ts title="Metadata in ID tokens"
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",

// Optional
    // organizationId: "org-id",
    // groupIds: ["group-id-1", "group-id-2"],
  },
  {
    userInfo: {
      name: "Marc",
      avatar: "https://example.com/marc.png",

// Your custom metadata
      // ...
    },
  }
);
```

Modify your `UserMeta` type in `liveblocks.config.ts` to match the metadata
format, adding type hints to your editor.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string;

info: {
        name: string;
        avatar: string;

// Your custom metadata
        // ...
      };
    };
  }
}
```

## Resolving users

To show each user’s name and avatar in threads and comments, we need to use
[`resolveUsers`](https://liveblocks.io/docs/api-reference/liveblocks-client#resolveUsers).

<Steps>
  <Step>
    <StepTitle>Add the function to your LiveblocksProvider</StepTitle>
    <StepContent>
      The [`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) function is passed as an option to
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)—let’s add it. This function
      provides you with `userIds`, an array of user IDs that have interacted with Comments.
      These `userIds` match the IDs set when authenticating users in your app.

```tsx highlight="2-8"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          // ...
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Return your users</StepTitle>
    <StepContent>
      `resolveUsers` requires you to return a list of users in
      the `UserMeta["info"]` format we set earlier. Remember
      that _name_ and _avatar_ are required for the default components,
      but you can also use any other metadata in your app.

```tsx highlight="7-16"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          return [
            {
              name: "Marc",
              avatar: "https://example.com/marc.png",

// Your custom metadata
              // ...
            },
            // ...
          ];
        }}

// ...
      />;
      ```

We’re only returning one user here, but make sure to return an
      array containing each user, in the same order you received the IDs.

</StepContent>

</Step>
  <Step>
    <StepTitle>Real-world example</StepTitle>
    <StepContent>
      In your real application you’ll probably be getting users from your
      API endpoint and database via `fetch`. This is how we’d recommend
      building out this function.

```tsx highlight="3-7"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // Get users from your back end
          const users = await __fetchUsers__(userIds);

// Return a list of users
          return users;
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Users are now visible</StepTitle>
    <StepContent>
      After adding this, you should now be able to see your users in threads!

</StepContent>

</Step>
</Steps>

## Resolving mention suggestions

We can see the users that have commented, but we don’t have a way to search for
users to mention, for example after typing the `@` character. We can create a
simple search that resolves this data with
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#resolveMentionSuggestions).

<Steps>
  <Step>
    <StepTitle>Add the function to your config file</StepTitle>
    <StepContent>
      `resolveMentionSuggestions` is placed alongside `resolveUsers`, and
      provides you with `text`, which is the string that the user is searching for.
      You can use this string to return a list of matching user IDs.

```tsx highlight="5-11"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ...
        }}
        resolveMentionSuggestions={async ({ text, roomId }) => {
          // The text the user is searching for, e.g. "mar"
          console.log(text);

// Return a list of user IDs that match the query
          return ["marc@example.com", "marissa@example.com"];
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Real-world example</StepTitle>
    <StepContent>

In a real application, you’ll most likely be getting a list of each user,
      before filtering the list by the user’s names or IDs. If `text` is an empty
      string, then you need to return a list of every user, instead of a filtered list.

```tsx highlight="6-16"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ...
        }}
        resolveMentionSuggestions={async ({ text, roomId }) => {
          // Fetch all users from your back end
          let users = await __fetchAllUsers__();

// If there's a query, filter for the relevant users
          if (text) {
            // Filter any way you'd like, e.g. checking if the name matches
            users = users.filter((user) => user.name.includes(text));
          }

// Return the filtered `userIds`
          return users.map((user) => user.id);
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Mention suggestions now appear</StepTitle>
    <StepContent>

Now we’ve found and returned the correct users, Comments can display
      a list of mention suggestions!

</StepContent>

</Step>
</Steps>

## Next steps

You’re now ready to start building your Comments application! Here’s where you
can learn more:

- [API reference](/docs/api-reference/liveblocks-react#Comments)
- [Component reference](/docs/api-reference/liveblocks-react-ui#Comments)
- [Examples](/examples/browse/comments)

---
meta:
  title: "How to add users to Liveblocks Notifications"
  description:
    "Learn how to add your user’s avatars and names to Liveblocks Notifications
    using the resolver functions."
---

After following the get started guide for Notifications, and sending
notifications with [Comments](/docs/ready-made-features/comments) or
[Text editor](/docs/ready-made-features/text-editor), you’ll notice that each
user is currently “Anonymous”, and that there’s no way to mention or tag other
users. To enable these features, we need to tell Notifications where to find
your users’ information.

## What we’re learning

In this guide we’ll be modifying
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
learning how to:

- Add names and avatars to notifications with
  [`resolveUsers`](/docs/api-reference/liveblocks-react#resolveUsers).

## Authenticate your application

The first step is to find an
[authentication guide for your framework](/docs/authentication) and authenticate
your app, as this is necessary for Notifications.

Make sure to follow the metadata step in the guide, and attach the name of your
user, along with the URL of their avatar, as these properties will both be used
in the [default components](/docs/ready-made-features/notifications#Components).
Here’s an example using ID token authentication, our recommended method, with an
email address as a user’s ID.

```ts title="Metadata in ID tokens"
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",

// Optional
    // organizationId: "org-id",
    // groupIds: ["group-id-1", "group-id-2"],
  },
  {
    userInfo: {
      name: "Marc",
      avatar: "https://example.com/marc.png",

// Your custom metadata
      // ...
    },
  }
);
```

Modify your `UserMeta` type in `liveblocks.config.ts` to match the metadata
format, adding type hints to your editor.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string;

info: {
        name: string;
        avatar: string;

// Your custom metadata
        // ...
      };
    };
  }
}
```

## Resolving users

To show each user’s name and avatar in threads and comments, we need to use
[`resolveUsers`](https://liveblocks.io/docs/api-reference/liveblocks-client#resolveUsers).

<Steps>
  <Step>
    <StepTitle>Add the function to your LiveblocksProvider</StepTitle>
    <StepContent>
      The [`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) function is passed as an option to
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)—let’s add it. This function
      provides you with `userIds`, an array of user IDs that have interacted with Notifications.
      These `userIds` match the IDs set when authenticating users in your app.

```tsx highlight="2-8"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          // ...
        }}

// ...
      />;
      ```

</StepContent>

```tsx highlight="7-16"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          return [
            {
              name: "Marc",
              avatar: "https://example.com/marc.png",

// Your custom metadata
              // ...
            },
            // ...
          ];
        }}

// ...
      />;
      ```

We’re only returning one user here, but make sure to return an
      array containing each user, in the same order you received the IDs.

</StepContent>

```tsx highlight="3-7"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // Get users from your back end
          const users = await __fetchUsers__(userIds);

// Return a list of users
          return users;
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Users are now visible</StepTitle>
    <StepContent>
      After adding this, you should now be able to see your users in notifications!

</StepContent>

</Step>
</Steps>

## Next steps

You’re now ready to start building your Notifications application! Here’s where
you can learn more:

- [API reference](/docs/api-reference/liveblocks-react#Notifications)
- [Component reference](/docs/api-reference/liveblocks-react-ui#Notifications)
- [Examples](/examples/browse/notifications)

---
meta:
  title: "How to add users to Liveblocks presence components"
  description:
    "Learn how to add your user’s avatars and names to Liveblocks avatar stack
    and cursors componentsusing the resolver functions."
---

After following the get started guide for presence components, you’ll notice
that each user is currently “Anonymous”, and that there’s no way to mention or
tag other users. To enable these features, we need to tell Liveblocks where to
find your users’ information.

## What we’re learning

In this guide we’ll be modifying
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
learning how to:

- Authenticate your application with
  [`authEndpoint`](/docs/api-reference/liveblocks-react#LiveblocksProviderAuthEndpoint)
  and [`identifyUser`](/docs/api-reference/liveblocks-node#id-tokens).
- Add names and avatars to threads and comments with
  [`resolveUsers`](/docs/api-reference/liveblocks-react#resolveUsers).

## Authenticate your application

The first step is to find an
[authentication guide for your framework](/docs/authentication) and authenticate
your app, as this is necessary for adding users. Here’s an example using ID
token authentication, our recommended method, with an email address as a user’s
ID.

```ts title="Metadata in ID tokens"
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",

// Optional
    // organizationId: "org-id",
    // groupIds: ["group-id-1", "group-id-2"],
  },
  {
    userInfo: {
      // Optional, custom metadata
      // ...
    },
  }
);
```

## Resolving users

To show each user’s name and avatar in the ready-made
[`AvatarStack`](/docs/api-reference/liveblocks-react-ui#AvatarStack) and
[`Cursors`](/docs/api-reference/liveblocks-react-ui#Cursors) components, we need
to use
[`resolveUsers`](https://liveblocks.io/docs/api-reference/liveblocks-client#resolveUsers).

```tsx highlight="2-8"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          // ...
        }}

// ...
      />;
      ```

</StepContent>

```tsx highlight="7-16"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          return [
            {
              name: "Marc",
              avatar: "https://example.com/marc.png",

// Your custom metadata
              // ...
            },
            // ...
          ];
        }}

// ...
      />;
      ```

We’re only returning one user here, but make sure to return an
      array containing each user, in the same order you received the IDs.

</StepContent>

```tsx highlight="3-7"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // Get users from your back end
          const users = await __fetchUsers__(userIds);

// Return a list of users
          return users;
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Users are now visible</StepTitle>
    <StepContent>
      After adding this, you should now be able to see your users in threads!

</StepContent>

</Step>
</Steps>

## Next steps

You’re now ready to start building your multiplayer Liveblocks application!
Here’s where you can learn more:

- [Overview](/docs/ready-made-features/multiplayer)
- [API reference](/docs/api-reference/liveblocks-react)
- [Examples](/examples/browse/comments)

---
meta:
  title: "How to add users to Liveblocks Text Editor"
  description:
    "Learn how to add your user’s avatars and names to Liveblocks Text Editor
    using the resolver functions."
---

After following the get started guide for Text Editor, you’ll notice that each
user is currently “Anonymous”, and that there’s no way to mention or tag other
users. To enable these features, we need to tell Text Editor where to find your
users’ information.

## What we’re learning

In this guide we’ll be modifying
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
learning how to:

- Add names and avatars to cursors and suggestions with
  [`resolveUsers`](/docs/api-reference/liveblocks-react#resolveUsers).
- Create user mention suggestions in the editor using
  [`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#resolveMentionSuggestions).

## Authenticate your application

The first step is to find an
[authentication guide for your framework](/docs/authentication) and authenticate
your app, as this is necessary for Text Editor.

Make sure to follow the metadata step in the guide, and attach the name of your
user, the color of their cursor, and their avatar URL, as these properties will
both be used in the [Text editor](/docs/ready-made-features/text-editor). Here’s
an example using ID token authentication, our recommended method, with an email
address as a user’s ID.

```ts title="Metadata in ID tokens"
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",

// Optional
    // organizationId: "org-id",
    // groupIds: ["group-id-1", "group-id-2"],
  },
  {
    userInfo: {
      name: "Marc",
      avatar: "https://example.com/marc.png",

// Your custom metadata
      // ...
    },
  }
);
```

Modify your `UserMeta` type in `liveblocks.config.ts` to match the metadata
format, adding type hints to your editor.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string;

info: {
        name: string;
        avatar: string;

// Your custom metadata
        // ...
      };
    };
  }
}
```

## Resolving users

To show each user’s name and color in their cursors, we need to use
[`resolveUsers`](https://liveblocks.io/docs/api-reference/liveblocks-client#resolveUsers).

<Steps>
  <Step>
    <StepTitle>Add the function to your LiveblocksProvider</StepTitle>
    <StepContent>
      The [`resolveUsers`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) function is passed as an option to
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)—let’s add it. This function
      provides you with `userIds`, an array of user IDs that have interacted with Text Editor.
      These `userIds` match the IDs set when authenticating users in your app.

```tsx highlight="2-8"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          // ...
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Return your users</StepTitle>
    <StepContent>
      `resolveUsers` requires you to return a list of users in
      the `UserMeta["info"]` format we set earlier. Remember
      that _name_, _color_, and _avatar_, are required for the editor component,
      but you can also use any other metadata in your app.

```tsx highlight="7-17"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // ["marc@example.com", ...]
          console.log(userIds);

// Return a list of users
          return [
            {
              name: "Marc",
              color: "#00ff00",
              avatar: "https://example.com/marc.png",

// Your custom metadata
              // ...
            },
            // ...
          ];
        }}

// ...
      />;
      ```

We’re only returning one user here, but make sure to return an
      array containing each user, in the same order you received the IDs.

</StepContent>

```tsx highlight="3-7"
      <LiveblocksProvider
        resolveUsers={async ({ userIds }) => {
          // Get users from your back end
          const users = await __fetchUsers__(userIds);

// Return a list of users
          return users;
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Users are now visible</StepTitle>
    <StepContent>
      After adding this, you should now be able to see your user names in cursors!

</StepContent>

</Step>
</Steps>

## Resolving mention suggestions

We can see the users that are connected, but we don’t have a way to search for
users to mention inline, for example after typing the `@` character. We can
create a simple search that resolves this data with
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-react#resolveMentionSuggestions).

// Return a list of user IDs that match the query
          return ["marc@example.com", "marissa@example.com"];
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step>
    <StepTitle>Real-world example</StepTitle>
    <StepContent>

// Return the filtered `userIds`
          return users.map((user) => user.id);
        }}

// ...
      />;
      ```

</StepContent>

</Step>
  <Step lastStep>
    <StepTitle>Mention suggestions now appear</StepTitle>
    <StepContent>

Now we’ve found and returned the correct users, Text Editor can display
      a list of mention suggestions!

</StepContent>

</Step>
</Steps>

## Next steps

You’re now ready to start building your Text Editor application! Here’s where
you can learn more:

- [API reference for Lexical React](/docs/api-reference/liveblocks-react-lexical)
- [API reference for Lexical Node](/docs/api-reference/liveblocks-node-lexical)
- [Examples](/examples/browse/text-editor)
- [Overview](/docs/ready-made-features/text-editor)

---
meta:
  title:
    "How to create a collaborative code editor with CodeMirror, Yjs, Next.js,
    and Liveblocks"
  description:
    "Build a collaborative code editor with CodeMirror, Yjs, Next.js, and
    Liveblocks"
---

In this tutorial, we’ll be building a collaborative code editor using
CodeMirror, Yjs, Next.js, and Liveblocks.

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org/),
[TypeScript](https://www.typescriptlang.org/), and
[CodeMirror](https://codemirror.net/).

## Install CodeMirror, Yjs, and Liveblocks into your Next.js application

On GitHub we have a working example of this
[collaborative CodeMirror editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-codemirror)
for you to download and run.

</Banner>

Run the following command to install the CodeMirror, Yjs, and Liveblocks
packages:

```bash
npm install @liveblocks/client @liveblocks/react @liveblocks/node @liveblocks/yjs yjs codemirror @codemirror/lang-javascript y-codemirror.next
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

export async function POST(request: NextRequest) {
  // Get the current user's info from your database
  const user = {
    id: "charlielayne@example.com",
    info: {
      name: "Charlie Layne",
      color: "#D583F0",
      picture: "https://liveblocks.io/avatars/avatar-1.png",
    },
  };

// Create a session for the current user
  // userInfo is made available in Liveblocks presence hooks, e.g. useOthers
  const session = liveblocks.prepareSession(user.id, {
    userInfo: user.info,
  });

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  // Get the current user's info from your database
  const user = {
    id: "charlielayne@example.com",
    info: {
      name: "Charlie Layne",
      color: "#D583F0",
      picture: "https://liveblocks.io/avatars/avatar-1.png",
    },
  };

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

We’ll also need another type for this tutorial. After creating the config file,
open it up and insert the following:

```tsx file="liveblocks.config.ts"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";

// ...

export type TypedLiveblocksProvider = LiveblocksYjsProvider<
  Presence,
  Storage,
  UserMeta,
  RoomEvent
>;
```

## Join a Liveblocks room

Liveblocks uses the concept of rooms, separate virtual spaces where people
collaborate. To create a realtime experience, multiple users must be connected
to the same room. Create a file in the current directory within `/app`, and name
it `Room.tsx`. Pass the location of your endpoint to `LiveblocksProvider`.

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

export function Room({ children }: { children: ReactNode }) {
  return (
    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      <RoomProvider id="my-room">
        <ClientSideSuspense fallback={<div>Loading…</div>}>
          {children}
        </ClientSideSuspense>
      </RoomProvider>
    </LiveblocksProvider>
  );
}
```

## Set up the CodeMirror editor

Now that we’ve set up Liveblocks, we can start integrating Monaco and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
"use client";

import * as Y from "yjs";
import { yCollab } from "y-codemirror.next";
import { EditorView, basicSetup } from "codemirror";
import { EditorState } from "@codemirror/state";
import { javascript } from "@codemirror/lang-javascript";
import { useCallback, useEffect, useState } from "react";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { TypedLiveblocksProvider, useRoom } from "@/liveblocks.config";
import styles from "./CollaborativeEditor.module.css";

// Collaborative code editor with undo/redo, live cursors, and live avatars
export function CollaborativeEditor() {
  const room = useRoom();
  const [element, setElement] = useState<HTMLElement>();
  const [yUndoManager, setYUndoManager] = useState<Y.UndoManager>();

const ref = useCallback((node: HTMLElement | null) => {
    if (!node) return;
    setElement(node);
  }, []);

// Set up Liveblocks Yjs provider and attach CodeMirror editor
  useEffect(() => {
    let provider: TypedLiveblocksProvider;
    let ydoc: Y.Doc;
    let view: EditorView;

if (!element || !room || !userInfo) {
      return;
    }

// Create Yjs provider and document
    ydoc = new Y.Doc();
    provider = new LiveblocksYjsProvider(room as any, ydoc);
    const ytext = ydoc.getText("codemirror");
    const undoManager = new Y.UndoManager(ytext);
    setYUndoManager(undoManager);

// Set up CodeMirror and extensions
    const state = EditorState.create({
      doc: ytext.toString(),
      extensions: [
        basicSetup,
        javascript(),
        yCollab(ytext, provider.awareness, { undoManager }),
      ],
    });

// Attach CodeMirror to element
    view = new EditorView({
      state,
      parent: element,
    });

return () => {
      ydoc?.destroy();
      provider?.destroy();
      view?.destroy();
    };
  }, [element, room, userInfo]);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer} ref={ref}></div>
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

```css file="Editor.module.css" isCollapsed isCollapsable
.container {
  display: flex;
  flex-direction: column;
  position: relative;
  border-radius: 12px;
  background: #fff;
  width: 100%;
  height: 100%;
  color: #111827;
  overflow: hidden;
}

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editorContainer {
  position: relative;
  flex-grow: 1;
  overflow: auto;
}
```

## Add your editor to the current page

Next, add the `CollaborativeEditor` into the page file, and place it inside the
`Room` component we created earlier. We should now be seeing a basic
collaborative editor!

```tsx file="/app/page.tsx"
import { Room } from "./Room";
import CollaborativeEditor from "@/components/Editor";

export default function Page() {
  return (
    <Room>
      <CollaborativeEditor />
    </Room>
  );
}
```

## Add live cursors

```tsx file="Cursors.tsx" highlight="1,10-11,35-40"
import { useRoom, useSelf } from "@/liveblocks.config";
// ...

// Get user info from Liveblocks authentication endpoint
  const userInfo = useSelf((me) => me.info);

const ref = useCallback((node: HTMLElement | null) => {
    if (!node) return;
    setElement(node);
  }, []);

// Set up Liveblocks Yjs provider and attach CodeMirror editor
  useEffect(() => {
    let provider: TypedLiveblocksProvider;
    let ydoc: Y.Doc;
    let view: EditorView;

if (!element || !room || !userInfo) {
      return;
    }

// Attach user info to Yjs
    provider.awareness.setLocalStateField("user", {
      name: userInfo.name,
      color: userInfo.color,
      colorLight: userInfo.color + "80", // 6-digit hex code at 50% opacity
    });

// Attach CodeMirror to element
    view = new EditorView({
      state,
      parent: element,
    });

return () => {
      ydoc?.destroy();
      provider?.destroy();
      view?.destroy();
    };
  }, [element, room, userInfo]);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer} ref={ref}></div>
    </div>
  );
}
```

We can style these cursors by placing CSS in a global CSS file.

```css file="globals.css" isCollapsed isCollapsable
/* Cursor name */
.cm-editor .cm-ySelectionInfo {
  position: absolute;
  top: -1.6em;
  left: -1px;
  padding: 2px 6px;
  opacity: 1;
  color: #fff;
  border: 0;
  border-radius: 6px;
  border-bottom-left-radius: 0;
  line-height: normal;
  white-space: nowrap;
  font-size: 14px;
  font-family: sans-serif;
  font-style: normal;
  font-weight: 600;
  pointer-events: none;
  user-select: none;
  z-index: 1000;
}

.cm-editor .cm-ySelectionCaretDot {
  display: none;
}

/* Other CodeMirror styles */
.cm-editor {
  height: 100%;
  font-size: 14px;
}

.cm-editor.cm-focused {
  outline: none;
}

.cm-editor .cm-scroller {
  padding-top: 1rem;
}

.cm-editor .cm-gutters {
  background: none;
  border: 0;
}

.cm-editor .cm-lineNumbers .cm-gutterElement {
  padding-left: 1rem;
  padding-right: 0.5rem;
}
```

## Add a toolbar

From this point onwards, you can build your CodeMirror app as normal! For
example, should you wish to add a basic undo/redo toolbar to your app:

```tsx file="Toolbar.tsx"
import * as Y from "yjs";
import styles from "./Toolbar.module.css";

type Props = {
  yUndoManager: Y.UndoManager;
};

export function Toolbar({ yUndoManager }: Props) {
  return (
    <div className={styles.toolbar}>
      <button className={styles.button} onClick={() => yUndoManager.undo()}>
        Undo
      </button>
      <button className={styles.button} onClick={() => yUndoManager.redo()}>
        Redo
      </button>
    </div>
  );
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button {
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
  border-radius: 6px;
  height: 32px;
  width: 32px;
  background: #fff;
  color: #1f2937;
  border: none;
  box-shadow:
    rgba(0, 0, 0, 0.12) 0 4px 8px 0,
    rgba(0, 0, 0, 0.02) 0 0 0 1px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}
```

You can then import this into your editor to enable basic CodeMirror features:

```tsx file="Editor.tsx" highlight="1,9-13"
import { Toolbar } from "@/components/Toolbar";
// ...

export function CollaborativeEditor() {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <div>
          {yUndoManager ? <Toolbar yUndoManager={yUndoManager} /> : null}
        </div>
      </div>
      <div className={styles.editorContainer} ref={ref}></div>
    </div>
  );
}
```

## Create live avatars with Liveblocks hooks

Along with building out your code editor, you can now use other Liveblocks
features, such as [Presence](/docs/ready-made-features/presence). The
[`useOthers`](/docs/api-reference/liveblocks-react#useOthers) hook allows us to
view information about each user currently online, and we can turn this into a
live avatars component.

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

return (
    <div className={styles.avatars}>
      {users.map(({ connectionId, info }) => {
        return (
          <Avatar key={connectionId} picture={info.picture} name={info.name} />
        );
      })}

{currentUser && (
        <div className="relative ml-8 first:ml-0">
          <Avatar
            picture={currentUser.info.picture}
            name={currentUser.info.name}
          />
        </div>
      )}
    </div>
  );
}

export function Avatar({ picture, name }: { picture: string; name: string }) {
  return (
    <div className={styles.avatar} data-tooltip={name}>
      <img
        src={picture}
        className={styles.avatar_picture}
        data-tooltip={name}
      />
    </div>
  );
}
```

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar {
  display: flex;
  place-content: center;
  position: relative;
  border: 4px solid #fff;
  border-radius: 9999px;
  width: 42px;
  height: 42px;
  background-color: #9ca3af;
  margin-left: -0.75rem;
}

.avatar:before {
  content: attr(data-tooltip);
  position: absolute;
  top: 100%;
  opacity: 0;
  transition: opacity 0.15s ease;
  padding: 5px 10px;
  color: white;
  font-size: 0.75rem;
  border-radius: 8px;
  margin-top: 10px;
  z-index: 1;
  background: black;
  white-space: nowrap;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  width: 100%;
  height: 100%;
  border-radius: 9999px;
}
```

You can then import this to your editor to see it in action:

```tsx file="Editor.tsx" highlight="1,13"
import { Avatars } from "@/components/Avatars";
// ...

export function CollaborativeEditor() {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <div>
          {yUndoManager ? <Toolbar yUndoManager={yUndoManager} /> : null}
        </div>
        <Avatars />
      </div>
      <div className={styles.editorContainer} ref={ref}></div>
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

You should now see the complete editor, along with live cursors, live avatars,
and some basic features! On GitHub we have a working example of this
[multiplayer code editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-codemirror).

---
meta:
  title:
    "How to create a collaborative code editor with Monaco, Yjs, Next.js, and
    Liveblocks"
  description:
    "Build a collaborative code editor with Monaco, Yjs, Next.js, and Liveblocks"
---

In this tutorial, we’ll be building a collaborative code editor using Monaco,
Yjs, Next.js, and Liveblocks.

## Install Monaco, Yjs, and Liveblocks into your Next.js application

On GitHub we have a working example of this
[collaborative Monaco editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-monaco)
for you to download and run.

</Banner>

Run the following command to install the Monaco, Yjs, and Liveblocks packages:

```bash
npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs @monaco-editor/react y-monaco y-protocols
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

We’ll also need another type for this tutorial. After creating the config file,
open it up and insert the following:

```tsx file="liveblocks.config.ts"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";

// ...

export type TypedLiveblocksProvider = LiveblocksYjsProvider<
  Presence,
  Storage,
  UserMeta,
  RoomEvent
>;
```

## Join a Liveblocks room

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

## Set up the Monaco editor

Now that we’ve set up Liveblocks, we can start integrating Monaco and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
"use client";

import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { TypedLiveblocksProvider, useRoom } from "@/liveblocks.config";
import { useCallback, useEffect, useState } from "react";
import styles from "./CollaborativeEditor.module.css";
import { Editor } from "@monaco-editor/react";
import { editor } from "monaco-editor";
import { MonacoBinding } from "y-monaco";
import { Awareness } from "y-protocols/awareness";

// Collaborative code editor with undo/redo, live cursors, and live avatars
export function CollaborativeEditor() {
  const room = useRoom();
  const [provider, setProvider] = useState<TypedLiveblocksProvider>();
  const [editorRef, setEditorRef] = useState<editor.IStandaloneCodeEditor>();

// Set up Liveblocks Yjs provider and attach Monaco editor
  useEffect(() => {
    let yProvider: TypedLiveblocksProvider;
    let yDoc: Y.Doc;
    let binding: MonacoBinding;

if (editorRef) {
      yDoc = new Y.Doc();
      const yText = yDoc.getText("monaco");
      yProvider = new LiveblocksYjsProvider(room, yDoc);
      setProvider(yProvider);

// Attach Yjs to Monaco
      binding = new MonacoBinding(
        yText,
        editorRef.getModel() as editor.ITextModel,
        new Set([editorRef]),
        yProvider.awareness as Awareness
      );
    }

return () => {
      yDoc?.destroy();
      yProvider?.destroy();
      binding?.destroy();
    };
  }, [editorRef, room]);

const handleOnMount = useCallback((e: editor.IStandaloneCodeEditor) => {
    setEditorRef(e);
  }, []);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <Editor
          onMount={handleOnMount}
          height="100%"
          width="100%"
          theme="vs-light"
          defaultLanguage="typescript"
          defaultValue=""
          options={{
            tabSize: 2,
            padding: { top: 20 },
          }}
        />
      </div>
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editorContainer {
  position: relative;
  flex-grow: 1;
}
```

## Add your editor to the current page

Next, add the `CollaborativeEditor` into the page file, and place it inside the
`Room` component we created earlier. We should now be seeing a basic
collaborative editor!

```tsx file="/app/page.tsx"
import { Room } from "./Room";
import CollaborativeEditor from "@/components/Editor";

export default function Page() {
  return (
    <Room>
      <CollaborativeEditor />
    </Room>
  );
}
```

## Add live cursors

To add live cursors to the code editor, we can get the `userInfo` for the
current user with [`useSelf`](/docs/api-reference/liveblocks-react#useSelf), and
attach it Yjs awareness. Currently, the only way to style this is to loop
through each Yjs user, and dynamically insert CSS styles into the page, using
`::after` to display users’ names. We’ll place this in a new file:

```tsx file="Cursors.tsx"
import { useEffect, useMemo, useState } from "react";
import {
  AwarenessList,
  TypedLiveblocksProvider,
  UserAwareness,
  useSelf,
} from "@/liveblocks.config";

type Props = {
  yProvider: TypedLiveblocksProvider;
};

export function Cursors({ yProvider }: Props) {
  // Get user info from Liveblocks authentication endpoint
  const userInfo = useSelf((me) => me.info);

const [awarenessUsers, setAwarenessUsers] = useState<AwarenessList>([]);

useEffect(() => {
    // Add user info to Yjs awareness
    const localUser: UserAwareness["user"] = userInfo;
    yProvider.awareness.setLocalStateField("user", localUser);

// On changes, update `awarenessUsers`
    function setUsers() {
      setAwarenessUsers([...yProvider.awareness.getStates()] as AwarenessList);
    }
    yProvider.awareness.on("change", setUsers);
    setUsers();

return () => {
      yProvider.awareness.off("change", setUsers);
    };
  }, [yProvider]);

// Insert awareness info into cursors with styles
  const styleSheet = useMemo(() => {
    let cursorStyles = "";

for (const [clientId, client] of awarenessUsers) {
      if (client?.user) {
        cursorStyles += `
          .yRemoteSelection-${clientId},
          .yRemoteSelectionHead-${clientId}  {
            --user-color: ${client.user.color};
          }

.yRemoteSelectionHead-${clientId}::after {
            content: "${client.user.name}";
          }
        `;
      }
    }

return { __html: cursorStyles };
  }, [awarenessUsers]);

return <style dangerouslySetInnerHTML={styleSheet} />;
}
```

This CSS will work in combination with some other styles, which we can place in
a global CSS file:

```css file="globals.css" isCollapsed isCollapsable
/* Cursor selection background */
.yRemoteSelection {
  opacity: 0.5;
  background-color: var(--user-color);
  margin-right: -1px;
}

/* Cursor caret */
.yRemoteSelectionHead {
  position: absolute;
  box-sizing: border-box;
  height: 100%;
  border-left: 2px solid var(--user-color);
}

/* Cursor name */
.yRemoteSelectionHead::after {
  position: absolute;
  top: -1.4em;
  left: -2px;
  padding: 2px 6px;
  background: var(--user-color);
  color: #fff;
  border: 0;
  border-radius: 6px;
  border-bottom-left-radius: 0;
  line-height: normal;
  white-space: nowrap;
  font-size: 14px;
  font-style: normal;
  font-weight: 600;
  pointer-events: none;
  user-select: none;
  z-index: 1000;
}
```

You can then import this into your editor to enable live cursors:

```tsx file="Editor.tsx" highlight="1,9"
import { Cursors } from "@/components/Cursors";
// ...

export function CollaborativeEditor() {
  // ...

return (
    <div className={styles.container}>
      {provider ? <Cursors yProvider={provider} /> : null}
      <div className={styles.editorContainer}>
        <Editor
          onMount={handleOnMount}
          height="100%"
          width="100%"
          theme="vs-light"
          defaultLanguage="typescript"
          defaultValue=""
          options={{
            tabSize: 2,
            padding: { top: 20 },
          }}
        />
      </div>
    </div>
  );
}
```

## Add a toolbar

From this point onwards, you can build your Monaco app as normal! For example,
should you wish to add a basic undo/redo toolbar to your app:

```tsx file="Toolbar.tsx"
import styles from "./Toolbar.module.css";
import { editor } from "monaco-editor";

type Props = {
  editor: editor.IStandaloneCodeEditor;
};

export function Toolbar({ editor }: Props) {
  return (
    <div className={styles.toolbar}>
      <button
        className={styles.button}
        onClick={() => editor.trigger("", "undo", null)}
      >
        Undo
      </button>
      <button
        className={styles.button}
        onClick={() => editor.trigger("", "redo", null)}
      >
        Redo
      </button>
    </div>
  );
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}

.button:active {
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 2px 3px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}
```

You can then import this into your editor to enable basic Monaco features:

```tsx file="Editor.tsx" highlight="1,10-12"
import { Toolbar } from "@/components/Toolbar";
// ...

export function CollaborativeEditor() {
  // ...

return (
    <div className={styles.container}>
      {provider ? <Cursors yProvider={provider} /> : null}
      <div className={styles.editorHeader}>
        <div>{editorRef ? <Toolbar editor={editorRef} /> : null}</div>
      </div>
      <div className={styles.editorContainer}>
        <Editor
          onMount={handleOnMount}
          height="100%"
          width="100%"
          theme="vs-light"
          defaultLanguage="typescript"
          defaultValue=""
          options={{
            tabSize: 2,
            padding: { top: 20 },
          }}
        />
      </div>
    </div>
  );
}
```

## Create live avatars with Liveblocks hooks

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  width: 100%;
  height: 100%;
  border-radius: 9999px;
}
```

You can then import this to your editor to see it in action:

```tsx file="Editor.tsx" highlight="1,12"
import { Avatars } from "@/components/Avatars";
// ...

export function CollaborativeEditor() {
  // ...

return (
    <div className={styles.container}>
      {provider ? <Cursors yProvider={provider} /> : null}
      <div className={styles.editorHeader}>
        <div>{editorRef ? <Toolbar editor={editorRef} /> : null}</div>
        <Avatars />
      </div>
      <div className={styles.editorContainer}>
        <Editor
          onMount={handleOnMount}
          height="100%"
          width="100%"
          theme="vs-light"
          defaultLanguage="typescript"
          defaultValue=""
          options={{
            tabSize: 2,
            padding: { top: 20 },
          }}
        />
      </div>
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

---
meta:
  title:
    "How to create a collaborative online whiteboard with React, Redux, and
    Liveblocks"
  description:
    "Build a multiplayer whiteboard app with React, Redux, and Liveblocks"
---

In this 25-minute tutorial, we’ll be building a collaborative whiteboard app
using React, Redux and Liveblocks. As users add and move rectangles in a canvas,
changes will be automatically synced and persisted, allowing for a canvas that
updates in realtime across clients. Users will also be able to see other users
selections, and undo and redo actions.

This guide assumes that you’re already familiar with
[React](https://reactjs.org/) and [Redux](https://redux.js.org/). If you’re not
using Redux, we recommend reading one of our dedicated whiteboard tutorials:

- [React tutorial](/docs/tutorials/collaborative-online-whiteboard/react)
- [React + Zustand tutorial](/docs/tutorials/collaborative-online-whiteboard/react-zustand)

A live demo and the source code for this guide are
[in our examples](/examples/collaborative-whiteboard/redux-whiteboard).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

Create a new app with [`create-react-app`](https://create-react-app.dev/):

```bash
npx create-react-app redux-whiteboard
```

Then run the following command to install the Liveblocks packages and Redux:

```bash
npm install redux react-redux @reduxjs/toolkit @liveblocks/client @liveblocks/redux
```

### Connect to Liveblocks servers [#connect-liveblocks-servers]

In order to use Liveblocks, we’ll need to sign up and get an API key.
[Create an account](/auth/signup), then navigate to
[the dashboard](/dashboard/apikeys) to find your public key. It should start
with `pk_`.

With a secret key, you can control who can access the room. it’s more secure but
you need your own back-end endpoint. For this tutorial, we’ll go with a public
key. For more info, see the [authentication guide](/docs/authentication).

</Banner>

Create a new file `src/store.js` and initialize the Liveblocks client with your
public API key. Then add our
[enhancer](/docs/api-reference/liveblocks-redux#enhancer) to your store
configuration.

```js file="src/store.js"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

export const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const initialState = {
  /* default state will go there */
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    /* Reducer logic will go there */
  },
});

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(liveblocksEnhancer({ client })),
  });
}

const store = makeStore();

export default store;
```

And edit `src/index.js` to add the react-redux provider to your app:

```js highlight="6,7,11,13" file="src/index.js"
import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";

import { Provider } from "react-redux";
import store from "./store";

ReactDOM.render(
  <React.StrictMode>
    <Provider store={store}>
      <App />
    </Provider>
  </React.StrictMode>,
  document.getElementById("root")
);
```

### Connect to a Liveblocks room [#connect-liveblocks-room]

Liveblocks uses the concept of _rooms_, separate virtual spaces where people can
collaborate. To create a multiplayer experience, multiple users must be
connected to the same room.

Our enhancer is responsible to enter or leave a room when you dispatch
[`enterRoom`](/docs/api-reference/liveblocks-redux#actions-enter) or
[`leaveRoom`](/docs/api-reference/liveblocks-redux#actions-leave).

In our main component, we want to connect to the Liveblocks room when the
component does mount, and leave the room when it unmounts.

```js file="src/App.js"
import { useEffect } from "react";
import "./App.css";
import { useDispatch } from "react-redux";
import { actions } from "@liveblocks/redux";

const roomId = "redux-whiteboard";

export default function App() {
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom(roomId));

return () => {
      dispatch(actions.leaveRoom());
    };
  }, [dispatch]);

return <div className="container">Whiteboard app</div>;
}
```

## Create a canvas [#basic-canvas]

Whiteboard shapes will be stored even after all users disconnect, so we will use
Liveblocks storage to persist them.

Add a `shapes` property to your store, and configure the enhancer to sync and
persist them with Liveblocks.

To achieve that, we are going to use the enhancer option
[`storageMapping: { shapes: true }`](/docs/api-reference/liveblocks-redux#middleware-option-storage-mapping).
It means that the part of the state named `shapes` should be automatically
synced with Liveblocks Storage.

```js file="src/store.js" highlight="10,28"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

export const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const initialState = {
  shapes: {},
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    /* Reducer logic will go there */
  },
});

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(
        liveblocksEnhancer({
          client,
          storageMapping: { scientist: true },
        })
      ),
  });
}

const store = makeStore();

export default store;
```

Afterwards, we draw the shapes in our canvas. To keep it simple for the
tutorial, we are going to only support rectangle.

```jsx file="src/App.js" highlight="3,9-10,25-35,38-48"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom(roomId));

return () => {
      dispatch(actions.leaveRoom());
    };
  }, [dispatch]);

if (isLoading) {
    return <div className="loading">Loading</div>;
  }

return (
    <div className="canvas">
      {Object.entries(shapes).map(([shapeId, shape]) => {
        return <Rectangle key={shapeId} shape={shape} />;
      })}
    </div>
  );
}

const Rectangle = ({ shape }) => {
  return (
    <div
      className="rectangle"
      style={{
        transform: `translate(${shape.x}px, ${shape.y}px)`,
        backgroundColor: shape.fill ? shape.fill : "#CCC",
      }}
    ></div>
  );
};
```

_Place the following within `src/App.css`, and then you will be able to insert
rectangular shapes into the whiteboard._

```css file="src/App.css" isCollapsed isCollapsable
body {
  background-color: #eeeeee;
}

.loading {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
  width: 100vw;
}

.canvas {
  background-color: #eeeeee;
  touch-action: none;
  width: 100vw;
  height: 100vh;
}

.rectangle {
  position: absolute;
  /* transition: all 0.1s ease; */
  stroke-width: 1;
  border-style: solid;
  border-width: 2px;
  height: 100px;
  width: 100px;
}

.toolbar {
  position: fixed;
  top: 12px;
  left: 50%;
  transform: translateX(-50%);
  padding: 4px;
  border-radius: 8px;
  box-shadow:
    0px 2px 4px rgba(0, 0, 0, 0.1),
    0px 0px 0px 1px rgba(0, 0, 0, 0.05);
  display: flex;
  background-color: #ffffff;
  user-select: none;
}

.toolbar button {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 4px 8px;
  border-radius: 4px;
  background-color: #f8f8f8;
  color: #181818;
  border: none;
  box-shadow:
    0px 2px 4px rgba(0, 0, 0, 0.1),
    0px 0px 0px 1px rgba(0, 0, 0, 0.05);
  margin: 4px;
  font-weight: 500;
  font-size: 12px;
}

.toolbar button:hover,
.toolbar button:focus {
  background-color: #ffffff;
}

.toolbar button:active {
  background-color: #eeeeee;
}
```

## Insert rectangles

Currently our whiteboard is empty, and there’s no way to add rectangles. Let’s
create a button that adds a randomly placed rectangle to the board.

Add a new action to your store that randomly insert a rectangle on the board.

```js file="src/store.js" highlight="9-17,27-35,39"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

export const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const COLORS = ["#DC2626", "#D97706", "#059669", "#7C3AED", "#DB2777"];

function getRandomInt(max) {
  return Math.floor(Math.random() * max);
}

function getRandomColor() {
  return COLORS[getRandomInt(COLORS.length)];
}

const initialState = {
  shapes: {},
};

export const { insertRectangle } = slice.actions;

const store = makeStore();

export default store;
```

Then add a button to dispatch this action from the board.

```jsx file="src/App.js" highlight="6,18,24-27"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import { insertRectangle } from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const dispatch = useDispatch();

/* ... */

return (
    <>
      <div className="canvas">
        {Object.entries(shapes).map(([shapeId, shape]) => {
          return <Rectangle key={shapeId} shape={shape} />;
        })}
      </div>
      <div className="toolbar">
        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>
      </div>
    </>
  );
}

/* Rectangle */
```

## Add selection [#selection]

We can use Liveblocks to display which shape each user is currently selecting,
in this case by adding a border to the rectangles. We’ll use a blue border to
represent the local user, and green borders for remote users.

Any online user could select a shape, and we need to keep track of this, so it’s
best if each user holds their own `selectedShape` property.

Luckily, Liveblocks uses the concept of presence to handle these temporary
states. A user’s presence can be used to represent the position of a cursor on
screen, or in this case the selected shape in a design tool.

We want to add some data to our Redux store, `selectedShape` will contain the
selected shape id. `selectedShape` will be set when the user select or insert a
rectangle.

The middleware option
[`presenceMapping: { selectedShape: true }`](/docs/api-reference/liveblocks-redux#middleware-option-presence-mapping)
means that we want to automatically sync the part of the state named
`selectedShape` to Liveblocks Presence.

```js file="src/store.js" highlight="5,15-17,21,31"
/* ... */

const initialState = {
  shapes: {},
  selectedShape: null,
};

export const { insertRectangle, onShapePointerDown } = slice.actions;

const store = makeStore();

export default store;
```

Update your `App` and `Rectangle` components to show if a shape is selected by
the current user or someone else in the room.

```jsx file="src/App.js" highlight="6,13-14,23-31,36,38,50-51,59,61-64"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import { insertRectangle, onShapePointerDown } from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const others = useSelector((state) => state.liveblocks.others);
  const selectedShape = useSelector((state) => state.selectedShape);
  const dispatch = useDispatch();

/* ... */

return (
    <>
      <div className="canvas">
        {Object.entries(shapes).map(([shapeId, shape]) => {
          let selectionColor = "transparent";

if (selectedShape === shapeId) {
            selectionColor = "blue";
          } else if (
            others.some((user) => user.presence?.selectedShape === shapeId)
          ) {
            selectionColor = "green";
          }

return (
            <Rectangle
              key={shapeId}
              id={shapeId}
              shape={shape}
              selectionColor={selectionColor}
            />
          );
        })}
      </div>
      <div className="toolbar">
        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>
      </div>
    </>
  );
}

const Rectangle = ({ shape, selectionColor, id }) => {
  const dispatch = useDispatch();

return (
    <div
      className="rectangle"
      style={{
        transform: `translate(${shape.x}px, ${shape.y}px)`,
        backgroundColor: shape.fill ? shape.fill : "#CCC",
        borderColor: selectionColor,
      }}
      onPointerDown={(e) => {
        e.stopPropagation();
        dispatch(onShapePointerDown(id));
      }}
    ></div>
  );
};
```

## Delete rectangles

Now that users can select rectangles, we can add a button that allow deleting
rectangles too.

Create a `deleteShape` action to remove the selected shape from `shapes`, and
then reset the user’s selection:

```js file="src/store.js" highlight="20,25-30,34"
/* ... */

const initialState = {
  shapes: {},
  selectedShape: null,
};

export const { insertRectangle, onShapePointerDown, deleteShape } =
  slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(
        liveblocksEnhancer({
          client,
          presenceMapping: { selectedShape: true },
          storageMapping: { shapes: true },
        })
      ),
  });
}

const store = makeStore();

export default store;
```

```jsx file="src/App.js" highlight="6,25-30"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import { insertRectangle, onShapePointerDown, deleteShape } from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const selectedShape = useSelector((state) => state.selectedShape);
  const others = useSelector((state) => state.liveblocks.others);

const dispatch = useDispatch();

/* ... */

return (
    <>
      <div className="canvas">{/* ... */}</div>
      <div className="toolbar">
        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>
        <button
          onClick={() => dispatch(deleteShape())}
          disabled={selectedShape == null}
        >
          Delete
        </button>
      </div>
    </>
  );
}

/* Rectangle */
```

## Move rectangles

Let’s move some rectangles!

To allow users to move rectangles, we’ll update the `x` and `y` properties of
the selected shape when a user drags it:

```js file="src/store.js" highlight="6,18,23-31,39-40"
/* ... */

const initialState = {
  shapes: {},
  selectedShape: null,
  isDragging: false,
};

export const {
  insertRectangle,
  onShapePointerDown,
  deleteShape,
  onCanvasPointerUp,
  onCanvasPointerMove,
} = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(
        liveblocksEnhancer({
          client,
          presenceMapping: { selectedShape: true },
          storageMapping: { shapes: true },
        })
      ),
  });
}

const store = makeStore();

export default store;
```

```jsx file="src/App.js" highlight="10-11,30-36"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import {
  insertRectangle,
  onShapePointerDown,
  deleteShape,
  onCanvasPointerUp,
  onCanvasPointerMove,
} from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const selectedShape = useSelector((state) => state.selectedShape);
  const others = useSelector((state) => state.liveblocks.others);

const dispatch = useDispatch();

/* ... */

return (
    <>
      <div
        className="canvas"
        onPointerMove={(e) => {
          e.preventDefault();
          dispatch(onCanvasPointerMove({ x: e.clientX, y: e.clientY }));
        }}
        onPointerUp={() => {
          dispatch(onCanvasPointerUp());
        }}
      >
        {/* ... */}
      </div>
      <div className="toolbar">{/* ... */}</div>
    </>
  );
}

/* ... */
```

## Multiplayer undo/redo [#undo-redo]

With Liveblocks, you can enable multiplayer undo/redo in just a few lines of
code.

Add two buttons to the toolbar and bind them to
[`room.history.undo`](/docs/api-reference/liveblocks-client#Room.history.undo)
and
[`room.history.redo`](/docs/api-reference/liveblocks-client#Room.history.redo).
These functions only impact modifications made to the room’s storage.

```jsx file="src/App.js" highlight="12,48-53"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import {
  insertRectangle,
  onShapePointerDown,
  deleteShape,
  onCanvasPointerUp,
  onCanvasPointerMove,
  client,
} from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const selectedShape = useSelector((state) => state.selectedShape);
  const others = useSelector((state) => state.liveblocks.others);

const dispatch = useDispatch();

/* ... */

return (
    <>
      <div
        className="canvas"
        onPointerMove={(e) => {
          /* ... */
        }}
        onPointerUp={() => {
          /* ... */
        }}
      >
        {/* ... */}
      </div>
      <div className="toolbar">
        <button onClick={() => dispatch(insertRectangle())}>Rectangle</button>
        <button
          onClick={() => dispatch(deleteShape())}
          disabled={selectedShape == null}
        >
          Delete
        </button>
        <button onClick={() => client.getRoom(roomId).history.undo()}>
          Undo
        </button>
        <button onClick={() => client.getRoom(roomId).history.redo()}>
          Redo
        </button>
      </div>
    </>
  );
}

/* Rectangle */
```

### Pause and resume history [#pause-resume-history]

When a user moves a rectangle, a large number of actions are sent to Liveblocks
and live synced, enabling other users to see movements in realtime.

The problem with this is that the undo button returns the rectangle to the last
intermediary position, and not the position where the rectangle started its
movement. We can fix this by pausing storage history until the move has
completed.

We’ll use
[`history.pause`](/docs/api-reference/liveblocks-client#Room.history.pause) to
disable adding any positions to the history stack while the cursors moves, and
then call
[`history.resume`](/docs/api-reference/liveblocks-client#Room.history.resume)
afterwards.

```js file="src/App.js" highlight="36,59"
import { useEffect } from "react";
import "./App.css";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import {
  insertRectangle,
  onShapePointerDown,
  deleteShape,
  onCanvasPointerUp,
  onCanvasPointerMove,
  client,
} from "./store";

const roomId = "redux-whiteboard";

export default function App() {
  const shapes = useSelector((state) => state.shapes);
  const isLoading = useSelector((state) => state.liveblocks.isStorageLoading);
  const selectedShape = useSelector((state) => state.selectedShape);
  const others = useSelector((state) => state.liveblocks.others);

const dispatch = useDispatch();

/* ... */

return (
    <>
      <div
        className="canvas"
        onPointerMove={(e) => {
          /* ... */
        }}
        onPointerUp={() => {
          dispatch(onCanvasPointerUp());
          client.getRoom(roomId).history.resume();
        }}
      >
        {/* ... */}
      </div>
      <div className="toolbar">{/* ... */}</div>
    </>
  );
}

const Rectangle = ({ shape, selectionColor, id }) => {
  const dispatch = useDispatch();

return (
    <div
      className="rectangle"
      style={{
        transform: `translate(${shape.x}px, ${shape.y}px)`,
        backgroundColor: shape.fill ? shape.fill : "#CCC",
        borderColor: selectionColor,
      }}
      onPointerDown={(e) => {
        e.stopPropagation();
        client.getRoom(roomId).history.pause();
        dispatch(onShapePointerDown(id));
      }}
    ></div>
  );
};
```

Voilà! We have a working collaborative whiteboard app, with persistent data
storage.

## Summary

In this tutorial, we’ve learnt about the concept of rooms, presence, and others.
We've also learnt how to put all these into practice, and how to persist state
using storage too.

You can see some stats about the room you created in your
[dashboard](https://liveblocks.io/dashboard/rooms).

## Next steps

- [API reference](/docs/api-reference/liveblocks-redux)
- [Authentication](/docs/authentication)

---
meta:
  title:
    "How to create a collaborative online whiteboard with React, Zustand, and
    Liveblocks"
  description:
    "Build a multiplayer whiteboard app with React, Zustand, and Liveblocks"
---

In this 25-minute tutorial, we’ll be building a collaborative whiteboard app
using React, Zustand and Liveblocks. As users add and move rectangles in a
canvas, changes will be automatically synced and persisted, allowing for a
canvas that updates in realtime across clients. Users will also be able to see
other users selections, and undo and redo actions.

This guide assumes that you’re already familiar with
[React](https://reactjs.org/) and [Zustand](https://github.com/pmndrs/zustand).
If you’re not using Zustand, we recommend reading one of our dedicated
whiteboard tutorials:

- [React tutorial](/docs/tutorials/collaborative-online-whiteboard/react)
- [React + Redux tutorial](/docs/tutorials/collaborative-online-whiteboard/react-redux)

A live demo and the source code for this guide are
[in our examples](/examples/collaborative-whiteboard/zustand-whiteboard).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

Create a new app with [`create-react-app`](https://create-react-app.dev/):

```bash
npx create-react-app zustand-whiteboard --template typescript
```

To start a plain JavaScript project, you can omit the `--template typescript`
flag.

Then install the Liveblocks packages and Zustand:

```bash
npm install zustand @liveblocks/client @liveblocks/zustand
```

### Connect to Liveblocks servers [#connect-liveblocks-servers]

</Banner>

Create a new file `src/store.ts` and initialize the Liveblocks client with your
public API key. Then add our
[`liveblocks` middleware](/docs/api-reference/liveblocks-zustand#middleware) to
your store configuration.

```ts file="src/store.ts"
import create from "zustand";
import { createClient } from "@liveblocks/client";
import { liveblocks } from "@liveblocks/zustand";
import type { WithLiveblocks } from "@liveblocks/zustand";

type State = {
  // Your Zustand state type will be defined here
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      // Your state and actions will go here
    }),
    { client }
  )
);

export default useStore;
```

### Connect to a Liveblocks room [#connect-liveblocks-room]

Liveblocks uses the concept of _rooms_, separate virtual spaces where people can
collaborate. To create a multiplayer experience, multiple users must be
connected to the same room.

Our middleware injected the object `liveblocks` to the store. Inside that
object, the first methods that we are going to use are
[`enterRoom`](/docs/api-reference/liveblocks-zustand#liveblocks-state-enter-room)
and
[`leaveRoom`](/docs/api-reference/liveblocks-zustand#liveblocks-state-leave-room).

In our main component, we want to connect to the Liveblocks room when the
component does mount, and leave the room when it unmounts.

```tsx file="src/App.tsx"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

export default function App() {
  const enterRoom = useStore((state) => state.liveblocks.enterRoom);
  const leaveRoom = useStore((state) => state.liveblocks.leaveRoom);

useEffect(() => {
    enterRoom("zustand-whiteboard");
    return () => {
      leaveRoom("zustand-whiteboard");
    };
  }, [enterRoom, leaveRoom]);

return <div className="container">Whiteboard app</div>;
}
```

## Create a canvas [#basic-canvas]

Whiteboard shapes will be stored even after all users disconnect, so we will use
Liveblocks storage to persist them.

Add a `shapes` property to your store, and tell the middleware to sync and
persist them with Liveblocks.

To achieve that, we are going to use the middleware option
[`storageMapping: { shapes: true }`](/docs/api-reference/liveblocks-zustand#middleware-option-storage-mapping).
It means that the part of the state named `shapes` should be automatically
synced with Liveblocks Storage.

```ts file="src/store.ts" highlight="6-10,13,23,27"
import create from "zustand";
import { createClient } from "@liveblocks/client";
import { liveblocks } from "@liveblocks/zustand";
import type { WithLiveblocks } from "@liveblocks/zustand";

export type Shape = {
  x: number;
  y: number;
  fill: string;
};

type State = {
  shapes: Record<string, Shape>;
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      shapes: {},
    }),
    {
      client,
      storageMapping: { shapes: true },
    }
  )
);

export default useStore;
```

Afterwards, we draw the shapes in our canvas. To keep it simple for the
tutorial, we are going to only support rectangle.

```tsx file="src/App.tsx" highlight="8,11,20-30,33-43"
import { useEffect } from "react";
import useStore from "./store";
import type { Shape } from "./store";

import "./App.css";

export default function App() {
  const shapes = useStore((state) => state.shapes);
  const enterRoom = useStore((state) => state.liveblocks.enterRoom);
  const leaveRoom = useStore((state) => state.liveblocks.leaveRoom);
  const isLoading = useStore((state) => state.liveblocks.isStorageLoading);

useEffect(() => {
    enterRoom("zustand-whiteboard");
    return () => {
      leaveRoom("zustand-whiteboard");
    };
  }, [enterRoom, leaveRoom]);

if (isLoading) {
    return <div className="loading">Loading...</div>;
  }

return (
    <div className="canvas">
      {Object.entries(shapes).map(([shapeId, shape]) => {
        return <Rectangle key={shapeId} shape={shape} />;
      })}
    </div>
  );
}

const Rectangle = ({ shape }: { shape: Shape }) => {
  return (
    <div
      className="rectangle"
      style={{
        transform: `translate(${shape.x}px, ${shape.y}px)`,
        backgroundColor: shape.fill ? shape.fill : "#CCC",
      }}
    ></div>
  );
};
```

_Place the following within `src/App.css`, and then you will be able to insert
rectangular shapes into the whiteboard._

```css file="src/App.css" isCollapsed isCollapsable
body {
  background-color: #eeeeee;
}

.loading {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
  width: 100vw;
}

.canvas {
  background-color: #eeeeee;
  touch-action: none;
  width: 100vw;
  height: 100vh;
}

.rectangle {
  position: absolute;
  /* transition: all 0.1s ease; */
  stroke-width: 1;
  border-style: solid;
  border-width: 2px;
  height: 100px;
  width: 100px;
}

.toolbar button:hover,
.toolbar button:focus {
  background-color: #ffffff;
}

.toolbar button:active {
  background-color: #eeeeee;
}
```

## Insert rectangles

Currently our whiteboard is empty, and there’s no way to add rectangles. Let’s
create a button that adds a randomly placed rectangle to the board.

Add a new function to your store that randomly insert a rectangle on the board.

```ts file="src/store.ts" highlight="14,21-29,33,35-48"
import create from "zustand";
import { createClient } from "@liveblocks/client";
import { liveblocks } from "@liveblocks/zustand";
import type { WithLiveblocks } from "@liveblocks/zustand";

export type Shape = {
  x: number;
  y: number;
  fill: string;
};

type State = {
  shapes: Record<string, Shape>;
  insertRectangle: () => void;
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const COLORS = ["#DC2626", "#D97706", "#059669", "#7C3AED", "#DB2777"];

function getRandomInt(max: number) {
  return Math.floor(Math.random() * max);
}

function getRandomColor() {
  return COLORS[getRandomInt(COLORS.length)];
}

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      shapes: {},
      insertRectangle: () => {
        const { shapes } = get();

const shapeId = Date.now().toString();
        const shape = {
          x: getRandomInt(300),
          y: getRandomInt(300),
          fill: getRandomColor(),
        };

set({
          shapes: { ...shapes, [shapeId]: shape },
        });
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
    }
  )
);

export default useStore;
```

Then add a button to call this function from the board.

```tsx file="src/App.tsx" highlight="8,13,19-22"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

export default function App() {
  const shapes = useStore((state) => state.shapes);
  const insertRectangle = useStore((state) => state.insertRectangle);

/* ... */

return (
    <>
      <div className="canvas">
        {Object.entries(shapes).map(([shapeId, shape]) => {
          return <Rectangle key={shapeId} shape={shape} />;
        })}
      </div>
      <div className="toolbar">
        <button onClick={insertRectangle}>Rectangle</button>
      </div>
    </>
  );
}

/* Rectangle */
```

## Add selection [#selection]

Any online user could select a shape, and we need to keep track of this, so it’s
best if each user holds their own `selectedShape` property.

We want to add some data to our Zustand store, `selectedShape` will contain the
selected shape id. `selectedShape` will be set when the user select or insert a
rectangle.

The middleware option
[`presenceMapping: { selectedShape: true }`](/docs/api-reference/liveblocks-zustand#middleware-option-presence-mapping)
means that we want to automatically sync the part of the state named
`selectedShape` to Liveblocks Presence.

```ts file="src/store.ts" highlight="5,7,16,29,32-34,39"
/* ... */

type State = {
  shapes: Record<string, Shape>;
  selectedShape: string | null;
  insertRectangle: () => void;
  onShapePointerDown: (shapeId: string | null) => void;
};

/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      shapes: {},
      selectedShape: null,
      insertRectangle: () => {
        const { shapes } = get();

const shapeId = Date.now().toString();
        const shape = {
          x: getRandomInt(300),
          y: getRandomInt(300),
          fill: getRandomColor(),
        };

set({
          shapes: { ...shapes, [shapeId]: shape },
          selectedShape: shapeId,
        });
      },
      onShapePointerDown: (shapeId) => {
        set({ selectedShape: shapeId });
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
      presenceMapping: { selectedShape: true },
    }
  )
);

export default useStore;
```

Update your `App` and `Rectangle` components to show if a shape is selected by
the current user or someone else in the room.

```tsx file="src/App.tsx" highlight="9,10,18-26,31,33,45-51,59,61-64"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

/* ... */

return (
    <>
      <div className="canvas">
        {Object.entries(shapes).map(([shapeId, shape]) => {
          let selectionColor = "transparent";

return (
            <Rectangle
              key={shapeId}
              id={shapeId}
              shape={shape}
              selectionColor={selectionColor}
            />
          );
        })}
      </div>
      <div className="toolbar">
        <button onClick={insertRectangle}>Rectangle</button>
      </div>
    </>
  );
}

const Rectangle = (props: {
  id: string;
  shape: Shape;
  selectionColor: string;
}) => {
  const { id, shape, selectionColor } = props;
  const onShapePointerDown = useStore((state) => state.onShapePointerDown);

return (
    <div
      className="rectangle"
      style={{
        transform: `translate(${shape.x}px, ${shape.y}px)`,
        backgroundColor: shape.fill ? shape.fill : "#CCC",
        borderColor: selectionColor,
      }}
      onPointerDown={(e) => {
        e.stopPropagation();
        onShapePointerDown(id);
      }}
    ></div>
  );
};
```

## Delete rectangles

Now that users can select rectangles, we can add a button that allow deleting
rectangles too.

Add a `deleteShape` to remove the selected shape from `shapes`, and then reset
the user’s selection:

```ts file="src/store.ts" highlight="8,24-35"
/* ... */

type State = {
  shapes: Record<string, Shape>;
  selectedShape: string | null;
  insertRectangle: () => void;
  onShapePointerDown: (shapeId: string | null) => void;
  deleteShape: () => void;
};

/* ... */

export default useStore;
```

```tsx file="src/App.ts" highlight="11,20-22"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

/* ... */

return (
    <>
      <div className="canvas">{/* ... */}</div>
      <div className="toolbar">
        <button onClick={insertRectangle}>Rectangle</button>
        <button onClick={deleteShape} disabled={selectedShape === null}>
          Delete
        </button>
      </div>
    </>
  );
}

/* Rectangle */
```

## Move rectangles

Let’s move some rectangles!

To allow users to move rectangles, we’ll update the `x` and `y` properties of
the selected shape when a user drags it:

```ts file="src/store.ts" highlight="6,10-11,21,27,32-58"
/* ... */

type State = {
  shapes: Record<string, Shape>;
  selectedShape: string | null;
  isDragging: boolean;
  insertRectangle: () => void;
  onShapePointerDown: (shapeId: string | null) => void;
  deleteShape: () => void;
  onCanvasPointerUp: () => void;
  onCanvasPointerMove: (e: React.PointerEvent) => void;
};

/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      shapes: {},
      selectedShape: null,
      isDragging: false,

insertRectangle: () => {
        /* ... */
      },
      onShapePointerDown: (shapeId) => {
        set({ selectedShape: shapeId, isDragging: true });
      },
      deleteShape: () => {
        /* ... */
      },
      onCanvasPointerUp: () => {
        set({ isDragging: false });
      },
      onCanvasPointerMove: (e) => {
        e.preventDefault();

const { isDragging, shapes, selectedShape } = get();
        if (!selectedShape) {
          /* Nothing todo */
          return;
        }

const shape = shapes[selectedShape];

if (shape && isDragging) {
          set({
            shapes: {
              ...shapes,
              [selectedShape]: {
                ...shape,
                x: e.clientX - 50,
                y: e.clientY - 50,
              },
            },
          });
        }
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
      presenceMapping: { selectedShape: true },
    }
  )
);

export default useStore;
```

```tsx file="src/App.tsx" highlight="12,13,21,22"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

export default function App() {
  const shapes = useStore((state) => state.shapes);
  const insertRectangle = useStore((state) => state.insertRectangle);
  const others = useStore((state) => state.liveblocks.others);
  const selectedShape = useStore((state) => state.selectedShape);
  const deleteShape = useStore((state) => state.deleteShape);
  const onCanvasPointerMove = useStore((state) => state.onCanvasPointerMove);
  const onCanvasPointerUp = useStore((state) => state.onCanvasPointerUp);

/* ... */

return (
    <>
      <div
        className="canvas"
        onPointerMove={onCanvasPointerMove}
        onPointerUp={onCanvasPointerUp}
      >
        {/* ... */}
      </div>
      <div className="toolbar">{/* ... */}</div>
    </>
  );
}

/* Rectangle */
```

## Multiplayer undo/redo [#undo-redo]

With Liveblocks, you can enable multiplayer undo/redo in just a few lines of
code.

```tsx file="src/App.tsx" highlight="14,15,33,34"
import { useEffect } from "react";
import useStore from "./store";

import "./App.css";

/* ... */

return (
    <>
      <div
        className="canvas"
        onPointerMove={onCanvasPointerMove}
        onPointerUp={onCanvasPointerUp}
      >
        {/* ... */}
      </div>
      <div className="toolbar">
        <button onClick={insertRectangle}>Rectangle</button>
        <button onClick={deleteShape} disabled={selectedShape === null}>
          Delete
        </button>
        <button onClick={undo}>Undo</button>
        <button onClick={redo}>Redo</button>
      </div>
    </>
  );
}

/* Rectangle */
```

### Pause and resume history [#pause-resume-history]

When a user moves a rectangle, a large number of actions are sent to Liveblocks
and live synced, enabling other users to see movements in realtime.

```ts file="src/store.ts" highlight="14,22"
/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      isDragging: false,
      shapes: {},
      selectedShape: null,

insertRectangle: () => {
        /* ... */
      },
      onShapePointerDown: (shapeId) => {
        get().liveblocks.room?.history.pause();
        set({ selectedShape: shapeId, isDragging: true });
      },
      deleteShape: () => {
        /* ... */
      },
      onCanvasPointerUp: () => {
        set({ isDragging: false });
        get().liveblocks.room?.history.resume();
      },
      onCanvasPointerMove: (e) => {
        /* ... */
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
      presenceMapping: { selectedShape: true },
    }
  )
);

export default useStore;
```

### Add selection to history [#selection-history]

By default, presence updates are not added to the room’s history. Let’s add the
current user selection to the room’s history to improve our undo/redo behavior.

To accomplish that, use
[`room.updatePresence`](/docs/api-reference/liveblocks-client#Room.updatePresence)
with the option `addToHistory` to update `selectedShape`. Liveblocks middleware
will update store `selectedShape` for you.

```ts file="src/store.ts" highlight="11,20-26,29-35,38,44-48"
/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      isDragging: false,
      shapes: {},
      selectedShape: null,

insertRectangle: () => {
        const { shapes, liveblocks } = get();

const shapeId = Date.now().toString();
        const shape = {
          x: getRandomInt(300),
          y: getRandomInt(300),
          fill: getRandomColor(),
        };

liveblocks.room?.updatePresence(
          { selectedShape: shapeId },
          { addToHistory: true }
        );
        set({
          shapes: { ...shapes, [shapeId]: shape },
        });
      },
      onShapePointerDown: (shapeId) => {
        const room = get().liveblocks.room;
        room?.history.pause();
        room?.updatePresence(
          { selectedShape: shapeId },
          { addToHistory: true }
        );
        set({ isDragging: true });
      },
      deleteShape: () => {
        const { shapes, selectedShape, liveblocks } = get();
        if (!selectedShape) {
          /* Nothing todo */
          return;
        }
        const { [selectedShape]: shapeToDelete, ...newShapes } = shapes;
        liveblocks.room?.updatePresence(
          { selectedShape: null },
          { addToHistory: true }
        );
        set({ shapes: newShapes });
      },
      onCanvasPointerUp: () => {
        /* ... */
      },
      onCanvasPointerMove: (e) => {
        /* ... */
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
      presenceMapping: { selectedShape: true },
    }
  )
);

export default useStore;
```

Voilà! We have a working collaborative whiteboard app, with persistent data
storage.

## Summary

In this tutorial, we’ve learnt about the concept of rooms, presence, and others.
We've also learnt how to put all these into practice, and how to persist state
using storage too.

You can see some stats about the room you created in your
[dashboard](https://liveblocks.io/dashboard/rooms).

## Next steps

- [API reference](/docs/api-reference/liveblocks-zustand)
- [Authentication](/docs/authentication)

---
meta:
  title:
    "How to create a collaborative text editor with Lexical, Yjs, Next.js, and
    Liveblocks"
  description:
    "Build a collaborative text editor with Lexical, Yjs, Next.js, and
    Liveblocks"
---

In this tutorial, we’ll be building a collaborative text editor using Lexical,
Yjs, Next.js, and Liveblocks.

We now have an official Lexical package, and we recommend you use this instead
of following this guide. Read more in our
[Lexical getting started guide](/docs/get-started/nextjs-lexical). However,
should you like to set up Lexical manually with Yjs, without using our full
feature set, continue reading.

</Banner>

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org),
[TypeScript](https://www.typescriptlang.org/), and
[Lexical](https://lexical.dev).

## Install Lexical, Yjs, and Liveblocks into your React application

On GitHub we have a working example of this
[collaborative Lexical editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-lexical)
for you to download and run.

</Banner>

Run the following command to install the Lexical, Yjs, and Liveblocks packages:

```bash
npm install lexical @lexical/react @lexical/yjs @liveblocks/client @liveblocks/react @liveblocks/yjs yjs
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

## Join a Liveblocks room

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

## Set up the Lexical editor

Now that we set up Liveblocks, we can start integrating Lexical and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
"use client";

import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import * as Y from "yjs";
import { useRoom } from "@/liveblocks.config";
import styles from "./Editor.module.css";
import {
  $createParagraphNode,
  $createTextNode,
  $getRoot,
  LexicalEditor,
} from "lexical";
import { LexicalComposer } from "@lexical/react/LexicalComposer";
import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";
import { ContentEditable } from "@lexical/react/LexicalContentEditable";
import LexicalErrorBoundary from "@lexical/react/LexicalErrorBoundary";
import { CollaborationPlugin } from "@lexical/react/LexicalCollaborationPlugin";
import { Provider } from "@lexical/yjs";

// Set up editor config
const initialConfig = {
  // NOTE: This is critical for collaboration plugin to set editor state to null. It
  // would indicate that the editor should not try to set any default state
  // (not even empty one), and let collaboration plugin do it instead
  editorState: null,
  namespace: "Demo",
  nodes: [],
  onError: (error: unknown) => {
    throw error;
  },
};

// Define initial editor state
function initialEditorState(editor: LexicalEditor): void {
  const root = $getRoot();
  const paragraph = $createParagraphNode();
  const text = $createTextNode();
  paragraph.append(text);
  root.append(paragraph);
}

// Collaborative text editor with simple rich text
export default function Editor() {
  // Get Liveblocks room
  const room = useRoom();

return (
    <div className={styles.container}>
      <LexicalComposer initialConfig={initialConfig}>
        <div className={styles.editorContainer}>
          <RichTextPlugin
            contentEditable={<ContentEditable className={styles.editor} />}
            placeholder={
              <p className={styles.placeholder}>Start typing here…</p>
            }
            ErrorBoundary={LexicalErrorBoundary}
          />
          <CollaborationPlugin
            id="yjs-plugin"
            providerFactory={(id, yjsDocMap) => {
              // Set up Liveblocks Yjs provider
              const doc = new Y.Doc();
              yjsDocMap.set(id, doc);
              const provider = new LiveblocksYjsProvider(room, doc) as Provider;
              return provider;
            }}
            initialEditorState={initialEditorState}
            shouldBootstrap={true}
          />
        </div>
      </LexicalComposer>
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editor {
  border-radius: inherit;
  flex-grow: 1;
  width: 100%;
  height: 100%;
  padding: 1rem;
}

.editor:focus {
  outline: none;
}

.editorContainer {
  position: relative;
  height: 100%;
}

.placeholder {
  pointer-events: none;
  position: absolute;
  inset: 0;
  opacity: 0.3;
  padding: 0 1em;
}
```

## Add live cursors

To add live cursors to the text editor, we can pass the current user’s
information from our authentication endpoint into `CollaborationPlugin`.

```tsx file="Editor.tsx" highlight="1,7,22-23"
import { useSelf } from "../liveblocks.config";
// ...

export default function Editor() {
  // Get Liveblocks room, and user info from Liveblocks authentication endpoint
  const room = useRoom();
  const userInfo = useSelf((me) => me.info);

return (
    <div className={styles.container}>
      <LexicalComposer initialConfig={initialConfig}>
        <div className={styles.editorContainer}>
          <RichTextPlugin
            contentEditable={<ContentEditable className={styles.editor} />}
            placeholder={
              <p className={styles.placeholder}>Start typing here…</p>
            }
            ErrorBoundary={LexicalErrorBoundary}
          />
          <CollaborationPlugin
            id="yjs-plugin"
            cursorColor={userInfo.color}
            username={userInfo.name}
            providerFactory={(id, yjsDocMap) => {
              // Set up Liveblocks Yjs provider
              const doc = new Y.Doc();
              yjsDocMap.set(id, doc);
              const provider = new LiveblocksYjsProvider(room, doc) as Provider;
              return provider;
            }}
            initialEditorState={initialEditorState}
            shouldBootstrap={true}
          />
        </div>
      </LexicalComposer>
    </div>
  );
}
```

## Add a toolbar

From this point onwards, you can build your Lexical app as normal! For example,
should you wish to add a basic text-style toolbar to your app:

```tsx file="Toolbar.tsx"
import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
import { FORMAT_TEXT_COMMAND } from "lexical";
import styles from "./Toolbar.module.css";

export function Toolbar() {
  const [editor] = useLexicalComposerContext();

return (
    <div className={styles.toolbar}>
      <button
        className={styles.buttonBold}
        onClick={() => {
          editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold");
        }}
        aria-label="Format bold"
      >
        B
      </button>
      <button
        className={styles.buttonItalic}
        onClick={() => {
          editor.dispatchCommand(FORMAT_TEXT_COMMAND, "italic");
        }}
        aria-label="Format italic"
      >
        i
      </button>
      <button
        className={styles.buttonUnderline}
        onClick={() => {
          editor.dispatchCommand(FORMAT_TEXT_COMMAND, "underline");
        }}
        aria-label="Format underline"
      >
        u
      </button>
    </div>
  );
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}

.button:active {
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 2px 3px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}
```

You can then import this into your editor to enable basic rich-text:

```tsx file="Editor.tsx" highlight="1,10-12"
import { Toolbar } from "./Toolbar";
// ...

export default function Editor() {
  // ...

return (
    <div className={styles.container}>
      <LexicalComposer initialConfig={initialConfig}>
        <div className={styles.editorHeader}>
          <Toolbar />
        </div>
        <div className={styles.editorContainer}>{/* ... */}</div>
      </LexicalComposer>
    </div>
  );
}
```

### Theme your text styles

You can go a step further and theme your basic custom text styles by using the
`theme` property, and adding corresponding styles:

```tsx file="Editor.tsx" highlight="15-22"
import styles from "./Editor.module.css";
// ...

// Set up editor config and theme
const initialConfig = {
  // NOTE: This is critical for collaboration plugin to set editor state to null. It
  // would indicate that the editor should not try to set any default state
  // (not even empty one), and let collaboration plugin do it instead
  editorState: null,
  namespace: "Demo",
  nodes: [],
  onError: (error: unknown) => {
    throw error;
  },
  theme: {
    text: {
      bold: styles.textBold,
      italic: styles.textItalic,
      underline: styles.textUnderline,
    },
    paragraph: styles.paragraph,
  },
};

// ...
```

And then in your CSS module, you can style your rich-text:

```css file="Editor.module.css" isCollapsed isCollapsable
/* ... */

.textBold {
  font-weight: bold;
}

.textItalic {
  font-style: italic;
}

.textUnderline {
  text-decoration: underline;
}

.paragraph {
  margin: 0.2rem 0;
}
```

## Create live avatars with Liveblocks hooks

Along with building out your text editor, you can now use other Liveblocks
features, such as [Presence](/docs/ready-made-features/presence). The
[`useOthers`](/docs/api-reference/liveblocks-react#useOthers) hook allows us to
view information about each user currently online, and we can turn this into a
live avatars component.

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  width: 100%;
  height: 100%;
  border-radius: 9999px;
}
```

You can then import this to your editor to see it in action:

```tsx file="Editor.tsx" highlight="1,12"
import { Avatars } from "./Avatars";
// ...

export default function Editor() {
  // ...

return (
    <div className={styles.container}>
      <LexicalComposer initialConfig={initialConfig}>
        <div className={styles.editorHeader}>
          <Toolbar />
          <Avatars />
        </div>
        <div className={styles.editorContainer}>{/* ... */}</div>
      </LexicalComposer>
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

You should now see the complete editor, along with live cursors, live avatars,
and some basic rich-text features! On GitHub we have a working example of this
[multiplayer text editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-lexical).

---
meta:
  title:
    "How to create a collaborative text editor with Quill, Yjs, Next.js, and
    Liveblocks"
  description:
    "Build a collaborative text editor with Quill, Yjs, Next.js, and Liveblocks"
---

In this tutorial, we’ll be building a collaborative text editor using Quill,
Yjs, Next.js, and Liveblocks.

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org/),
[TypeScript](https://www.typescriptlang.org/), and
[Quill](https://quilljs.com/).

## Install Quill, Yjs, and Liveblocks into your Next.js application

On GitHub we have a working example of this
[collaborative Quill editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-quill)
for you to download and run.

</Banner>

Run the following command to install the Quill, Yjs, and Liveblocks packages:

```bash
npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs quill quill-cursors react-quill y-quill
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

## Join a Liveblocks room

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

## Set up the Quill editor

Now that we’ve set up Liveblocks, we can start integrating Quill and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
"use client";

import Quill from "quill";
import ReactQuill from "react-quill";
import { QuillBinding } from "y-quill";
import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { useRoom } from "@/liveblocks.config";
import { useEffect, useRef, useState } from "react";
import styles from "./Editor.module.css";

// Collaborative text editor with simple rich text, live cursors, and live avatars
export function CollaborativeEditor() {
  const room = useRoom();
  const [text, setText] = useState<Y.Text>();
  const [provider, setProvider] = useState<any>();

// Set up Liveblocks Yjs provider
  useEffect(() => {
    const yDoc = new Y.Doc();
    const yText = yDoc.getText("quill");
    const yProvider = new LiveblocksYjsProvider(room, yDoc);
    setText(yText);
    setProvider(yProvider);

return () => {
      yDoc?.destroy();
      yProvider?.destroy();
    };
  }, [room]);

if (!text || !provider) {
    return null;
  }

return <QuillEditor yText={text} provider={provider} />;
}

type EditorProps = {
  yText: Y.Text;
  provider: any;
};

function QuillEditor({ yText, provider }: EditorProps) {
  const reactQuillRef = useRef<ReactQuill>(null);

// Set up Yjs and Quill
  useEffect(() => {
    let quill: ReturnType<ReactQuill["getEditor"]>;
    let binding: QuillBinding;

if (!reactQuillRef.current) {
      return;
    }

quill = reactQuillRef.current.getEditor();
    binding = new QuillBinding(yText, quill, provider.awareness);
    return () => {
      binding?.destroy?.();
    };
  }, [yText, provider]);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <ReactQuill
          className={styles.editor}
          placeholder="Start typing here…"
          ref={reactQuillRef}
          theme="snow"
          modules={{
            toolbar: false,
            history: {
              // Local undo shouldn't undo changes from remote users
              userOnly: true,
            },
          }}
        />
      </div>
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editor {
  border-radius: inherit;
  flex-grow: 1;
  width: 100%;
  height: 100%;
  padding: 1rem;
  outline: none;
}

.editorContainer {
  position: relative;
  height: 100%;
}

.placeholder {
  pointer-events: none;
  position: absolute;
  inset: 0;
  opacity: 0.3;
  padding: 0 1em;
}

.editor p {
  margin: 1em 0;
}
```

We recommend importing some global styles into your `layout.tsx` or `page.tsx`
file too. We’ll be creating a custom UI, but some classes are still necessary
for Quill:

```css file="globals.css" isCollapsed isCollapsable
/* Let cursor flags show on the first line */
div.ql-container {
  overflow: unset;
}

/* Remove editor focus */
div.ql-editor:focus {
  outline: none;
}

/* Hide non-visible clipboard element */
div.ql-clipboard {
  left: -100000px;
  height: 1px;
  overflow-y: hidden;
  position: absolute;
  top: 50%;
}
```

## Add your editor to the current page

Next, add the `CollaborativeEditor` into the page file, and place it inside the
`Room` component we created earlier. We should now be seeing a basic
collaborative editor!

```tsx file="/app/page.tsx"
import { Room } from "./Room";
import CollaborativeEditor from "@/components/Editor";

export default function Page() {
  return (
    <Room>
      <CollaborativeEditor />
    </Room>
  );
}
```

## Add live cursors

To add live cursors to the text editor, we can get the `userInfo` for the
current user with [`useSelf`](/docs/api-reference/liveblocks-react#useSelf), and
feed it into `editor`. We should now see some cursors with names.

```tsx file="CollaborativeEditor.tsx" highlight="1,4,9-17,30"
import { useSelf } from "../liveblocks.config.ts";
// ...

Quill.register("modules/cursors", QuillCursors);

// ...

// ...

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <ReactQuill
          className={styles.editor}
          placeholder="Start typing here…"
          ref={reactQuillRef}
          theme="snow"
          modules={{
            cursors: true,
            toolbar: false,
            history: {
              // Local undo shouldn't undo changes from remote users
              userOnly: true,
            },
          }}
        />
      </div>
    </div>
  );
}
```

## Add a toolbar

From this point onwards, you can build your Quill app as normal! For example,
should you wish to add a basic text-style toolbar to your app:

```tsx file="Toolbar.tsx"
import styles from "./Toolbar.module.css";
import { QuillEditorType } from "@/components/CollaborativeEditor";
import { useCallback } from "react";

type Props = {
  getQuill: () => QuillEditorType | null;
};

type Formats = "bold" | "italic" | "underline";

export function Toolbar({ getQuill }: Props) {
  const formatSelection = useCallback(
    (format: Formats) => {
      const quill = getQuill();
      if (!quill) {
        return;
      }

const selection = quill.getSelection();
      if (!selection) {
        return;
      }

const { index, length } = selection;
      const hasFormat = quill.getFormat(index, length)[format];

quill.formatText(
        index,
        length,
        {
          [format]: !hasFormat,
        },
        "user"
      );
    },
    [getQuill]
  );

return (
    <div className={styles.toolbar}>
      <button
        className={styles.button}
        onClick={() => formatSelection("bold")}
        aria-label="bold"
      >
        B
      </button>
      <button
        onClick={() => formatSelection("italic")}
        className={styles.button}
        aria-label="italic"
      >
        I
      </button>
      <button
        onClick={() => formatSelection("underline")}
        className={styles.button}
        aria-label="underline"
      >
        U
      </button>
    </div>
  );
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}

.button:active {
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 2px 3px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button[data-active] {
  background: #fafafa;
}
```

You can then import this into your editor, and create the `getQuill` function to
enable basic rich-text:

```tsx file="Editor.tsx" highlight="1,7-14,18-20"
import { Toolbar } from "./Toolbar";
// ...

function QuillEditor({ yText, provider }: EditorProps) {
  // ...

// Function to get the current Quill editor
  const getQuill = useCallback(() => {
    if (!reactQuillRef.current) {
      return null;
    }

return reactQuillRef.current.getEditor();
  }, []);

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <Toolbar getQuill={getQuill} />
      </div>
      <div className={styles.editorContainer}>{/* ... */}</div>
    </div>
  );
}
```

## Create live avatars with Liveblocks hooks

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  width: 100%;
  height: 100%;
  border-radius: 9999px;
}
```

You can then import this into your editor to see it in action:

```tsx file="Editor.tsx" highlight="1,11"
import { Avatars } from "./Avatars";
// ...

function QuillEditor({ yText, provider }: EditorProps) {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <Toolbar getQuill={getQuill} />
        <Avatars />
      </div>
      <div className={styles.editorContainer}>{/* ... */}</div>
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

---
meta:
  title:
    "How to create a collaborative text editor with Slate, Yjs, Next.js, and
    Liveblocks"
  description:
    "Build a collaborative text editor with Slate, Yjs, Next.js, and Liveblocks"
---

In this tutorial, we’ll be building a collaborative text editor using Slate,
Yjs, Next.js, and Liveblocks.

## Install Slate, Yjs, and Liveblocks into your Next.js application

On GitHub we have a working example of this
[collaborative Slate editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-slate)
for you to download and run.

</Banner>

Run the following command to install the Slate, Yjs, and Liveblocks packages:

```bash
npm install @liveblocks/client @liveblocks/react @liveblocks/yjs @liveblocks/node yjs slate slate-react @slate-yjs/core @slate-yjs/react
```

### Transpile slate-yjs

Add `transpilePackages` to your `next.config.ts` file to allow
`@slate-yjs/react` to be bundled correctly.

```js highlight="2"
module.exports = {
  transpilePackages: ["@slate-yjs/react"],

// ...
};
```

#### Got an error?

Note that if you’re seeing an error that resembles the following, you’re
probably using an older version of Next.js that doesn’t support
`transpilePackages`.

```
Error: Directory import '/node_modules/use-sync-external-store/shim' is not supported resolving ES modules imported from /node_modules/@slate-yjs/react/dist/index.js
Did you mean to import use-sync-external-store/shim/index.js?
```

You may need to upgrade to a newer version of Next.js for this to work.

```bash
npm i next@latest
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="/pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

## Join a Liveblocks room

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

## Set up the Slate editor

Now that we’ve set up Liveblocks, we can start integrating Slate and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { useEffect, useMemo, useState } from "react";
import { createEditor, Editor, Transforms } from "slate";
import { Editable, Slate, withReact } from "slate-react";
import { withYjs, YjsEditor } from "@slate-yjs/core";
import * as Y from "yjs";
import { LiveblocksProviderType, useRoom } from "../liveblocks.config";
import styles from "./Editor.module.css";

export default function CollaborativeEditor() {
  const room = useRoom();
  const [connected, setConnected] = useState(false);
  const [sharedType, setSharedType] = useState<Y.XmlText>();
  const [provider, setProvider] = useState<LiveblocksProviderType>();

// Set up Liveblocks Yjs provider
  useEffect(() => {
    const yDoc = new Y.Doc();
    const yProvider = new LiveblocksYjsProvider(room, yDoc);
    const sharedDoc = yDoc.get("slate", Y.XmlText) as Y.XmlText;
    yProvider.on("sync", setConnected);

setSharedType(sharedDoc);
    setProvider(yProvider);

return () => {
      yDoc?.destroy();
      yProvider?.off("sync", setConnected);
      yProvider?.destroy();
    };
  }, [room]);

if (!connected || !sharedType || !provider) {
    return <div>Loading…</div>;
  }

return <SlateEditor sharedType={sharedType} />;
}

const emptyNode = {
  children: [{ text: "" }],
};

function SlateEditor({ sharedType }: { sharedType: Y.XmlText }) {
  // Set up editor with plugins
  const editor = useMemo(() => {
    const e = withReact(withYjs(createEditor(), sharedType));

// Ensure editor always has at least 1 valid child
    const { normalizeNode } = e;
    e.normalizeNode = (entry) => {
      const [node] = entry;

if (!Editor.isEditor(node) || node.children.length > 0) {
        return normalizeNode(entry);
      }

Transforms.insertNodes(editor, emptyNode, { at: [0] });
    };

return e;
  }, [sharedType]);

useEffect(() => {
    YjsEditor.connect(editor);
    return () => YjsEditor.disconnect(editor);
  }, [editor]);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <Slate editor={editor} initialValue={[emptyNode]}>
          <Editable
            className={styles.editor}
            placeholder="Start typing here…"
          />
        </Slate>
      </div>
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editor {
  border-radius: inherit;
  flex-grow: 1;
  width: 100%;
  height: 100%;
  padding: 1rem;
}

.editor:focus {
  outline: none;
}

.editorContainer {
  position: relative;
  height: 100%;
}

.placeholder {
  pointer-events: none;
  position: absolute;
  inset: 0;
  opacity: 0.3;
  padding: 0 1em;
}

.editor p {
  margin: 1em 0;
}
```

## Add your editor to the current page

Next, add the `CollaborativeEditor` into the page file, and place it inside the
`Room` component we created earlier. We should now be seeing a basic
collaborative editor!

```tsx file="/app/page.tsx"
import { Room } from "@/app/Room";
import CollaborativeEditor from "@/components/Editor";

export default function Page() {
  return (
    <Room>
      <CollaborativeEditor />
    </Room>
  );
}
```

## Add live cursors

To add live cursors to the text editor, we can rely on hooks from the
`@slate-yjs/react` package.

```tsx file="Cursors.tsx"
import {
  CursorOverlayData,
  useRemoteCursorOverlayPositions,
} from "@slate-yjs/react";
import React, { CSSProperties, ReactNode, useRef } from "react";
import { Cursor } from "./types";
import styles from "./Cursors.module.css";

export function Cursors({ children }: { children: ReactNode }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [cursors] = useRemoteCursorOverlayPositions<Cursor>({
    containerRef,
  });

return (
    <div className={styles.cursors} ref={containerRef}>
      {children}
      {cursors.map((cursor) => (
        <Selection key={cursor.clientId} {...cursor} />
      ))}
    </div>
  );
}

function Selection({
  data,
  selectionRects,
  caretPosition,
}: CursorOverlayData<Cursor>) {
  if (!data) {
    return null;
  }

const selectionStyle: CSSProperties = {
    backgroundColor: data.color,
  };

return (
    <>
      {selectionRects.map((position, i) => (
        <div
          style={{ ...selectionStyle, ...position }}
          className={styles.selection}
          key={i}
        />
      ))}
      {caretPosition && <Caret caretPosition={caretPosition} data={data} />}
    </>
  );
}

type CaretProps = Pick<CursorOverlayData<Cursor>, "caretPosition" | "data">;

function Caret({ caretPosition, data }: CaretProps) {
  const caretStyle: CSSProperties = {
    ...caretPosition,
    background: data?.color,
  };

const labelStyle: CSSProperties = {
    transform: "translateY(-100%)",
    background: data?.color,
  };

return (
    <div style={caretStyle} className={styles.caretMarker}>
      <div className={styles.caret} style={labelStyle}>
        {data?.name}
      </div>
    </div>
  );
}
```

And of course we need some corresponding CSS to keep the cursors in the correct
positions.

```css file="Cursors.module.css" isCollapsed isCollapsable
.cursors {
  position: relative;
}

.caretMarker {
  position: absolute;
  width: 2px;
}

.caret {
  position: absolute;
  font-size: 14px;
  color: #fff;
  white-space: nowrap;
  top: 0;
  border-radius: 6px;
  border-bottom-left-radius: 0;
  padding: 2px 6px;
  pointer-events: none;
}

.selection {
  position: absolute;
  pointer-events: none;
  opacity: 0.2;
}
```

Back in your `Editor` component, get the current user’s info with
[`useSelf`](/docs/api-reference/liveblocks-react#useSelf), add the `withCursors`
plugin, and pass the user info and awareness. Then wrap your editor in the
Cursors component to see them working.

```tsx file="Editor.tsx" highlight="1-3,7-8,12-20,29,34"
import { withCursors, withYjs, YjsEditor } from "@slate-yjs/core";
import { useSelf } from "../liveblocks.config";
import { Cursors } from "./Cursors";
// ...

export default function SlateEditor() {
  // Get user info from Liveblocks authentication endpoint
  const userInfo = useSelf((self) => self.info);

// Set up editor with plugins, and place user info into Yjs awareness and cursors
  const editor = useMemo(() => {
    const e = withReact(
      withCursors(
        withYjs(createEditor(), sharedType),
        provider.awareness as any,
        {
          data: userInfo,
        }
      )
    );

// ...
  }, [sharedType, provider.awareness, userInfo]);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <Slate editor={editor} initialValue={[emptyNode]}>
          <Cursors>
            <Editable
              className={styles.editor}
              placeholder="Start typing here…"
            />
          </Cursors>
        </Slate>
      </div>
    </div>
  );
}
```

## Add a toolbar

From this point onwards, you can build your Slate app as normal! For example,
should you wish to add a basic text-style toolbar to your app:

```tsx file="Toolbar.tsx"
import { Editor } from "slate";
import { useSlate } from "slate-react";
import styles from "./Toolbar.module.css";
import { CustomText } from "./types";

export function Toolbar() {
  const editor = useSlate();

return (
    <div className={styles.toolbar}>
      <button
        className={styles.button}
        data-active={isMarkActive(editor, "bold") || undefined}
        onClick={(event) => {
          event.preventDefault();
          toggleMark(editor, "bold");
        }}
      >
        B
      </button>
      <button
        className={styles.button}
        data-active={isMarkActive(editor, "italic") || undefined}
        onClick={(event) => {
          event.preventDefault();
          toggleMark(editor, "italic");
        }}
      >
        i
      </button>
      <button
        className={styles.button}
        data-active={isMarkActive(editor, "underline") || undefined}
        onClick={(event) => {
          event.preventDefault();
          toggleMark(editor, "underline");
        }}
      >
        u
      </button>
    </div>
  );
}

function toggleMark(editor: Editor, format: keyof CustomText) {
  const isActive = isMarkActive(editor, format);

if (isActive) {
    Editor.removeMark(editor, format);
  } else {
    Editor.addMark(editor, format, true);
  }
}

function isMarkActive(editor: Editor, format: keyof CustomText) {
  const marks = Editor.marks(editor);
  return marks ? marks?.[format] === true : false;
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}

.button:active {
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 2px 3px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button[data-active] {
  background: #fafafa;
}
```

### Theme your leaf styles

These styles are rendered with leaf components, which we’ll add to a new file:

```tsx file="Leaf.tsx"
import { PropsWithChildren } from "react";
import { CustomText } from "@/src/types";

type Props = PropsWithChildren<{
  attributes: Record<string, string>;
  leaf: CustomText;
}>;

export function Leaf({ attributes, children, leaf }: Props) {
  if (leaf.bold) {
    children = <strong>{children}</strong>;
  }

if (leaf.italic) {
    children = <em>{children}</em>;
  }

if (leaf.underline) {
    children = <u>{children}</u>;
  }

return <span {...attributes}>{children}</span>;
}
```

You can then import this into your editor to enable basic rich-text:

```tsx file="Editor.tsx" highlight="1,2,8,13,15-17"
import { Toolbar } from "@/src/Toolbar";
import { Leaf } from "@/src/Leaf";
// ...

export default function SlateEditor() {
  // ...

const renderLeaf = useCallback((props: any) => <Leaf {...props} />, []);

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <Slate editor={editor} initialValue={[emptyNode]}>
          <Cursors>
            <div className={styles.editorHeader}>
              <Toolbar />
            </div>
            <Editable
              className={styles.editor}
              placeholder="Start typing here…"
              renderLeaf={renderLeaf}
            />
          </Cursors>
        </Slate>
      </div>
    </div>
  );
}
```

## Create live avatars with Liveblocks hooks

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  border-radius: 9999px;
}
```

You can then import this to your editor to see it in action:

```tsx file="Editor.tsx" highlight="1,14"
import { Avatars } from "./Avatars";
// ...

export default function SlateEditor() {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorContainer}>
        <Slate editor={editor} initialValue={[emptyNode]}>
          <Cursors>
            <div className={styles.editorHeader}>
              <Toolbar />
              <Avatars />
            </div>
            <Editable
              className={styles.editor}
              placeholder="Start typing here…"
              renderLeaf={renderLeaf}
            />
          </Cursors>
        </Slate>
      </div>
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

---
meta:
  title:
    "How to create a collaborative text editor with Tiptap, Yjs, Next.js, and
    Liveblocks"
  description:
    "Build a collaborative text editor with Tiptap, Yjs, Next.js, and Liveblocks"
---

In this tutorial, we’ll be building a collaborative text editor using Tiptap,
Yjs, Next.js, and Liveblocks.

We now have an official Tiptap package, and we recommend you use this instead of
following this guide. Read more in our
[Tiptap getting started guide](/docs/get-started/nextjs-tiptap). However, should
you like to set up Tiptap manually with Yjs, without using our full feature set,
continue reading.

</Banner>

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org/),
[TypeScript](https://www.typescriptlang.org/), and
[Tiptap](https://tiptap.dev/).

## Install Tiptap, Yjs, and Liveblocks into your Next.js application

On GitHub we have a working example of this
[collaborative Tiptap editor](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-yjs-tiptap)
for you to download and run.

</Banner>

Run the following command to install the Tiptap, Yjs, and Liveblocks packages:

```bash
npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor @tiptap/pm @tiptap/react @tiptap/starter-kit
```

## Set up access token authentication

The first step in connecting to Liveblocks is to set up an authentication
endpoint in `/app/api/liveblocks-auth/route.ts`.

```ts
import { Liveblocks } from "@liveblocks/node";
import { NextRequest } from "next/server";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = await request.json();
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { body, status } = await session.authorize();
  return new Response(body, { status });
}
```

Here’s an example using the older API routes format in `/pages`.

```ts file="pages/api/liveblocks-auth.ts" isCollapsed isCollapsable
import { Liveblocks } from "@liveblocks/node";
import type { NextApiRequest, NextApiResponse } from "next";

const API_KEY = "{{SECRET_KEY}}";

const liveblocks = new Liveblocks({
  secret: API_KEY!,
});

// Give the user access to the room
  const { room } = request.body;
  session.allow(room, session.FULL_ACCESS);

// Authorize the user and return the result
  const { status, body } = await session.authorize();
  response.status(status).send(body);
}
```

## Initialize your Liveblocks config file

Let’s initialize the `liveblocks.config.ts` file in which you’ll set up the
Liveblocks client.

```bash
npx create-liveblocks-app@latest --init --framework react
```

## Join a Liveblocks room

```tsx file="/app/Room.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

## Set up the Tiptap editor

Now that we’ve set up Liveblocks, we can start integrating Tiptap and Yjs in the
`Editor.tsx` file.

```tsx file="Editor.tsx"
"use client";

import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Collaboration from "@tiptap/extension-collaboration";
import CollaborationCursor from "@tiptap/extension-collaboration-cursor";
import * as Y from "yjs";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import { useRoom } from "@/liveblocks.config";
import { useEffect, useState } from "react";
import styles from "./CollaborativeEditor.module.css";

// Collaborative text editor with simple rich text, live cursors, and live avatars
export function CollaborativeEditor() {
  const room = useRoom();
  const [doc, setDoc] = useState<Y.Doc>();
  const [provider, setProvider] = useState<any>();

// Set up Liveblocks Yjs provider
  useEffect(() => {
    const yDoc = new Y.Doc();
    const yProvider = new LiveblocksYjsProvider(room, yDoc);
    setDoc(yDoc);
    setProvider(yProvider);

return () => {
      yDoc?.destroy();
      yProvider?.destroy();
    };
  }, [room]);

if (!doc || !provider) {
    return null;
  }

return <TiptapEditor doc={doc} provider={provider} />;
}

type EditorProps = {
  doc: Y.Doc;
  provider: any;
};

function TiptapEditor({ doc, provider }: EditorProps) {
  // Set up editor with plugins
  const editor = useEditor({
    editorProps: {
      attributes: {
        // Add styles to editor element
        class: styles.editor,
      },
    },
    extensions: [
      StarterKit.configure({
        // The Collaboration extension comes with its own history handling
        undoRedo: false,
      }),
      // Register the document with Tiptap
      Collaboration.configure({
        document: doc,
      }),
      // Attach provider and user info
      CollaborationCursor.configure({
        provider: provider,
      }),
    ],
  });

return (
    <div className={styles.container}>
      <EditorContent editor={editor} className={styles.editorContainer} />
    </div>
  );
}
```

And here is the `Editor.module.css` file to make sure your multiplayer text
editor looks nice and tidy.

.editorHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.editor {
  border-radius: inherit;
  flex-grow: 1;
  width: 100%;
  height: 100%;
  padding: 1rem;
}

.editor:focus {
  outline: none;
}

.editorContainer {
  position: relative;
  height: 100%;
}

.placeholder {
  pointer-events: none;
  position: absolute;
  inset: 0;
  opacity: 0.3;
  padding: 0 1em;
}

.editor p {
  margin: 1em 0;
}
```

## Add your editor to the current page

Next, add the `CollaborativeEditor` into the page file, and place it inside the
`Room` component we created earlier. We should now be seeing a basic
collaborative editor!

```tsx file="/app/page.tsx"
import { Room } from "./Room";
import CollaborativeEditor from "@/components/Editor";

export default function Page() {
  return (
    <Room>
      <CollaborativeEditor />
    </Room>
  );
}
```

## Add live cursors

```tsx file="CollaborativeEditor.tsx" highlight="1,5-6,17"
import { useSelf } from "../liveblocks.config.ts";
// ...

function TiptapEditor({ doc, provider }: EditorProps) {
  // Get user info from Liveblocks authentication endpoint
  const userInfo = useSelf((me) => me.info);

// Set up editor with plugins, and place user info into Yjs awareness and cursors
  const editor = useEditor({
    // ...
    extensions: [
      // ...

// Attach provider and user info
      CollaborationCursor.configure({
        provider: provider,
        user: userInfo,
      }),
    ],
  });

return (
    <div className={styles.container}>
      <EditorContent editor={editor} className={styles.editorContainer} />
    </div>
  );
}
```

We can style these cursors by placing CSS in a global CSS file.

```css file="globals.css" isCollapsed isCollapsable
/* Give a remote user a caret */
.collaboration-carets__caret {
  border-left: 1px solid #0d0d0d;
  border-right: 1px solid #0d0d0d;
  margin-left: -1px;
  margin-right: -1px;
  pointer-events: none;
  position: relative;
  word-break: normal;
}

/* Render the username above the caret */
.collaboration-carets__label {
  font-style: normal;
  font-weight: 600;
  left: -1px;
  line-height: normal;
  position: absolute;
  user-select: none;
  white-space: nowrap;
  font-size: 14px;
  color: #fff;
  top: -1.4em;
  border-radius: 6px;
  border-bottom-left-radius: 0;
  padding: 2px 6px;
  pointer-events: none;
}
```

## Add a toolbar

From this point onwards, you can build your Tiptap app as normal! For example,
should you wish to add a basic text-style toolbar to your app:

```tsx file="Toolbar.tsx"
import { Editor } from "@tiptap/react";
import styles from "./Toolbar.module.css";

type Props = {
  editor: Editor | null;
};

export function Toolbar({ editor }: Props) {
  if (!editor) {
    return null;
  }

return (
    <div className={styles.toolbar}>
      <button
        className={styles.button}
        onClick={() => editor.chain().focus().toggleBold().run()}
        disabled={!editor.can().chain().focus().toggleBold().run()}
        data-active={editor.isActive("bold") ? "is-active" : undefined}
        aria-label="bold"
      >
        B
      </button>
      <button
        className={styles.button}
        onClick={() => editor.chain().focus().toggleItalic().run()}
        disabled={!editor.can().chain().focus().toggleItalic().run()}
        data-active={editor.isActive("italic") ? "is-active" : undefined}
        aria-label="italic"
      >
        i
      </button>
      <button
        className={styles.button}
        onClick={() => editor.chain().focus().toggleStrike().run()}
        disabled={!editor.can().chain().focus().toggleStrike().run()}
        data-active={editor.isActive("strike") ? "is-active" : undefined}
        aria-label="strikethrough"
      >
        S
      </button>
    </div>
  );
}
```

Add some matching styles:

```css file="Toolbar.module.css" isCollapsed isCollapsable
.toolbar {
  display: flex;
  padding: 1em;
  gap: 6px;
}

.button:hover {
  color: #111827;
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 5px 8px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button:focus-visible {
  outline-offset: 2px;
}

.button:active {
  box-shadow:
    rgba(0, 0, 0, 0.16) 0 2px 3px 0,
    rgba(0, 0, 0, 0.04) 0 0 0 1px;
}

.button[data-active] {
  background: #fafafa;
}
```

You can then import this into your editor to enable basic rich-text:

```tsx file="Editor.tsx" highlight="1,9-11"
import { Toolbar } from "./Toolbar";
// ...

function TiptapEditor({ doc, provider }: EditorProps) {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <Toolbar editor={editor} />
      </div>
      <EditorContent editor={editor} className={styles.editorContainer} />
    </div>
  );
}
```

## Create live avatars with Liveblocks hooks

```tsx file="Avatars.tsx"
import { useOthers, useSelf } from "@/liveblocks.config";
import styles from "./Avatars.module.css";

export function Avatars() {
  const users = useOthers();
  const currentUser = useSelf();

And here’s the styles:

```css file="Avatars.module.css" isCollapsed isCollapsable
.avatars {
  display: flex;
  padding: 0 0.75rem;
}

.avatar:hover:before {
  opacity: 1;
}

.avatar_picture {
  width: 100%;
  height: 100%;
  border-radius: 9999px;
}
```

You can then import this to your editor to see it in action:

```tsx file="Editor.tsx" highlight="11"
import { Avatars } from "./Avatars";
// ...

function TiptapEditor({ doc, provider }: EditorProps) {
  // ...

return (
    <div className={styles.container}>
      <div className={styles.editorHeader}>
        <Toolbar editor={editor} />
        <Avatars />
      </div>
      <EditorContent editor={editor} className={styles.editorContainer} />
    </div>
  );
}
```

Note that the cursors and avatars match in color and name, as the info for both
is sourced from the Liveblocks authentication endpoint.

## Try it out

---
meta:
  title:
    "How to create a collaborative to-do list with JavaScript and Liveblocks"
  description: "Build a collaborative to-do list with JavaScript and Liveblocks"
---

The goal of this tutorial is to show you how to build a collaborative to-do list
app in 15 minutes. The to-dos will be persisted on Liveblocks backend and synced
in realtime across clients. Users will also be able to see who’s currently using
the app and when someone is typing.

We’re going to use vanilla JavaScript and [esbuild](https://esbuild.github.io/)
for the bundling.

If you’re using a front-end framework such as React, we recommend reading one of
our dedicated to-do list tutorials:

- [React tutorial](/docs/tutorials/collaborative-to-do-list/react)
- [React + Redux tutorial](/docs/tutorials/collaborative-to-do-list/react-redux)
- [React + Zustand tutorial](/docs/tutorials/collaborative-to-do-list/react-zustand)

The source code for this guide is
[available on GitHub](https://github.com/liveblocks/liveblocks/tree/main/examples/javascript-todo-list).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

Create an empty node project with `npm init` and run the following command to
install Liveblocks package and `esbuild`:

```bash
npm install @liveblocks/client esbuild
```

[`@liveblocks/client`][] lets you interact with Liveblocks servers.
[`esbuild`](https://esbuild.github.io/) lets your bundle your app with
`@liveblocks/client`.

Then add a build script to your `package.json` that will be responsible to
bundle our app.

```json
"scripts": {
  "build": "esbuild app.js --bundle --outfile=static/app.js"
},
```

### Connect to Liveblocks servers [#connect-liveblocks-servers]

You’ll need an API key in order to use Liveblocks.
[Create a Liveblocks account](/auth/signup) to get
[your API key](/dashboard/apikeys). It should start with `pk_`.

</Banner>

To connect to Liveblocks servers, create a client with [`createClient`][] and
set your public API key like below.

```jsx file="app.js"
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});
```

### Connect to a Liveblocks room [#connect-liveblocks-room]

A room is the virtual space where people collaborate. To create a collaborative
experience, you’ll need to connect your users to a Liveblocks room following the
instructions below.

You can easily connect to a room by using [`client.enter`][] by passing the room
id as a parameter. For this tutorial we’ll use `javascript-todo-app`.

```jsx highlight="7-13" file="app.js"
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
  });
}

run();
```

We’ve also passed an `initialPresence` value here—we’ll be using this later.

## Show who’s currently in the room [#who-is-here]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

Now that Liveblocks is set up, we’re going to use [`room.subscribe("others")`][]
to show who’s currently inside the room.

Create a file `static/index.html` with the following content:

```html file="static/index.html"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Liveblocks - Todo list</title>
    <link rel="stylesheet" href="index.css" />
  </head>
  <body>
    <div class="container">
      <div id="who_is_here" class="who_is_here"></div>
    </div>
    <script src="app.js"></script>
  </body>
</html>
```

And replace `app.js` content with the code below, build your app with
`npm run build` and open `static/index.html` in multiple browser windows.

```jsx file="app.js" highlight="12-16"
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
  });

const whoIsHere = document.getElementById("who_is_here");

room.subscribe("others", (others) => {
    whoIsHere.innerHTML = `There are ${others.count} other users online`;
  });
}

run();
```

_If you want to make your app feel less "brutalist" while following along,
create a file `static/index.css` with the following CSS._

```css file="static/index.css" isCollapsed isCollapsable
body {
  background-color: rgb(243, 243, 243);
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
    "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
    "Helvetica Neue", sans-serif;
  -webkit-font-smoothing: antialiased;
}

.container {
  display: flex;
  flex-direction: column;
  width: 100%;
  margin-left: auto;
  margin-right: auto;
  margin-top: 3rem;
  max-width: 28rem;
}

input {
  box-sizing: border-box;
  padding: 0.5rem 0.875rem;
  margin: 0.5rem 0;
  width: 100%;
  background-color: white;
  box-shadow:
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 1px 2px 0 rgba(0, 0, 0, 0.05);
  border-radius: 0.5rem;
  color: black;
  border: 0 solid;
  font-size: 16px;
}

input:hover {
  box-shadow:
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 1px 3px 0 rgba(0, 0, 0, 0.1),
    0 1px 2px 0 rgba(0, 0, 0, 0.06);
}

input:focus {
  outline: none;
}

.todo_container {
  display: flex;
  padding: 0.5rem 0.875rem;
  align-items: center;
  justify-content: space-between;
}

.todo {
  flex-grow: 1;
}

.delete_button {
  padding: 0;
  margin: 0;
  font-size: 16px;
  border: 0 solid;
  appearance: button;
  background-color: transparent;
}

.delete_button:focus {
  outline: none;
}

.who_is_here {
  align-self: flex-end;
  font-size: 11px;
  color: #aaa;
}

.someone_is_typing {
  position: absolute;
  font-size: 11px;
  color: #aaa;
}
```

## Show if someone is typing [#someone-is-typing]

Any users in the room can be typing, so we need to have a state `isTyping` per
connected user. This state is only temporary, it is not persisted after users
leave the room. Liveblocks has a concept of "presence" to handle this kind of
temporary states. For example, a user "presence" can be used to share the cursor
position or the selected shape if your building a design tool.

We’re going to use [`room.updatePresence`][] hook to set the `presence` of the
current user.

First, add an input to `static/index.html`

```html file="static/index.html" highlight="11"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Liveblocks - Todo list</title>
    <link rel="stylesheet" href="index.css" />
  </head>
  <body>
    <div class="container">
      <div id="who_is_here" class="who_is_here"></div>
      <input id="todo_input" type="text" placeholder="What needs to be done?" />
    </div>
    <script src="app.js"></script>
  </body>
</html>
```

Then listen to `keydown` and `blur` to detect when the user is typing.

```jsx file="App.js" highlight="13,19-32"
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
  });

const whoIsHere = document.getElementById("who_is_here");
  const todoInput = document.getElementById("todo_input");

room.subscribe("others", (others) => {
    whoIsHere.innerHTML = `There are ${others.count} other users online`;
  });

todoInput.addEventListener("keydown", (e) => {
    // Clear the input when the user presses "Enter".
    // We'll add todo later on
    if (e.key === "Enter") {
      room.updatePresence({ isTyping: false });
      todoInput.value = "";
    } else {
      room.updatePresence({ isTyping: true });
    }
  });

todoInput.addEventListener("blur", () => {
    room.updatePresence({ isTyping: false });
  });
}

run();
```

Now that we set the `isTyping` state when necessary, add a new `div` to display
a message when at least one other user has `isTyping` equals to `true`.

```html file="static/index.html" highlight="12"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Liveblocks - Todo list</title>
    <link rel="stylesheet" href="index.css" />
  </head>
  <body>
    <div class="container">
      <div id="who_is_here" class="who_is_here"></div>
      <input id="todo_input" type="text" placeholder="What needs to be done?" />
      <div id="someone_is_typing" class="someone_is_typing"></div>
    </div>
    <script src="app.js"></script>
  </body>
</html>
```

```jsx highlight="14,19-23" file="app.js"
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
  });

const whoIsHere = document.getElementById("who_is_here");
  const todoInput = document.getElementById("todo_input");
  const someoneIsTyping = document.getElementById("someone_is_typing");

room.subscribe("others", (others) => {
    whoIsHere.innerHTML = `There are ${others.count} other users online`;

someoneIsTyping.innerHTML = others
      .toArray()
      .some((user) => user.presence?.isTyping)
      ? "Someone is typing..."
      : "";
  });

todoInput.addEventListener("blur", () => {
    room.updatePresence({ isTyping: false });
  });
}

run();
```

## Sync and persist to-dos [#add-liveblocks-storage]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

As opposed to the `presence`, some collaborative features require that every
user interacts with the same piece of state. For example, in Google Doc, it is
the paragraphs, headings, images in the document. In Figma, it’s all the shapes
that make your design. That’s what we call the room’s `storage`.

The room’s storage is a conflicts-free state that multiple users can edit at the
same time. It is persisted to our backend even after everyone leaves the room.
Liveblocks provides custom data structures inspired by
[CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) that
can be nested to create the state that you want.

- [`LiveObject`][] - Similar to JavaScript object. If multiple users update the
  same property simultaneously, the last modification received by the Liveblocks
  servers is the winner.
- [`LiveList`][] - An ordered collection of items synchronized across clients.
  Even if multiple users add/remove/move elements simultaneously, LiveList will
  solve the conflicts to ensure everyone sees the same collection of items.
- [`LiveMap`][] - Similar to a JavaScript Map. If multiple users update the same
  property simultaneously, the last modification received by the Liveblocks
  servers is the winner.

We’re going to store the list of todos in a `LiveList`. Initialize the storage
with the `initialStorage` option when entering the room. Then we use
[`LiveList.push`][] when the user press "Enter".

```jsx highlight="1,8-11,17-19,28" file="src/App.js"
import { createClient, LiveList } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

async function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
    initialStorage: { todos: new LiveList() },
  });

const whoIsHere = document.getElementById("who_is_here");
  const todoInput = document.getElementById("todo_input");
  const someoneIsTyping = document.getElementById("someone_is_typing");

const { root } = await room.getStorage();

let todos = root.get("todos");

room.subscribe("others", (others) => {
    /* ... */
  });

todoInput.addEventListener("keydown", (e) => {
    if (e.key === "Enter") {
      room.updatePresence({ isTyping: false });
      todos.push({ text: todoInput.value });
      todoInput.value = "";
    } else {
      room.updatePresence({ isTyping: true });
    }
  });

todoInput.addEventListener("blur", () => {
    room.updatePresence({ isTyping: false });
  });
}

run();
```

At this point, the todos are added to the storage but they are not rendered! Add
a container for our todos and use [`room.subscribe(todos)`][] to get rerender
the app whenever the todos are updated.

```html file="static/index.html" highlight="13"
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Liveblocks - Todo list</title>
    <link rel="stylesheet" href="index.css" />
  </head>
  <body>
    <div class="container">
      <div id="who_is_here" class="who_is_here"></div>
      <input id="todo_input" type="text" placeholder="What needs to be done?" />
      <div id="someone_is_typing" class="someone_is_typing"></div>
      <div id="todos_container"></div>
    </div>
    <script src="app.js"></script>
  </body>
</html>
```

```jsx highlight="16,34-56" file="src/App.js"
import { createClient, LiveList } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

async function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
    initialStorage: { todos: new LiveList() },
  });

const whoIsHere = document.getElementById("who_is_here");
  const todoInput = document.getElementById("todo_input");
  const someoneIsTyping = document.getElementById("someone_is_typing");
  const todosContainer = document.getElementById("todos_container");

const { root } = await room.getStorage();

let todos = root.get("todos");

room.subscribe("others", (others) => {
    /* ... */
  });

todoInput.addEventListener("keydown", (e) => {
    /* ... */
  });

todoInput.addEventListener("blur", () => {
    /* ... */
  });

function renderTodos() {
    todosContainer.innerHTML = "";

for (let i = 0; i < todos.length; i++) {
      const todo = todos.get(i);

const todoContainer = document.createElement("div");
      todoContainer.classList.add("todo_container");

const todoText = document.createElement("div");
      todoText.classList.add("todo");
      todoText.innerHTML = todo.text;
      todoContainer.appendChild(todoText);

todosContainer.appendChild(todoContainer);
    }
  }

room.subscribe(todos, () => {
    renderTodos();
  });

renderTodos();
}

run();
```

Finally, add a delete button for each todo and call [`LiveList.delete`][] to
remove a todo from the list by index.

```jsx highlight="48-54" file="src/App.js"
import { createClient, LiveList } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

async function run() {
  const { room, leave } = client.enterRoom("javascript-todo-app", {
    initialPresence: { isTyping: false },
    initialStorage: { todos: new LiveList() },
  });

const { root } = await room.getStorage();

let todos = root.get("todos");

room.subscribe("others", (others) => {
    /* ... */
  });

todoInput.addEventListener("keydown", (e) => {
    /* ... */
  });

todoInput.addEventListener("blur", () => {
    /* ... */
  });

function renderTodos() {
    todosContainer.innerHTML = "";

for (let i = 0; i < todos.length; i++) {
      const todo = todos.get(i);

const todoContainer = document.createElement("div");
      todoContainer.classList.add("todo_container");

const todoText = document.createElement("div");
      todoText.classList.add("todo");
      todoText.innerHTML = todo.text;
      todoContainer.appendChild(todoText);

const deleteButton = document.createElement("button");
      deleteButton.classList.add("delete_button");
      deleteButton.innerHTML = "✕";
      deleteButton.addEventListener("click", () => {
        todos.delete(i);
      });
      todoContainer.appendChild(deleteButton);

todosContainer.appendChild(todoContainer);
    }
  }

room.subscribe(todos, () => {
    renderTodos();
  });

renderTodos();
}

run();
```

In this tutorial, we discovered what’s a room, how to connect and enter a room.
And how to use the room’s api to interact with its presence and storage.

You can see some stats about the room you created in your
[dashboard](https://liveblocks.io/dashboard/rooms).

## Next steps

- [API reference](/docs/api-reference/liveblocks-client)
- [Authentication](/docs/authentication)

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`client.enter`]: /docs/api-reference/liveblocks-client#Client.enter
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[`livelist.delete`]: /docs/api-reference/liveblocks-client#LiveList.delete
[`livelist.push`]: /docs/api-reference/liveblocks-client#LiveList.push
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`room.subscribe("others")`]:
  /docs/api-reference/liveblocks-client#Room.subscribe.others
[`room.subscribe(todos)`]:
  /docs/api-reference/liveblocks-client#Room.subscribe(storageItem)
[`room.updatepresence`]:
  /docs/api-reference/liveblocks-client#Room.updatePresence

---
meta:
  title: "How to create a collaborative to-do list with React and Liveblocks"
  description: "Build a collaborative to-do list with React and Liveblocks"
---

In this 15-minute tutorial, we’ll be building a collaborative to-do list using
React and Liveblocks. As users edit the list, changes will be automatically
synced and persisted, allowing for a list that updates in realtime across
clients. Users will also be able to see who else is currently online, and when
another user is typing.

This guide assumes that you’re already familiar with React,
[Next.js](https://nextjs.org/) and
[TypeScript](https://www.typescriptlang.org/). If you’re using a
state-management library such as Redux or Zustand, we recommend reading one of
our dedicated to-do list tutorials:

- [React + Redux tutorial](/docs/tutorials/collaborative-to-do-list/react-redux)
- [React + Zustand tutorial](/docs/tutorials/collaborative-to-do-list/react-zustand)

The source code for this guide is
[available on GitHub](https://github.com/liveblocks/liveblocks/tree/main/examples/nextjs-todo-list).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

Create a new app with [`create-next-app`](https://nextjs.org/docs):

```bash
npx create-next-app@latest next-todo-list --typescript
```

For this tutorial, we won’t use the `src` directory or the experimental `app`
directory.

</Banner>

Then run the following command to install the Liveblocks packages:

```bash
npm install @liveblocks/client @liveblocks/react
```

## Join a Liveblocks room

```tsx file="/pages/index.tsx"
"use client";

import { ReactNode } from "react";
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
} from "@liveblocks/react/suspense";

export default function Page() {
  return (
    <LiveblocksProvider publicApiKey={"{{SECRET_KEY}}"}>
      <RoomProvider id="my-room">
        <ClientSideSuspense fallback={<div>Loading…</div>}>
          <TodoList />
        </ClientSideSuspense>
      </RoomProvider>
    </LiveblocksProvider>
  );
}

function TodoList() {
  return (
    <div>
      {/* We’re starting to implement the to-do list in the next section */}
    </div>
  );
}
```

## Show who’s currently in the room [#who-is-here]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

Now that Liveblocks is set up, we can start using the hooks to display how many
users are currently online.

We’ll be doing this by adding [`useOthers`][], a selector hook that provides us
information about which _other_ users are online.

[`useOthers`][] takes a selector function that receives an array, `others`,
containing information about each user. We can get the current user count from
the length of that array. Add the following code to `pages/index.tsx`, and open
your app in multiple windows to see it in action.

```tsx file="pages/index.tsx"
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
  useOthers,
} from "@liveblocks/react/suspense";

function WhoIsHere() {
  const userCount = useOthers((others) => others.length);

return (
    <div className="who_is_here">There are {userCount} other users online</div>
  );
}

function TodoList() {
  return (
    <div className="container">
      <WhoIsHere />
    </div>
  );
}

/* Page */
```

_For a tidier UI, replace the content of `styles/globals.css` file with the
following css._

```css file="styles/globals.css" isCollapsed isCollapsable
body {
  background-color: rgb(243, 243, 243);
}

.container {
  display: flex;
  flex-direction: column;
  width: 100%;
  margin-left: auto;
  margin-right: auto;
  margin-top: 3rem;
  max-width: 28rem;
}

input:hover {
  box-shadow:
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 1px 3px 0 rgba(0, 0, 0, 0.1),
    0 1px 2px 0 rgba(0, 0, 0, 0.06);
}

input:focus {
  outline: none;
}

.todo_container {
  display: flex;
  padding: 0.5rem 0.875rem;
  align-items: center;
  justify-content: space-between;
}

.todo {
  flex-grow: 1;
}

.delete_button {
  padding: 0;
  margin: 0;
  font-size: 16px;
  border: 0 solid;
  appearance: button;
  background-color: transparent;
}

.delete_button:focus {
  outline: none;
}

.who_is_here {
  align-self: flex-end;
  font-size: 11px;
  color: #aaa;
}

.someone_is_typing {
  position: absolute;
  font-size: 11px;
  color: #aaa;
}
```

## Show if someone is typing [#someone-is-typing]

Next, we’ll add some code to show a message when another user is typing.

Any online user could start typing, and we need to keep track of this, so it’s
best if each user holds their own `isTyping` property.

Luckily, Liveblocks uses the concept of _presence_ to handle these temporary
states. A user’s presence can be used to represent the position of a cursor on
screen, the selected shape in a design tool, or in this case, if they’re
currently typing or not.

Let’s define a new type `Presence` with the property `isTyping` in
`liveblocks.config.ts` to ensure all our presence hooks are typed properly.

```tsx file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // +++
    Presence: { isTyping: boolean };
    // +++
  }
}
```

We can then call [`useUpdateMyPresence`][] whenever we wish to update the user’s
current presence, in this case whether they’re typing or not.

```tsx file="pages/index.tsx"
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
  useOthers,
  useUpdateMyPresence,
} from "@liveblocks/react/suspense";
import { useState } from "react";

/* WhoIsHere */

function TodoList() {
  const [draft, setDraft] = useState("");
  const updateMyPresence = useUpdateMyPresence();

return (
    <div className="container">
      <WhoIsHere />
      <input
        type="text"
        placeholder="What needs to be done?"
        value={draft}
        onChange={(e) => {
          setDraft(e.target.value);
          updateMyPresence({ isTyping: true });
        }}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            updateMyPresence({ isTyping: false });
            setDraft("");
          }
        }}
        onBlur={() => updateMyPresence({ isTyping: false })}
      />
    </div>
  );
}

/* Page */
```

Now that we’re keeping track of everyone’s state, we can create a new component
called `SomeoneIsTyping`, and use this to display a message whilst anyone else
is typing. To check if anyone is typing, we’re iterating through `others` and
returning true if `isTyping` is true for any user.

/* WhoIsHere */

function SomeoneIsTyping() {
  const someoneIsTyping = useOthers((others) =>
    others.some((other) => other.presence.isTyping)
  );

return (
    <div className="someone_is_typing">
      {someoneIsTyping ? "Someone is typing..." : ""}
    </div>
  );
}

function TodoList() {
  const [draft, setDraft] = useState("");
  const updateMyPresence = useUpdateMyPresence();

return (
    <div className="container">
      <WhoIsHere />
      <input {/* ... */ } />
      <SomeoneIsTyping />
    </div>
  );
}

/* Page */
```

We also need to make sure that we pass an `initialPresence` for `isTyping` to
`RoomProvider`.

```tsx file="pages/index.tsx"
/* WhoIsHere */
/* SomeoneIsTyping */
/* TodoList */

export default function Page() {
  return (
    <LiveblocksProvider publicApiKey={"{{SECRET_KEY}}"}>
      // +++
      <RoomProvider id="my-room" initialPresence={{ isTyping: false }}>
        // +++
        <ClientSideSuspense fallback={<div>Loading…</div>}>
          <ToDoList />
        </ClientSideSuspense>
      </RoomProvider>
    </LiveblocksProvider>
  );
}
```

## Sync and persist to-dos [#add-liveblocks-storage]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

To-do list items will be stored even after all users disconnect, so we won’t be
using presence to store these values. For this, we need something new.

We’re going to use a [`LiveList`][] to store the list of todos inside the room’s
storage, a type of storage that Liveblocks provides. A `LiveList` is similar to
a JavaScript array, but its items are synced in realtime across different
clients. Even if multiple users insert, delete, or move items simultaneously,
the `LiveList` will still be consistent for all users in the room.

First, let's declare a new type `Storage` in `liveblocks.config.ts`, like we did
for `Presence`. This will ensure that our storage hooks are properly typed.

```tsx file="liveblocks.config.ts"
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Presence: { isTyping: boolean };

// +++
    Storage: {
      todos: LiveList<{ text: string }>;
    };
    // +++
  }
}
```

Go back to `Page` to initialize the storage with the `initialStorage` prop on
the `RoomProvider`.

```tsx highlight="3,14" file="pages/index.tsx"
/* ... */

import { LiveList } from "@liveblocks/client";

/* WhoIsHere */
/* SomeoneIsTyping */
/* TodoList */

export default function Page() {
  return (
    <LiveblocksProvider publicApiKey={"{{SECRET_KEY}}"}>
      <RoomProvider
        id="my-room"
        initialPresence={{ isTyping: false }}
        // +++
        initialStorage={{ todos: new LiveList() }}
        // +++
      >
        <ClientSideSuspense fallback={<div>Loading…</div>}>
          <ToDoList />
        </ClientSideSuspense>
      </RoomProvider>
    </LiveblocksProvider>
  );
}
```

### Accessing storage [#accessing-liveblocks-storage]

We’re going to use the [`useStorage`][] hook to get the list of todos previously
created.

`useStorage` allows us to select part of the storage from the `root` level. We
can find our `todos` `LiveList` at `root.todos`, and we can map through our list
to display each item.

```tsx file="pages/index.tsx"
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
  useOthers,
  useUpdateMyPresence,
  useStorage,
} from "@liveblocks/react/suspense";
import { LiveList } from "@liveblocks/client";
import { useState } from "react";

/* WhoIsHere */
/* SomeoneIsTyping */

function TodoList() {
  const [draft, setDraft] = useState("");
  const updateMyPresence = useUpdateMyPresence();
  const todos = useStorage((root) => root.todos);

return (
    <div className="container">
      <WhoIsHere />
      <input
        {/* ... */}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            updateMyPresence({ isTyping: false });
            setDraft("");
          }
        }}
      />
      <SomeoneIsTyping />
      {todos.map((todo, index) => {
        return (
          <div key={index} className="todo_container">
            <div className="todo">{todo.text}</div>
            <button
              className="delete_button"
            >
              ✕
            </button>
          </div>
        );
      })}
    </div>
  );
}

/* Page */
```

### Setting storage [#setting-liveblocks-storage]

To modify the list, we can use the [`useMutation`][] hook. This is a hook that
works similarly to `useCallback`, with a dependency array, allowing you to
create a reusable storage mutation.

`useMutation` gives you access to the storage root, a [`LiveObject`][]. From
here we can use [`LiveObject.get`][] to retrieve the `todos` list, then use
[`LiveList.push`][] and [`LiveList.delete`][] to modify our todo list. These
functions are then passed into the appropriate events.

```tsx file="pages/index.tsx"
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
  useOthers,
  useUpdateMyPresence,
  useStorage,
  useMutation,
} from "@liveblocks/react/suspense";
import { LiveList } from "@liveblocks/client";
import { useState } from "react";

/* WhoIsHere */
/* SomeoneIsTyping */

export default function TodoList() {
  const [draft, setDraft] = useState("");
  const updateMyPresence = useUpdateMyPresence();
  const todos = useStorage((root) => root.todos);

const addTodo = useMutation(({ storage }, text) => {
    storage.get("todos").push({ text })
  }, []);

const deleteTodo = useMutation(({ storage }, index) => {
    storage.get("todos").delete(index);
  }, []);

return (
    <div className="container">
      <WhoIsHere />
      <input
        {/* ... */}

onKeyDown={(e) => {
          if (e.key === "Enter") {
            updateMyPresence({ isTyping: false });
            addTodo(draft);
            setDraft("");
          }
        }}
      />
      <SomeoneIsTyping />
      {todos.map((todo, index) => {
        return (
          <div key={index} className="todo_container">
            <div className="todo">{todo.text}</div>

<button
              className="delete_button"
              onClick={() => deleteTodo(index)}
            >
              ✕
            </button>

</div>
        );
      })}
    </div>
  );
}

/* Page */
```

Voilà! We have a working collaborative to-do list, with persistent data storage.

## Summary

In this tutorial, we’ve learnt about the concept of rooms, presence, and others.
We’ve also learnt how to put all these into practice, and how to persist state
using storage too.

You can see some stats about the room you created in your
[dashboard](https://liveblocks.io/dashboard/rooms).

## Next steps

- [API reference](/docs/api-reference/liveblocks-react)
- [Authentication](/docs/authentication)

[`livelist.delete`]: /docs/api-reference/liveblocks-client#LiveList.delete
[`livelist.push`]: /docs/api-reference/liveblocks-client#LiveList.push
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`liveobject.get`]: /docs/api-reference/liveblocks-client#LiveList.push
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveList.push
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`create-react-app`]: https://create-react-app.dev/
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`useothers`]: /docs/api-reference/liveblocks-react#useOthers
[`useupdatemypresence`]:
  /docs/api-reference/liveblocks-react#useUpdateMyPresence
[`usestorage`]: /docs/api-reference/liveblocks-react#useStorage
[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation

---
meta:
  title:
    "How to create a collaborative to-do list with React, Redux, and Liveblocks"
  description:
    "Build a collaborative to-do list with React, Redux, and Liveblocks"
---

In this 15-minute tutorial, we’ll be building a collaborative to-do list using
React, [Redux](https://redux.js.org/), and Liveblocks. As users edit the list,
changes will be automatically synced and persisted, allowing for a list that
updates in realtime across clients. Users will also be able to see who else is
currently online, and when another user is typing.

- [React tutorial](/docs/tutorials/collaborative-to-do-list/react)
- [React + Zustand tutorial](/docs/tutorials/collaborative-to-do-list/react-zustand)

The source code for this guide is
[available on github](https://github.com/liveblocks/liveblocks/tree/main/examples/redux-todo-list).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

First, we need to create a new app with
[`create-react-app`](https://create-react-app.dev/):

```bash
npx create-react-app redux-todo-app
```

Then run the following command to install the Liveblocks packages and Redux:

```bash
npm install redux react-redux @reduxjs/toolkit @liveblocks/client @liveblocks/redux
```

[`@liveblocks/client`](/docs/api-reference/liveblocks-client) lets you interact
with Liveblocks servers.
[`@liveblocks/redux`](/docs/api-reference/liveblocks-redux) contains a
Liveblocks enhancer for a redux store.

### Connect to Liveblocks servers [#connect-liveblocks-servers]

</Banner>

Create a new file `src/store.js` and initialize the Liveblocks client with your
public API key. Then add our
[enhancer](/docs/api-reference/liveblocks-redux#enhancer) to your store
configuration.

```js file="src/store.js"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const initialState = {};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    /* logic will be added here */
  },
});

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(liveblocksEnhancer({ client })),
  });
}

const store = makeStore();

export default store;
```

We need to edit `src/index.js` to add the react-redux provider:

```js highlight="6,7,11,13" file="src/index.js"
import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";

import { Provider } from "react-redux";
import store from "./store";

ReactDOM.render(
  <React.StrictMode>
    <Provider store={store}>
      <App />
    </Provider>
  </React.StrictMode>,
  document.getElementById("root")
);
```

### Connect to a Liveblocks room [#connect-liveblocks-room]

Liveblocks uses the concept of _rooms_, separate virtual spaces where people can
collaborate. To create a multiplayer experience, multiple users must be
connected to the same room.

We are going to dispatch the actions provided by `@liveblocks/redux` to
[`enter`](/docs/api-reference/liveblocks-redux#actions-enter) and
[`leave`](/docs/api-reference/liveblocks-redux#actions-leave) the room.

In our main component, we want to connect to the Liveblocks room when the
component does mount, and leave the room when it unmounts.

```js file="src/App.js"
import React, { useEffect } from "react";
import { useDispatch } from "react-redux";
import { actions } from "@liveblocks/redux";

import "./App.css";

export default function App() {
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom("redux-demo-room"));

return () => {
      dispatch(actions.leaveRoom("redux-demo-room"));
    };
  }, [dispatch]);

return <div className="container">To-do list app</div>;
}
```

## Show who’s currently in the room [#who-is-here]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

Now that Liveblocks is set up, we can start updating our code to display how
many users are currently online.

We’ll be doing this by using the injected object
[`liveblocks.others`](/docs/api-reference/liveblocks-redux#liveblocks-state-others)
to show who’s currently inside the room.

```js highlight="2,7-17,35-37" file="src/App.js"
import React, { useEffect } from "react";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import "./App.css";

function WhoIsHere() {
  const othersUsersCount = useSelector(
    (state) => state.liveblocks.others.length
  );

return (
    <div className="who_is_here">
      There are {othersUsersCount} other users online
    </div>
  );
}

export default function App() {
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom("redux-demo-room"));

return () => {
      dispatch(actions.leaveRoom("redux-demo-room"));
    };
  }, [dispatch]);

return (
    <div className="container">
      <WhoIsHere />
    </div>
  );
}
```

_For a tidier look, here's some styling to place within `src/App.css`._

```css file="src/App.css" isCollapsed isCollapsable
body {
  background-color: rgb(243, 243, 243);
}

.container {
  display: flex;
  flex-direction: column;
  width: 100%;
  margin-left: auto;
  margin-right: auto;
  margin-top: 3rem;
  max-width: 28rem;
}

input:hover {
  box-shadow:
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 0 #000,
    0 1px 3px 0 rgba(0, 0, 0, 0.1),
    0 1px 2px 0 rgba(0, 0, 0, 0.06);
}

input:focus {
  outline: none;
}

.todo_container {
  display: flex;
  padding: 0.5rem 0.875rem;
  align-items: center;
  justify-content: space-between;
}

.todo {
  flex-grow: 1;
}

.delete_button {
  padding: 0;
  margin: 0;
  font-size: 16px;
  border: 0 solid;
  appearance: button;
  background-color: transparent;
}

.delete_button:focus {
  outline: none;
}

.who_is_here {
  align-self: flex-end;
  font-size: 11px;
  color: #aaa;
}

.someone_is_typing {
  position: absolute;
  font-size: 11px;
  color: #aaa;
}
```

## Show if someone is typing [#someone-is-typing]

Next, we'll add some code to show a message when another user is typing.

Any online user could start typing, and we need to keep track of this, so it's
best if each user holds their own `isTyping` property.

Luckily, Liveblocks uses the concept of presence to handle these temporary
states. A user's presence can be used to represent the position of a cursor on
screen, the selected shape in a design tool, or in this case, if they're
currently typing or not.

We want to add some data to our redux store, `draft` will contain the value of
the input. `isTyping` will be set when the user is writing a draft.

The enhancer option
[`presenceMapping: { isTyping: true }`](/docs/api-reference/liveblocks-redux#enhancer-option-presence-mapping)
means that we want to automatically sync the part of the state named `isTyping`
to Liveblocks Presence.

```js highlight="10-11,18-21,25,34" file="src/store.js"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const initialState = {
  draft: "",
  isTyping: false,
};

export const { setDraft } = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: (getDefaultEnhancers) =>
      getDefaultEnhancers().concat(
        liveblocksEnhancer({
          client,
          presenceMapping: { isTyping: true },
        })
      ),
  });
}

const store = makeStore();

export default store;
```

Now that we set the `isTyping` state when necessary, let's create a new
component called `SomeoneIsTyping` to display a message when at least one other
user has `isTyping` equals to `true`.

```js highlight="5,11-19,22,40-47" file="src/App.js"
import React, { useEffect } from "react";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import { setDraft } from "./store";

import "./App.css";

/* WhoIsHere */

function SomeoneIsTyping() {
  const someoneIsTyping = useSelector((state) =>
    state.liveblocks.others.some((user) => user.presence?.isTyping)
  );

return someoneIsTyping ? (
    <div className="someone_is_typing">Someone is typing</div>
  ) : null;
}

export default function App() {
  const draft = useSelector((state) => state.draft);
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom("redux-demo-room"));

return () => {
      dispatch(actions.leaveRoom("redux-demo-room"));
    };
  }, [dispatch]);

## Sync and persist to-dos [#add-liveblocks-storage]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

To-do list items will be stored even after all users disconnect, so we won't be
using presence to store these values. For this, we need something new.

Add an array of todos to your redux store, and tell the enhancer to sync and
persist them with Liveblocks.

To achieve that, we are going to use the enhancer option
[`storageMapping: { todos: true }`](/docs/api-reference/liveblocks-redux#enhancer-option-storage-mapping).
It means that the part of the state named `todos` will be synced with Liveblocks
Storage.

```js highlight="10,23-30,34,43" file="src/store.js"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore, createSlice } from "@reduxjs/toolkit";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const initialState = {
  todos: [],
  draft: "",
  isTyping: false,
};

export const { setDraft, addTodo, deleteTodo } = slice.actions;

const store = makeStore();

export default store;
```

We can display the list of todos and use the actions `addTodo` and `deleteTodo`
to update our list:

```js highlight="5,13,38-41,45-57" file="src/App.js"
import React, { useEffect } from "react";
import { useDispatch, useSelector } from "react-redux";
import { actions } from "@liveblocks/redux";

import { setDraft, addTodo, deleteTodo } from "./store";

import "./App.css";

/* WhoIsHere */
/* SomeoneIsTyping */

export default function App() {
  const todos = useSelector((state) => state.todos);
  const draft = useSelector((state) => state.draft);
  const dispatch = useDispatch();

useEffect(() => {
    dispatch(actions.enterRoom("redux-demo-room"));

return () => {
      dispatch(actions.leaveRoom("redux-demo-room"));
    };
  }, [dispatch]);

return (
    <div className="container">
      <WhoIsHere />
      <input
        className="input"
        type="text"
        placeholder="What needs to be done?"
        value={draft}
        onChange={(e) => dispatch(setDraft(e.target.value))}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            dispatch(addTodo());
          }
        }}
      ></input>
      <SomeoneIsTyping />
      {todos.map((todo, index) => {
        return (
          <div className="todo_container" key={index}>
            <div className="todo">{todo.text}</div>
            <button
              className="delete_button"
              onClick={() => dispatch(deleteTodo(index))}
            >
              ✕
            </button>
          </div>
        );
      })}
    </div>
  );
}
```

Voilà! We have a working collaborative to-do list, with persistent data storage.

## Summary

In this tutorial, we’ve learnt about the concept of rooms, presence, and others.
We've also learnt how to put all these into practice, and how to persist state
using storage too.

You can see some stats about the room you created in your
[dashboard](https://liveblocks.io/dashboard/rooms).

## Next steps

- [API reference](/docs/api-reference/liveblocks-redux)
- [Authentication](/docs/authentication)

---
meta:
  title:
    "How to create a collaborative to-do list with React, Zustand, and
    Liveblocks"
  description:
    "Build a collaborative to-do list with React, Zustand, and Liveblocks"
---

In this 15-minute tutorial, we’ll be building a collaborative to-do list using
React, [Zustand](https://github.com/pmndrs/zustand), and Liveblocks. As users
edit the list, changes will be automatically synced and persisted, allowing for
a list that updates in realtime across clients. Users will also be able to see
who else is currently online, and when another user is typing.

- [React tutorial](/docs/tutorials/collaborative-to-do-list/react)
- [React + Redux tutorial](/docs/tutorials/collaborative-to-do-list/react-redux)

The source code for this guide is
[available on github](https://github.com/liveblocks/liveblocks/tree/main/examples/zustand-todo-list).

## Install Liveblocks into your project [#install-liveblocks]

### Install Liveblocks packages

First, we need to create a new app with
[`create-react-app`](https://create-react-app.dev/):

```bash
npx create-react-app zustand-todo-app --template typescript
```

To start a plain JavaScript project, you can omit the `--template typescript`
flag.

Then install the Liveblocks packages and Zustand:

```bash
npm install zustand @liveblocks/client @liveblocks/zustand
```

[`@liveblocks/client`](/docs/api-reference/liveblocks-client) lets you interact
with Liveblocks servers.
[`@liveblocks/zustand`](/docs/api-reference/liveblocks-zustand) contains a
middleware for Zustand.

### Connect to Liveblocks servers [#connect-liveblocks-servers]

</Banner>

Create a new file `src/store.ts` and initialize the Liveblocks client with your
public API key. Then add our
[liveblocks](/docs/api-reference/liveblocks-zustand#liveblocks) to your store
configuration.

type State = {
  // Your Zustand state type will be defined here
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      // Your state and actions will go here
    }),
    { client }
  )
);

export default useStore;
```

### Connect to a Liveblocks room [#connect-liveblocks-room]

Liveblocks uses the concept of _rooms_, separate virtual spaces where people can
collaborate. To create a collaborative experience, multiple users must be
connected to the same room.

In our main component, we want to connect to the Liveblocks room when the
component does mount, and leave the room when it unmounts.

```tsx file="src/App.tsx"
import React, { useEffect } from "react";
import useStore from "./store";

import "./App.css";

export default function App() {
  const {
    liveblocks: { enterRoom, leaveRoom },
  } = useStore();

useEffect(() => {
    enterRoom("zustand-todo-app");
    return () => {
      leaveRoom("zustand-todo-app");
    };
  }, [enterRoom, leaveRoom]);

return <div className="container">To-do list app</div>;
}
```

## Show who’s currently in the room [#who-is-here]

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

Now that Liveblocks is set up, we’re going to use the injected object
[`liveblocks.others`](/docs/api-reference/liveblocks-zustand#liveblocks-state-others)
to show who’s currently inside the room.

```tsx highlight="6-14,30" file="src/App.tsx"
import React, { useEffect } from "react";
import useStore from "./store";

import "./App.css";

function WhoIsHere() {
  const othersUsersCount = useStore((state) => state.liveblocks.others.length);