---
meta:
  title: "@liveblocks/client"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/client package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/client` provides you with JavaScript bindings for our realtime
collaboration APIs, built on top of WebSockets. Read our
[getting started](/docs/get-started) guides to learn more.

## createClient

Creates a [client](#Client) that allows you to connect to Liveblocks servers.
You must define either `authEndpoint` or `publicApiKey`. Resolver functions
should be placed inside here, and a number of other options are available.

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

const client = createClient({
  authEndpoint: "/api/liveblocks-auth",

  // Other options
  // ...
});
```

```tsx title="Every createClient option" isCollapsable isCollapsed
import { createClient } from "@liveblocks/client";

const client = createClient({
  // Connect with authEndpoint
  authEndpoint: "/api/liveblocks-auth",

  // Alternatively, use an authEndpoint callback
  // authEndpoint: async (room) => {
  //   const response = await fetch("/api/liveblocks-auth", {
  //   method: "POST",
  //   headers: {
  //     Authentication: "<your own headers here>",
  //     "Content-Type": "application/json",
  //   },
  //   body: JSON.stringify({ room }),
  // });
  // return await response.json();
  // },

  // Alternatively, use a public key
  // publicApiKey: "pk_...",

  // Throttle time (ms) between WebSocket updates
  throttle: 100,

  // Prevent browser tab from closing while local changes aren’t synchronized yet
  preventUnsavedChanges: false,

  // Throw lost-connection event after 5 seconds offline
  lostConnectionTimeout: 5000,

  // Disconnect users after X (ms) of inactivity, disabled by default
  backgroundKeepAliveTimeout: undefined,

  // Resolve user info for Comments and Notifications
  resolveUsers: async ({ userIds }) => {
    const usersData = await __getUsersFromDB__(userIds);

    return usersData.map((userData) => ({
      name: userData.name,
      avatar: userData.avatar.src,
    }));
  },

  // Resolve room info for Notifications
  resolveRoomsInfo: async ({ roomIds }) => {
    const documentsData = await __getDocumentsFromDB__(roomIds);

    return documentsData.map((documentData) => ({
      name: documentData.name,
      // url: documentData.url,
    }));
  },

  // Resolve mention suggestions for Comments
  resolveMentionSuggestions: async ({ text, roomId }) => {
    const workspaceUsers = await __getWorkspaceUsersFromDB__(roomId);

    if (!text) {
      // Show all workspace users by default
      return __getUserIds__(workspaceUsers);
    } else {
      const matchingUsers = __findUsers__(workspaceUsers, text);
      return __getUserIds__(matchingUsers);
    }
  },

  // Polyfill options for non-browser environments
  polyfills: {
    // atob,
    // fetch,
    // WebSocket,
  },
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="client" type="Client">
    Returns a [Client](#Client), used for connecting to Liveblocks.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem
    name="authEndpoint"
    detailedType="string | async ((room?: string) => CustomAuthenticationResult)"
  >
    The URL of your back end’s [authentication endpoint](/docs/authentication)
    as a string, or an async callback function that returns a Liveblocks token
    result. Either `authEndpoint` or `publicApikey` are required. Learn more
    about [using a URL string](#createClientAuthEndpoint) and [using a
    callback](#createClientCallback).
  </PropertiesListItem>
  <PropertiesListItem name="publicApiKey" type="string">
    The public API key taken from your project’s
    [dashboard](/dashboard/apikeys). Generally not recommended for production
    use. Either `authEndpoint` or `publicApikey` are required. [Learn
    more](#createClientPublicKey).
  </PropertiesListItem>
  <PropertiesListItem name="throttle" type="number" defaultValue="100">
    The throttle time between WebSocket messages in milliseconds, a number
    between `16` and `1000` is allowed. Using `16` means your app will update 60
    times per second. [Learn more](#createClientThrottle).
  </PropertiesListItem>
  <PropertiesListItem
    name="preventUnsavedChanges"
    type="boolean"
    defaultValue="false"
  >
    When set, navigating away from the current page is prevented while
    Liveblocks is still synchronizing local changes. [Learn
    more](#prevent-users-losing-unsaved-changes).
  </PropertiesListItem>
  <PropertiesListItem
    name="lostConnectionTimeout"
    type="number"
    defaultValue="5000"
  >
    After a user disconnects, the time in milliseconds before a
    [`"lost-connection"`](/docs/api-reference/liveblocks-client#Room.subscribe.lost-connection)
    event is fired. [Learn more](#createClientLostConnectionTimeout).
  </PropertiesListItem>
  <PropertiesListItem name="backgroundKeepAliveTimeout" type="number">
    The time before an inactive WebSocket connection is disconnected. This is
    disabled by default, but setting a number will activate it. [Learn
    more](#createClientBackgroundKeepAliveTimeout).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. [Learn
    more](#createClientResolveUsers).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveRoomsInfo"
    detailedType="async? (args: ResolveRoomsInfoArgs) => (RoomInfo | undefined)[] | undefined"
  >
    A function that resolves room information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `RoomInfo` objects in the same order they arrived. [Learn
    more](#createClientResolveRoomsInfo).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveMentionSuggestions"
    detailedType="async? (args: ResolveMentionSuggestionsArgs) => string[]"
  >
    A function that resolves mention suggestions in
    [Comments](/docs/ready-made-features/comments). Return an array of user IDs.
    [Learn more](#createClientResolveMentionSuggestions).
  </PropertiesListItem>
  <PropertiesListItem name="polyfills">
    Place polyfills for `atob`, `fetch`, and `WebSocket` inside here. Useful
    when using a non-browser environment, such as [Node.js](#createClientNode)
    or [React Native](#createClientReactNative).
  </PropertiesListItem>
  <PropertiesListItem
    name="largeMessageStrategy"
    detailedType='"default" | "split" | "experimental-fallback-to-http"'
    defaultValue={`"default"`}
  >
    <div className="-mb-3">
      How to handle WebSocket messages that are larger than the maximum message size. Can be set to one of these values:
    </div>

    - `"default"` Don’t send anything, but log the error to the console.
    - `"split"` Break the message up into chunks each of which is smaller than the maximum message size.
      Beware that using `"split"` will sacrifice atomicity of changes! Depending on your use case, this may or may not be problematic.
    - `"experimental-fallback-to-http"` Try sending the update over HTTP instead of WebSockets (experimental).

  </PropertiesListItem>
  <PropertiesListItem
    name="unstable_streamData"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Stream the initial Storage content over HTTP, instead of
    waiting for a large initial WebSocket message to be sent from the server.
  </PropertiesListItem>
</PropertiesList>

### createClient with public key [#createClientPublicKey]

When creating a client with a public key, you don’t need to set up an
authorization endpoint. We only recommend using a public key when prototyping,
or on public landing pages, as it makes it possible for end users to access any
room’s data. You should instead use an
[auth endpoint](#createClientAuthEndpoint).

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});
```

### createClient with auth endpoint [#createClientAuthEndpoint]

If you are not using a public key, you need to set up your own `authEndpoint`.
Please refer to our [Authentication guide](/docs/authentication).

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({ authEndpoint: "/api/liveblocks-auth" });
```

### createClient with auth endpoint callback [#createClientCallback]

If you need to add additional headers or use your own function to call your
endpoint, `authEndpoint` can be provided as a custom callback. You should return
the token created with
[`Liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
or [`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens),
learn more in [authentication guide](/docs/rooms/authentication).

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  authEndpoint: async (room) => {
    // Fetch your authentication endpoint and retrieve your access or ID token
    // ...

    return { token: "..." };
  },
});
```

`room` is the room ID that the user is connecting to. When using
[Notifications](/docs/ready-made-features/comments/email-notifications), `room`
can be `undefined`, as the client is requesting a token that grants access to
multiple rooms, rather than a specific room.

#### Fetch your endpoint

Here’s an example of fetching your API endpoint at `/api/liveblocks-auth` within
the callback.

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  authEndpoint: async (room) => {
    const response = await fetch("/api/liveblocks-auth", {
      method: "POST",
      headers: {
        Authentication: "<your own headers here>",
        "Content-Type": "application/json",
      },
      // Don't forget to pass `room` down. Note that it
      // can be undefined when using Notifications.
      body: JSON.stringify({ room }),
    });
    return await response.json();
  },
});
```

#### Token details

You should return the token created with
[`Liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
or [`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens).
These are the values the functions can return.

1. A valid token, it returns a `{ "token": "..." }` shaped response.
1. A token that explicitly forbids access, it returns an
   `{ "error": "forbidden", "reason": "..." }` shaped response. If this is
   returned, the client will disconnect and won't keep trying to authorize.

Any other error will be treated as an unexpected error, after which the client
will retry the request until it receives either 1. or 2.

### WebSocket throttle [#createClientThrottle]

By default, the client throttles the WebSocket messages sent to one every 100
milliseconds, which translates to 10 updates per second. It’s possible to
override that configuration with the `throttle` option with a value between `16`
and `1000` milliseconds.

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  throttle: 16,

  // Other options
  // ...
});
```

This option is helpful for smoothing out realtime animations in your
application, as you can effectively increase the framerate without using any
interpolation. Here are some examples with their approximate frames per second
(FPS) values.

```ts
throttle:  16, // 60 FPS
throttle:  32, // 30 FPS
throttle: 200, //  5 FPS
```

### Prevent users losing unsaved changes [#prevent-users-losing-unsaved-changes]

Liveblocks usually synchronizes milliseconds after a local change, but if a user
immediately closes their tab, or if they have a slow connection, it may take
longer for changes to synchronize. Enabling `preventUnsavedChanges` will stop
tabs with unsaved changes closing, by opening a dialog that warns users. In
usual circumstances, it will very rarely trigger.

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

const client = createClient({
  preventUnsavedChanges: true,

  // Other options
  // ...
});
```

More specifically, this option triggers when:

- There are unsaved changes after calling any hooks or methods, in all of our
  products.
- There are unsaved changes in a
  [Text Editor](/docs/ready-made-features/text-editor).
- There’s an unsubmitted comment in the
  [Composer](/docs/api-reference/liveblocks-react-ui#Composer).
- The user has made changes and is currently offline.

Internally, this option uses the
[beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).

### Lost connection timeout [#createClientLostConnectionTimeout]

If you’re connected to a room and briefly lose connection, Liveblocks will
reconnect automatically and quickly. However, if reconnecting takes longer than
usual, for example if your network is offline, then the room will emit an event
informing you about this.

How quickly this event is triggered can be configured with the
`lostConnectionTimeout` setting, and it takes a number in milliseconds.
`lostConnectionTimeout` can be set between `1000` and `30000` milliseconds. The
default is `5000`, or 5 seconds.

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  lostConnectionTimeout: 5000,

  // Other options
  // ...
});
```

You can listen to the event with [`room.subscribe("lost-connection")`][]. Note
that this also affects when `others` are reset to an empty array after a
disconnection. This helps prevent temporary flashes in your application as a
user quickly disconnects and reconnects. For a demonstration of this behavior,
see our [connection status example][].

### Background keep-alive timeout [#createClientBackgroundKeepAliveTimeout]

By default, Liveblocks applications will maintain an active WebSocket connection
to the Liveblocks servers, even when running in a browser tab that’s in the
background. However, if you’d prefer for background tabs to disconnect after a
period of inactivity, then you can use `backgroundKeepAliveTimeout`.

When `backgroundKeepAliveTimeout` is specified, the client will automatically
disconnect applications that have been in an unfocused background tab for _at
least_ the specified time. When the browser tab is refocused, the client will
immediately reconnect to the room and synchronize the document.

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  // Disconnect users after 15 minutes of inactivity
  backgroundKeepAliveTimeout: 15 * 60 * 1000,

  // Other options
  // ...
});
```

`backgroundKeepAliveTimeout` accepts a number in milliseconds—we advise using a
value of at least a few minutes, to avoid unnecessary disconnections.

### resolveUsers [#createClientResolveUsers]

[Comments](/docs/ready-made-features/comments) stores user IDs in its system,
but no other user information. To display user information in Comments
components, such as a user’s name or avatar, you need to resolve these IDs into
user objects. This function receives a list of user IDs and you should return a
list of user objects of the same size, in the same order.

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

const client = createClient({
  resolveUsers: async ({ userIds }) => {
    const usersData = await __getUsersFromDB__(userIds);

    return usersData.map((userData) => ({
      name: userData.name,
      avatar: userData.avatar.src,
    }));
  },

  // Other options
  // ...
});
```

The name and avatar you return are rendered in
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) components.

#### User objects

The user objects returned by the resolver function take the shape of
`UserMeta["info"]`, which contains `name` and `avatar` by default. These two
values are optional, though if you’re using the
[Comments default components](/docs/api-reference/liveblocks-react-ui#Components),
they are necessary. Here’s an example of `userIds` and the exact values
returned.

```ts
resolveUsers: async ({ userIds }) => {
  // ["marc@example.com", "nimesh@example.com"];
  console.log(userIds);

  return [
    { name: "Marc", avatar: "https://example.com/marc.png" },
    { name: "Nimesh", avatar: "https://example.com/nimesh.png" },
  ];
};
```

You can also return custom information, for example, a user’s `color`:

```ts
resolveUsers: async ({ userIds }) => {
  // ["marc@example.com"];
  console.log(userIds);

  return [
    {
      name: "Marc",
      avatar: "https://example.com/marc.png",
      // +++
      color: "purple",
      // +++
    },
  ];
};
```

#### Accessing user data in React

You can access any values set within `resolveUsers` with the
[`useUser`](/docs/api-reference/liveblocks-react#useUser) hook.

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

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

  // { name: "Marc", avatar: "https://...", ... }
  console.log(user);
}
```

### resolveRoomsInfo [#createClientResolveRoomsInfo]

When using
[Notifications](/docs/ready-made-features/comments/email-notifications) with
[Comments](/docs/ready-made-features/comments), room IDs will be used to
contextualize notifications (e.g. “Chris mentioned you in _room-id_”) in the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component. To replace room IDs with more fitting names (e.g. document names,
“Chris mentioned you in _Document A_”), you can provide a resolver function to
the `resolveRoomsInfo` option in [`createClient`](#createClient).

This resolver function will receive a list of room IDs and should return a list
of room info objects of the same size and in the same order.

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

const client = createClient({
  resolveRoomsInfo: async ({ roomIds }) => {
    const documentsData = await __getDocumentsFromDB__(roomIds);

    return documentsData.map((documentData) => ({
      name: documentData.name,
      // url: documentData.url,
    }));
  },

  // Other options
  // ...
});
```

In addition to the room’s name, you can also provide a room’s URL as the `url`
property. If you do so, the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component will automatically use it. It’s possible to use an inbox
notification’s `roomId` property to construct a room’s URL directly in React and
set it on
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
via `href`, but the room ID might not be enough for you to construct the URL ,
you might need to call your backend for example. In that case, providing it via
`resolveRoomsInfo` is the preferred way.

### resolveMentionSuggestions [#createClientResolveMentionSuggestions]

To enable creating mentions in [Comments](/docs/ready-made-features/comments),
you can provide a resolver function to the `resolveMentionSuggestions` option in
[`createClient`](#createClient). These mentions will be displayed in the
[`Composer`](/docs/api-reference/liveblocks-react-ui#Composer) component.

This resolver function will receive the mention currently being typed (e.g. when
writing “@jane”, `text` will be `jane`) and should return a list of user IDs
matching that text. This function will be called every time the text changes but
with some debouncing.

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

const client = createClient({
  resolveMentionSuggestions: async ({ text, roomId }) => {
    const workspaceUsers = await __getWorkspaceUsersFromDB__(roomId);

    if (!text) {
      // Show all workspace users by default
      return __getUserIds__(workspaceUsers);
    } else {
      const matchingUsers = __findUsers__(workspaceUsers, text);
      return __getUserIds__(matchingUsers);
    }
  },

  // Other options
  // ...
});
```

### createClient for Node.js [#createClientNode]

To use `@liveblocks/client` in Node.js, you need to provide [`WebSocket`][] and
[`fetch`][] polyfills. As polyfills, we recommend installing [`ws`][] and
[`node-fetch`][].

```bash
npm install ws node-fetch
```

Then, pass them to the `createClient` polyfill option as below.

```ts
import { createClient } from "@liveblocks/client";
import fetch from "node-fetch";
import WebSocket from "ws";

const client = createClient({
  polyfills: {
    fetch,
    WebSocket,
  },

  // Other options
  // ...
});
```

Note that `node-fetch` v3+
[does not support CommonJS](https://github.com/node-fetch/node-fetch/blob/main/docs/v3-UPGRADE-GUIDE.md#converted-to-es-module).
If you are using CommonJS, downgrade `node-fetch` to v2.

### createClient for React Native [#createClientReactNative]

To use `@liveblocks/client` with [React Native](https://reactnative.dev/), you
need to add an [`atob`][] polyfill. As a polyfill, we recommend installing
[`base-64`][].

```bash
npm install base-64
```

Then you can pass the `decode` function to our `atob` polyfill option when you
create the client.

```ts
import { createClient } from "@liveblocks/client";
import { decode } from "base-64";

const client = createClient({
  polyfills: {
    atob: decode,
  },

  // Other options
  // ...
});
```

## Client

Client returned by [`createClient`][] which allows you to connect to Liveblocks
servers in your application, and enter rooms.

### Client.enterRoom

Enters a room and returns both the local `Room` instance, and a `leave`
unsubscribe function. The authentication endpoint is called as soon as you call
this function. Used for setting [initial Presence](#setting-initial-presence)
and [initial Storage](#setting-initial-storage) values.

```ts
const { room, leave } = client.enterRoom("my-room-id", {
  // Options
  // ...
});
```

Note that it’s possible to [add types to your room](#typing-your-data).

<PropertiesList title="Returns">
  <PropertiesListItem
    name="room"
    type="Room<Presence, Storage, UserMeta, RoomEvent>"
  >
    A [Room](#Room), used for building your Liveblocks application. Learn more
    about [typing your room](#typing-your-data).
  </PropertiesListItem>
  <PropertiesListItem name="leave" type="() => void">
    A function that’s used to leave the room and disconnect.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="roomId" type="string" required>
    The ID of the room you’re connecting to.
  </PropertiesListItem>
  <PropertiesListItem name="options.initialPresence" type="JsonObject">
    The initial Presence of the user entering the room. Each user has their own
    presence, and this is readable for all other connected users. A user’s
    Presence resets every time they disconnect. This object must be
    JSON-serializable. [Learn more](#setting-initial-presence).
  </PropertiesListItem>
  <PropertiesListItem name="options.initialStorage" type="LsonObject">
    The initial Storage structure for the room when it’s joined for the first
    time. This is only set a single time, when the room has not yet been
    populated. This object must contain [conflict-free live
    structures](/docs/api-reference/liveblocks-client#Storage). [Learn
    more](#setting-initial-storage).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.autoConnect"
    type="boolean"
    defaultValue="true"
  >
    Whether the room immediately connects to Liveblocks servers.
  </PropertiesListItem>
</PropertiesList>

#### Setting initial Presence [#setting-initial-presence]

Presence is used for storing temporary user-based values, such as a user’s
cursor coordinates, or their current selection. Each user has their own
presence, and this is readable for all other connected users. Set your initial
Presence value by using `initialPresence`.

```ts
const { room, leave } = client.enterRoom("my-room-id", {
  // +++
  initialPresence: {
    cursor: null,
    colors: ["red", "purple"],
    selection: {
      id: 72426,
    },
  },
  // +++

  // Other options
  // ...
});
```

Each user’s Presence resets every time they disconnect, as this is only meant
for temporary data. Any JSON-serializable object is allowed (the `JsonObject`
type).

#### Setting initial Storage [#setting-initial-storage]

Storage is used to store permanent data that’s used in your application, such as
shapes on a whiteboard, nodes on a flowchart, or text in a form. The first time
a room is entered, you can set an initial value by using `initialStorage`.
`initialStorage` is only read and set a single time, unless a new top-level
property is added.

```ts
import { LiveList, LiveObject } from "@liveblocks/client";

const { room, leave } = client.enterRoom("my-room-id", {
  // +++
  initialStorage: {
    title: "Untitled",
    shapes: new LiveList([
      new LiveObject({ type: "rectangle", color: "yellow" }),
    ]),
  },
  // +++

  // Other options
  // ...
});
```

If a new top-level property is added to `initialStorage`, the next time a user
connects, the new property will be created. Other properties will be unaffected.
Any
[conflict-free live structures](/docs/api-reference/liveblocks-client#Storage)
and JSON-serializable objects are allowed (the `LsonObject` type).

### Client.getRoom

Gets a room by its ID. Returns `null` if [`client.enterRoom`][] has not been
called previously.

```ts
const room = client.getRoom("my-room");
```

It’s unlikely you’ll need this API if you’re using the newer
[`client.enterRoom`][] API. Note that it’s possible to
[add types to your room](#typing-your-data).

<PropertiesList title="Returns">
  <PropertiesListItem
    name="room"
    type="Room<Presence, Storage, UserMeta, RoomEvent> | null"
  >
    A [Room](#Room), used for building your Liveblocks application. Returns
    `null` if the room has not yet been joined by the current client. Learn more
    about [typing your room](#typing-your-data).
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="roomId" type="string" required>
    The ID of the room you’re connecting to.
  </PropertiesListItem>
</PropertiesList>

### Client.getSyncStatus

Gets the current Liveblocks synchronization status.

```ts
const syncStatus = client.getSyncStatus();
// "synchronizing" | "synchronized"
```

<PropertiesList title="Returns">
  <PropertiesListItem name="returns" type={'"synchronizing" | "synchronized"'}>
    Will be `"synchronizing"` if there are any local changes to any part of
    Liveblocks that still need to be acknowledged by the server. Will be
    `"synchronized"` when all local changes have been persisted.
  </PropertiesListItem>
</PropertiesList>

### Client.logout

Purges any auth tokens from the client’s memory. If there are any rooms that are
still connected, they will be forced to reauthorize.

```ts
client.logout();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### When to logout

Use this function if you have a single page application (SPA) and you wish to
log your user out, and reauthenticate them. This is a way to update your user’s
`info` after a connection has begun.

## Room

Room returned by [`client.enterRoom`][] (or [`client.getRoom`][]).

### Room.getPresence

Return the current user’s Presence.
[Presence](/docs/ready-made-features/presence) is used to store custom
properties on each user that exist until the user disconnects. An example use
would be storing a user’s cursor coordinates.

```ts
const presence = room.getPresence();

// { cursor: { x: 363, y: 723 } }
console.log(presence);
```

Presence is set with [`updatePresence`](#Room.updatePresence) and can be typed
when you [enter a room](#enter-room-typing-a-room). The example above is using
the following type:

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    Presence: {
      cursor: { x: number; y: number };
    };
  }
}
```

<PropertiesList title="Returns">
  <PropertiesListItem name="presence" type="TPresence">
    An object holding the Presence value for the currently connected user.
    Presence is set with [`updatePresence`](#Room.updatePresence). Will always
    be JSON-serializable. `TPresence` is the `Presence` type you set yourself,
    [learn more](#Typing-presence).
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.updatePresence

Updates the current user’s [Presence](/docs/ready-made-features/presence). Only
pass the properties you wish to update—any changes will be merged into the
current presence. The entire presence object will not be replaced.

```ts
room.updatePresence({ typing: true });
room.updatePresence({ status: "Online" });

// { typing: true, status: "Online" }
const presence = room.getPresence();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="update" type="TPresence" required>
    The updated Presence properties for the current user inside an object. The
    user’s entire Presence object will not be replaced, instead these properties
    will be merged with the existing Presence. This object must be
    JSON-serializable.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.addToHistory"
    type="boolean"
    defaultValue="false"
  >
    Adds Presence values to the history stack, meaning using undo and redo
    functions will change them. [Learn more](#add-presence-to-history).
  </PropertiesListItem>
</PropertiesList>

#### Add Presence to history [#add-presence-to-history]

By default, Presence values are not added to history. However, using the
`addToHistory` option will add items to the undo/redo stack.

```ts
room.updatePresence({ color: "blue" }, { addToHistory: true });
room.updatePresence({ color: "red" }, { addToHistory: true });
room.history.undo();

// { color: "blue" }
const presence = room.getPresence();
```

See [`room.history`][] for more information.

### Room.getOthers

Returns an array of currently connected users in the room. Returns a
[`User`](#user-type) object for each user. Note that you can also subscribe to
others using [`Room.subscribe("others")`](#Room.subscribe.others).

```ts
const others = room.getOthers();

for (const other of others) {
  const { connectionId, id, info, presence, canWrite, canComment } = other;
  // Do things
}
```

<PropertiesList title="Returns">
  <PropertiesListItem name="others" type="User<Presence, UserMeta>[]">
    An array holding each connected user’s [`User`](#user-type) object. `User`
    contains the current user’s Presence value, along with other information.
    Presence is set with [`updatePresence`](#Room.updatePresence). Returns an
    empty array when no other users are currently connected. Will always be
    JSON-serializable.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.broadcastEvent

Broadcast an event to other users in the Room. Events broadcast to the room can
be listened to with [`Room.subscribe("event")`][]. Takes a custom event payload
as first argument. Should be serializable to JSON.

```ts
room.broadcastEvent({ type: "REACTION", emoji: "🔥" });
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="event" type="TRoomEvent" required>
    The event to broadcast to every other user in the room. Must be
    JSON-serializable. `TRoomEvent` is the `RoomEvent` type you set yourself,
    [learn more](#typing-multiple-events).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.shouldQueueEventIfNotReady"
    type="boolean"
    defaultValue="false"
  >
    Queue the event if the connection is currently closed, or has not been
    opened yet. We’re not sure if we want to support this option in the future
    so it might be deprecated to be replaced by something else. [Learn
    more](#broadcasting-an-event-when-disconnected).
  </PropertiesListItem>
</PropertiesList>

#### Receiving an event

To receive an event, use [`Room.subscribe("event")`][]. The `user` property
received on the other end is the sender’s [`User`](#user-type) instance.

```ts
// User 1
room.broadcastEvent({ type: "REACTION", emoji: "🔥" });

// User 2
const unsubscribe = room.subscribe("event", ({ event, user, connectionId }) => {
  //                                                  ^^^^ User 1
  if (event.type === "REACTION") {
    // Do something
  }
});
```

We recommend using a property such as `type`, so that it’s easy to distinguish
between different events on the receiving end.

#### Typing multiple events [#typing-multiple-events]

When [defining your types](#typing-your-data), you can pass a `RoomEvent` type
in your config file to receive type hints in your app. To define multiple
different custom events, use a union.

```ts
declare global {
  interface Liveblocks {
    RoomEvent:
      | { type: "REACTION"; emoji: string }
      | { type: "ACTION"; action: string };
  }
}
```

```ts
room.subscribe("event", ({ event, user, connectionId }) => {
  if (event.type === "REACTION") {
    // Do something
  }
  if (event.type === "ACTION") {
    // Do something else
  }
});
```

#### Broadcasting an event when disconnected [#broadcasting-an-event-when-disconnected]

By default, broadcasting an event is a “fire and forget” action. If the sending
client is not currently connected to a room, the event is simply discarded. When
passing the `shouldQueueEventIfNotReady` option, the client will queue up the
event, and only send it once the connection to the room is (re)established.

<Banner>

We’re not sure if we want to support `shouldQueueEventIfNotReady` in the future,
so it may be deprecated and replaced with something else.

</Banner>

```ts
room.broadcastEvent(
  { type: "REACTION", emoji: "🔥" },
  {
    // +++
    shouldQueueEventIfNotReady: true,
    // +++
  }
);
```

### Room.getSelf

Gets the current [`User`](#user-type). Returns `null` if the client is not yet
connected to the room.

```ts
const { connectionId, presence, id, info, canWrite, canComment } =
  room.getSelf();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="user" type="User<Presence, UserMeta> | null">
    Returns the current [`User`](#user-type). Returns `null` if the client is
    not yet connected to the room.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

Here’s an example of a full return value, assuming `Presence` and `UserMeta`
[have been set](#user-type).

```ts
const user = room.getSelf();

// {
//   connectionId: 52,
//   presence: {
//     cursor: { x: 263, y: 786 },
//   },
//   id: "mislav.abha@example.com",
//   info: {
//     avatar: "/mislav.png",
//   },
//   canWrite: true,
//   canComment: true,
// }
console.log(user);
```

### Room.getStatus

Gets the current WebSocket connection status of the room. The possible value
are: `initial`, `connecting`, `connected`, `reconnecting`, or `disconnected`.

```ts
const status = room.getStatus();

// "connected"
console.log(status);
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="status"
    type={`"initial" | "connecting" | "connected" | "reconnecting" | "disconnected"`}
  >
    <div className="-mb-3">
    Returns the room’s current connection status. It can return one of five values:
    </div>

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

  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.getStorageStatus

Get the Storage status. Use this to tell whether Storage has been synchronized
with the Liveblocks servers.

```ts
const status = room.getStorageStatus();

// "synchronizing"
console.log(status);
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="status"
    type={`"not-loaded" | "loading" | "synchronizing" | "synchronized"`}
  >
    <div className="-mb-3">
    The current room’s Storage status. `status` can be one of four types.
    </div>

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

  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.subscribe(storageItem)

Subscribe to updates on a particular storage item, and takes a callback function
that’s called when the storage item is updated. The Storage `root` is a
[`LiveObject`][], which means you can subscribe to this, as well as other live
structures. Returns an unsubscribe function.

```ts
const { root } = await room.getStorage();

const unsubscribe = room.subscribe(root, (updatedRoot) => {
  // Do something
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="storageItem"
    type="L extends (LiveObject | LiveMap | LiveList)"
    required
  >
    The `LiveObject`, `LiveMap`, or `LiveList` which is being subscribed to.
    Each time the structure is updated, the callback is called.
  </PropertiesListItem>
  <PropertiesListItem name="callback" type="(node: L) => void" required>
    Function that’s called when `storageItem` updates. Returns the updated
    storage structure.
  </PropertiesListItem>
  <PropertiesListItem name="options.isDeep" type="boolean">
    Subscribe to both `storageItem` and its children. The callback function will
    be passed a list of updates instead of just the new Storage item. [Learn
    more](#listening-for-nested-changes).
  </PropertiesListItem>
</PropertiesList>

#### Typing Storage

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

```ts file="liveblocks.config.ts"
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: {
      animals: LiveList<{ name: string }>;
    };
  }
}
```

The type received in the callback will match the type passed. Learn more under
[typing your room](#typing-your-data).

```ts
const { root } = await room.getStorage();
const animals = root.get("animals");

const unsubscribe = room.subscribe(animals, (updatedAnimals) => {
  // LiveList<[{ name: "Fido" }, { name: "Felix" }]>
  console.log(updatedAnimals);
});
```

#### Subscribe to any live structure

You can subscribe to any live structure, be it the Storage `root`, a child, or a
structure even more deeply nested.

```ts file="liveblocks.config.ts"
import { LiveMap, LiveObject } from "@liveblocks/client";

type Person = LiveObject<{ name: string; age: number }>;

declare global {
  interface Liveblocks {
    Storage: {
      people: LiveMap<string, Person>;
    };
  }
}
```

```ts
const { root } = await room.getStorage();
const people = root.get("people");
const steven = people.get("steven");

const unsubscribeRoot = room.subscribe(root, (updatedRoot) => {
  // ...
});

const unsubscribePeople = room.subscribe(people, (updatedPeople) => {
  // ...
});

const unsubscribeSteven = room.subscribe(steven, (updatedSteven) => {
  // ...
});
```

#### Listening for nested changes [#listening-for-nested-changes]

It’s also possible to subscribe to a Storage item and all of its children by
passing an optional `isDeep` option in the third argument. In this case, the
callback will be passed a list of updates instead of just the new Storage item.
Each such update is a `{ type, node, updates }` object.

```ts
const { root } = await room.getStorage();

const unsubscribe = room.subscribe(
  root,
  (storageUpdates) => {
    for (const update of storageUpdates) {
      const {
        type, // "LiveObject", "LiveList", or "LiveMap"
        node,
        updates,
      } = update;
      switch (type) {
        case "LiveObject": {
          // updates["property"]?.type; is "update" or "delete"
          // update.node is the LiveObject that has been updated/deleted
          break;
        }
        case "LiveMap": {
          // updates["key"]?.type; is "update" or "delete"
          // update.node is the LiveMap that has been updated/deleted
          break;
        }
        case "LiveList": {
          // updates[0]?.type; is "delete", "insert", "move", or "set"
          // update.node is the LiveList that has been updated, deleted, or modified
          break;
        }
      }
    }
  },
  { isDeep: true }
);
```

#### Using async functions

You use an `async` function inside the subscription callback, though bear in
mind that the callback itself is synchronous, and there’s no guarantee the
`async` function will complete before the callback is run again.

```ts
const { root } = await room.getStorage();

const unsubscribe = room.subscribe(root, (updatedRoot) => {
  async function doThing() {
    await fetch(/* ... */);
  }

  doThing();
});
```

If the order of updates is imporant in your application, and it’s important to
ensure that your `async` function doesn’t start before the previous one
finishes, you can use a package such as
[`async-mutex`](https://www.npmjs.com/package/async-mutex) to help you with
this. Using `runExclusive` will effectively form a queue for all upcoming
updates, guaranteeing serial execution.

```ts
import { Mutex } from "async-mutex";

const { root } = await room.getStorage();
const myMutex = new Mutex();

const unsubscribeUpdates = room.subscribe(root, (root) => {
  void myMutex.runExclusive(async () => {
    await fetch(/* ... */);
  });
});
```

Note that this may cause a performance penalty in your application, as certain
updates will be ignored.

### Room.subscribe("event") [#Room.subscribe.event]

Subscribe to events broadcast by [`Room.broadcastEvent`][]. Takes a callback
that’s run when another user calls [`Room.broadcastEvent`][]. Provides the
`event` along with the `user` and their `connectionId` of the user that sent the
message. Returns an unsubscribe function.

```ts
// User 1
room.broadcastEvent({ type: "REACTION", emoji: "🔥" });

// +++
// User 2
const unsubscribe = room.subscribe("event", ({ event, user, connectionId }) => {
  //                                                  ^^^^ Will be User 1
  if (event.type === "REACTION") {
    // Do something
  }
});
// +++
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"event"`} required>
    Listen to events.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType="(event: RoomEventMessage<Presence, UserMeta, RoomEvent>) => void"
    required
  >
    Function that’s called when another user sends an event. Receives the event,
    the [`user`](#user-type) that sent the event, and their `connectionId`. If
    this event was sent via
    [`liveblocks.broadcastEvent`](/docs/api-reference/liveblocks-node#post-broadcast-event)
    or the [Broadcast event
    API](/docs/api-reference/rest-api-endpoints#post-broadcast-event), `user`
    will be `null` and `connectionId` will be `-1`. [Learn
    more](#receiving-events-from-the-server)
  </PropertiesListItem>
</PropertiesList>

#### Typing events

When [defining your types](#typing-your-data), you can pass a `RoomEvent` type
to your config file to receive type hints in your app. To define multiple
different custom events, use a union.

```ts
declare global {
  interface Liveblocks {
    RoomEvent:
      | { type: "REACTION"; emoji: string }
      | { type: "ACTION"; action: string };
  }
}
```

```ts
room.subscribe("event", ({ event, user, connectionId }) => {
  if (event.type === "REACTION") {
    // Do something
  }
  if (event.type === "ACTION") {
    // Do something else
  }
});
```

#### Receiving events from the server [#receiving-events-from-the-server]

Events can be received from the server with either
[`liveblocks.broadcastEvent`](/docs/api-reference/liveblocks-node#post-broadcast-event)
or the
[Broadcast Event API](/docs/api-reference/rest-api-endpoints#post-broadcast-event).
In events sent from the server, `user` will be `null`, and `connectionId` will
be `-1`.

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

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST() {
  await liveblocks.broadcastEvent({ type: "REACTION", emoji: "🔥" });
}
```

```ts
const unsubscribe = room.subscribe("event", ({ event, user, connectionId }) => {
  // `null`, `-1`
  console.log(user, connectionId);
});
```

### Room.subscribe("my-presence") [#Room.subscribe.my-presence]

Subscribe to the current user’s Presence. Takes a callback that is called every
time the current user presence is updated with [`Room.updatePresence`][].
Returns an unsubscribe function.

```ts
const unsubscribe = room.subscribe("my-presence", (presence) => {
  // Do something
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"my-presence"`} required>
    Listen to the current user’s presence.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    type="(presence: TPresence) => void"
    required
  >
    Function that’s called when the current user’s Presence has updated, for
    example with [`Room.updatePresence`][]. Receives the updates Presence value.
  </PropertiesListItem>
</PropertiesList>

#### Typing Presence

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

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    Presence: {
      status: string;
      cursor: { x: number; y: number };
    };
  }
}
```

The type received in the callback will match the type passed. Learn more under
[typing your data](#typing-your-data).

```ts
const unsubscribe = room.subscribe("my-presence", (presence) => {
  // { status: "typing", cursor: { x: 45, y: 67 }
  console.log(presence);
});
```

### Room.subscribe("others") [#Room.subscribe.others]

Subscribe to every other users’ updates. Takes a callback that’s called when a
user’s Presence updates, or when they enter or leave the room. Returns an
unsubscribe function.

```ts
const unsubscribe = room.subscribe("others", (others, event) => {
  // Do something
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"others"`} required>
    Listen to others.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    type="(others: User<Presence, UserMeta>[], event: OthersEvent) => void"
    required
  >
    Function that’s called when another user’s Presence has updated, for example
    with [`Room.updatePresence`][], or an others event has occurred. Receives an
    array of [`User`](#user-type) values for each currently connected user. Also
    received an object with information about the event that has triggered the
    update, [learn more](#listening-for-others-events).
  </PropertiesListItem>
</PropertiesList>

#### Typing Presence

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

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    Presence: {
      status: string;
      cursor: { x: number; y: number };
    };
  }
}
```

The type received in the callback will match the type passed. Learn more under
[typing your data](#typing-your-data).

```ts
const unsubscribe = room.subscribe("others", (others, event) => {
  // { status: "typing", cursor: { x: 45, y: 67 }
  console.log(others[0].presence);
});
```

#### Listening for others events [#listening-for-others-events]

The `event` parameter returns information on why the callback has just run, for
example if their Presence has updated, if they’ve just left or entered the room,
or if the current user has disconnected.

```ts
const unsubscribe = room.subscribe("others", (others, event) => {
  if (event.type === "leave") {
    // A user has left the room
    // event.user;
  }

  if (event.type === "enter") {
    // A user has entered the room
    // event.user;
  }

  if (event.type === "update") {
    // A user has updated
    // event.user;
    // event.updates;
  }

  if (event.type === "reset") {
    // A disconnection has occurred and others has reset
  }
});
```

#### Live cursors

Here’s a basic example showing you how to render live cursors.
[`Room.updatePresence`](/docs/api-reference/liveblocks-client#Room.updatePresence)
is being used to update each user’s cursor position.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    Presence: {
      cursor: { x: number; y: number };
    };
  }
}
```

```ts
const { room, leave } = client.enterRoom("my-room-id");

// Call this to update the current user's Presence
function updateCursorPosition({ x, y }) {
  room.updatePresence({ cursor: { x, y } });
}

const others = room.getOthers();

// Run __renderCursor__ when any other connected user updates their presence
const unsubscribe = room.subscribe("others", (others, event) => {
  for (const { id, presence } of others) {
    const { x, y } = presence.cursor;
    __renderCursor__(id, { x, y });
  }
}

// Handle events and rendering
// ...
```

Check our [examples page](/examples/browse/cursors) for live demos.

### Room.subscribe("status") [#Room.subscribe.status]

Subscribe to WebSocket connection status updates. Takes a callback that is
called whenever the connection status changes. Possible value are: `initial`,
`connecting`, `connected`, `reconnecting`, or `disconnected`. Returns an
unsubscribe function.

```ts
const unsubscribe = room.subscribe("status", (status) => {
  // "connected"
  console.log(status);
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"status"`} required>
    Listen to status updates.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType={`(status: "initial" | "connecting" | "connected" | "reconnecting" | "disconnected") => void`}
    required
  >
    <div className="-mb-3">
    Function that’s called when the room’s connection status has changed. It can return one of five values:
    </div>

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

  </PropertiesListItem>
</PropertiesList>

#### When to use status

Status is a low-level API that exposes the WebSocket’s connectivity status. You
can use this, for example, to update a connection status indicator in your UI.
It would be normal for a client to briefly lose the connection and restore it
with quick `connected` → `reconnecting` → `connected` status jumps.

```ts
let indicator = "⚪";

const unsubscribe = room.subscribe("status", (status) => {
  switch (status) {
    case "connecting":
      indiciator = "🟡";
      break;
    case "connected":
      indicator = "🟢";
      break;
    // ...
  }
});
```

If you’d like to let users know that there may be connectivity issues, don’t use
this API, but instead refer to [`Room.subscribe("lost-connection")`][] which was
specially built for this purpose.

Do not use this API to detect when Storage or Presence are initialized or
loaded. "Connected" does not guarantee that Storage or Presence are ready. To
detect when Storage is loaded, rely on awaiting the [`Room.getStorage`][]
promise or using the [`Room.subscribe("storage-status")`][] event.

### Room.subscribe("lost-connection") [#Room.subscribe.lost-connection]

A special-purpose event that will fire when a previously connected Liveblocks
client has lost connection, for example due to a network outage, and was unable
to recover quickly. This event is
[designed to help improve UX for your users](#when-to-use-lost-connection-events),
and will not trigger on short interruptions, those that are less than
[5 seconds by default](#setting-lost-connection-timeout). The event only
triggers if a previously connected client disconnects.

```ts
const unsubscribe = room.subscribe("lost-connection", (event) => {
  // "lost"
  console.log(event);
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"lost-connection"`} required>
    Listen to lost connection events.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType={`(event: "lost" | "restored" | "failed") => void`}
    required
  >
    <div className="-mb-3">
    Function that’s called when a room’s lost connection event has been triggered. It can return one of three values:
    </div>

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

  </PropertiesListItem>
</PropertiesList>

#### When to use lost connection events [#when-to-use-lost-connection-events]

Lost connections events allows you to build high-quality UIs by warning your
users that the application is still trying to re-establish the connection, for
example through a toast notification. You may want to take extra care in the
mean time to ensure their changes won’t go unsaved, or to help them understand
why they’re not seeing updates made by others yet.

When this happens, this callback is called with the event `lost`. Then, once the
connection restores, the callback will be called with the value `restored`. If
the connection could definitively not be restored, it will be called with
`failed` (uncommon).

```ts
import { toast } from "my-preferred-toast-library";

const unsubscribe = room.subscribe("lost-connection", (event) => {
  switch (event) {
    case "lost":
      toast.warn("Still trying to reconnect...");
      break;

    case "restored":
      toast.success("Successfully reconnected again!");
      break;

    case "failed":
      toast.error("Could not restore the connection");
      break;
  }
});
```

#### Setting lost connection timeout [#setting-lost-connection-timeout]

The [`lostConnectionTimeout`][] configuration option will determine how quickly
the event triggers after a connection loss occurs. By default, it’s set to
`5000`ms, which is 5 seconds.

```ts
import { createClient } from "@liveblocks/client";

const client = createClient({
  // Throw lost-connection event after 5 seconds offline
  lostConnectionTimeout: 5000,

  // ...
});
```

### Room.subscribe("error") [#Room.subscribe.error]

Subscribe to unrecoverable room connection errors. This event will be emitted
immediately before the client disconnects and won’t try reconnecting again.
Returns an unsubscribe function. If you’d like to retry connecting, call
[`room.reconnect`][].

```ts
const unsubscribe = room.subscribe("error", (error) => {
  switch (error.code) {
    case -1:
      // Authentication error
      break;

    case 4001:
      // Could not connect because you don't have access to this room
      break;

    case 4005:
      // Could not connect because room was full
      break;

    case 4006:
      // The room ID has changed, get the new room ID (use this for redirecting)
      const newRoomId = error.message;
      break;

    default:
      // Unexpected error
      break;
  }
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"error"`} required>
    Listen to error events.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType={`(error: LiveblocksError) => void`}
    required
  >
    <div className="-mb-3">
    Function that’s called when an unrecoverable error event has been triggered. `error.code` can return one of these
    values:
    </div>

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

  </PropertiesListItem>
</PropertiesList>

#### When to use error events

You can use this event to trigger a “Not allowed” screen/dialog. It can also be
helpful for implementing a redirect to another page.

```ts
const unsubscribe = room.subscribe("error", (error) => {
  // Could not connect because you don't have access to this room
  if (error.code === 4001)
    return __displayForbiddenEntryDialog__();
  }
});
```

#### When a room ID has changed

When a room ID has been changed with
[`liveblocks.updateRoomId`](/docs/api-reference/liveblocks-node#post-rooms-update-roomId)
or the
[Update Room ID API](/docs/api-reference/rest-api-endpoints#post-rooms-update-roomId),
`error.message` will contain the new room ID.

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

### Room.subscribe("history") [#Room.subscribe.history]

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

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

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"history"`} required>
    Listen to history events.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType={`({ canUndo: boolean, canRedo: boolean }) => void`}
    required
  >
    Function that’s called when the current user’s history changes. Returns
    booleans that describe whether the user can use
    [undo](/docs/api-reference/liveblocks-client#Room.history.undo) or
    [redo](/docs/api-reference/liveblocks-client#Room.history.redo).
  </PropertiesListItem>
</PropertiesList>

### Room.subscribe("storage-status") [#Room.subscribe.storage-status]

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

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

<PropertiesList title="Returns">
  <PropertiesListItem name="unsubscribe" type="() => void">
    Unsubscribe function. Call it to cancel the subscription.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="eventType" type={`"storage-status"`} required>
    Listen to Storage status events.
  </PropertiesListItem>
  <PropertiesListItem
    name="callback"
    detailedType={`(status: "not-loaded" | "loading" | "synchronizing" | "synchronized") => void`}
    required
  >
    <div className="-mb-3">
    Function that’s called when the current user’s Storage updated status have
    changed. `status` can be one of four types.
    </div>

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

  </PropertiesListItem>
</PropertiesList>

### Room.batch

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

```ts
const { root } = await room.getStorage();

room.batch(() => {
  root.set("x", 0);
  room.updatePresence({ cursor: { x: 100, y: 100 } });
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="return" type="T">
    Returns the return value from the callback.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="callback" type="() => T" required>
    A callback containing every Storage and Presence notification that will be
    part of the batch. Cannot be an `async` function.
  </PropertiesListItem>
</PropertiesList>

#### When to batch updates

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

```ts
const { root } = await room.getStorage();
const notes = root.get("notes");

// ✅ Batch simultaneous changes together
room.batch(() => {
  for (const noteId of notes.keys()) {
    notes.delete(noteId);
  }
});
```

This batch places each
[`LiveMap.delete`](/docs/api-reference/liveblocks-client#LiveMap.delete) call
into a single WebSocket update, instead of sending multiple updates. This will
be much quicker.

#### Batching groups history changes

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

```ts
const { root } = await room.getStorage();
const pet = root.set("pet", new LiveObject({ name: "Fido", age: 5 }));

// ✅ Batch groups changes into one
room.batch(() => {
  pet.set("name", "Felix");
  pet.set("age", 10);
});

// { name: "Felix", age: 10 }
pet.toImmutable();

room.history.undo();

// { name: "Fido", age: 5 }
pet.toImmutable();
```

#### Doesn’t work with async functions

Note that `room.batch` cannot take an `async` function.

```tsx
// ❌ Won't work
room.batch(async () => {
  // ...
});

// ✅ Will work
room.batch(() => {
  // ...
});
```

### Room.history

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

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

<Banner title="History in Yjs">

Note that to undo or redo in Yjs, you must use a separate history manager,
[`Y.UndoManager`](https://docs.yjs.dev/api/undo-manager).

</Banner>

#### Add Presence to history

By default, history is only enabled for Storage. However, you can use the
`addToHistory` option to additionally
[add Presence state to history](/docs/api-reference/liveblocks-client#add-presence-to-history).

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

### Room.history.undo

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

```ts
const person = new LiveObject();
person.set("name", "Pierre");
person.set("name", "Jonathan");

room.history.undo();

// "Pierre"
root.get("name");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.redo

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

```ts
const person = new LiveObject();
person.set("name", "Pierre");
person.set("name", "Jonathan");

room.history.undo();
room.history.redo();

// "Jonathan"
root.get("name");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.canUndo

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

```ts
const person = new LiveObject();
person.set("name", "Pierre");

// true
room.history.canUndo();

room.history.undo();

// false
room.history.canUndo();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="canUndo" type="boolean">
    Whether there is an undo operation in the current history stack.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.canRedo

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

```ts
const person = new LiveObject();
person.set("name", "Pierre");

// false
room.history.canRedo();

room.history.undo();

// true
room.history.canRedo();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="canRedo" type="boolean">
    Whether there is a redo operation in the current history stack.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.clear

Clears the undo and redo stacks for the current client. Explicitly clearing
history resets the ability to undo beyond the current document state. Other
clients’ histories are unaffected.

```ts
const person = new LiveObject();
person.set("name", "Pierre");

// true
room.history.canUndo();

room.history.clear();

// false
room.history.canUndo();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.pause

All future modifications made on the Room will be merged together to create a
single history item until resume is called.

```ts
const info = new LiveObject({ time: "one" });

room.history.pause();
info.set("time", "two");
info.set("time", "three");
room.history.resume();

room.history.undo();

// "one"
room.get("time");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.history.resume

Resumes history after a [pause](#Room.history.pause). Modifications made on the
Room are not merged into a single history item any more.

```ts
const info = new LiveObject({ time: "one" });

room.history.pause();
info.set("time", "two");
info.set("time", "three");
room.history.resume();

room.history.undo();

// "one"
room.get("time");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.connect

Connect the local room instance to the Liveblocks server. Does nothing if the
room is already connecting, reconnecting or connected. We don’t recommend using
this API directly.

```ts
room.connect();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.reconnect

Reconnect the local room instance to the Liveblocks server, using a new
WebSocket connection.

```ts
room.reconnect();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.disconnect

Disconnect the local room instance from the Liveblocks server. The room instance
will remain functional (for example, it will still allow local presence or
storage mutations), but since it’s no longer connected, changes will not be
persisted or synchronized until the room instance is reconnected again. We don’t
recommend using this API directly.

```ts
room.disconnect();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

## Comments

### Room.getThreads

Returns threads, and their associated inbox notifications, that are in the
current room. It also returns the request date that can be used for subsequent
polling. It’s possible to filter for
[a thread’s resolved status](#filtering-resolved-status) and using
[custom metadata](#filtering-metadata).

```ts
const { threads, inboxNotifications, requestedAt } = await room.getThreads();

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

// [{ id: "in_fwh3d4...", kind: "thread", }, ...]
console.log(inboxNotifications);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="threads" type="ThreadData[]">
    Threads within the current room.
  </PropertiesListItem>
  <PropertiesListItem name="inboxNotifications" type="InboxNotificationData[]">
    Inbox notifications associated with the threads.
  </PropertiesListItem>
  <PropertiesListItem name="requestedAt" type="Date">
    The request date to use for subsequent polling.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="resolved" type="boolean">
    Only return `resolved` or `unresolved` threads. [Learn more](#filtering-resolved-status).
  </PropertiesListItem>
  <PropertiesListItem name="metadata" type="Partial<ThreadMetadata>">
    Only return threads containing the custom metadata. Metadata is set yourself when creating a thread, for example `{ priority: "HIGH" }`. [Learn more](#filtering-metadata).
  </PropertiesListItem>
</PropertiesList>

#### Filtering resolved status [#filtering-resolved-status]

You can filter threads by those that are resolved, or unresolved, by passing a
`boolean` to `query.resolved`.

```ts
// Filtering for threads that are unresolved
const threads = await room.getThreads({
  query: {
    // +++
    resolved: false,
    // +++
  },
});
```

#### Filtering metadata [#filtering-metadata]

You can define custom metadata when
[creating a thread](/docs/api-reference/liveblocks-client#Room.createThread),
and the `query.metadata` option allows you to return only threads that match.

```ts
// Creating a thread with `priority` metadata
await room.createThread({
  body: {
    // ...
  },
  // +++
  metadata: { priority: "HIGH" },
  // +++
});

// Filtering for threads with the same metadata
const threads = await room.getThreads({
  query: {
    // +++
    metadata: { priority: "HIGH" },
    // +++
  },
});
```

You can also filter for metadata that begins with a specific string.

```ts
// Creating a thread with `{ assigned: "sales:stacy" } metadata
await room.createThread({
  body: {
    // ...
  },
  // +++
  metadata: { assigned: "sales:stacy" },
  // +++
});

// Filtering for threads with `assigned` metadata that starts with `sales:`
const threads = await room.getThreads({
  query: {
    // +++
    metadata: {
      assigned: {
        startsWith: "sales:",
      },
    },
    // +++
  },
});
```

### Room.getThreadsSince

Returns threads, and their associated inbox notifications, that have been
updated or deleted since the requested date. Helpful when used in combination
with [`Room.getThreads`](#Room.getThreads) to initially fetch all threads, then
receive updates later.

```ts
const initial = await room.getThreads();

const { threads, inboxNotifications, requestedAt } = await room.getThreadsSince(
  { since: initial.requestedAt }
);

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

// { updated: [{ id: "in_ds83hs...", kind: "thread", }, ...], deleted: [...] }
console.log(inboxNotifications);
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="threads"
    detailedType="{ updated: ThreadData[], deleted: ThreadDeleteInfo[] }"
  >
    Threads that have been updated or deleted since the requested date.
  </PropertiesListItem>
  <PropertiesListItem
    name="inboxNotifications"
    detailedType="{ updated: InboxNotificationData[], deleted: InboxNotificationDeleteInfo[] }"
  >
    Inbox notifications that have been updated or deleted since the requested
    date.
  </PropertiesListItem>
  <PropertiesListItem name="requestedAt" type="Date">
    The request date to use for subsequent polling.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="since" type="Date" required>
    Only return threads that have been updated or deleted after this date.
  </PropertiesListItem>
</PropertiesList>

### Room.getThread

Returns a thread and its associated inbox notification, from its ID, if it
exists.

```ts
const { thread, inboxNotification } = await room.getThread("th_xxx");
```

The thread ID can be retrieved from existing threads.

```ts
const newThread = await room.createThread(/* ... */);

const { thread, inboxNotification } = await room.getThread(newThread.id);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="thread" type="ThreadData | undefined">
    The requested thread, or `undefined` if it doesn’t exist.
  </PropertiesListItem>
  <PropertiesListItem
    name="inboxNotification"
    type="InboxNotificationThreadData | undefined"
  >
    The inbox notification associated with the thread, or `undefined` if it
    doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="value" type="string" required>
    The ID of the thread you want to retrieve.
  </PropertiesListItem>
</PropertiesList>

### Room.createThread

Creates a thread, and its initial comment, in the current room. A comment’s body
is an array of paragraphs, each containing child nodes, learn more under
[creating thread content](#creating-thread-content).

```ts
const thread = await room.createThread({
  body: {
    version: 1,
    content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
  },
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="ThreadData">
    The thread that has been created.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="body" type="CommentBody" required>
    The content of the comment, see [creating thread
    content](#creating-thread-content).
  </PropertiesListItem>
  <PropertiesListItem name="attachmentIds" type="string">
    The IDs of the comment’s attachments.
  </PropertiesListItem>
  <PropertiesListItem name="metadata" type="ThreadMetadata">
    Custom metadata to be attached to the thread, see [defining thread
    metadata](#defining-thread-metadata).
  </PropertiesListItem>
</PropertiesList>

#### Creating thread content [#creating-thread-content]

A comment’s body is an array of paragraphs, each containing child nodes. Here’s
an example of how to construct the following simple comment body, which can be
passed to `room.createThread`.

> Hello **world**
>
> <div className="h-2"></div>
> _Second_ paragraph!

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

const body: CommentBody = {
  version: 1,
  content: [
    // +++
    {
      type: "paragraph",
      children: [{ text: "Hello " }, { text: "world", bold: true }],
    },
    {
      type: "paragraph",
      children: [{ text: "Second", italic: true }, { text: " paragraph!" }],
    },
    // +++
  ],
};

const thread = await room.createThread({ body });
```

It’s also possible to create links and mentions.

> <span title="jody.hekla">**@Jody Hekla**</span> the
> **[Liveblocks](https://liveblocks.io)** website is cool!

```ts
const body: CommentBody = {
  version: 1,
  content: [
    // +++
    {
      type: "paragraph",
      children: [
        { type: "mention", id: "jody.hekla" },
        { text: " the " },
        { text: "Liveblocks", type: "link", url: "https://liveblocks.io" },
        { text: " website is cool!" },
      ],
    },
    // +++
  ],
};
```

#### Defining thread metadata [#defining-thread-metadata]

Custom metadata can be attached to each thread. `string`, `number`, and
`boolean` properties are allowed.

```ts
import { ThreadMetadata } from "@liveblocks/client";

const metadata: ThreadMetadata = {
  color: "blue",
  page: 3,
  pinned: true,
};

const thread = await room.createThread({ body, metadata });
```

### Room.deleteThread

Deletes a thread by its ID.

```ts
await room.deleteThread("th_xxx");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread to delete.
  </PropertiesListItem>
</PropertiesList>

### Room.editThreadMetadata

Edits a thread’s custom metadata. Metadata can be a `string`, `number`, or
`boolean`. To delete an existing metadata property, set its value to `null`.

```ts
await room.editThreadMetadata({
  threadId: "th_xxx",
  metadata: {
    color: "blue",
    page: 3,
    pinned: true,
  },
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="metadata" type="ThreadMetadata">
    The thread metadata.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread.
  </PropertiesListItem>
  <PropertiesListItem name="metadata" type="Patchable<ThreadMetadata>" required>
    An object containing the metadata properties to update. Metadata can be a
    `string`, `number`, or `boolean`. To delete an existing metadata property,
    set its value to `null`.
  </PropertiesListItem>
</PropertiesList>

### Room.markThreadAsResolved

Marks a thread as resolved.

```ts
await room.markThreadAsResolved("th_xxx");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread to resolve.
  </PropertiesListItem>
</PropertiesList>

### Room.markThreadAsUnresolved

Marks a thread as unresolved.

```ts
await room.markThreadAsUnresolved("th_xxx");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread to resolve.
  </PropertiesListItem>
</PropertiesList>

### Room.createComment

Creates a comment in a given thread.

```ts
const comment = await room.createComment({
  threadId: "th_xxx",
  body: {
    version: 1,
    content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
  },
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="CommentData">
    The comment that has been created.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread that the comment will be added to.
  </PropertiesListItem>
  <PropertiesListItem name="attachmentIds" type="string">
    The IDs of the comment’s attachments.
  </PropertiesListItem>
  <PropertiesListItem name="body" type="CommentBody" required>
    The content of the comment, see [creating comment
    content](#creating-comment-content).
  </PropertiesListItem>
</PropertiesList>

#### Creating comment content [#creating-comment-content]

A comment’s body is an array of paragraphs, each containing child nodes. Here’s
an example of how to construct the following simple comment body, which can be
passed to `room.createComment`.

> Hello **world**
>
> <div className="h-2"></div>
> _Second_ paragraph!

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

const thread = await room.createThread(/* ... */);

const body: CommentBody = {
  version: 1,
  content: [
    // +++
    {
      type: "paragraph",
      children: [{ text: "Hello " }, { text: "world", bold: true }],
    },
    {
      type: "paragraph",
      children: [{ text: "Second", italic: true }, { text: " paragraph!" }],
    },
    // +++
  ],
};

const comment = await room.createComment({ threadId: thread.id, body });
```

It’s also possible to create links and mentions.

> <span title="jody.hekla">**@Jody Hekla**</span> the
> **[Liveblocks](https://liveblocks.io)** website is cool!

```ts
const body: CommentBody = {
  version: 1,
  content: [
    // +++
    {
      type: "paragraph",
      children: [
        { type: "mention", id: "jody.hekla" },
        { text: " the " },
        { text: "Liveblocks", type: "link", url: "https://liveblocks.io" },
        { text: " website is cool!" },
      ],
    },
    // +++
  ],
};
```

### Room.editComment

Edits a comment, replacing its existing comment body and optionally updating its
attachments. Learn more about
[creating comment content](#creating-comment-content).

```ts
const comment = await room.editComment({
  threadId: "th_xxx",
  commentId: "cm_xxx"
  body: {
    version: 1,
    content: [{ type: "paragraph", children: [{ text: "Hello" }] }],
  },
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="CommentData">
    The comment that has been edited.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread containing the comment.
  </PropertiesListItem>
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the comment that’s being edited.
  </PropertiesListItem>
  <PropertiesListItem name="attachmentIds" type="string">
    The IDs of the comment’s attachments.
  </PropertiesListItem>
  <PropertiesListItem name="body" type="CommentBody" required>
    The content of the comment, see [creating comment
    content](#creating-comment-content).
  </PropertiesListItem>
</PropertiesList>

### Room.deleteComment

Deletes a comment. If it is the last non-deleted comment, the thread also gets
deleted.

```ts
await room.deleteComment({
  threadId: "th_xxx",
  commentId: "cm_xxx",
});
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread containing the comment.
  </PropertiesListItem>
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the comment that’s being edited.
  </PropertiesListItem>
</PropertiesList>

### Room.addReaction

Adds a reaction from the current user on a comment.

```ts
const reaction = await room.addReaction({
  threadId: "th_xxx",
  commentId: "cm_xxx",
  emoji: "👍",
});
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="CommentUserReaction">
    The reaction that has been created.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread containing the comment.
  </PropertiesListItem>
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the comment to add a reaction to.
  </PropertiesListItem>
  <PropertiesListItem name="emoji" type="string" required>
    The emoji reaction to add.
  </PropertiesListItem>
</PropertiesList>

### Room.removeReaction

Removes a reaction from a comment.

```ts
await room.removeReaction({
  threadId: "th_xxx",
  commentId: "cm_xxx",
  emoji: "👍",
});
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Options">
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the thread containing the comment.
  </PropertiesListItem>
  <PropertiesListItem name="threadId" type="string" required>
    The ID of the comment to remove a reaction from.
  </PropertiesListItem>
  <PropertiesListItem name="emoji" type="string" required>
    The emoji reaction to remove.
  </PropertiesListItem>
</PropertiesList>

### Room.prepareAttachment

Creates a local attachment from a file.

```ts
const attachment = room.prepareAttachment({
  file: new File(["Hello, world!"], "hello.txt"),
});

// { "id": "at_1e6nNX...", "name": "hello.txt", "type": "attachment", ... }
console.log(attachment);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="CommentLocalAttachment">
    The local attachment that has been created.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="file" type="File" required>
    The file to create the attachment from.
  </PropertiesListItem>
</PropertiesList>

### Room.uploadAttachment

Uploads a local attachment.

```ts
const attachment = room.prepareAttachment(file);
await room.uploadAttachment(attachment);
```

Optionally, an
[`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
can be passed to cancel the upload.

```ts
const attachment = room.prepareAttachment(file);

// Cancel the upload after 5 seconds
room.uploadAttachment(attachment, { signal: AbortSignal.timeout(5000) });
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="CommentAttachment">
    The attachment that has been uploaded.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="attachment" type="CommentLocalAttachment" required>
    The file to create the attachment from.
  </PropertiesListItem>
  <PropertiesListItem name="options" type="UploadAttachmentOptions">
    A set of options.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="signal" type="AbortSignal">
    Only the inbox notifications updated or deleted after this date will be
    returned.
  </PropertiesListItem>
</PropertiesList>

### Room.getAttachmentUrl

Returns a presigned URL for an attachment by its ID.

```ts
const url = await room.getAttachmentUrl("at_xxx");

// "https://..."
console.log(url);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="string">
    A presigned URL for the attachment.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="attachmentId" type="string" required>
    The ID of the attachment to get the URL for.
  </PropertiesListItem>
</PropertiesList>

## Notifications

### Client.getInboxNotifications

Returns the current user’s inbox notifications and their associated threads. It
also returns the request date that can be used for subsequent polling.

```ts
const { inboxNotifications, threads, requestedAt } =
  await client.getInboxNotifications();

// [{ id: "in_fwh3d4...", kind: "thread", }, ...]
console.log(inboxNotifications);

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

<PropertiesList title="Returns">
  <PropertiesListItem name="inboxNotifications" type="InboxNotificationData[]">
    Current user’s inbox notifications.
  </PropertiesListItem>
  <PropertiesListItem name="threads" type="ThreadData[]">
    Threads associated with the inbox notifications.
  </PropertiesListItem>
  <PropertiesListItem name="requestedAt" type="Date">
    The request date to use for subsequent polling.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Client.getInboxNotificationsSince

Returns the updated and deleted inbox notifications and their associated threads
since the requested date. Helpful when used in combination with
[`Client.getInboxNotifications`](#Client.getInboxNotifications) to initially
fetch all notifications, then receive updates later.

```ts
const initial = await client.getInboxNotifications();

const { inboxNotifications, threads, requestedAt } =
  await client.getInboxNotificationsSince({ since: initial.requestedAt });

// { updated: [{ id: "in_ds83hs...", kind: "thread", }, ...], deleted: [...] }
console.log(inboxNotifications);

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

<PropertiesList title="Returns">
  <PropertiesListItem
    name="inboxNotifications"
    detailedType="{ updated: InboxNotificationData[], deleted: InboxNotificationDeleteInfo[] }"
  >
    Inbox notifications that have been updated or deleted since the requested
    date.
  </PropertiesListItem>
  <PropertiesListItem
    name="threads"
    detailedType="{ updated: ThreadData[], deleted: ThreadDeleteInfo[] }"
  >
    Threads that have been updated or deleted since the requested date.
  </PropertiesListItem>
  <PropertiesListItem name="requestedAt" type="Date">
    The request date to use for subsequent polling.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="since" type="Date" required>
    Only the inbox notifications updated or deleted after this date will be
    returned.
  </PropertiesListItem>
</PropertiesList>

### Client.getUnreadInboxNotificationsCount

Gets the number of unread inbox notifications for the current user.

```ts
const count = await client.getUnreadInboxNotificationsCount();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="number">
    Number of unread inbox notifications.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Client.markAllInboxNotificationsAsRead

Marks all inbox notifications as read, for the current user.

```ts
await client.markAllInboxNotificationsAsRead();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Client.markInboxNotificationAsRead

Marks an inbox notification as read, for the current user.

```ts
await client.markAllInboxNotificationsAsRead("in_xxx");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="inboxNotificationId" type="string" required>
    The ID of the inbox notification to be marked as read.
  </PropertiesListItem>
</PropertiesList>

### Client.deleteAllInboxNotifications

Deletes an inbox notification for the current user.

```ts
await client.deleteAllInboxNotifications();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Client.deleteInboxNotification

Deletes an inbox notification for the current user.

```ts
await client.deleteInboxNotification("in_xxx");
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="inboxNotificationId" type="string" required>
    The ID of the inbox notification to be deleted.
  </PropertiesListItem>
</PropertiesList>

### Room.getNotificationSettings

Gets the user’s notification settings for the current room. This notates which
[`inboxNotifications`](/docs/api-reference/liveblocks-client#Client.getInboxNotifications)
the current user receives in the current room.

```ts
const settings = await room.getNotificationSettings();
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="settings"
    type="{ threads }"
  >
    Notification settings for Liveblocks products.
  </PropertiesListItem>
  <PropertiesListItem
    name="settings.threads"
    type={`"all" | "replies_and_mentions" | "none"`}
  >
    <div className="-mb-3">
      Returns the current room’s notification settings for threads. It can return one of three values:
    </div>

    - `"all"` Receive notifications for every activity.
    - `"replies_and_mentions"` Receive notifications for mentions and thread you’re participating in.
    - `"none"` No notifications are received.

  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Room.updateNotificationSettings

Updates the user’s notification settings for the current room. Updating this
setting will change which
[`inboxNotifications`](/docs/api-reference/liveblocks-client#Client.getInboxNotifications)
the current user receives in the current room.

```ts
const settings = await room.updateNotificationSettings({
  threads: "replies_and_mentions",
});
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="settings"
    type="{ threads }"
  >
    Notification settings for Liveblocks products.
  </PropertiesListItem>
  <PropertiesListItem
    name="settings.threads"
    type={`"all" | "replies_and_mentions" | "none"`}
  >
    <div className="-mb-3">
      Returns the current room’s notification settings for threads. It can return one of three values:
    </div>

    - `"all"` Receive notifications for every activity.
    - `"replies_and_mentions"` Receive notifications for mentions and thread you’re participating in.
    - `"none"` No notifications are received.

  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem
    name="threads"
    type={`"all" | "replies_and_mentions" | "none"`}
  >
    <div className="-mb-3">
      Sets the current room’s notification settings for threads. It can be one of three values:
    </div>

    - `"all"` Receive notifications for every activity.
    - `"replies_and_mentions"` Receive notifications for mentions and thread you’re participating in.
    - `"none"` No notifications are received.

  </PropertiesListItem>
</PropertiesList>

### Client.getNotificationSettings [@badge=Beta]

Returns the user’s notification settings in the current project, in other words
which [notification webhook events](/docs/platform/webhooks#NotificationEvent)
will be sent for the current user. User notification settings are project-based,
which means that this returns the current user’s settings for every room.

```ts
const settings = await client.getNotificationSettings();

// { 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 client.getNotificationSettings();

// { email: null, ... }
console.log(settings);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="settings" type="UserNotificationSettings">
    Current user’s notification settings.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### Client.updateNotificationSettings [@badge=Beta]

Updates the current user’s notification settings, which affects which
[notification webhook events](/docs/platform/webhooks#NotificationEvent) will be
sent for the current user. User notification settings are project-based, which
means that this modifies the current 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.

```ts
const settings = await client.updateNotificationSettings({
  email: { thread: false },
  slack: { textMention: true },
});

// { email: { thread: false, ... }, slack: { textMention: true, ... }, ... }
console.log(settings);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="settings" type="UserNotificationSettings">
    Current user’s notification settings.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="settings" type="object" required>
    A deep partial object containing the user notification settings to
    update. Custom notifications can be set too.

    <div className="-mt-2">
    ```js title="Examples" isCollapsable isCollapsed
    // You only need to pass partials
    await client.updateNotificationSettings({
      email: { thread: true },
    });

    // Enabling a custom notification on the slack channel
    await client.updateNotificationSettings({
      slack: { $myCustomNotification: true },
    });

    // Setting complex settings
    await client.updateNotificationSettings({
      email: {
        thread: true,
        textMention: false,
        $newDocument: true,
      },
        slack: {
        thread: false,
        $fileUpload: false,
      },
        teams: {
        thread: true,
      },
    });
    ```
    </div>

  </PropertiesListItem>
  <PropertiesListItem name="settings.email" type="ChannelNotificationSetting">
    The email notification settings.
  </PropertiesListItem>
  <PropertiesListItem name="settings.slack" type="ChannelNotificationSetting">
    The slack notification settings.
  </PropertiesListItem>
  <PropertiesListItem name="settings.teams" type="ChannelNotificationSetting">
    The microsoft teams notification settings.
  </PropertiesListItem>
  <PropertiesListItem name="settings.webPush" type="ChannelNotificationSetting">
    The web push notification settings.
  </PropertiesListItem>
</PropertiesList>

## Storage

Each room contains Storage, a conflict-free data store that multiple users can
edit at the same time. When users make edits simultaneously, conflicts are
resolved automatically, and each user will see the same state. Storage is ideal
for storing permanent document state, such as shapes on a canvas, notes on a
whiteboard, or cells in a spreadsheet.

### Data structures

Storage provides three different conflict-free data structures, which you can
use to build your application. All structures are permanent and persist when all
users have left the room, unlike [Presence](/docs/ready-made-features/presence)
which is temporary.

- [`LiveObject`][] - Similar to JavaScript object. Use this for storing records
  with fixed key names and where the values don’t necessarily have the same
  types. For example, a `Person` with a `name: string` and an `age: number`
  field. If multiple clients 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. Use this for indexing values that
  all have the same structure. For example, to store an index of `Person` values
  by their name. If multiple users update the same property simultaneously, the
  last modification received by the Liveblocks servers is the winner.

### Typing Storage [#typing-storage]

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

```ts file="liveblocks.config.ts"
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: {
      animals: LiveList<{ name: string }>;
    };
  }
}
```

The type received in the callback will match the type passed. Learn more under
[typing your data](#typing-your-data).

```ts
const { root } = await room.getStorage();
const animals = root.get("animals");

const unsubscribe = room.subscribe(animals, (updatedAnimals) => {
  // LiveList<[{ name: "Fido" }, { name: "Felix" }]>
  console.log(updatedAnimals);
});
```

### Nesting data structures

All Storage data structures can be nested, allowing you to create complex trees
of conflict-free data.

```ts file="liveblocks.config.ts"
import { LiveObject, LiveList, LiveMap } from "@liveblocks/client";

type Person = LiveObject<{
  name: string;
  pets: LiveList<string>;
}>;

declare global {
  interface Liveblocks {
    Storage: {
      people: LiveMap<string, Person>;
    };
  }
}
```

```ts
import { LiveObject, LiveList, LiveMap } from "@liveblocks/client";

const pets = new LiveList(["Cat", "Dog"]);
const person = new LiveObject({ name: "Alicia", pets });
const people = new LiveMap();
people.set("alicia", person);

const { root } = await room.getStorage();
root.set(people);
```

<Banner title="Need help troubleshooting Storage?">

Get the [Liveblocks DevTools extension](/devtools) to develop and debug your
application as you build it.

</Banner>

### Room.getStorage

Get the room’s Storage asynchronously (returns a Promise). The promise will
resolve once the Storage’s root is loaded and available. The Storage’s root is
always a [`LiveObject`][].

```ts
const { root } = await room.getStorage();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="storage" type="{ root: LiveObject<TStorage> }">
    The room’s Storage structures. `root` is a `LiveObject`, and is the root of
    your Storage. Learn more about [typing Storage](#typing-storage).
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

## LiveObject

The `LiveObject` class is similar to a JavaScript object that is synchronized on
all clients. Use this for storing records with fixed key names and where the
values don’t necessarily have the same types. For example, a `Person` with
`name` and `age` fields. To add typing, read more under
[typing Storage](#typing-storage).

```ts
type Person = LiveObject<{
  name: string;
  age: number;
}>;
```

Keys are strings, and values can contain other Storage structures, or
JSON-serializable data. If multiple clients update the same property
simultaneously, the last modification received by the Liveblocks servers is the
winner.

### new LiveObject [#LiveObject.constructor]

Create an empty `LiveObject`

```ts
import { LiveObject } from "@liveblocks/client";

const object = new LiveObject();
```

Create a `LiveObject` with initial data.

```ts
import { LiveObject } from "@liveblocks/client";

const object = new LiveObject({ firstName: "Margaret", lastName: "Hamilton" });
```

<PropertiesList title="Returns">
  <PropertiesListItem name="LiveObject" type="LiveObject<L>">
    The newly created `LiveObject`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="initialValue" type="L extends LsonObject" required>
    The initial value for the `LiveObject`. Can contain JSON-serializable data
    and other Liveblocks conflict-free data structures.
  </PropertiesListItem>
</PropertiesList>

#### Add a LiveObject to Storage

The Storage root is `LiveObject` itself, so you can use [`LiveObject.set`]() to
add a new property to your root. If you’ve [typed Storage](#typing-storage)
you’ll have type hints as you build.

```ts
import { LiveObject } from "@liveblocks/client";

const { root } = await room.getStorage();

const person = new LiveObject({ name: "Alicia" });
root.set("person", person);
```

### delete [#LiveObject.delete]

Delete a property from the `LiveObject`

```ts
const object = new LiveObject({ firstName: "Ada", lastName: "Lovelace" });
object.delete("lastName");

// { firstName: "Ada" }
object.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the property you’re deleting. If the property doesn’t exist,
    nothing will occur.
  </PropertiesListItem>
</PropertiesList>

### get [#LiveObject.get]

Get a property from the `LiveObject`.

```ts
const object = new LiveObject({ firstName: "Ada", lastName: "Lovelace" });

// "Ada"
object.get("firstName");
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value">
    The value of the property. Returns `undefined` if it doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the property you’re getting.
  </PropertiesListItem>
</PropertiesList>

### set [#LiveObject.set]

Adds or updates a property with the specified key and a value.

```ts
const object = new LiveObject({ firstName: "Marie" });
object.set("lastName", "Curie");

// { firstName: "Ada", lastName: "Curie" }
object.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the property you’re setting.
  </PropertiesListItem>
  <PropertiesListItem name="value" type="LsonObject" required>
    The value of the property you’re setting. Can contain JSON-serializable data
    and other Liveblocks conflict-free data structures.
  </PropertiesListItem>
</PropertiesList>

### update [#LiveObject.update]

Adds or updates multiple properties at once. Nested changes to other Storage
types will not be applied.

```ts
const object = new LiveObject({ firstName: "Grace" });
object.update({ lastName: "Hopper", job: "Computer Scientist" });

// { firstName: "Grace", lastName: "Hopper", job: "Computer Scientist" }
object.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="value" type="LsonObject" required>
    The keys and values you’re updating. Can contain JSON-serializable data and
    other Liveblocks conflict-free data structures. Nested changes to other
    Storage types will not be applied.
  </PropertiesListItem>
</PropertiesList>

### clone [#LiveObject.clone]

Returns a deep copy of the `LiveObject` that can be inserted elsewhere in the
Storage tree.

```ts
const obj = new LiveObject(/* ... */);
root.set("a", obj);
root.set("b", obj.clone());
```

<PropertiesList title="Returns">
  <PropertiesListItem name="clonedStructure" type="LiveObject">
    The cloned `LiveObject`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### toImmutable [#LiveObject.toImmutable]

Returns an immutable JavaScript object that is equivalent to the `LiveObject`.
Nested values will also be immutable.

```ts
const liveObject = new LiveObject({
  firstName: "Grace",
  lastName: "Hopper",
  hobbies: new LiveList(["reading", "piano"]),
});

// {
//   firstName: "Grace",
//   lastName: "Hopper",
//   hobbies: ["reading", "piano"]
// }
liveObject.toImmutable();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="immutableStructure" type="object">
    Returns a JavaScript object in the shape of your data structure.
    `LiveObject` is converted to an object, `LiveMap` to a map, and `LiveList`
    to an array.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### toObject [#LiveObject.toObject]

<Banner title="Will be deprecated in the future">

Starting with 0.18, we recommend [`toImmutable`][] instead. It’s faster, cached,
and leads to fewer surprises.

</Banner>

Transform the `LiveObject` into a normal JavaScript object.

```ts
const liveObject = new LiveObject({ firstName: "Grace", lastName: "Hopper" });
liveObject.toObject();
// { firstName: "Grace", lastName: "Hopper" }
```

Please note that this method won’t recursively convert Live structures, which
may be surprising:

```ts
const liveObject = new LiveObject({
  animals: new LiveList(["🦁", "🦊", "🐵"]),
});
liveObject.toObject();
// { animals: <LiveList instance> } // ❗️
```

## LiveMap

The `LiveMap` class is similar to a
[JavaScript Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
that is synchronized on all clients. Use this for indexing values that all have
the same structure. For example, to store an index of `Person` values by their
name. To add typing, read more under [typing Storage](#typing-storage).

```ts
type Shapes = LiveMap<string, LiveObject<{ name: string }>>;
```

Keys are strings, and values can contain other Storage structures, or
JSON-serializable data. If multiple clients update the same property
simultaneously, the last modification received by the Liveblocks servers is the
winner.

### new LiveMap [#LiveMap.constructor]

Create an empty `LiveMap`.

```ts
const map = new LiveMap();
```

Create a `LiveMap` with initial data.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="LiveMap" type="LiveMap<string, L>">
    The newly created `LiveMap`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="initialValue"
    type="[string, L extends LsonObject][]"
    required
  >
    The initial value for the `LiveMap`. An array of tuples, each containing a
    key and a value. The values can contain JSON-serializable data and other
    Liveblocks conflict-free data structures.
  </PropertiesListItem>
</PropertiesList>

#### Add a LiveMap to Storage

The Storage root is a `LiveObject`, so you can create a new `LiveMap` then use
[`LiveObject.set`]() to add it to your root. If you’ve
[typed Storage](#typing-storage) you’ll have type hints as you build.

```ts
import { LiveMap } from "@liveblocks/client";

const { root } = await room.getStorage();

const people = new LiveMap([
  ["vincent", "engineer"],
  ["marc", "designer"],
]);
root.set("people", people);
```

### delete [#LiveMap.delete]

Removes the specified element by key. Returns true if an element existed and has
been removed, or false if the element does not exist.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);

// true
map.delete("nimesh");

// Map { "pierre" => "designer" }
map.toImmutable();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="deleted" type="boolean">
    If the element existed and was removed.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the element you’re deleting. If the element doesn’t exist,
    nothing will occur.
  </PropertiesListItem>
</PropertiesList>

### entries [#LiveMap.entries]

Returns a new
[Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
object that contains the `[key, value]` pairs for each element.

```ts
for (const [key, value] of map.entries()) {
  // Iterate over all the keys and values of the map
}
```

<Banner title="Iteration with TypeScript">

If your TypeScript project targets <code>es5</code> or lower, you’ll need to
enable the <code>--downlevelIteration</code> option to use this API.

</Banner>

<PropertiesList title="Returns">
  <PropertiesListItem name="iterator" type="IterableIterator<[string, L]>">
    A new Iterator object for the `LiveMap`, containing the `[key, value]` pairs
    for each element.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### forEach [#LiveMap.forEach]

Executes a provided function once per each key/value pair in the Map object, in
insertion order.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);

// "developer", "designer"
map.forEach((value, key, liveMap) => console.log(value));
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    detailedType="(value: L, key: string, map: LiveMap<string, L>) => void"
    required
  >
    A callback for each entry. The callback is passed the current `value`,
    `key`, and the `LiveMap`. Return values are ignored.
  </PropertiesListItem>
</PropertiesList>

### get [#LiveMap.get]

Returns a specified element from the `LiveMap`. Returns `undefined` if the key
can’t be found.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);

// "developer"
map.get("nimesh");

// undefined
map.get("alicia");
```

<PropertiesList title="Returns">
  <PropertiesListItem name="value" type="L | undefined">
    The value of the entry. Returns `undefined` if it doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the entry you’re getting.
  </PropertiesListItem>
</PropertiesList>

### has [#LiveMap.has]

Returns a boolean indicating whether an element with the specified key exists or
not.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);

// true
map.has("nimesh");

// false
map.has("alicia");
```

<PropertiesList title="Returns">
  <PropertiesListItem name="exists" type="boolean">
    Whether the entry exists.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the entry you’re getting.
  </PropertiesListItem>
</PropertiesList>

### keys [#LiveMap.keys]

Returns a new
[Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
object that contains the keys for each element.

```ts
for (const key of map.keys()) {
  // Iterate over all the keys and values of the map
}
```

<Banner title="Iteration with TypeScript">

If your TypeScript project targets <code>es5</code> or lower, you’ll need to
enable the <code>--downlevelIteration</code> option to use this API.

</Banner>

<PropertiesList title="Returns">
  <PropertiesListItem name="iterator" type="IterableIterator<string>">
    A new Iterator object for the `LiveMap`, containing the keys of each entry.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### set [#LiveMap.set]

Adds or updates an element with a specified key and a value.

```ts
const map = new LiveMap();
map.set("vincent", "engineer");

// Map { "vincent" => "engineer" }
map.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="key" type="string" required>
    The key of the entry you’re setting.
  </PropertiesListItem>
  <PropertiesListItem name="value" type="LsonObject" required>
    The value of the entry you’re setting. Can contain JSON-serializable data
    and other Liveblocks conflict-free data structures.
  </PropertiesListItem>
</PropertiesList>

### size [#LiveMap.size]

Returns the number of elements in the `LiveMap`.

```ts
const map = new LiveMap([
  ["nimesh", "developer"],
  ["pierre", "designer"],
]);

// 2
map.size;
```

<PropertiesList title="Returns">
  <PropertiesListItem name="size" type="number">
    The number of entries in the `LiveMap`
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem>_N/A_</PropertiesListItem>
</PropertiesList>

### values [#LiveMap.values]

Returns a new
[Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
object that contains the the values for each element.

```ts
for (const value of map.values()) {
  // Iterate over all the values of the map
}
```

<Banner title="Iteration with TypeScript">

If your TypeScript project targets <code>es5</code> or lower, you’ll need to
enable the <code>--downlevelIteration</code> option to use this API.

</Banner>

<PropertiesList title="Returns">
  <PropertiesListItem name="iterator" type="IterableIterator<L>">
    A new Iterator object for the `LiveMap`, containing the values of each
    entry.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### clone [#LiveMap.clone]

Returns a deep copy of the `LiveMap` that can be inserted elsewhere in the
Storage tree.

```ts
const map = new LiveMap(/* ... */);
root.set("a", map);
root.set("b", map.clone());
```

<PropertiesList title="Returns">
  <PropertiesListItem name="clonedStructure" type="LiveMap">
    The cloned `LiveMap`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### toImmutable [#LiveMap.toImmutable]

Returns an immutable ES6 Map that is equivalent to the `LiveMap`. Nested values
will also be immutable.

```ts
const map = new LiveMap([
  ["florent", new LiveObject({ role: "engineer" })],
  ["marc", new LiveObject({ role: "designer" })],
]);

// Map {
//   "florent" => { role: "engineer" },
//   "marc" => { role: "designer" },
// }
map.toImmutable();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="immutableStructure" type="object">
    Returns a JavaScript object in the shape of your data structure. `LiveMap`
    is converted to a map, `LiveObject` to an object, and `LiveList` to an
    array.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

## LiveList

The `LiveList` class represents an ordered collection of items that is
synchronized across clients. To add typing, read more under
[typing Storage](#typing-storage).

```ts
type Names = LiveList<string>;
```

Items can contain other Storage structures, or JSON-serializable data.

### new LiveList [#LiveList.constructor]

Create an empty `LiveList`.

```ts
const list = new LiveList();
```

Create a `LiveList` with initial data.

```ts
const list = new LiveList(["adrien", "jonathan"]);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="LiveList" type="LiveList<L>">
    The newly created `LiveList`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="initialValue"
    type="Array<L extends LsonObject>"
    required
  >
    The initial array of values for the `LiveList`. Can contain
    JSON-serializable data and other Liveblocks conflict-free data structures.
  </PropertiesListItem>
</PropertiesList>

### clear [#LiveList.clear]

Removes all the elements.

```ts
const list = new LiveList(["adrien", "jonathan"]);
list.clear();

// []
list.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### delete [#LiveList.delete]

Deletes an element at the specified index. If the index doesn’t exist, an
`Error` is thrown.

```ts
const list = new LiveList(["adrien", "jonathan"]);
list.delete(1);

// ["adrien"]
list.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="index" type="number" required>
    The index of the property you’re deleting. If the property doesn’t exist, an
    `Error` is thrown.
  </PropertiesListItem>
</PropertiesList>

### every [#LiveList.every]

Tests whether all elements pass the test implemented by the provided function.
Returns true if the predicate function returns a truthy value for every element.
Otherwise, false.

```ts
const list = new LiveList([0, 2, 4]);

// true
list.every((i) => i % 2 === 0);

list.push(5);

// false
list.every((i) => i % 2 === 0);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="isEvery" type="boolean">
    Whether all elements pass the test implemented by the provided function.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(value: L, index: number) => unknown"
    required
  >
    A function to execute for each item in the array. It should return a truthy
    value to indicate the element passes the test, and a falsy value otherwise.
    The function is passed the `value` of the item and its current `index`.
  </PropertiesListItem>
</PropertiesList>

### filter [#LiveList.filter]

Creates an array with all elements that pass the test implemented by the
provided function.

```ts
const list = new LiveList([0, 1, 2, 3, 4]);

// [0, 2, 4]
list.filter((i) => i % 2 === 0);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="filteredArray" type="L[]">
    An array containing each item of the `LiveList` that passed the test
    implemented by the provided function.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(value: L, index: number) => unknown"
    required
  >
    A function to execute for each item in the array. It should return a truthy
    value to indicate the element passes the test, and a falsy value otherwise.
    The function is passed the `value` of the item and its current `index`.
  </PropertiesListItem>
</PropertiesList>

### find [#LiveList.find]

Returns the first element that satisfies the provided testing function. If no
item passes the test, `undefined` is returned.

```ts
const list = new LiveList(["apple", "lemon", "tomato"]);

// "lemon"
list.find((value, index) => value.startsWith("l"));
```

<PropertiesList title="Returns">
  <PropertiesListItem name="item" type="L | undefined">
    The item that has been found. If no item passes the test, `undefined` is
    returned.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(value: L, index: number) => unknown"
    required
  >
    A function to execute for each item in the array. It should return a truthy
    value to indicate the element passes the test, and a falsy value otherwise.
    The function is passed the `value` of the item and its current `index`.
  </PropertiesListItem>
</PropertiesList>

### findIndex [#LiveList.findIndex]

Returns the index of the first element in the `LiveList` that satisfies the
provided testing function. If no item passes the test, `-1` is returned.

```ts
const list = new LiveList(["apple", "lemon", "tomato"]);

// 1
list.findIndex((value, index) => value.startsWith("l"));
```

<PropertiesList title="Returns">
  <PropertiesListItem name="index" type="number">
    The index of the item that has been found. If no item passes the test, `-1`
    is returned.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(value: L, index: number) => unknown"
    required
  >
    A function to execute for each item in the array. It should return a truthy
    value to indicate the element passes the test, and a falsy value otherwise.
    The function is passed the `value` of the item and its current `index`.
  </PropertiesListItem>
</PropertiesList>

### forEach [#LiveList.forEach]

Executes a provided function once for each element.

```ts
const list = new LiveList(["adrien", "jonathan"]);

// "adrien", "jonathan"
list.forEach((item) => console.log(item));
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    detailedType="(value: L, index: number) => void"
    required
  >
    A callback for each item. The callback is passed the current `value` and
    `index`. Return values are ignored.
  </PropertiesListItem>
</PropertiesList>

### get [#LiveList.get]

Get the element at the specified index. Returns `undefined` if the index doesn’t
exist.

```ts
const list = new LiveList(["adrien", "jonathan"]);

// "jonathan"
list.get(1);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="item" type="L | undefined">
    The value of the item at the index. Returns `undefined` if it doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="index" type="number" required>
    The index of the item you’re getting.
  </PropertiesListItem>
</PropertiesList>

### indexOf [#LiveList.indexOf]

Returns the first index at which a given element can be found in the `LiveList`.
Returns `-1` if it is not present.

```ts
const list = new LiveList(["adrien", "jonathan"]);

// 1
list.indexOf("jonathan");

// undefined
list.indexOf("chris");
```

<PropertiesList title="Returns">
  <PropertiesListItem name="index" type="number">
    The index of the item. Returns `-1` if it doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="searchElement" type="L" required>
    The item you’re locating.
  </PropertiesListItem>
  <PropertiesListItem name="index" type="number">
    The index to start the search at.
  </PropertiesListItem>
</PropertiesList>

### insert [#LiveList.insert]

Inserts one element at a specified index. Throws an `Error` if the index is out
of bounds.

```ts
const list = new LiveList(["adrien", "jonathan"]);

list.insert("chris", 1);

// ["adrien", "chris", "jonathan"]
list.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="value" type="L extends LsonObject" required>
    The value of the item you’re inserting.
  </PropertiesListItem>
  <PropertiesListItem name="index" type="number" required>
    The index to insert the item into.
  </PropertiesListItem>
</PropertiesList>

### lastIndexOf [#LiveList.lastIndexOf]

Returns the last index at which a given element can be found in the `LiveList`,
or -1 if it is not present. The `LiveList` is searched backwards, starting at
fromIndex. Returns `-1` if it is not present.

```ts
const list = new LiveList(["adrien", "jonathan", "adrien"]);

// 2
list.indexOf("adrien");

// undefined
list.indexOf("chris");
```

<PropertiesList title="Returns">
  <PropertiesListItem name="index" type="number">
    The index of the item. Returns `-1` if it doesn’t exist.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="searchElement" type="L" required>
    The item you’re locating.
  </PropertiesListItem>
  <PropertiesListItem name="index" type="number">
    The index at which to start searching backwards.
  </PropertiesListItem>
</PropertiesList>

### length [#LiveList.length]

Returns the number of elements.

```ts
const list = new LiveList(["adrien", "jonathan"]);

// 3
list.length; // equals
```

<PropertiesList title="Returns">
  <PropertiesListItem name="length" type="number">
    The number of items in the `LiveList`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem>_N/A_</PropertiesListItem>
</PropertiesList>

### map [#LiveList.map]

Creates an array populated with the results of calling a provided function on
every element.

```ts
const list = new LiveList(["apple", "lemon", "tomato"]);

// ["APPLE", "LEMON", "TOMATO"]
list.map((value, index) => value.toUpperCase());
```

<PropertiesList title="Returns">
  <PropertiesListItem name="array">
    The array of each item has been transformed by the callback function.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    detailedType="(value: L, index: number) => void"
    required
  >
    A callback for each item. The callback is passed the current `value` and
    `index`. Return values are used in the returned array.
  </PropertiesListItem>
</PropertiesList>

### move [#LiveList.move]

Moves one element at a specified index.

```ts
const list = new LiveList(["adrien", "chris", "jonathan"]);

list.move(2, 0);

// ["jonathan", "adrien", "chris"]
list.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="index" type="number" required>
    The index of the item to move.
  </PropertiesListItem>
  <PropertiesListItem name="targetIndex" type="number" required>
    The index where the element should be after moving.
  </PropertiesListItem>
</PropertiesList>

### push [#LiveList.push]

Adds one element to the end of the `LiveList`.

```ts
const list = new LiveList(["adrien", "jonathan"]);

list.push("chris");

// ["adrien", "jonathan", "chris"]
list.toImmutable();
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="index" type="L" required>
    The item to add to the end of the `LiveList`.
  </PropertiesListItem>
</PropertiesList>

### set [#LiveList.set]

Replace one element at the specified index.

```ts
const list = new LiveList(["adrien", "jonathan"]);

list.set(1, "chris");

// equals ["adrien", "chris"]
list.toImmutable();
```

### some [#LiveList.some]

Tests whether at least one element in the `LiveList` passes the test implemented
by the provided function.

```ts
const list = new LiveList(["apple", "lemon", "tomato"]);

// true
list.some((value, index) => value.startsWith("l"));

// false
list.some((value, index) => value.startsWith("x"));
```

<PropertiesList title="Returns">
  <PropertiesListItem name="areSome" type="boolean">
    Whether any elements pass the test implemented by the provided function.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(value: L, index: number) => unknown"
    required
  >
    A function to execute for each item in the array. It should return a truthy
    value to indicate the element passes the test, and a falsy value otherwise.
    The function is passed the `value` of the item and its current `index`.
  </PropertiesListItem>
</PropertiesList>

### clone [#LiveList.clone]

Returns a deep copy of the `LiveList` that can be inserted elsewhere in the
Storage tree.

```ts
const list = new LiveList(/* ... */);
root.set("a", list);
root.set("b", list.clone());
```

<PropertiesList title="Returns">
  <PropertiesListItem name="clonedStructure" type="LiveList">
    The cloned `LiveList`.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### toImmutable [#LiveList.toImmutable]

Returns an immutable JavaScript array that is equivalent to the `LiveList`.
Nested values will also be immutable.

```ts
const list = new LiveList([
  new LiveObject({ name: "Olivier" }),
  new LiveObject({ name: "Vincent" }),
]);

// [
//   { name: "Olivier" },
//   { name: "Vincent" },
// ]
list.toImmutable();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="immutableStructure" type="object">
    Returns a JavaScript object in the shape of your data structure.`ListList`
    is converted to an array, `LiveObject` to an object, and `LiveMap` to a map.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

### toArray [#LiveList.toArray]

<Banner title="Will be deprecated in the future">

Starting with 0.18, we recommend [`toImmutable`][] instead. It’s faster, cached,
and leads to fewer surprises.

</Banner>

Transforms the `LiveList` into a normal JavaScript array.

```ts
const list = new LiveList(["🦁", "🦊", "🐵"]);
list.toArray();
// ["🦁", "🦊", "🐵"]
```

Please note that this method won’t recursively convert Live structures, which
may be surprising:

```ts
const list = new LiveList([
  new LiveObject({ firstName: "Grace", lastName: "Hopper" }),
]);
list.toArray();
// [ <LiveObject instance> ]  // ❗️
```

## Resolvers

### invalidateUsers

`client.resolvers.invalidateUsers` can be used to invalidate some or all users
that were previously cached by [`resolveUsers`](#createClientResolveUsers).

It can be used when updating the current user’s avatar for example, to instantly
refresh the user data everywhere without having to perform a page reload.

```tsx
// Invalidate all users
client.resolvers.invalidateUsers();

// Only invalidate "user-0" and "user-1"
client.resolvers.invalidateUsers(["user-0", "user-1"]);
```

### invalidateRoomsInfo

`client.resolvers.invalidateRoomsInfo` can be used to invalidate some or all
rooms that were previously cached by
[`resolveRoomsInfo`](#createClientResolveRoomsInfo).

It can be used when updating a room’s name for example, to instantly refresh the
room info everywhere without having to perform a page reload.

```tsx
// Invalidate all rooms
client.resolvers.invalidateRoomsInfo();

// Only invalidate "room-0" and "room-1"
client.resolvers.invalidateRoomsInfo(["room-0", "room-1"]);
```

### invalidateMentionSuggestions

`client.resolvers.invalidateRoomsInfo` can be used to invalidate all mention
suggestions that were previously cached by
[`resolveMentionSuggestions`](#createClientResolveMentionSuggestions).

It can be used when updating a room’s list of users for example, to prevent
creating out-of-date mentions without having to perform a page reload.

```tsx
// Invalidate all mention suggestions
client.resolvers.invalidateMentionSuggestions();
```

## Utilities

### getMentionedIdsFromCommentBody [#get-mentioned-ids-from-comment-body]

Returns an array of each user’s ID that has been mentioned in a `CommentBody`
(found under `comment.body`).

```ts
import { getMentionedIdsFromCommentBody } from "@liveblocks/client";

const mentionedIds = getMentionedIdsFromCommentBody(comment.body);
```

Here’s an example with a custom `CommentBody`.

```ts
import {
  CommentBody,
  getMentionedIdsFromCommentBody,
} from "@liveblocks/client";

// 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 mentionedIds = getMentionedIdsFromCommentBody(commentBody);

// ["chris@example.com"]
console.log(mentionedIds);
```

<Banner title="Also available from @liveblocks/node">

If you’d like to use this on the server side, it's also available from
[`@liveblocks/node`](/docs/api-reference/liveblocks-node#get-mentioned-ids-from-comment-body).

</Banner>

### 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/client";

const stringComment = await stringifyCommentBody(comment.body);

// "Hello marc@example.com from https://liveblocks.io"
console.log(stringComment);
```

A number of options are 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 }) => `<p>${children}</p>`,

    // Optional, override the `text` element
    text: ({ element }) =>
      element.bold ? `<strong>${element.text}</strong>` : `${element.text}`,

    // Optional, override the `link` element
    link: ({ element, href }) =>
      `<a href="${href}" target="_blank">${element.url}</a>`,

    // Optional, override the `mention` element. `user` available if `resolveUsers` supplied
    mention: ({ element, user }) =>
      `<a href="${user.profileUrl}">${element.id}</a>`,
  },

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

<Banner title="Also available from @liveblocks/node">

If you’d like to use this on the server side, it's also available from
[`@liveblocks/node`](/docs/api-reference/liveblocks-node#stringify-comment-body).

</Banner>

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

// "<b>Hello</b> <span data-mention>@Marc</span> from
// <a href="https://liveblocks.io">https://liveblocks.io</a>"
await stringifyCommentBody(comment.body, {
  format: "html",

  resolveUsers() {
    return [{ name: "Marc" }];
  },
});

// "<b>Hello</b> <a href="https://example.com" data-id="marc@example.com">@Marc</a> from
// <a href="https://liveblocks.io">https://liveblocks.io</a>"
await stringifyCommentBody(comment.body, {
  format: "html",

  mention: ({ element, user }) =>
    `<a href="${user.profileUrl}" data-id="${element.id}">${user.name}</a>`,

  resolveUsers() {
    return [{ name: "Marc", profileUrl: "https://example.com" }];
  },
});
```

## TypeScript

### Typing your data

It’s possible to have automatic types flow through your application by defining
a global `Liveblocks` interface. We recommend doing this in a
`liveblocks.config.ts` file in the root of your app, so it’s easy to keep track
of your types. Each type (`Presence`, `Storage`, etc.), is optional, but it’s
recommended to make use of them.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // Each user's Presence
    Presence: {};

    // The Storage tree for the room
    Storage: {};

    UserMeta: {
      id: string;
      // Custom user info set when authenticating with a secret key
      info: {};
    };

    // Custom events
    RoomEvent: {};

    // Custom metadata set on threads
    ThreadMetadata: {};

    // Custom room info set with resolveRoomsInfo
    RoomInfo: {};

    // Custom activities data for custom notification kinds
    ActivitiesData: {};
  }
}

// Necessary if you have no imports/exports
export {};
```

Here are some example values that might be used.

```ts file="liveblocks.config.ts"
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    // Each user's Presence
    Presence: {
      // Example, real-time cursor coordinates
      cursor: { x: number; y: number };
    };

    // The Storage tree for the room
    Storage: {
      // Example, a conflict-free list
      animals: LiveList<string>;
    };

    UserMeta: {
      id: string;
      // Custom user info set when authenticating with a secret key
      info: {
        // Example properties
        name: string;
        avatar: string;
      };
    };

    // Custom events
    // Example has two events, using a union
    RoomEvent: { type: "PLAY" } | { type: "REACTION"; emoji: "🔥" };

    // Custom metadata set on threads
    ThreadMetadata: {
      // Example, attaching coordinates to a thread
      x: number;
      y: number;
    };

    // Custom room info set with resolveRoomsInfo
    RoomInfo: {
      // Example, rooms with a title and url
      title: string;
      url: string;
    };

    // Custom activities data for custom notification kinds
    ActivitiesData: {
      // Example, a custom $alert kind
      $alert: {
        title: string;
        message: string;
      };
    };
  }
}

// Necessary if you have no imports/exports
export {};
```

### Typing with client.enter

Before Liveblocks 2.0, it was recommended to type your data by passing
`Presence`, `Storage`, `UserMeta`, and `RoomEvents` types to
[`client.enterRoom`][]. This is no longer
[the recommended method](#Typing-your-data) for setting up Liveblocks, but it
can still be helpful, for example you can use `client.enter` multiple times to
create different room types, each with their own correctly typed hooks.

```ts
import { LiveList } from "@liveblocks/client";

// Each user’s Presence
type Presence = {
  cursor: { x: number; y: number };
};

// The Storage tree for the room
type Storage = {
  animals: LiveList<string>;
};

// User information set when authenticating with a secret key
type UserMeta = {
  id: string;
  info: {
    // Custom properties, corresponds with userInfo
  };
};

// Custom events that can be broadcast, use a union for multiple events
type RoomEvent = {
  type: "REACTION";
  emoji: "🔥";
};

const { room, leave } = client.enterRoom<
  Presence,
  Storage,
  UserMeta,
  RoomEvent
>("my-room-id");
```

You can also pass types to
[`client.getRoom`](/docs/api-reference/liveblocks-client#Client.getRoom).

```ts
const { room, leave } = client.getRoom<Presence, Storage, UserMeta, RoomEvent>(
  "my-room-id"
);
```

### User [#user-type]

`User` is a type that’s returned by [`room.getSelf`][], [`room.getOthers`][],
and other functions. Some of its values are set when
[typing your room](#typing-your-data), here are some example values:

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // Each user's Presence
    // +++
    Presence: {
      cursor: { x: number; y: number };
    };
    // +++

    UserMeta: {
      id: string;
      // Custom user info set when authenticating with a secret key
      // +++
      info: {
        name: string;
        avatar: string;
      };
      // +++
    };
  }
}
```

```ts
const { room, leave } = client.enterRoom("my-room-id");

// {
//   connectionId: 52,
//   +++
//   presence: {
//     cursor: { x: 263, y: 786 },
//   },
//   +++
//   id: "mislav.abha@example.com",
//   +++
//   info: {
//     name: "Mislav Abha",
//     avatar: "/mislav.png",
//   },
//   +++
//   canWrite: true,
//   canComment: true,
// }
const user = room.getSelf();
```

<PropertiesList title="Properties">
  <PropertiesListItem name="connectionId" type="number">
    The connection ID of the User. It is unique and increments with every new
    connection.
  </PropertiesListItem>
  <PropertiesListItem name="id" type={`UserMeta["id"]`}>
    The ID of the User that has been set in the authentication endpoint. Useful
    to get additional information about the connected user.
  </PropertiesListItem>
  <PropertiesListItem name="info" type={`UserMeta["info"]`}>
    Additional user information that has been set in the authentication
    endpoint.
  </PropertiesListItem>
  <PropertiesListItem name="presence" type={`TPresence`}>
    The user’s Presence data.
  </PropertiesListItem>
  <PropertiesListItem name="canWrite" type="boolean">
    True if the user can mutate the Room’s Storage and/or YDoc, false if they
    can only read but not mutate it.
  </PropertiesListItem>
  <PropertiesListItem name="canComment" type="boolean">
    The ID of the User that has been set in the authentication endpoint. Useful
    to get additional information about the connected user.
  </PropertiesListItem>
</PropertiesList>

## Deprecated

### Client.enter [@badge=Deprecated]

<Banner title="Deprecated" type="error">
  This is no longer supported. We recommend using [`client.enterRoom`][]
  instead.
</Banner>

Enters a room and returns its local `Room` instance.

```ts
// ❌ This API was recommended before 1.5
const room = client.enter("my-room", {
  initialPresence: { cursor: null },
  initialStorage: { todos: new LiveList() },
});
client.leave(roomId);

// ✅ Prefer this instead
const { room, leave } = client.enterRoom("my-room", {
  initialPresence: { cursor: null },
  initialStorage: { todos: new LiveList() },
});
leave();
```

### Client.leave [@badge=Deprecated]

<Banner title="Deprecated" type="error">
  This is no longer supported. We recommend using [`client.enterRoom`][]
  instead.
</Banner>

Leaves a room.

```ts
// ❌ This API was recommended before 1.5
client.leave("my-room");

// ✅ Prefer this instead
const { room, leave } = client.enterRoom("my-room" /* options */);
leave();
```

[`atob`]: https://developer.mozilla.org/en-US/docs/Web/API/atob
[`base-64`]: https://www.npmjs.com/package/base-64
[`client.enterRoom`]: /docs/api-reference/liveblocks-client#Client.enterRoom
[`client.getroom`]: /docs/api-reference/liveblocks-client#Client.getRoom
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[`fetch`]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`lostconnectiontimeout`]:
  /docs/api-reference/liveblocks-client#createClientLostConnectionTimeout
[`toimmutable`]: /docs/api-reference/liveblocks-client#LiveObject.toImmutable
[`node-fetch`]: https://npmjs.com/package/node-fetch
[`room.broadcastevent`]:
  /docs/api-reference/liveblocks-client#Room.broadcastEvent
[`room.getstorage`]: /docs/api-reference/liveblocks-client#Room.getStorage
[`room.reconnect`]: /docs/api-reference/liveblocks-client#Room.reconnect
[`room.getSelf`]: /docs/api-reference/liveblocks-client#Room.getSelf
[`room.getOthers`]: /docs/api-reference/liveblocks-client#Room.getOthers
[`room.getStorage`]: /docs/api-reference/liveblocks-client#Room.getStorage
[`room.history`]: /docs/api-reference/liveblocks-client#Room.history
[`room.subscribe("event")`]:
  /docs/api-reference/liveblocks-client#Room.subscribe.event
[`room.subscribe("status")`]:
  /docs/api-reference/liveblocks-client#Room.subscribe.status
[`room.subscribe("lost-connection")`]:
  /docs/api-reference/liveblocks-client#Room.subscribe.lost-connection
[`room.subscribe("storage-status")`]:
  /docs/api-reference/liveblocks-client#Room.subscribe.storage-status
[`room.updatepresence`]:
  /docs/api-reference/liveblocks-client#Room.updatePresence
[`websocket`]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
[`ws`]: https://www.npmjs.com/package/ws
[connection status example]:
  https://liveblocks.io/examples/connection-status/nextjs

---
meta:
  title: "@liveblocks/emails"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/emails package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/emails` provides a set of functions that simplifies sending styled
emails with [Notifications](/docs/ready-made-features/notifications) and
[webhooks](/docs/platform/webhooks). This library is only intended for use in
your Node.js back end.

## Requirements

`@liveblocks/emails` requires the
[`@liveblocks/node`](/docs/api-reference/liveblocks-node) package to be
installed and for [`react`](https://react.dev/) to be a peer dependency in your
project.

## Setup

This package exposes functions that enable easy creation of styled emails with
React and HTML. Each method is designed to be used with our
[webhooks](/docs/platform/webhooks) which means you must
[set them up](/docs/guides/how-to-test-webhooks-on-localhost) first. Webhooks
require an API endpoint in your application, and this is typically what they
will look like.

```tsx title="Next.js route handler for webhooks"
import { isThreadNotificationEvent, WebhookHandler } from "@liveblocks/node";
import { Liveblocks } from "@liveblocks/node";
// +++
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";
// +++

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const webhookHandler = new WebhookHandler(
  process.env.LIVEBLOCKS_WEBHOOK_SECRET_KEY as string
);

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

  // +++
  // Using `@liveblocks/emails` to create an email
  if (isThreadNotificationEvent(event)) {
    const emailData = await prepareThreadNotificationEmailAsReact(
      liveblocks,
      event
    );

    if (emailData.type === "unreadMention") {
      const email = (
        <div>
          <div>
            @{emailData.comment.author.id} at {emailData.comment.createdAt}
          </div>
          <div>{emailData.comment.reactBody}</div>
        </div>
      );

      // Send unread mention email
      // ...
    }
  }
  // +++

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

**We’ll only show the highlighted part below**, as it’s assumed you’ve set this
already, and your file contains `liveblocks` and `event`.

### End-to-end guides

We have two guides that take you through every step of setting up your email
notifications, including setting up webhooks:

- [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).

### Ready-made email templates

We have a number of examples that show you how to set up emails with your
Comments or Text Editor application. Each [Resend](https://resend.com) example
has full ready-made email templates inside, which are a great starting point for
your application.

- [Comments + Resend](/examples/comments-emails/nextjs-comments-emails-resend).
- [Comments + SendGrid](/examples/comments-emails/nextjs-comments-emails-sendgrid).
- [Text Editor/Tiptap + Resend](/examples/collaborative-text-editor-emails/nextjs-tiptap-emails-resend).
- [Text Editor/Lexical + Resend](/examples/collaborative-text-editor-emails/nextjs-lexical-emails-resend).

## Thread notification emails [#thread-notification-emails]

These functions help you create emails to notify users of _unread comments_ in
threads. They fetch each relevant comment, filtering out any that have already
been read, and help you style each comment’s body with either
[React](#prepare-thread-notification-email-as-react) or
[HTML](#prepare-thread-notification-email-as-html).

<Figure>
  <Image
    src="/assets/emails/new-comments-email.png"
    alt="An email showing 7 new comments, with comment bodies and links to each comment"
    width={1567}
    height={830}
  />
</Figure>

<Banner>

This screenshot shows a ready-made template from our
[Comments + Resend](/examples/comments-emails/nextjs-comments-emails-resend)
example.

</Banner>

These functions also help you distinguish between _unread mentions_ and _unread
replies_.

A thread has _unread replies_ if a comment was created after the `readAt` date
on the notification, and created before or at the same time as the `notifiedAt`
date. All unread replies are returned in an array.

```js
{
  type: "unreadReplies",
  roomId: "my-room-id",
  comments: [
    {/* Comment data */},
    // ...
  ],
}
```

A thread has an _unread mention_ if it has unread replies, and one of the
replies mentions the user. A single comment with the latest mention is returned.

```js
{
  type: "unreadMention",
  roomId: "my-room-id",
  comment: {/* Comment data */},
}
```

### Limitations

Before you get started, there are some limitations with thread notifications
that you should be aware of.

#### Duplicated emails for unread mentions

If a user is mentioned (e.g `@username`) in a thread, all further notifications
received for this thread will be `unreadMention` types, _until the user reads
the thread again_. This means that you will receive duplicated `unreadMention`
notifications, even if a notification should be an `unreadReplies` type. After
the thread has been read by the user, `unreadReplies` will be sent for the
thread again if the user isn’t mentioned another time in the thread.

This is due to the architecture of our notifications database, and we’re
investigating solutions to move past this limitation.

### prepareThreadNotificationEmailAsReact [#prepare-thread-notification-email-as-react]

Takes a
[thread notification webhook event](/docs/platform/webhooks#Thread-notification)
and returns unread comment body(s) related to the notification, as React nodes.
It can return one of three formats, an `unreadMention` type containing one
comment, an `unreadReplies` type returning multiple comments, or `null` if there
are no unread mentions/replies. You can also
[resolve user & room data](#prepare-thread-notification-email-as-react-resolving-data)
and
[customize the components](#prepare-thread-notification-email-as-react-customizing-components).

```tsx
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";
import { isThreadNotificationEvent } from "@liveblocks/node";

// Get `liveblocks` and `event` (see "Setup" section)
// ...

if (isThreadNotificationEvent(event)) {
  // +++
  const emailData = await prepareThreadNotificationEmailAsReact(
    liveblocks,
    event
  );
  // +++
  let email;

  switch (emailData.type) {
    case "unreadMention": {
      email = (
        <div>
          <div>
            @{emailData.comment.author.id} at {emailData.comment.createdAt}
          </div>
          <div>{emailData.comment.reactBody}</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.reactBody}</div>
            </div>
          ))}
        </div>
      );
      break;
    }
  }
}

// Send your email
// ...
```

It’s designed to be used in a webhook event, which requires a
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client and a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler). Check
for the correct webhook event using
[`isThreadNotificationEvent`](/docs/api-reference/liveblocks-node#isThreadNotificationEvent)
before running the function, such as in this Next.js route handler.

```tsx title="Full Next.js route handler example" isCollapsed isCollapsable
import { isThreadNotificationEvent, WebhookHandler } from "@liveblocks/node";
import { Liveblocks } from "@liveblocks/node";
// +++
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";
// +++

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const webhookHandler = new WebhookHandler(
  process.env.LIVEBLOCKS_WEBHOOK_SECRET_KEY as string
);

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

  // +++
  if (isThreadNotificationEvent(event)) {
    const emailData = await prepareThreadNotificationEmailAsReact(
      liveblocks,
      event
    );
    let email;

    switch (emailData.type) {
      case "unreadMention": {
        email = (
          <div>
            <div>
              @{emailData.comment.author.id} at {emailData.comment.createdAt}
            </div>
            <div>{emailData.comment.reactBody}</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.reactBody}</div>
              </div>
            ))}
          </div>
        );
        break;
      }
    }

    // Send your email
    // ...
  }
  // +++

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

<PropertiesList title="Returns">
  <PropertiesListItem
    name="value"
    type="ThreadNotificationEmailDataAsReact | null"
  >
    Returns comment information, and a formatted React body, ready for use in emails. Returns `null` if there are no unread mentions or replies. The result has two formats depending on whether this notification is for a *single unread mention*, or for *multiple unread replies*:

    ```js title="Unread mention" isCollapsable isCollapsed
    {
      type: "unreadMention",
      roomId: "my-room-id",

      // An unread mention has just one comment
      comment: {
        id: "cm_asfs8f...",
        threadId: "th_sj30as..."
        createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,

        // The formatted comment, pass it to React `children`
        reactBody: { /* ... */ },

        author: {
          id: "aurélien@example.com",
          info: { /* Custom user info you have resolved */ },
        },
      },
    }
    ```

    <div className="-mt-2">

    ```js title="Unread replies" isCollapsable isCollapsed
    {
      type: "unreadReplies",
      roomId: "my-room-id",

      // Unread replies means multiple comments
      comments: [
        {
          id: "cm_asfs8f...",
          threadId: "th_sj30as..."
          createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,

          // The formatted comment, pass it to React `children`
          reactBody: { /* ... */ },

          author: {
            id: "aurélien@example.com",
            info: { /* Custom user info you have resolved */ },
          },
        },

        // More comments
        //...
      ],
    }
    ```

    </div>

  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="client" type="Liveblocks" required>
    A [`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client)
    Node.js client.
  </PropertiesListItem>
  <PropertiesListItem name="event" type="ThreadNotificationEvent" required>
    An object passed from a webhook event, specifically the
    [`ThreadNotificationEvent`](/docs/platform/webhooks#Thread-notification).
    [Learn more about setting this up](#Setup).
  </PropertiesListItem>
  <PropertiesListItem name="options" type="object">
    A number of options to customize the format of the comments, adding user
    info, room info, and styles.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. Works similarly
    to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers).
    [Learn more](#prepare-thread-notification-email-as-react-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveRoomInfo"
    detailedType="async? (args: ResolveRoomInfoArgs) => RoomInfo | undefined"
  >
    A function that resolves room information. Return a `RoomInfo` object, as
    matching your types. Works similarly to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo)
    but for one room. [Learn
    more](#prepare-thread-notification-email-as-react-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem name="options.components" type="object">
    Pass different React components to customize the elements in the comment
    bodies. Five components can be passed to the object: `Container`,
    `Paragraph`, `Text`, `Link`, `Mention`. [Learn
    more](#prepare-thread-notification-email-as-react-customizing-components).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Container"
    type="({ children: ReactNode }) => ReactNode"
  >
    The comment body container.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Paragraph"
    type="({ children: ReactNode }) => ReactNode"
  >
    The paragraph block.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Text"
    type="({ children: ReactNode }) => ReactNode"
  >
    The text element.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Link"
    detailedType="({ element: CommentBodyLink, href: string }) => ReactNode"
  >
    The link element.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Mention"
    detailedType={`({ element: CommentBodyMention, user?: UserInfo["info"]" }) => ReactNode`}
  >
    The mention element.
  </PropertiesListItem>
</PropertiesList>

#### Resolving data [#prepare-thread-notification-email-as-react-resolving-data]

Similarly to on the client, you can resolve
[users](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) 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.

```tsx
const emailData = await prepareThreadNotificationEmailAsReact(
  liveblocks,
  webhookEvent,
  {
    // +++
    resolveUsers: async ({ userIds }) => {
      const usersData = await __getUsersFromDB__(userIds);

      return usersData.map((userData) => ({
        name: userData.name, // "Nimesh"
        avatar: userData.avatar.src, // "https://..."
      }));
    },
    resolveRoomInfo({ roomId }) {
      return {
        name: roomId, // "my-room-name"
        url: `https://example.com/${roomId}`,
      };
    },
    // +++
  }
);

// { type: "unreadMention", comment: { ... }, ... }
console.log(emailData);

// { name: "Nimesh", avatar: "https://..." }
console.log(emailData.comment.author.info);

// { name: "my-room-name", url: "https://example.com/my-room-name" }
console.log(emailData.roomInfo);
```

#### Customizing components [#prepare-thread-notification-email-as-react-customizing-components]

Each React component in the comment body can be replaced with a custom React
component, if you wish to apply different styles. Five components are available:
`Container`, `Paragraph`, `Text`, `Link`, `Mention`.

```tsx
const emailData = await prepareThreadNotificationEmailAsReact(
  liveblocks,
  webhookEvent,
  {
    // +++
    components: {
      Paragraph: ({ children }) => <p>{children}</p>,

      // `react-email` components are supported
      Text: ({ children }) => (
        <Text className="text-sm text-black m-0 mb-4">{children}</Text>
      ),

      // `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}>{element?.text ?? href}</a>,
    },
    // +++
  }
);

// { type: "unreadMention", comment: { ... }, ... }
console.log(emailData);

// The components are now used in this React body
console.log(emailData.comment.reactBody);
```

### prepareThreadNotificationEmailAsHtml [#prepare-thread-notification-email-as-html]

Takes a
[thread notification webhook event](/docs/platform/webhooks#Thread-notification)
and returns unread comment body(s) related to the notification, as an HTML-safe
string. It can return one of three formats, an `unreadMention` type containing
one comment, an `unreadReplies` type returning multiple comments, or `null` if
there are no unread mentions/replies. You can also
[resolve user & room data](#prepare-thread-notification-email-as-html-resolving-data)
and
[customize the styles](#prepare-thread-notification-email-as-html-styling-elements).

```ts
import { prepareThreadNotificationEmailAsHtml } from "@liveblocks/emails";
import { isThreadNotificationEvent } from "@liveblocks/node";

// Get `liveblocks` and `event` (see "Setup" section)
// ...

if (isThreadNotificationEvent(event)) {
  // +++
  const emailData = await prepareThreadNotificationEmailAsHtml(
    liveblocks,
    event
  );
  // +++
  let email;

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

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

// Send your email
// ...
```

It’s designed to be used in a webhook event, which requires a
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client, a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler). Check
for the correct webhook event using
[`isThreadNotificationEvent`](/docs/api-reference/liveblocks-node#isThreadNotificationEvent)
before running the function, such as in this Next.js route handler.

```tsx title="Full Next.js route handler example" isCollapsed isCollapsable
import { isThreadNotificationEvent, WebhookHandler } from "@liveblocks/node";
import { Liveblocks } from "@liveblocks/node";
// +++
import { prepareThreadNotificationEmailAsHtml } from "@liveblocks/emails";
// +++

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const webhookHandler = new WebhookHandler(
  process.env.LIVEBLOCKS_WEBHOOK_SECRET_KEY as string
);

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

  // +++
  if (isThreadNotificationEvent(event)) {
    const emailData = await prepareThreadNotificationEmailAsHtml(
      liveblocks,
      event
    );
    let email;

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

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

    // Send your email
    // ...
  }
  // +++

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

<PropertiesList title="Returns">
  <PropertiesListItem
    name="value"
    type="ThreadNotificationEmailDataAsHtml | null"
  >
    Returns comment information, and a formatted HTML body, ready for use in emails. Returns `null` if there are no unread mentions or comments. The result has two formats depending on whether this notification is for a *single unread mention*, or for *multiple unread replies*:

    ```js title="Unread mention" isCollapsable isCollapsed
    {
      type: "unreadMention",
      roomId: "my-room-id",

      // An unread mention has just one comment
      comment: {
        id: "cm_asfs8f...",
        threadId: "th_sj30as..."
        createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,

        // The formatted comment, as an HTML string
        htmlBody: "<div>...</div>",

        author: {
          id: "aurélien@example.com",
          info: { /* Custom user info you have resolved */ },
        },
      },
    }
    ```

    <div className="-mt-2">

      ```js title="Unread replies" isCollapsable isCollapsed
      {
        type: "unreadReplies",
        roomId: "my-room-id",

        // Unread replies means multiple comments
        comments: [
          {
            id: "cm_asfs8f...",
            threadId: "th_sj30as..."
            createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,

            // The formatted comment, as an HTML string
            htmlBody: "<div>...</div>",

            author: {
              id: "aurélien@example.com",
              info: { /* Custom user info you have resolved */ },
            },
          },

        // More comments
        //...
        ],
      }
      ```

    </div>

  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="client" type="Liveblocks" required>
    A [`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client)
    Node.js client.
  </PropertiesListItem>
  <PropertiesListItem name="event" type="ThreadNotificationEvent" required>
    An object passed from a webhook event, specifically the
    [`ThreadNotificationEvent`](/docs/platform/webhooks#Thread-notification).
    [Learn more about setting this up](#Setup).
  </PropertiesListItem>
  <PropertiesListItem name="options" type="object">
    A number of options to customize the format of the comments, adding user
    info, room info, and styles.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. Works similarly
    to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers).
    [Learn more](#prepare-thread-notification-email-as-html-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveRoomInfo"
    detailedType="async? (args: ResolveRoomInfoArgs) => RoomInfo | undefined"
  >
    A function that resolves room information. Return a `RoomInfo` object, as
    matching your types. Works similarly to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo)
    but for one room. [Learn
    more](#prepare-thread-notification-email-as-html-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem name="options.styles" type="object">
    Pass CSS properties to style the different HTML elements in the comment
    bodies. Five elements can be styled: `paragraph`, `code`, `strong`, `link`,
    `mention`. [Learn
    more](#prepare-thread-notification-email-as-html-styling-elements).
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.container" type="CSSProperties">
    Inline styles to apply to the comment body container.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.paragraph" type="CSSProperties">
    Inline styles to apply to the paragraph block.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.code" type="CSSProperties">
    Inline styles to apply to the code element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.strong" type="CSSProperties">
    Inline styles to apply to the strong element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.mention" type="CSSProperties">
    Inline styles to apply to the mention element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.link" type="CSSProperties">
    Inline styles to apply to the link element.
  </PropertiesListItem>
</PropertiesList>

#### Resolving data [#prepare-thread-notification-email-as-html-resolving-data]

Similarly to on the client, you can resolve
[users](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) 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.

```tsx
const emailData = await prepareThreadNotificationEmailAsHtml(
  liveblocks,
  webhookEvent,
  {
    // +++
    resolveUsers: async ({ userIds }) => {
      const usersData = await __getUsersFromDB__(userIds);

      return usersData.map((userData) => ({
        name: userData.name, // "Nimesh"
        avatar: userData.avatar.src, // "https://..."
      }));
    },
    resolveRoomInfo({ roomId }) {
      return {
        name: roomId, // "my-room-name"
        url: `https://example.com/${roomId}`,
      };
    },
    // +++
  }
);

// { type: "unreadMention", comment: { ... }, ... }
console.log(emailData);

// { name: "Nimesh", avatar: "https://..." }
console.log(emailData.comment.author.info);

// { name: "my-room-name", url: "https://example.com/my-room-name" }
console.log(emailData.roomInfo);
```

#### Styling elements [#prepare-thread-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`, `link`.

```tsx
const emailData = await prepareThreadNotificationEmailAsHtml(
  liveblocks,
  webhookEvent,
  {
    // +++
    styles: {
      paragraph: { margin: "12px 0" },

      mention: {
        fontWeight: "bold",
        color: "red",
      },

      link: {
        textDecoration: "underline",
      },
    },
    // +++
  }
);

// { type: "unreadMention", comment: { ... }, ... }
console.log(emailData);

// The elements in the comment body are now styled
console.log(emailData.comment.htmlBody);
```

## Text Mention notification emails [#text-mention-notification-emails]

These functions help you create emails to notify users when they have an _unread
mention_ in a [Text Editor](/docs/ready-made-features/text-editor) document. In
this case, a mention is not related to comments, but is instead an inline
mention inside the text editor itself. If the mention has not been read, the
functions fetch a text mention and its surrounding text, giving you more
context, and helping you style the mention content with either
[React](#prepare-text-mention-notification-email-as-react) or
[HTML](#prepare-text-mention-notification-email-as-html).

<Figure>
  <Image
    src="/assets/emails/new-text-mention-email.png"
    alt="An email showing a text mention in a text editor document"
    width={1126}
    height={470}
  />
</Figure>

<Banner>

This screenshot shows a ready-made template from our
[Text Editor + Resend](/examples/collaborative-text-editor-emails/nextjs-tiptap-emails-resend)
examples.

</Banner>

The functions helps to determine if the mention still exists in the document and
will indicate that there’s no email to send in this case. Currently, only
mentions in paragraph blocks create notifications, as there are limitations
around retrieving mentions in plugins.

### Limitations

Before you get started, there are some limitations with text mentions that you
should be aware of.

#### Mentions in plugins

If a user is mentioned in a plugin or extension, a text mention notification is
not sent. This is because Liveblocks doesn’t know the exact schema of your
editor and all its plugins, and we can’t extract the data correctly. This means
that _only mentions in paragraph blocks are sent_, and mentions in lists,
checkboxes, etc., are not, as they are all powered by plugins. We’re
investigating solutions for this, and we’d like to
[hear from you](/contact/support) if you have any thoughts.

#### Multiple Tiptap editors

Tiptap optionally allows you to
[render multiple editors per page](/docs/ready-made-features/text-editor/tiptap#Multiple-editors),
instead of just one. For now, these functions only support one editor per room,
but we’ll be looking to add support for more later.

### prepareTextMentionNotificationEmailAsReact [#prepare-text-mention-notification-email-as-react]

Takes a
[text mention notification webhook event](/docs/platform/webhooks#TextMention-notification)
and returns an unread text mention with its surrounding text as React nodes. It
can also return `null` if the text mention does not exist anymore or has been
already been read. You can also
[resolve user & room data](#prepare-text-mention-notification-email-as-react-resolving-data)
and
[customize the components](#prepare-text-mention-notification-email-as-react-customizing-components).

```tsx
import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails";
import { isTextMentionNotificationEvent } from "@liveblocks/node";

// Get `liveblocks` and `event` (see "Setup" section)
// ...

if (isTextMentionNotificationEvent(event)) {
  // +++
  const emailData = await prepareTextMentionNotificationEmailAsReact(
    liveblocks,
    event
  );
  // +++

  const email = (
    <div>
      <div>
        @{emailData.mention.author.id} at {emailData.mention.createdAt}
      </div>
      <div>{emailData.mention.reactContent}</div>
    </div>
  );
}

// Send your email
// ...
```

It’s designed to be used in a webhook event, which requires a
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client and a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler). Check
for the correct webhook event using
[`isTextMentionNotificationEvent`](/docs/api-reference/liveblocks-node#isTextMentionNotificationEvent)
before running the function, such as in this Next.js route handler.

```tsx title="Full Next.js route handler example" isCollapsed isCollapsable
import {
  isTextMentionNotificationEvent,
  WebhookHandler,
} from "@liveblocks/node";
import { Liveblocks } from "@liveblocks/node";
// +++
import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails";
// +++

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const webhookHandler = new WebhookHandler(
  process.env.LIVEBLOCKS_WEBHOOK_SECRET_KEY as string
);

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

  // +++
  if (isTextMentionNotificationEvent(event)) {
    const emailData = await prepareTextMentionNotificationEmailAsReact(
      liveblocks,
      event
    );

    const email = (
      <div>
        <div>
          @{emailData.mention.author.id} at {emailData.mention.createdAt}
        </div>
        <div>{emailData.mention.reactContent}</div>
      </div>
    );

    // Send your email
    // ...
  }
  // +++

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

<PropertiesList title="Returns">
  <PropertiesListItem
    name="value"
    type="TextMentionNotificationEmailDataAsReact | null"
  >
    Returns text mention information, and a formatted React content ready for
    use in emails. Returns `null` if the text mention does not exist anymore or
    has been already been read.

    ```js title="Unread text mention"
    {
      roomInfo: {
        name: "my room name"
        url: "https://my-room-url.io"
      },
      mention: {
        id: "in_oiujhdg...",
        roomId: "my-room-id",
        createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
        userId: "user_0"

        // The formatted content, pass it to React `children`
        reactContent: { /* ... */}

        author: {
          id: "vincent@example.com",
          info: { /* Custom user info you have resolved */ }
        }
      },
    }
    ```

  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="client" type="Liveblocks" required>
    A [`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client)
    Node.js client.
  </PropertiesListItem>
  <PropertiesListItem name="event" type="TextMentionNotificationEvent" required>
    An object passed from a webhook event, specifically the
    [`TextMentionNotificationEvent`](/docs/platform/webhooks#TextMention-notification).
    [Learn more about setting this up](#Setup).
  </PropertiesListItem>
  <PropertiesListItem name="options" type="object">
    A number of options to customize the format of the content, adding user
    info, room info, and styles.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. Works similarly
    to the [resolver on the
    client](/docs/ready-made-features/text-editor/lexical#Users-and-mentions).
    [Learn
    more](#prepare-text-mention-notification-email-as-react-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveRoomInfo"
    detailedType="async? (args: ResolveRoomInfoArgs) => RoomInfo | undefined"
  >
    A function that resolves room information. Return a `RoomInfo` object, as
    matching your types. Works similarly to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo)
    but for one room. [Learn
    more](#prepare-text-mention-notification-email-as-react-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem name="options.components" type="object">
    Pass different React components to customize the elements in the mention
    content. Three components can be passed to the object: `Container`, `Text`,
    and `Mention`. [Learn
    more](#prepare-text-mention-notification-email-as-react-customizing-components).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Container"
    type="({ children: ReactNode }) => ReactNode"
  >
    The mention and its surrounding text container
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Text"
    type="({ children: ReactNode }) => ReactNode"
  >
    The text element.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.components.Mention"
    detailedType={`({ element: LiveblocksTextEditorMentionNode, user?: UserInfo["info"]" }) => ReactNode`}
  >
    The mention element.
  </PropertiesListItem>
</PropertiesList>

#### Resolving data [#prepare-text-mention-notification-email-as-react-resolving-data]

Similarly to on the client, you can resolve
[users](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers) 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.

```tsx
const emailData = await prepareTextMentionNotificationEmailAsReact(
  liveblocks,
  webhookEvent,
  {
    // +++
    resolveUsers: async ({ userIds }) => {
      const usersData = await __getUsersFromDB__(userIds);

      return usersData.map((userData) => ({
        name: userData.name, // "Nimesh"
        avatar: userData.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);
```

#### Customizing components [#prepare-text-mention-notification-email-as-react-customizing-components]

Each React component in the mention context can be replaced with a custom React
component, if you wish to apply different styles. Three components are
available: `Container`, `Text`, and `Mention`.

```tsx
const emailData = await prepareThreadNotificationEmailAsReact(
  liveblocks,
  webhookEvent,
  {
    // +++
    components: {
      // `react-email` components are supported
      Container: ({ children }) => <Section>{children}</Section>,

      Text: ({ children }) => (
        <Text className="text-sm text-black m-0 mb-4">{children}</Text>
      ),

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

// { mention: { ... }, ... }
console.log(emailData);

// The components are now used in this React content
console.log(emailData.mention.reactContent);
``;
```

### prepareTextMentionNotificationEmailAsHtml [#prepare-text-mention-notification-email-as-html]

Takes a
[text mention notification webhook event](/docs/platform/webhooks#TextMention-notification)
and returns an unread text mention with its surrounding text as an HTML string.
It can also return `null` if the text mention does not exist anymore or has been
already been read. You can also
[resolve user & room data](#prepare-text-mention-notification-email-as-html-resolving-data)
and
[customize the styles](#prepare-text-mention-notification-email-as-html-styling-elements).

```tsx
import { prepareTextMentionNotificationEmailAsHtml } from "@liveblocks/emails";
import { isTextMentionNotificationEvent } from "@liveblocks/node";

// Get `liveblocks` and `event` (see "Setup" section)
// ...

if (isTextMentionNotificationEvent(event)) {
  // +++
  const emailData = await prepareTextMentionNotificationEmailAsHtml(
    liveblocks,
    event
  );
  // +++

  const email = (
    <div>
      <div>
        @{emailData.mention.author.id} at {emailData.mention.createdAt}
      </div>
      <div>{emailData.mention.htmlContent}</div>
    </div>
  );
}

// Send your email
// ...
```

It’s designed to be used in a webhook event, which requires a
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client and a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler). Check
for the correct webhook event using
[`isTextMentionNotificationEvent`](/docs/api-reference/liveblocks-node#isTextMentionNotificationEvent)
before running the function, such as in this Next.js route handler.

```tsx title="Full Next.js route handler example" isCollapsed isCollapsable
import {
  isTextMentionNotificationEvent,
  WebhookHandler,
} from "@liveblocks/node";
import { Liveblocks } from "@liveblocks/node";
// +++
import { prepareTextMentionNotificationEmailAsHtml } from "@liveblocks/emails";
// +++

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const webhookHandler = new WebhookHandler(
  process.env.LIVEBLOCKS_WEBHOOK_SECRET_KEY as string
);

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

  // +++
  if (isTextMentionNotificationEvent(event)) {
    const emailData = await prepareTextMentionNotificationEmailAsHtml(
      liveblocks,
      event
    );

    const email = `
    <div>
      <div>
        @${emailData.mention.author.id} at ${emailData.mention.createdAt}
      </div>
      <div>${emailData.mention.htmlContent}</div>
    </div>
    `;

    // Send your email
    // ...
  }
  // +++

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

<PropertiesList title="Returns">
  <PropertiesListItem
    name="value"
    type="TextMentionNotificationEmailDataAsHtml | null"
  >
    Returns text mention information, and formatted HTML content ready for
    use in emails. Returns `null` if the text mention does not exist anymore or
    has already been read.

    ```js title="Unread text mention"
    {
      roomInfo: {
        name: "my room name"
        url: "https://my-room-url.io"
      },
      mention: {
        id: "in_oiujhdg...",
        roomId: "my-room-id",
        createdAt: Date <Fri Dec 15 2023 14:15:22 GMT+0000 (Greenwich Mean Time)>,
        userId: "user_0"

        // The formatted content, as an HTML string
        htmlContent: { /* ... */}

        author: {
          id: "vincent@example.com",
          info: { /* Custom user info you have resolved */ }
        }
      },
    }
    ```

  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="client" type="Liveblocks" required>
    A [`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client)
    Node.js client.
  </PropertiesListItem>
  <PropertiesListItem name="event" type="TextMentionNotificationEvent" required>
    An object passed from a webhook event, specifically the
    [`TextMentionNotificationEvent`](/docs/platform/webhooks#TextMention-notification).
    [Learn more about setting this up](#Setup).
  </PropertiesListItem>
  <PropertiesListItem name="options" type="object">
    A number of options to customize the format of the content, adding user
    info, room info, and styles.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. Works similarly
    to the [resolver on the
    client](/docs/ready-made-features/text-editor/lexical#Users-and-mentions).
    [Learn
    more](#prepare-text-mention-notification-email-as-html-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem
    name="options.resolveRoomInfo"
    detailedType="async? (args: ResolveRoomInfoArgs) => RoomInfo | undefined"
  >
    A function that resolves room information. Return a `RoomInfo` object, as
    matching your types. Works similarly to the [resolver on the
    client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveRoomsInfo)
    but for one room. [Learn
    more](#prepare-text-mention-notification-email-as-html-resolving-data).
  </PropertiesListItem>
  <PropertiesListItem name="options.styles" type="object">
    Pass CSS properties to style the different HTML elements in the mention
    content. Four elements can be styled: `paragraph`, `code`, `strong`,
    `mention`, and, `link`. [Learn
    more](#prepare-text-mention-notification-email-as-html-styling-elements).
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.paragraph" type="CSSProperties">
    Inline styles to apply to the mention container container. It's a `<div />`
    element under the hood.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.code" type="CSSProperties">
    Inline styles to apply to the code element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.strong" type="CSSProperties">
    Inline styles to apply to the strong element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.mention" type="CSSProperties">
    Inline styles to apply to the mention element.
  </PropertiesListItem>
  <PropertiesListItem name="options.styles.link" type="CSSProperties">
    Inline styles to apply to the link element.
  </PropertiesListItem>
</PropertiesList>

#### 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) 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.

```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://..."
      }));
    },
    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.htmlContent);
```

---
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`
    // ...
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="returns" type="T">
    Returns the value you return from the `doc` callback.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="roomId" type="string" required>
    The ID of the room to use.
  </PropertiesListItem>
  <PropertiesListItem name="client" type="Liveblocks" required>
    The [Liveblocks
    client](/docs/api-reference/liveblocks-node#Liveblocks-client) to use.
  </PropertiesListItem>
  <PropertiesListItem
    name="nodes"
    type="Klass<LexicalNode>[] | LexicalNodeReplacement[]"
  >
    Optional. The Lexical nodes used in the document. Will extend the default
    schema which uses Liveblocks mentions and Liveblocks comments.
  </PropertiesListItem>
</PropertiesList>

### 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
      // ...
    });
    // +++
  }
);
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="callback" type="() => void">
    Callback function where you should handle your modifications.
  </PropertiesListItem>
</PropertiesList>

##### 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();
  }
  // +++
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="content" type="string">
    Returns the text retrieved from the document.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
  }
  // +++
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="editorState" type="EditorState">
    Your editor’s Lexical state.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
  }
  // +++
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="headlessEditor" type="LexicalEditor">
    Your headless Lexical editor.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
  }
  // +++
);
```

<PropertiesList title="Returns">
  <PropertiesListItem
    name="docAsJson"
    type="SerializedEditorState<SerializedLexicalNode>"
  >
    A serialized JSON object representation of your document.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
  }
  // +++
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="markdown" type="string">
    Returns the markdown string.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

---
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
    // ...
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="returns" type="T">
    Returns the value you return from the `api` callback.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Options">
  <PropertiesListItem name="roomId" type="string" required>
    The ID of the room to use.
  </PropertiesListItem>
  <PropertiesListItem name="client" type="Liveblocks" required>
    The [Liveblocks
    client](/docs/api-reference/liveblocks-node#Liveblocks-client) to use.
  </PropertiesListItem>
  <PropertiesListItem name="schema" type="Schema">
    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.
  </PropertiesListItem>
  <PropertiesListItem name="field" type="string">
    Optional. The
    [field](/docs/api-reference/liveblocks-react-tiptap#Multiple-editors) to use
    for the document. Defaults to `default`.
  </PropertiesListItem>
</PropertiesList>

### 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");
    });
    // +++
  }
);
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem
    name="callback"
    type="(doc: Node, tr: Transaction) => Transaction"
  >
    `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).
  </PropertiesListItem>
</PropertiesList>

#### 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
      // ...
    });
    // +++
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="content" type="string">
    Returns the text retrieved from the document.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="options.blockSeparator" type="string">
    Optional. The separator to use for blocks, e.g. `<br />
    `. Defaults to `\n\n`.
  </PropertiesListItem>
  <PropertiesListItem name="options.textSerializers" type="string">
    Optional. The serializers to use for text. Defaults to `{}`.
  </PropertiesListItem>
</PropertiesList>

#### 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<string>(
  {
    client,
    roomId: "test-room",
  },
  async (api) => {
    // +++
    await api.setContent(exampleDoc);
    // +++
    return JSON.stringify(api.toJSON());
  }
);
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesList title="Arguments">
  <PropertiesListItem name="content" type="null | object | string" required>
    The content to replace your document.
  </PropertiesListItem>
</PropertiesList>

#### doc.getEditorState

Returns the current ProseMirror state.

```ts
const editorState = await withProsemirrorDocument(
  { roomId: "my-room-id", client: liveblocks },
  async (api) => {
    // +++
    return api.getEditorState();
    // +++
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="editorState" type="EditorState">
    Your editor’s ProseMirror state.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
    // +++
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="editorState" type="string">
    Your editor’s serialized JSON state.
  </PropertiesListItem>
</PropertiesList>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### api.clearContent

Clears the content of the document.

```ts
await withProsemirrorDocument(
  { roomId: "my-room-id", client: liveblocks },
  async (api) => {
    // +++
    return api.clearContent();
    // +++
  }
);
```

<PropertiesListEmpty title="Returns">_Nothing_</PropertiesListEmpty>

<PropertiesListEmpty title="Arguments">_None_</PropertiesListEmpty>

#### 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();
    // +++
  }
);
```

<PropertiesList title="Returns">
  <PropertiesListItem name="markdown" type="string">
    Returns the markdown string.
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="serializer" type="MarkdownSerializer">
    Optional. A markdown serializer to use. By default it uses the
    `defaultMarkdownSerializer` from
    [prosemirror-markdown](https://github.com/prosemirror/prosemirror-markdown).
  </PropertiesListItem>
</PropertiesList>

##### 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 is new in 1.2, and offers access to our REST API.

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

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});
```

### Authorization

To authorize your users with Liveblocks, you have the choice between two
different APIs.

- [`Liveblocks.prepareSession`](#access-tokens) is recommended for most
  applications.
- [`Liveblocks.identifyUser`](#id-tokens) is best if you’re using fine-grained
  permissions with our REST API.

#### Liveblocks.prepareSession [#access-tokens]

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.

<Banner title="What are access tokens?">
  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.
</Banner>

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

To implement your back end, follow these steps:

<Steps>
  <Step>
    <StepTitle>Create a session</StepTitle>

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

      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.

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Decide which permissions to allow this session</StepTitle>
    <StepContent>
      ```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);
      ```

      <Banner title="Be diligent" type="warning">
        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.
      </Banner>
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Authorize the session</StepTitle>
    <StepContent>
      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 });
      ```
    </StepContent>

  </Step>

</Steps>

##### 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 });
}
```

#### Liveblocks.identifyUser [#id-tokens]

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.

<Banner title="What are ID tokens?">
  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.
</Banner>

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

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
  {
    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.

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

### 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, nextPage } = 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 pagination URL used for retrieving the next page of results with the REST API
// "/v2/rooms?startingAfter=L3YyL3Jvb21z..."
console.log(nextPage);
```

A number of options are also available, enabling you to filter for certain
rooms.

```ts
const {
  data: rooms,
  nextCursor,
  nextPage,
} = 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, 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;
}
```

#### 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", ... }
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",
  },
});
```

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", ... }
console.log(room);
```

#### 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", ... }
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.deleteRoom [#delete-rooms-roomId]

Deletes a room. Throws an error if the room isn’t found. 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");
```

#### Liveblocks.updateRoomId [#post-rooms-update-roomId]

Permanently updates a room’s ID. `newRoomId` will replace `roomId`. 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({
  roomId: "my-room-id",
  newRoomId: "new-room-id",
});

// { type: "room", id: "new-room-id", ... }
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.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
[`useBroadcastEvent`](/docs/api-reference/liveblocks-react#useBroadcastEvent)
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);
});
```

### 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<string>;
    };
  }
}

// {
//   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<string>;
    };
  }
}

// {
//   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<string>;
    };
  }
}

// Create the initial conflict-free data
const initialStorage: LiveObject<Liveblocks["Storage"]> = 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<string>;
    };
  }
}

// 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.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.

### Schema validation

#### Liveblocks.createSchema [#post-create-new-schema]

Creates a schema that can be used to enforce a room’s Storage data structure.
The schema consists of a unique name, and a body which specifies the data shape
of the room in Liveblocks
[schema syntax](/docs/platform/schema-validation/syntax). This is a wrapper
around the
[Create Schema API](/docs/api-reference/rest-api-endpoints#post-create-new-schema)
and returns the same response.

```ts
const schemaBody = `
  type Storage {
    names: LiveList<string>
  }
`;

const schema = await liveblocks.createSchema("my-schema-name", schemaBody);

// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }
console.log(schema);
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.getSchema [#get-create-new-schema]

Returns a schema from its ID. A schema’s ID is a combination of its name and
version, for example the ID for version `1` of `my-schema-name` is
`my-schema-name@1`. This is a wrapper around the
[Get Schema API](/docs/api-reference/rest-api-endpoints#get-create-new-schema)
and returns the same response.

```ts
const updatedBody = `
  type Storage {
    names: LiveMap<string, string>
  }
`;

const schema = await liveblocks.getSchema("my-schema-name@1", updatedBody);

// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }
console.log(schema);
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.updateSchema [#put-update-new-schema]

Updates a schema’s body and increments its version. A schema’s body specifies
the data shape of the room in Liveblocks
[schema syntax](/docs/platform/schema-validation/syntax). Find the schema by its
ID, a combination of its name and version, for example the ID for version `1` of
`my-schema-name` is `my-schema-name@1`. This is a wrapper around the
[Update Schema API](/docs/api-reference/rest-api-endpoints#put-update-new-schema)
and returns the same response.

```ts
const schema = await liveblocks.updateSchema("my-schema-name@1");

// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }
console.log(schema);
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.deleteSchema [#delete-a-schema]

Deletes a schema. This is only allowed if the schema is not attached to a room.
Find the schema by its ID, a combination of its name and version, for example
the ID for version `1` of `my-schema-name` is `my-schema-name@1`. This is a
wrapper around the
[Delete Schema API](/docs/api-reference/rest-api-endpoints#delete-a-schema) and
returns no response.

```ts
await liveblocks.deleteSchema("my-schema-name@1");
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.getSchemaByRoomId [#get-new-schema]

Returns the schema attached to a room. Throws an error if the room isn’t found.
This is a wrapper around the
[Get Schema By Room API](/docs/api-reference/rest-api-endpoints#get-new-schema)
and returns the same response.

```ts
const schema = await liveblocks.getSchemaByRoomId("my-room-id");

// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }
console.log(schema);
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.attachSchemaToRoom [#post-attach-schema-to-room]

Attaches a schema to a room, and instantly enables runtime schema validation in
it. Attach the schema by its ID, a combination of its name and version, for
example the ID for version `1` of `my-schema-name` is `my-schema-name@1`. This
is a wrapper around the
[Attach Schema to a Room API](/docs/api-reference/rest-api-endpoints#post-attach-schema-to-room)
and returns the same response.

If the current contents of the room’s Storage do not match the schema, attaching
will fail and the error message will give details on why the schema failed to
attach. It’ll also throw an error if the room isn’t found.

```ts
const schema = await liveblocks.attachSchemaToRoom(
  "my-room-id",
  "my-schema-name@1"
);

// { id: "my-schema-name@1", name: "my-schema-name", version: 1, ... }
console.log(schema);
```

Read the [schema validation](/docs/platform/schema-validation) page to learn
more.

#### Liveblocks.detachSchemaFromRoom [#delete-detach-schema-to-room]

Detaches a schema from a room. This is a wrapper around the
[Detach Schema from a Room API](/docs/api-reference/rest-api-endpoints#post-detach-schema-to-room)
and returns no response.

```ts
await liveblocks.detachSchemaFromRoom("my-room-id");
```

### 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(),

      // 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.getThreadParticipants [#get-rooms-roomId-threads-threadId-participants]

Returns a list of participants found inside a thread. A participant is a user
who has commented or been mentioned in the thread. Throws an error if the room
or thread isn’t found. This is a wrapper around the
[Get Thread Participants API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads-threadId-participants)
and returns the same response.

```ts
const { participantIds } = await liveblocks.getThreadParticipants({
  roomId: "my-room-id",
  threadId: "th_d75sF3...",
});

// ["chris@example.com", "nimesh@example.com", ...]
console.log(participantIds);
```

#### 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.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.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
[Get 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 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",

    // The time the comment was created
    createdAt: new Date(),
  },
});
```

#### 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: {
    body: {
      version: 1,
      content: [
        /* The comment's body text goes here, see below */
      ],
    },
    userId: "alicia@example.com",
    createdAt: new Date(), // Optional
  },
});

// { 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 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,

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

```ts
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: {
      version: 1,
      content: [
        /* The comment's body text goes here, see above */
      ],
    },

    // The ID of the user that edited the comment
    userId: "alicia@example.com",

    // Optional, the time the comment was edited
    editedAt: new Date(),
  },
});

// { type: "comment", threadId: "th_d75sF3...", ... }
console.log(editedComment);
```

#### 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.getRoomNotificationSettings [#get-rooms-roomId-users-userId-notification-settings]

Returns a user’s notification settings for a specific room. This is a wrapper
around the
[Get Room Notification Settings API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-users-userId-notification-settings).

```ts
const notificationSettings = await liveblocks.getRoomNotificationSettings({
  roomId: "my-room-id",
  userId: "steven@example.com",
});

// { threads: "all", ... }
console.log(notificationSettings);
```

#### Liveblocks.updateRoomNotificationSettings [#post-rooms-roomId-users-userId-notification-settings]

Updates a user’s notification settings for a specific room. This is a wrapper
around the
[Update Room Notification Settings API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-users-userId-notification-settings).

```ts
const updatedNotificationSettings =
  await liveblocks.updateRoomNotificationSettings({
    roomId: "my-room-id",
    userId: "steven@example.com",
    data: {
      threads: "replies_and_mentions",
    },
  });

// { threads: "replies_and_mentions", ... }
console.log(updatedNotificationSettings);
```

#### Liveblocks.deleteRoomNotificationSettings [#delete-rooms-roomId-users-userId-notification-settings]

Deletes a user’s notification settings for a specific room. This is a wrapper
around the
[Delete Room Notification Settings API](/docs/api-reference/rest-api-endpoints#delete-rooms-roomId-users-userId-notification-settings).

```ts
await liveblocks.deleteRoomNotificationSettings({
  roomId: "my-room-id",
  userId: "steven@example.com",
});
```

### 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 } = 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 } =
  await liveblocks.getInboxNotifications({
    userId: "steven@example.com",
    query: {
      unread: true,
    },
  });
```

#### 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. 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",
});
```

##### 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
    // ...
  }
}
```

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

#### 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. User notification settings are project-based, which
means that this returns the user’s settings for every room. This a wrapper
around the
[Get User 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. 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 User 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 User Notification Settings API](/docs/api-reference/rest-api-endpoints#delete-users-userId-notification-settings).

```ts
await liveblocks.deleteNotificationSettings({
  userId: "adri@example.com",
});
```

### 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

### getMentionedIdsFromCommentBody [#get-mentioned-ids-from-comment-body]

Returns an array of each user’s ID that has been mentioned in a `CommentBody`
(found under `comment.body`).

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

const mentionedIds = getMentionedIdsFromCommentBody(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, getMentionedIdsFromCommentBody } 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 mentionedIds = getMentionedIdsFromCommentBody(comment.body);

// ["marc@example.com", "vincent@example.com", ...]
console.log(mentionedIds);
```

Here’s an example with a custom `CommentBody`.

```ts
import { CommentBody, getMentionedIdsFromCommentBody } 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 mentionedIds = getMentionedIdsFromCommentBody(commentBody);

// ["chris@example.com"]
console.log(mentionedIds);
```

<Banner title="Also available from @liveblocks/client">

If you’d like to use this on the client side, it's also available from
[`@liveblocks/client`](/docs/api-reference/liveblocks-client#get-mentioned-ids-from-comment-body).

</Banner>

### 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/node";

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 }) => `<p>${children}</p>`,

    // Optional, override the `text` element
    text: ({ element }) =>
      element.bold ? `<strong>${element.text}</strong>` : `${element.text}`,

    // Optional, override the `link` element
    link: ({ element, href }) =>
      `<a href="${href}" target="_blank">${element.url}</a>`,

    // Optional, override the `mention` element. `user` available if `resolveUsers` supplied
    mention: ({ element, user }) =>
      `<a href="${user.profileUrl}">${element.id}</a>`,
  },

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

<Banner title="Also available from @liveblocks/client">

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

</Banner>

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

// "<b>Hello</b> <span data-mention>@Marc</span> from
// <a href="https://liveblocks.io">https://liveblocks.io</a>"
await stringifyCommentBody(comment.body, {
  format: "html",

  resolveUsers() {
    return [{ name: "Marc" }];
  },
});

// "<b>Hello</b> <a href="https://example.com" data-id="marc@example.com">@Marc</a> from
// <a href="https://liveblocks.io">https://liveblocks.io</a>"
await stringifyCommentBody(comment.body, {
  format: "html",

  mention: ({ element, user }) =>
    `<a href="${user.profileUrl}" data-id="${element.id}">${user.name}</a>`,

  resolveUsers() {
    return [{ name: "Marc", profileUrl: "https://example.com" }];
  },
});
```

### WebhookHandler [#WebhookHandler]

<Banner title="Need help implementing webhooks?">

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.

</Banner>

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.

## Deprecated

### authorize [#authorize] [@badge=Deprecated]

<Banner title="Deprecated" type="error">
  This is no longer supported. Adopt
  [`Liveblocks.prepareSession`](#access-tokens) or
  [`Liveblocks.identifyUser`](#id-tokens) APIs instead.
</Banner>

The purpose of `authorize()` was to help you implement your custom
authentication back end. It generates old-style single-room tokens.

Please refer to [our upgrade guide](/docs/platform/upgrading/1.2) if you’re
using the `authorize` function in your back end, and adopt
[`Liveblocks.prepareSession`](#access-tokens) or
[`Liveblocks.identifyUser`](#id-tokens) APIs instead.

[`room.getothers`]: /docs/api-reference/liveblocks-client#Room.getOthers
[Permissions REST API]: /docs/authentication/id-token

---
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"
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin />
</LexicalComposer>
```

{/* 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 (
    <LexicalComposer initialConfig={initialConfig}>
      // +++
      <LiveblocksPlugin>
        <FloatingThreads />
        <FloatingComposer />
        <AnchoredThreads />
      </LiveblocksPlugin>
      // +++
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

<Banner title="Resolved threads">

Annotations associated with resolved threads are hidden by default on the
editor.

</Banner>

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 (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        <FloatingThreads />
        <FloatingComposer />
        <AnchoredThreads />
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

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
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    // +++
    <Toolbar />
    // +++
  </LiveblocksPlugin>
</LexicalComposer>
```

<Figure>
  <Image
    src="/assets/text-editor/toolbar.png"
    alt="Toolbar"
    width={960}
    height={558}
  />
</Figure>

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 (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        // +++
        <Toolbar />
        // +++
        <FloatingComposer style={{ width: "350px" }} />
        <FloatingThreads threads={threads} style={{ width: "350px" }} />
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

#### 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";

<Toolbar
  // +++
  before={<>I'm at the start</>}
  after={
    <Toolbar.Button
      name="Help"
      icon={<Icon.QuestionMark />}
      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 (
    <Toolbar>
      Hello <strong>world</strong>
    </Toolbar>
  );
}
```

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 (
    <Toolbar>
      // +++
      <Toolbar.BlockSelector />
      <Toolbar.SectionInline />
      <Toolbar.Separator />
      <Toolbar.SectionCollaboration />
      // +++
    </Toolbar>
  );
}
```

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 (
    <Toolbar>
      // +++
      <Toolbar.SectionHistory />
      <Toolbar.Separator />
      <Toolbar.Button
        name="Help"
        icon={<Icon.QuestionMark />}
        shortcut="CMD-H"
        onClick={() => console.log("help")}
      />
      <Toolbar.Toggle
        name="Bold"
        icon={<strong>B️</strong>}
        active={isTextFormatActive(editor, "bold")}
        onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
      />
      // +++
    </Toolbar>
  );
}
```

To learn more about the different components, read more below.

#### Props [#Toolbar-props]

<PropertiesList>
  <PropertiesListItem name="editor" type="LexicalEditor" required>
    The Lexical editor.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    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.
  </PropertiesListItem>
  <PropertiesListItem name="before" type="ReactNode">
    The content to display at the start of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
  <PropertiesListItem name="after" type="ReactNode">
    The content to display at the end of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
</PropertiesList>

#### 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";

<Toolbar>
  <Toolbar.Button name="Question" onClick={(e) => console.log("Clicked")} />
</Toolbar>;
```

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"
<Toolbar.Toggle name="Question" onClick={/* ... */} />

// Tooltip says "Question [⌘+Q]"
<Toolbar.Button name="Question" shortcut="CMD+Q" onClick={/* ... */} />

// Custom icon, replaces the name in the button
<Toolbar.Button name="Question" icon={<div>?</div>} onClick={/* ... */} />

// Using a Liveblocks icon, replaces the name in the button
<Toolbar.Button name="Question" icon={<Icon.QuestionMark />} onClick={/* ... */} />

// Passing children visually replaces the `name` and `icon`
<Toolbar.Button name="Question" onClick={/* ... */}>
  ? Ask a question
</Toolbar.Button>

// Props are passed to the inner `button`
<Toolbar.Button
  name="Question"
  style={{ marginLeft: 10 }}
  className="custom-button"
  onMouseOver={() => console.log("Hovered")}
/>
```

##### Props [#ToolbarButton-props]

<PropertiesList>
  <PropertiesListItem name="name" type="string" required>
    The name of this button displayed in its tooltip. Will also be displayed in
    the button if no `icon` or `children` are passed.
  </PropertiesListItem>
  <PropertiesListItem name="icon" type="ReactNode">
    An optional icon displayed in this button.
  </PropertiesListItem>
  <PropertiesListItem name="shortcut" type="string">
    An optional keyboard shortcut displayed in this button’s tooltip. Common
    shortcuts such will be replaced by their symbols, for example `CMD` → `⌘`.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.Toggle

A toggle button for values that can be active or inactive. Best used with text
editor commands. The `name` is displayed in a tooltip. Props will be passed to
the underlying `button` element.

```tsx
import { FORMAT_TEXT_COMMAND } from "lexical";
import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  <Toolbar.Toggle
    name="Highlight"
    active={isTextFormatActive(editor, "bold")}
    onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
  />
</Toolbar>;
```

The snippet above shows how to toggle bold styling. The toggle button can also
be toggled with `useState`.

```tsx
import { Toolbar } from "@liveblocks/react-lexical";
import { useState } from "react";

function CustomToggle() {
  const [active, setActive] = useState(false);

  return (
    <Toolbar.Toggle
      name="Toggle options"
      active={active}
      onClick={() => setActive(!active)}
    />
  );
}
```

`Toolbar.Toggle` 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 "Highlight"
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
/>

// Tooltip says "Highlight [⌘+H]"
<Toolbar.Toggle
  name="Highlight"
  shortcut="CMD+H"
  active={/* ... */}
  onClick={/* ... */}
/>

// Custom icon, replaces the name in the button
<Toolbar.Toggle
  name="Highlight"
  icon={<div>🖊</div>}
  active={/* ... */}
  onClick={/* ... */}
/>

// Using a Liveblocks icon, replaces the name in the button
<Toolbar.Toggle
  name="Highlight"
  icon={<Icon.QuestionMark />}
  active={/* ... */}
  onClick={/* ... */}
/>

// Passing children visually replaces the `name` and `icon`
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
>
  🖊️Highlight
</Toolbar.Toggle>

// Props are passed to the inner `button`
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
  style={{ marginLeft: 10 }}
  className="custom-toggle"
  onMouseOver={() => console.log("Hovered")}
/>
```

##### Props [#ToolbarToggle-props]

<PropertiesList>
  <PropertiesListItem name="name" type="string" required>
    The name of this button displayed in its tooltip. Will also be displayed in
    the button if no `icon` or `children` are passed.
  </PropertiesListItem>
  <PropertiesListItem name="active" type="boolean" required>
    Whether the button is toggled.
  </PropertiesListItem>
  <PropertiesListItem name="icon" type="ReactNode">
    An optional icon displayed in this button.
  </PropertiesListItem>
  <PropertiesListItem name="shortcut" type="string">
    An optional keyboard shortcut displayed in this button’s tooltip. Common
    shortcuts such will be replaced by their symbols, for example `CMD` → `⌘`.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.BlockSelector

Adds a dropdown selector for switching between different block types, such as
_text_, _heading 1_, _blockquote_. Props will be passed to the inner `button`
element. Can also be placed inside [`FloatingToolbar`][].

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  <Toolbar.BlockSelector />
</Toolbar>;
```

##### Use custom item options

If you’d like to change the items shown in the dropdown menu, you can pass a
custom `items` array. Below a code block item
([Lexical extension](https://lexical.dev/docs/api/modules/lexical_code)) is
added after the default options.

```tsx
import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";
import { $setBlocksType } from "@lexical/selection";
import { $isCodeNode } from "@lexical/code";
import { $getSelection } from "lexical";

<Toolbar>
  <Toolbar.BlockSelector
    items={(defaultItems) => [
      ...defaultItems,
      {
        name: "Code block",
        icon: <div>❮ ❯</div>, // Optional
        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),
        setActive: (editor) =>
          $setBlocksType($getSelection(), () => $createCodeNode()),
      },
    ]}
  />
</Toolbar>;
```

##### Customize item styles

By passing a `label` property, you can overwrite the styles of the dropdown
items. The toolbar button will still display the `name`, but in the dropdown,
the `label` will be used instead of the `name` and `icon`. Below, a new item is
added and its `label` is customized.

```tsx
import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";
import { $setBlocksType } from "@lexical/selection";
import { $isCodeNode } from "@lexical/code";
import { $getSelection } from "lexical";

<Toolbar>
  <Toolbar.BlockSelector
    items={(defaultItems) => [
      ...defaultItems,
      {
        name: "Code block",
        // +++
        label: <div className="font-mono">Code</div>, // Optional, overwrites `icon` + `name`
        // +++
        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),
        setActive: (editor) =>
          $setBlocksType($getSelection(), () => $createCodeNode()),
      },
    ]}
  />
</Toolbar>;
```

You can also customize the default items. Below each item is styled to represent
the effect each block applies to the document.

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar.BlockSelector
  items={(defaultItems) =>
    defaultItems.map((item) => {
      let label;

      if (item.name === "Text") {
        label = <span>Regular text</span>;
      }

      if (item.name === "Heading 1") {
        label = (
          <span style={{ fontSize: 18, fontWeight: "bold" }}>Heading 1</span>
        );
      }

      if (item.name === "Heading 2") {
        label = (
          <span style={{ fontSize: 16, fontWeight: "bold" }}>Heading 2</span>
        );
      }

      if (item.name === "Heading 3") {
        label = (
          <span style={{ fontSize: 15, fontWeight: "bold" }}>Heading 3</span>
        );
      }

      if (item.name === "Blockquote") {
        label = (
          <span style={{ borderLeft: "3px solid gray", paddingLeft: 8 }}>
            Blockquote
          </span>
        );
      }

      return {
        ...item,
        label,
        icon: null, // Hide all icons
      };
    })
  }
/>;
```

##### Props [#ToolbarBlockSelector-props]

<PropertiesList>
  <PropertiesListItem
    name="items"
    type="array | function"
    detailedType="ToolbarBlockSelectorItem[] | (defaultItems: ToolbarBlockSelectorItem[]) => ToolbarBlockSelectorItem[]"
  >
    The items displayed in this block selector. When provided as an array, the
    default items are overridden. To avoid this, a function can be provided
    instead and it will receive the default items.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.Separator

Adds a visual, and accessible, separator used to separate sections in the
toolbar. Props will be passed to the inner `div` element. Can also be placed
inside [`FloatingToolbar`][].

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  // +++
  <Toolbar.SectionHistory />
  // +++
</Toolbar>;
```

#### Toolbar.SectionHistory

Adds a section containing _undo_ and _redo_ buttons. Can also be placed inside
[`FloatingToolbar`][].

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  // +++
  <Toolbar.SectionHistory />
  // +++
</Toolbar>;
```

#### Toolbar.SectionInline

Adds a section containing inline formatting actions such as _bold_, _italic_,
_underline_. Can also be placed inside [`FloatingToolbar`][].

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  // +++
  <Toolbar.SectionInline />
  // +++
</Toolbar>;
```

#### Toolbar.SectionCollaboration

Adds a section containing an _add comment_ button. Can also be placed inside
[`FloatingToolbar`][].

```tsx
import { Toolbar } from "@liveblocks/react-lexical";

<Toolbar>
  // +++
  <Toolbar.SectionCollaboration />
  // +++
</Toolbar>;
```

### FloatingToolbar

Displays a floating toolbar near the current Lexical selection, allowing you to
change styles. You can add content
[before or after](#floating-toolbar-extending-the-defaults), or the toolbar’s
options can be [customized](#creating-a-custom-floating-toolbar). A
[static toolbar](#Toolbar) also exists.

```tsx
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    // +++
    <FloatingToolbar />
    // +++
  </LiveblocksPlugin>
</LexicalComposer>
```

<Figure>
  <Image
    src="/assets/text-editor/floating-toolbar.png"
    alt="FloatingToolbar"
    width={960}
    height={558}
  />
</Figure>

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,
  // +++
  FloatingToolbar,
  //+++
} from "@liveblocks/react-lexical";

const initialConfig = liveblocksConfig({
  namespace: "MyEditor",
  theme: {},
  nodes: [],
  onError: (err) => console.error(err),
});

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

  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        // +++
        <FloatingToolbar />
        // +++
        <FloatingComposer style={{ width: "350px" }} />
        <FloatingThreads threads={threads} style={{ width: "350px" }} />
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

#### Changing float position

Using `position` and `offset` you can reposition the toolbar relative to the
current selection. `position` can be set to `"top"` or `"bottom"`, and `offset`
defines the vertical distance in pixels from the selection.

```tsx
<FloatingToolbar
  // +++
  position="bottom" // Position can be `top` or `bottom`
  offset={12} // Distance in px from selection
  // +++
/>
```

#### Extending the defaults [#floating-toolbar-extending-the-default]

You can insert custom 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 { FloatingToolbar } from "@liveblocks/react-lexical";
import { Icon } from "@liveblocks/react-ui";

<FloatingToolbar
  // +++
  before={<>I'm at the start</>}
  after={
    <Toolbar.Button
      name="Help"
      icon={<Icon.QuestionMark />}
      shortcut="CMD-H"
      onClick={() => console.log("help")}
    />
  }
  // +++
/>;
```

For more complex customization, instead read
[creating a custom floating toolbar](#creating-a-custom-floating-toolbar).

#### Creating a custom floating toolbar [#creating-a-custom-floating-toolbar]

By passing elements as children, it’s possible to create a fully custom floating
toolbar.

```tsx highlight="7"
import { FloatingToolbar } from "@liveblocks/react-lexical";

function CustomToolbar() {
  return (
    <FloatingToolbar>
      Hello <strong>world</strong>
    </FloatingToolbar>
  );
}
```

Each part of our default toolbar is available as blocks which can be slotted
together. This is how the default floating toolbar is constructed:

```tsx
import { FloatingToolbar } from "@liveblocks/react-lexical";

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

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, FloatingToolbar } from "@liveblocks/react-lexical";
import { Icon } from "@liveblocks/react-ui";

function CustomToolbar() {
  const [editor] = useLexicalComposerContext();

  return (
    <FloatingToolbar>
      // +++
      <Toolbar.SectionHistory />
      <Toolbar.Separator />
      <Toolbar.Button
        name="Help"
        icon={<Icon.QuestionMark />}
        shortcut="CMD-H"
        onClick={() => console.log("help")}
      />
      <Toolbar.Toggle
        name="Bold"
        icon={<strong>B️</strong>}
        active={isTextFormatActive(editor, "bold")}
        onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
      />
      // +++
    </FloatingToolbar>
  );
}
```

To learn more about the different components, read more under [`Toolbar`][].

#### Props [#FloatingToolbar-props]

<PropertiesList>
  <PropertiesListItem name="editor" type="LexicalEditor" required>
    The Lexical editor.
  </PropertiesListItem>
  <PropertiesListItem name="position" type={`"top" | "bottom"`}>
    The vertical position of the floating toolbar.
  </PropertiesListItem>
  <PropertiesListItem name="offset" type="number">
    The vertical offset of the floating toolbar from the selection.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    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.
  </PropertiesListItem>
  <PropertiesListItem name="before" type="ReactNode">
    The content to display at the start of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
  <PropertiesListItem name="after" type="ReactNode">
    The content to display at the end of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
</PropertiesList>

### FloatingComposer

Displays a [`Composer`][] near the current Lexical selection, allowing you to
create threads.

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

<Figure>
  <Image
    src="/assets/text-editor/floating-composer.jpg"
    alt="FloatingComposer"
    width={960}
    height={558}
  />
</Figure>

Submitting a comment will attach an annotation thread at the current selection.
Should be nested inside [`LiveblocksPlugin`][].

```tsx highlight="8,22"
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,
  FloatingComposer,
} from "@liveblocks/react-lexical";

const initialConfig = liveblocksConfig({
  namespace: "MyEditor",
  theme: {},
  nodes: [],
  onError: (err) => console.error(err),
});

function Editor() {
  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        <FloatingComposer style={{ width: "350px" }} />
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

Display created threads with [`AnchoredThreads`][] or [`FloatingThreads`][].

#### Opening the composer

To open the `FloatingComposer`, you need to dispatch the
`OPEN_FLOATING_COMPOSER_COMMAND`
[Lexical command](https://lexical.dev/docs/concepts/commands).

```tsx highlight="10"
import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
import { OPEN_FLOATING_COMPOSER_COMMAND } from "@liveblocks/react-lexical";

function Toolbar() {
  const [editor] = useLexicalComposerContext();

  return (
    <button
      onClick={() => {
        editor.dispatchCommand(OPEN_FLOATING_COMPOSER_COMMAND, undefined);
      }}
    >
      💬 New comment
    </button>
  );
}
```

#### Props [#FloatingComposer-props]

<PropertiesList>
  <PropertiesListItem name="metadata" type="ThreadMetadata">
    The metadata of the thread to create.
  </PropertiesListItem>
  <PropertiesListItem
    name="onComposerSubmit"
    type="function"
    detailedType="(comment: ComposerSubmitComment, event: FormEvent<HTMLFormElement>) => Promise<void> | void"
  >
    The event handler called when the composer is submitted.
  </PropertiesListItem>
  <PropertiesListItem name="defaultValue" type="CommentBody">
    The composer’s initial value.
  </PropertiesListItem>
  <PropertiesListItem name="collapsed" type="boolean">
    Whether the composer is collapsed. Setting a value will make the composer
    controlled.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCollapsedChange"
    type="function"
    detailedType="(collapsed: boolean) => void"
  >
    The event handler called when the collapsed state of the composer changes.
  </PropertiesListItem>
  <PropertiesListItem name="defaultCollapsed" type="boolean">
    Whether the composer is initially collapsed. Setting a value will make the
    composer uncontrolled.
  </PropertiesListItem>
  <PropertiesListItem name="disabled" type="boolean">
    Whether the composer is disabled.
  </PropertiesListItem>
  <PropertiesListItem name="autoFocus" type="boolean">
    Whether to focus the composer on mount.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & ComposerOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
</PropertiesList>

### FloatingThreads

Displays floating [`Thread`][] components below text highlights in the editor.

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

<Figure>
  <Image
    src="/assets/text-editor/floating-threads.jpg"
    alt="FloatingThreads"
    width={960}
    height={558}
  />
</Figure>

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.

```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,
  // +++
  FloatingThreads,
  // +++
} from "@liveblocks/react-lexical";

const initialConfig = liveblocksConfig({
  namespace: "MyEditor",
  theme: {},
  nodes: [],
  onError: (err) => console.error(err),
});

function Editor() {
  // +++
  const { threads } = useThreads();
  // +++

  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        <FloatingComposer />
        // +++
        <FloatingThreads threads={threads} style={{ width: "350px" }} />
        // +++
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

Should be nested inside [`LiveblocksPlugin`][].

<Banner title="Resolved threads">

The `FloatingThreads` component automatically excludes resolved threads from
display. Any resolved threads passed in the threads list will not be shown.

</Banner>

#### 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-lexical";

function ThreadOverlay() {
  const { threads } = useThreads({ query: { resolved: false } });

  return (
    <>
      <FloatingThreads
        threads={threads}
        className="w-[350px] block md:hidden"
      />
      <AnchoredThreads
        threads={threads}
        className="w-[350px] hidden sm:block"
      />
    </>
  );
}
```

```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-lexical";

function ThreadOverlay() {
  const { threads } = useThreads({ query: { resolved: false } });
  // +++
  const isMobile = useIsMobile();
  // +++

  // +++
  if (isMobile) {
    return <FloatingThreads threads={threads} style={{ width: "350px" }} />;
  }
  // +++

  // +++
  return <AnchoredThreads threads={threads} style={{ width: "350px" }} />;
  //+++
}

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
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    <FloatingComposer />
    // +++
    <ClientSideSuspense fallback={null}>
      <ThreadOverlay />
    </ClientSideSuspense>
    // +++
  </LiveblocksPlugin>
</LexicalComposer>
```

#### 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
<FloatingThreads threads={threads} className="my-floating-thread" />
```

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";

<FloatingThreads
  threads={threads}
  className="my-floating-thread"
  // +++
  components={{
    Thread: (props) => (
      <Thread {...props} className="border shadow" style={{ width: "300px" }} />
    ),
  }}
  // +++
/>;
```

You can return any custom `ReactNode` here, including anything from a simple
wrapper around `Thread`, up to a full custom `Thread` component built using our
[Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment).

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

<FloatingThreads
  threads={threads}
  className="my-floating-thread"
  components={{
    Thread: (props) => (
      // +++
      <div>
        {props.thread.comments.map((comment) => (
          <Comment.Body
            key={comment.id}
            body={comment.body}
            components={/* ... */}
          />
        ))}
      </div>
      // +++
    ),
  }}
/>;
```

#### Props [#FloatingThreads-props]

<PropertiesList>
  <PropertiesListItem name="threads" type="ThreadData[]" required>
    The threads to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="components"
    type="Partial<AnchoredThreadsComponents>"
  >
    Override the component’s components.
  </PropertiesListItem>
  <PropertiesListItem
    name="components.Thread"
    type="(props: ThreadProps) => ReactNode"
  >
    Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread)
    component.
  </PropertiesListItem>
</PropertiesList>

### AnchoredThreads

Displays a list of [`Thread`][] components vertically alongside the editor.

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

<Figure>
  <Image
    src="/assets/text-editor/anchored-threads.jpg"
    alt="AnchoredThreads"
    width={960}
    height={558}
  />
</Figure>

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 { 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,
  // +++
  AnchoredThreads,
  // +++
} from "@liveblocks/react-lexical";

const initialConfig = liveblocksConfig({
  namespace: "MyEditor",
  theme: {},
  nodes: [],
  onError: (err) => console.error(err),
});

function Editor() {
  // +++
  const { threads } = useThreads();
  // +++

  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        <FloatingComposer />
        // +++
        <AnchoredThreads threads={threads} style={{ width: "350px" }} />
        // +++
      </LiveblocksPlugin>
      <RichTextPlugin
        contentEditable={<ContentEditable />}
        placeholder={<div>Enter some text...</div>}
        ErrorBoundary={LexicalErrorBoundary}
      />
    </LexicalComposer>
  );
}
```

Should be nested inside [`LiveblocksPlugin`][].

<Banner title="Resolved threads">

The `AnchoredThreads` component automatically excludes resolved threads from
display. Any resolved threads passed in the threads list will not be shown.

</Banner>

#### 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-lexical";

function ThreadOverlay() {
  const { threads } = useThreads({ query: { resolved: false } });

  return (
    <>
      <FloatingThreads
        threads={threads}
        className="w-[350px] block md:hidden"
      />
      <AnchoredThreads
        threads={threads}
        className="w-[350px] hidden sm:block"
      />
    </>
  );
}
```

```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-lexical";

function ThreadOverlay() {
  const { threads } = useThreads({ query: { resolved: false } });
  // +++
  const isMobile = useIsMobile();
  // +++

  // +++
  if (isMobile) {
    return <FloatingThreads threads={threads} style={{ width: "350px" }} />;
  }
  // +++

  // +++
  return <AnchoredThreads threads={threads} style={{ width: "350px" }} />;
  //+++
}

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
<LexicalComposer initialConfig={initialConfig}>
  <LiveblocksPlugin>
    <FloatingComposer />
    // +++
    <ClientSideSuspense fallback={null}>
      <ThreadOverlay />
    </ClientSideSuspense>
    // +++
  </LiveblocksPlugin>
</LexicalComposer>
```

#### 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
<AnchoredThreads
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
/>
```

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";

<AnchoredThreads
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
  // +++
  components={{
    Thread: (props) => (
      <Thread
        {...props}
        className="border shadow"
        style={{ background: "white" }}
      />
    ),
  }}
  // +++
/>;
```

You can return any custom `ReactNode` here, including anything from a simple
wrapper around `Thread`, up to a full custom `Thread` component built using our
[Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment).

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

<AnchoredThreads
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
  components={{
    Thread: (props) => (
      // +++
      <div>
        {props.thread.comments.map((comment) => (
          <Comment.Body
            key={comment.id}
            body={comment.body}
            components={/* ... */}
          />
        ))}
      </div>
      // +++
    ),
  }}
/>;
```

##### 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-lexical-anchored-threads {
  /* Minimum gap between threads */
  --lb-lexical-anchored-threads-gap: 8px;

  /* How far the active thread is offset to the left */
  --lb-lexical-anchored-threads-active-thread-offset: 12px;
}
```

#### Props [#AnchoredThreads-props]

<PropertiesList>
  <PropertiesListItem name="threads" type="ThreadData[]" required>
    The threads to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="components"
    type="Partial<AnchoredThreadsComponents>"
  >
    Override the component’s components.
  </PropertiesListItem>
  <PropertiesListItem
    name="components.Thread"
    type="(props: ThreadProps) => ReactNode"
  >
    Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread)
    component.
  </PropertiesListItem>
</PropertiesList>

### HistoryVersionPreview

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

The `HistoryVersionPreview` component allows you to display a preview of a
specific version of your Lexical editor's content. It also contains a button and
logic for restoring. It must be used inside the `<LiveblocksPlugin>` context. To
render a list of versions, see
[`VersionHistory`](/docs/api-reference/liveblocks-react-ui#Version-History).

#### Usage

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

function VersionPreview({ selectedVersion, onVersionRestore }) {
  return (
    <HistoryVersionPreview
      version={selectedVersion}
      onVersionRestore={onVersionRestore}
    />
  );
}
```

#### Props

<PropertiesList>
  <PropertiesListItem name="version" type="HistoryVersion" required>
    The version of the editor content to preview.
  </PropertiesListItem>
  <PropertiesListItem
    name="onVersionRestore"
    type="(version: HistoryVersion) => void"
  >
    Callback function called when the user chooses to restore this version.
  </PropertiesListItem>
</PropertiesList>

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

### 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-lexical";

const status = useIsEditorReady();
```

Here’s how it can be used in the context of your editor.

```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,
  // +++
  useIsEditorReady,
  // +++
} from "@liveblocks/react-lexical";

const initialConfig = liveblocksConfig({
  namespace: "MyEditor",
  theme: {},
  nodes: [],
  onError: (err) => console.error(err),
});

function Editor() {
  // +++
  const ready = useIsEditorReady();
  // +++

  return (
    <LexicalComposer initialConfig={initialConfig}>
      <LiveblocksPlugin>
        <FloatingThreads />
        <FloatingComposer />
        <AnchoredThreads />
      </LiveblocksPlugin>
      // +++
      {!ready ? (
        <div>Loading...</div>
      ) : (
        <RichTextPlugin
          contentEditable={<ContentEditable />}
          placeholder={<div>Enter some text...</div>}
          ErrorBoundary={LexicalErrorBoundary}
        />
      )}
      // +++
    </LexicalComposer>
  );
}
```

### useEditorStatus

<Banner title="Deprecated">

Deprecated. Starting with 2.12.0, we recommend using [`useSyncStatus`][] instead
for tracking sync status, because it will reflect sync status of all parts of
Liveblocks, not just Storage.

</Banner>

Returns the current editor status.

```ts
import { useEditorStatus } from "@liveblocks/react-lexical";

const status = useEditorStatus();
```

The possible values are:

- `not-loaded`: Initial editor state when entering the room.
- `loading`: Once the editor state has been requested by `LiveblocksPlugin`.
- `synchronized`: The editor state is sync with Liveblocks servers.

### useIsThreadActive

Accepts a thread id and returns whether the thread annotation for this thread is
selected or not in the Lexical editor. This hook must be used in a component
nested inside [`LiveblocksPlugin`][].

```ts
import { useIsThreadActive } from "@liveblocks/react-lexical";

const isActive = useIsThreadActive(thread.id);
```

<PropertiesList title="Arguments">
  <PropertiesListItem name="threadId" type="strinng" required>
    The ID of the thread.
  </PropertiesListItem>
</PropertiesList>

This hook can be useful to style threads based on whether their associated
thread annotations are selected or not in the editor.

## Utilities

### isTextFormatActive

Checks if a text format (bold, italic, etc.) is active in the current selection.
Takes a Lexical editor, and returns a `boolean`.

```tsx
import { isTextFormatActive } from "@liveblocks/react-lexical";

// "true" | "false"
const isActive = isTextFormatActive(editor, "bold");
```

<PropertiesList title="Arguments">
  <PropertiesListItem name="editor" type="LexicalEditor" required>
    The Lexical editor.
  </PropertiesListItem>
  <PropertiesListItem name="format" type="TextFormatType" required>
    The Lexical text format to check for in the current selection.
  </PropertiesListItem>
</PropertiesList>

#### Creating toggle buttons

The `isTextFormatActive` helper is particularly useful for creating buttons with
[`Toolbar.Toggle`][].

```tsx
import { FORMAT_TEXT_COMMAND } from "lexical";
import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
// +++
import { isTextFormatActive, Toolbar } from "@liveblocks/react-lexical";
// +++

function CustomToggleButton() {
  const [editor] = useLexicalComposerContext();

  return (
    <Toolbar.Toggle
      name="Bold"
      icon={<strong>B️</strong>}
      // +++
      active={isTextFormatActive(editor, "bold")}
      // +++
      onClick={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
    />
  );
}
```

### isBlockNodeActive

Checks if a block node is active in the current selection. If the selection
contains multiple block nodes, it will only return `true` if all of them are of
the same type.

```tsx
import { isBlockNodeActive } from "@liveblocks/react-lexical";
import { $isTextNode } from "lexical";

// Checking if text node is currently active
const isActive = isBlockNodeActive(editor, $isTextNode);
```

<PropertiesList title="Arguments">
  <PropertiesListItem name="editor" type="LexicalEditor" required>
    The Lexical editor.
  </PropertiesListItem>
  <PropertiesListItem
    name="isActive"
    type="(node: LexicalNode) => boolean"
    required
  >
    Function that passes the current node, helping you check if the current
    block node is active. Helpful in combination with `$is___Node` functions.
  </PropertiesListItem>
</PropertiesList>

#### Creating custom block selector items

The `isBlockNodeActive` helper is particularly useful for adding custom
[`Toolbar.BlockSelector`][] items.

```tsx
//+++
import { isBlockNodeActive, Toolbar } from "@liveblocks/react-lexical";
// +++
import { $setBlocksType } from "@lexical/selection";
import { $isCodeNode } from "@lexical/code";
import { $getSelection } from "lexical";

<Toolbar>
  <Toolbar.BlockSelector
    items={(defaultItems) => [
      ...defaultItems,
      {
        name: "Code block",
        icon: <div>❮ ❯</div>,
        // +++
        isActive: (editor) => isBlockNodeActive(editor, $isCodeNode),
        // +++
        setActive: (editor) =>
          $setBlocksType($getSelection(), () => $createCodeNode()),
      },
    ]}
  />
</Toolbar>;
```

## Stylesheets

React Lexical 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-lexical/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).

[`LiveblocksPlugin`]: #LiveblocksPlugin
[`LexicalComposer`]: https://lexical.dev/docs/react/plugins
[`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
[`Toolbar`]: #Toolbar
[`Toolbar.Button`]: #Toolbar.Button
[`Toolbar.Toggle`]: #Toolbar.Toggle
[`Toolbar.BlockSelector`]: #Toolbar.BlockSelector
[`Toolbar.Separator`]: #Toolbar.Separator
[`Toolbar.SectionHistory`]: #Toolbar.SectionHistory
[`Toolbar.SectionInline`]: #Toolbar.SectionInline
[`Toolbar.SectionCollaboration`]: #Toolbar.SectionCollaboration
[`FloatingToolbar`]: #FloatingToolbar
[`FloatingComposer`]: #FloatingComposer
[`FloatingThreads`]: #FloatingThreads
[`AnchoredThreads`]: #AnchoredThreads
[`ClientSideSuspense`]: /docs/api-reference/liveblocks-react#ClientSideSuspense
[`useSyncStatus`]: /docs/api-reference/liveblocks-react#useSyncStatus

---
meta:
  title: "@liveblocks/react-tiptap"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/react-tiptap package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/react-tiptap` provides you with a [React](https://react.dev/)
plugin that adds collaboration to any [Tiptap](https://tiptap.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/tiptap) to
learn more. Use
[`@liveblocks/node-prosemirror`](/docs/api-reference/liveblocks-node-prosemirror)
for server-side editing.

## Setup

To set up your collaborative Tiptap editor, add
[`useLiveblocksExtension`](#useLiveblocksExtension) to your editor, passing the
return value `useEditor` extension array.

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

function TextEditor() {
  // +++
  const liveblocks = useLiveblocksExtension();
  // +++

  const editor = useEditor({
    extensions: [
      // +++
      liveblocks,
      // +++
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
    </div>
  );
}
```

Liveblocks Tiptap components should be passed `editor` to enable them.

```tsx
import {
  useLiveblocksExtension,
  // +++
  FloatingComposer,
  // +++
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
      // +++
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      // +++
    </div>
  );
}
```

Learn more in our [get started guides](/docs/get-started/text-editor/tiptap).

## 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
<Toolbar editor={editor} />
```

<Figure>
  <Image
    src="/assets/text-editor/toolbar.png"
    alt="Toolbar"
    width={960}
    height={558}
  />
</Figure>

Pass your Tiptap `editor` to use the component. By default, one of the toolbar
buttons can create comment threads—to enable this add [`FloatingComposer`][] and
display threads with [`AnchoredThreads`][] or [`FloatingThreads`][].

```tsx
import {
  useLiveblocksExtension,
  // +++
  Toolbar,
  // +++
  FloatingComposer,
  FloatingThreads,
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      // +++
      <Toolbar editor={editor} />
      // +++
      <EditorContent editor={editor} />
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      <FloatingThreads editor={editor} style={{ width: "350px" }} />
    </div>
  );
}
```

#### 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-tiptap";
import { Icon } from "@liveblocks/react-ui";

<Toolbar
  editor={editor}
  // +++
  before={<>I'm at the start</>}
  after={
    <Toolbar.Button
      name="Help"
      icon={<Icon.QuestionMark />}
      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="7"
import { Toolbar } from "@liveblocks/react-lexical";
import { Editor } from "@tiptap/react";

function CustomToolbar({ editor }: { editor: Editor | null }) {
  return (
    <Toolbar editor={editor}>
      Hello <strong>world</strong>
    </Toolbar>
  );
}
```

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-tiptap";
import { Editor } from "@tiptap/react";

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

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`][]. The
highlight toggle button requires a
[Tiptap extension](https://tiptap.dev/docs/editor/extensions/marks/highlight).

```tsx
import { Toolbar } from "@liveblocks/react-tiptap";
import { Icon } from "@liveblocks/react-ui";
import { Editor } from "@tiptap/react";

function CustomToolbar({ editor }: { editor: Editor | null }) {
  return (
    <Toolbar editor={editor}>
      // +++
      <Toolbar.SectionHistory />
      <Toolbar.Separator />
      <Toolbar.Button
        name="Help"
        icon={<Icon.QuestionMark />}
        shortcut="CMD-H"
        onClick={() => console.log("help")}
      />
      <Toolbar.Toggle
        name="Highlight"
        icon={<div>🖊️</div>}
        active={editor?.isActive("highlight") ?? false}
        onClick={() => editor?.chain().focus().toggleHighlight().run()}
        disabled={!editor?.can().chain().focus().toggleHighlight().run()}
      />
      // +++
    </Toolbar>
  );
}
```

To learn more about the different components, read more below.

#### Props [#Toolbar-props]

<PropertiesList>
  <PropertiesListItem name="editor" type="Editor | null" required>
    The Tiptap editor.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    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.
  </PropertiesListItem>
  <PropertiesListItem name="before" type="ReactNode">
    The content to display at the start of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
  <PropertiesListItem name="after" type="ReactNode">
    The content to display at the end of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
</PropertiesList>

#### 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-tiptap";

<Toolbar editor={editor}>
  <Toolbar.Button name="Question" onClick={(e) => console.log("Clicked")} />
</Toolbar>;
```

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-tiptap";
import { Icon } from "@liveblocks/react-ui";

// Button says "Question"
<Toolbar.Toggle name="Question" onClick={/* ... */} />

// Tooltip says "Question [⌘+Q]"
<Toolbar.Button name="Question" shortcut="CMD+Q" onClick={/* ... */} />

// Custom icon, replaces the name in the button
<Toolbar.Button name="Question" icon={<div>?</div>} onClick={/* ... */} />

// Using a Liveblocks icon, replaces the name in the button
<Toolbar.Button name="Question" icon={<Icon.QuestionMark />} onClick={/* ... */} />

// Passing children visually replaces the `name` and `icon`
<Toolbar.Button name="Question" onClick={/* ... */}>
  ? Ask a question
</Toolbar.Button>

// Props are passed to the inner `button`
<Toolbar.Button
  name="Question"
  style={{ marginLeft: 10 }}
  className="custom-button"
  onMouseOver={() => console.log("Hovered")}
/>
```

##### Props [#ToolbarButton-props]

<PropertiesList>
  <PropertiesListItem name="name" type="string" required>
    The name of this button displayed in its tooltip. Will also be displayed in
    the button if no `icon` or `children` are passed.
  </PropertiesListItem>
  <PropertiesListItem name="icon" type="ReactNode">
    An optional icon displayed in this button.
  </PropertiesListItem>
  <PropertiesListItem name="shortcut" type="string">
    An optional keyboard shortcut displayed in this button’s tooltip. Common
    shortcuts such will be replaced by their symbols, for example `CMD` → `⌘`.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.Toggle

A toggle button for values that can be active or inactive. Best used with text
editor commands. The `name` is displayed in a tooltip. Props will be passed to
the underlying `button` element.

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

<Toolbar editor={editor}>
  <Toolbar.Toggle
    name="Highlight"
    active={editor?.isActive("highlight") ?? false}
    onClick={() => editor?.chain().focus().toggleHighlight().run()}
  />
</Toolbar>;
```

The snippet above shows how to use the Toggle with the
[Tiptap highlight extension](https://tiptap.dev/docs/editor/extensions/marks/highlight).
The toggle button can also be toggled with `useState`.

```tsx
import { Toolbar } from "@liveblocks/react-tiptap";
import { Editor } from "@tiptap/react";
import { useState } from "react";

function CustomToggle({ editor }: { editor: Editor | null }) {
  const [active, setActive] = useState(false);

  return (
    <Toolbar.Toggle
      name="Toggle options"
      active={active}
      onClick={() => setActive(!active)}
    />
  );
}
```

`Toolbar.Toggle` 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-tiptap";
import { Icon } from "@liveblocks/react-ui";

// Button says "Highlight"
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
/>

// Tooltip says "Highlight [⌘+H]"
<Toolbar.Toggle
  name="Highlight"
  shortcut="CMD+H"
  active={/* ... */}
  onClick={/* ... */}
/>

// Custom icon, replaces the name in the button
<Toolbar.Toggle
  name="Highlight"
  icon={<div>🖊</div>}
  active={/* ... */}
  onClick={/* ... */}
/>

// Using a Liveblocks icon, replaces the name in the button
<Toolbar.Toggle
  name="Highlight"
  icon={<Icon.QuestionMark />}
  active={/* ... */}
  onClick={/* ... */}
/>

// Passing children visually replaces the `name` and `icon`
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
>
  🖊️Highlight
</Toolbar.Toggle>

// Props are passed to the inner `button`
<Toolbar.Toggle
  name="Highlight"
  active={/* ... */}
  onClick={/* ... */}
  style={{ marginLeft: 10 }}
  className="custom-toggle"
  onMouseOver={() => console.log("Hovered")}
/>
```

##### Props [#ToolbarToggle-props]

<PropertiesList>
  <PropertiesListItem name="name" type="string" required>
    The name of this button displayed in its tooltip. Will also be displayed in
    the button if no `icon` or `children` are passed.
  </PropertiesListItem>
  <PropertiesListItem name="active" type="boolean" required>
    Whether the button is toggled.
  </PropertiesListItem>
  <PropertiesListItem name="icon" type="ReactNode">
    An optional icon displayed in this button.
  </PropertiesListItem>
  <PropertiesListItem name="shortcut" type="string">
    An optional keyboard shortcut displayed in this button’s tooltip. Common
    shortcuts such will be replaced by their symbols, for example `CMD` → `⌘`.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.BlockSelector

Adds a dropdown selector for switching between different block types, such as
_text_, _heading 1_, _blockquote_. Props will be passed to the inner `button`
element. Can also be placed inside [`FloatingToolbar`][].

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

<Toolbar editor={editor}>
  <Toolbar.BlockSelector />
</Toolbar>;
```

##### Use custom item options

If you’d like to change the items shown in the dropdown menu, you can pass a
custom `items` array. Below a code block item
([Tiptap extension](https://tiptap.dev/docs/editor/extensions/nodes/code-block))
is added after the default options.

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

<Toolbar editor={editor}>
  <Toolbar.BlockSelector
    items={(defaultItems) => [
      ...defaultItems,
      {
        name: "Code block",
        icon: <div>❮ ❯</div>, // Optional
        isActive: (editor) => editor.isActive("codeBlock"),
        setActive: (editor) =>
          editor.chain().focus().clearNodes().toggleCodeBlock().run(),
      },
    ]}
  />
</Toolbar>;
```

##### Customize item styles

By passing a `label` property, you can overwrite the styles of the dropdown
items. The toolbar button will still display the `name`, but in the dropdown,
the `label` will be used instead of the `name` and `icon`. Below, a new item is
added and its `label` is customized.

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

<Toolbar editor={editor}>
  <Toolbar.BlockSelector
    items={(defaultItems) => [
      ...defaultItems,
      {
        name: "Code block",
        // +++
        label: <div className="font-mono">Code</div>, // Optional, overwrites `icon` + `name`
        // +++
        isActive: (editor) => editor.isActive("codeBlock"),
        setActive: (editor) =>
          editor.chain().focus().clearNodes().toggleCodeBlock().run(),
      },
    ]}
  />
</Toolbar>;
```

You can also customize the default items. Below each item is styled to represent
the effect each block applies to the document.

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

<Toolbar.BlockSelector
  items={(defaultItems) =>
    defaultItems.map((item) => {
      let label;

      if (item.name === "Text") {
        label = <span>Regular text</span>;
      }

      if (item.name === "Heading 1") {
        label = (
          <span style={{ fontSize: 18, fontWeight: "bold" }}>Heading 1</span>
        );
      }

      if (item.name === "Heading 2") {
        label = (
          <span style={{ fontSize: 16, fontWeight: "bold" }}>Heading 2</span>
        );
      }

      if (item.name === "Heading 3") {
        label = (
          <span style={{ fontSize: 15, fontWeight: "bold" }}>Heading 3</span>
        );
      }

      if (item.name === "Blockquote") {
        label = (
          <span style={{ borderLeft: "3px solid gray", paddingLeft: 8 }}>
            Blockquote
          </span>
        );
      }

      return {
        ...item,
        label,
        icon: null, // Hide all icons
      };
    })
  }
/>;
```

##### Props [#ToolbarBlockSelector-props]

<PropertiesList>
  <PropertiesListItem
    name="items"
    type="array | function"
    detailedType="ToolbarBlockSelectorItem[] | (defaultItems: ToolbarBlockSelectorItem[]) => ToolbarBlockSelectorItem[]"
  >
    The items displayed in this block selector. When provided as an array, the
    default items are overridden. To avoid this, a function can be provided
    instead and it will receive the default items.
  </PropertiesListItem>
</PropertiesList>

#### Toolbar.Separator

Adds a visual, and accessible, separator used to separate sections in the
toolbar. Props will be passed to the inner `div` element. Can also be placed
inside [`FloatingToolbar`][].

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

<Toolbar editor={editor}>
  // +++
  <Toolbar.SectionHistory />
  // +++
</Toolbar>;
```

#### Toolbar.SectionHistory

Adds a section containing _undo_ and _redo_ buttons. Can also be placed inside
[`FloatingToolbar`][].

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

<Toolbar editor={editor}>
  // +++
  <Toolbar.SectionHistory />
  // +++
</Toolbar>;
```

#### Toolbar.SectionInline

Adds a section containing inline formatting actions such as _bold_, _italic_,
_underline_. Can also be placed inside [`FloatingToolbar`][].

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

<Toolbar editor={editor}>
  // +++
  <Toolbar.SectionInline />
  // +++
</Toolbar>;
```

#### Toolbar.SectionCollaboration

Adds a section containing an _add comment_ button. Can also be placed inside
[`FloatingToolbar`][].

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

<Toolbar editor={editor}>
  // +++
  <Toolbar.SectionCollaboration />
  // +++
</Toolbar>;
```

### FloatingToolbar

Displays a floating toolbar near the current Tiptap selection, allowing you to
change styles. You can add content
[before or after](#floating-toolbar-extending-the-defaults), or the toolbar’s
options can be [customized](#creating-a-custom-floating-toolbar). A
[static toolbar](#Toolbar) also exists.

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

<Figure>
  <Image
    src="/assets/text-editor/floating-toolbar.png"
    alt="FloatingToolbar"
    width={960}
    height={558}
  />
</Figure>

Pass your Tiptap `editor` to use the component. By default, one of the toolbar
buttons can create comment threads—to enable this add [`FloatingComposer`][] and
display threads with [`AnchoredThreads`][] or [`FloatingThreads`][].

```tsx
import {
  useLiveblocksExtension,
  // +++
  FloatingToolbar,
  // +++
  FloatingComposer,
  FloatingThreads,
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
      // +++
      <FloatingToolbar editor={editor} />
      // +++
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      <FloatingThreads editor={editor} style={{ width: "350px" }} />
    </div>
  );
}
```

#### Changing float position

Using `position` and `offset` you can reposition the toolbar relative to the
current selection. `position` can be set to `"top"` or `"bottom"`, and `offset`
defines the vertical distance in pixels from the selection.

```tsx
<FloatingToolbar
  editor={editor}
  // +++
  position="bottom" // Position can be `top` or `bottom`
  offset={12} // Distance in px from selection
  // +++
/>
```

#### Extending the defaults [#floating-toolbar-extending-the-default]

You can insert custom 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-tiptap";
import { Icon } from "@liveblocks/react-ui";

<FloatingToolbar
  editor={editor}
  // +++
  before={<>I'm at the start</>}
  after={
    <Toolbar.Button
      name="Help"
      icon={<Icon.QuestionMark />}
      shortcut="CMD-H"
      onClick={() => console.log("help")}
    />
  }
  // +++
/>;
```

For more complex customization, instead read
[creating a custom floating toolbar](#creating-a-custom-floating-toolbar).

#### Creating a custom floating toolbar [#creating-a-custom-floating-toolbar]

By passing elements as children, it’s possible to create a fully custom floating
toolbar.

```tsx highlight="7"
import { FloatingToolbar } from "@liveblocks/react-tiptap";
import { Editor } from "@tiptap/react";

function CustomToolbar({ editor }: { editor: Editor | null }) {
  return (
    <FloatingToolbar editor={editor}>
      Hello <strong>world</strong>
    </FloatingToolbar>
  );
}
```

Each part of our default toolbar is available as blocks which can be slotted
together. This is how the default floating toolbar is constructed:

```tsx
import { FloatingToolbar, Toolbar } from "@liveblocks/react-tiptap";
import { Editor } from "@tiptap/react";

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

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`][]. The
highlight toggle button requires a
[Tiptap extension](https://tiptap.dev/docs/editor/extensions/marks/highlight).

```tsx
import { FloatingToolbar, Toolbar } from "@liveblocks/react-tiptap";
import { Icon } from "@liveblocks/react-ui";
import { Editor } from "@tiptap/react";

function CustomToolbar({ editor }: { editor: Editor | null }) {
  return (
    <FloatingToolbar editor={editor}>
      // +++
      <Toolbar.SectionHistory />
      <Toolbar.Separator />
      <Toolbar.Button
        name="Help"
        icon={<Icon.QuestionMark />}
        shortcut="CMD-H"
        onClick={() => console.log("help")}
      />
      <Toolbar.Toggle
        name="Highlight"
        icon={<div>🖊️</div>}
        active={editor?.isActive("highlight") ?? false}
        onClick={() => editor?.chain().focus().toggleHighlight().run()}
        disabled={!editor?.can().chain().focus().toggleHighlight().run()}
      />
      // +++
    </FloatingToolbar>
  );
}
```

To learn more about the different components, read more under [`Toolbar`][].

#### Props [#FloatingToolbar-props]

<PropertiesList>
  <PropertiesListItem name="editor" type="Editor | null" required>
    The Tiptap editor.
  </PropertiesListItem>
  <PropertiesListItem name="position" type={`"top" | "bottom"`}>
    The vertical position of the floating toolbar.
  </PropertiesListItem>
  <PropertiesListItem name="offset" type="number">
    The vertical offset of the floating toolbar from the selection.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    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.
  </PropertiesListItem>
  <PropertiesListItem name="before" type="ReactNode">
    The content to display at the start of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
  <PropertiesListItem name="after" type="ReactNode">
    The content to display at the end of the toolbar. Any `ReactNode` or
    `Toolbar.*` components work inside.
  </PropertiesListItem>
</PropertiesList>

### FloatingComposer

Displays a [`Composer`][] near the current Tiptap selection, allowing you to
create threads.

```tsx highlight="3"
<FloatingComposer editor={editor} />
```

<Figure>
  <Image
    src="/assets/text-editor/floating-composer.jpg"
    alt="FloatingComposer"
    width={960}
    height={558}
  />
</Figure>

Submitting a comment will attach an annotation thread at the current selection.
Should be passed your Tiptap `editor`, and it’s recommended you set a width
value. Display created threads with [`AnchoredThreads`][] or
[`FloatingThreads`][].

```tsx
import {
  useLiveblocksExtension,
  // +++
  FloatingComposer,
  // +++
  FloatingThreads,
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
      // +++
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      // +++
      <FloatingThreads editor={editor} style={{ width: "350px" }} />
    </div>
  );
}
```

#### Opening the composer

To open the `FloatingComposer`, you need to 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 { Editor } from "@tiptap/react";

function Toolbar({ editor }: { editor: Editor | null }) {
  if (!editor) {
    return null;
  }

  return (
    <button
      onClick={() => {
        // +++
        editor.chain().focus().addPendingComment().run();
        // +++
      }}
      // +++
      data-active={editor.isActive("liveblocksCommentMark")}
      // +++
    >
      💬 New comment
    </button>
  );
}
```

#### Props [#FloatingComposer-props]

<PropertiesList>
  <PropertiesListItem name="metadata" type="ThreadMetadata">
    The metadata of the thread to create.
  </PropertiesListItem>
  <PropertiesListItem
    name="onComposerSubmit"
    type="function"
    detailedType="(comment: ComposerSubmitComment, event: FormEvent<HTMLFormElement>) => Promise<void> | void"
  >
    The event handler called when the composer is submitted.
  </PropertiesListItem>
  <PropertiesListItem name="defaultValue" type="CommentBody">
    The composer’s initial value.
  </PropertiesListItem>
  <PropertiesListItem name="collapsed" type="boolean">
    Whether the composer is collapsed. Setting a value will make the composer
    controlled.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCollapsedChange"
    type="function"
    detailedType="(collapsed: boolean) => void"
  >
    The event handler called when the collapsed state of the composer changes.
  </PropertiesListItem>
  <PropertiesListItem name="defaultCollapsed" type="boolean">
    Whether the composer is initially collapsed. Setting a value will make the
    composer uncontrolled.
  </PropertiesListItem>
  <PropertiesListItem name="disabled" type="boolean">
    Whether the composer is disabled.
  </PropertiesListItem>
  <PropertiesListItem name="autoFocus" type="boolean">
    Whether to focus the composer on mount.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & ComposerOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
</PropertiesList>

### FloatingThreads

Displays floating [`Thread`][] components below text highlights in the editor.

```tsx highlight="3"
<FloatingThreads editor={editor} threads={threads} />
```

<Figure>
  <Image
    src="/assets/text-editor/floating-threads.jpg"
    alt="FloatingThreads"
    width={960}
    height={558}
  />
</Figure>

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 Tiptap `editor`, and it’s recommended you set a width
value.

```tsx
// +++
import { useThreads } from "@liveblocks/react/suspense";
// +++
import {
  useLiveblocksExtension,
  FloatingComposer,
  // +++
  FloatingThreads,
  // +++
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  // +++
  const { threads } = useThreads();
  // +++

  return (
    <div>
      <EditorContent editor={editor} />
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      // +++
      <FloatingThreads
        editor={editor}
        threads={threads}
        style={{ width: "350px" }}
      />
      // +++
    </div>
  );
}
```

<Banner title="Resolved threads">

The `FloatingThreads` component automatically excludes resolved threads from
display. Any resolved threads passed in the threads list will not be shown.

</Banner>

#### 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-tiptap";
import { Editor } from "@tiptap/react";

function ThreadOverlay({ editor }: { editor: Editor | null }) {
  const { threads } = useThreads({ query: { resolved: false } });

  return (
    <>
      <FloatingThreads
        editor={editor}
        threads={threads}
        className="w-[350px] block md:hidden"
      />
      <AnchoredThreads
        editor={editor}
        threads={threads}
        className="w-[350px] hidden sm:block"
      />
    </>
  );
}
```

```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-tiptap";
import { Editor } from "@tiptap/react";

function ThreadOverlay({ editor }: { editor: Editor | null }) {
  const { threads } = useThreads({ query: { resolved: false } });
  // +++
  const isMobile = useIsMobile();
  // +++

  // +++
  if (isMobile) {
    return (
      <FloatingThreads
        editor={editor}
        threads={threads}
        style={{ width: "350px" }}
      />
    );
  }
  // +++

  // +++
  return (
    <AnchoredThreads
      editor={editor}
      threads={threads}
      style={{ width: "350px" }}
    />
  );
  //+++
}

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
<div>
  <EditorContent editor={editor} />
  <FloatingComposer editor={editor} style={{ width: "350px" }} />
  // +++
  <ClientSideSuspense fallback={null}>
    <ThreadOverlay editor={editor} />
  </ClientSideSuspense>
  // +++
</div>
```

#### 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
<FloatingThreads
  editor={editor}
  threads={threads}
  className="my-floating-thread"
/>
```

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";

<FloatingThreads
  editor={editor}
  threads={threads}
  className="my-floating-thread"
  // +++
  components={{
    Thread: (props) => (
      <Thread {...props} className="border shadow" style={{ width: "300px" }} />
    ),
  }}
  // +++
/>;
```

You can return any custom `ReactNode` here, including anything from a simple
wrapper around `Thread`, up to a full custom `Thread` component built using our
[Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment).

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

<FloatingThreads
  editor={editor}
  threads={threads}
  className="my-floating-thread"
  components={{
    Thread: (props) => (
      // +++
      <div>
        {props.thread.comments.map((comment) => (
          <Comment.Body
            key={comment.id}
            body={comment.body}
            components={/* ... */}
          />
        ))}
      </div>
      // +++
    ),
  }}
/>;
```

#### Props [#FloatingThreads-props]

<PropertiesList>
  <PropertiesListItem name="threads" type="ThreadData[]" required>
    The threads to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="components"
    type="Partial<AnchoredThreadsComponents>"
  >
    Override the component’s components.
  </PropertiesListItem>
  <PropertiesListItem
    name="components.Thread"
    type="(props: ThreadProps) => ReactNode"
  >
    Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread)
    component.
  </PropertiesListItem>
</PropertiesList>

### AnchoredThreads

Displays a list of [`Thread`][] components vertically alongside the editor.

```tsx highlight="3"
<AnchoredThreads editor={editor} threads={threads} />
```

<Figure>
  <Image
    src="/assets/text-editor/anchored-threads.jpg"
    alt="AnchoredThreads"
    width={960}
    height={558}
  />
</Figure>

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 {
  useLiveblocksExtension,
  FloatingComposer,
  // +++
  AnchoredThreads,
  // +++
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension();

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  // +++
  const { threads } = useThreads();
  // +++

  return (
    <div>
      <EditorContent editor={editor} />
      <FloatingComposer editor={editor} style={{ width: "350px" }} />
      // +++
      <AnchoredThreads
        editor={editor}
        threads={threads}
        style={{ width: "350px" }}
      />
      // +++
    </div>
  );
}
```

<Banner title="Resolved threads">

The `AnchoredThreads` component automatically excludes resolved threads from
display. Any resolved threads passed in the threads list will not be shown.

</Banner>

#### 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-tiptap";
import { Editor } from "@tiptap/react";

function ThreadOverlay({ editor }: { editor: Editor | null }) {
  const { threads } = useThreads({ query: { resolved: false } });

  return (
    <>
      <FloatingThreads
        editor={editor}
        threads={threads}
        className="w-[350px] block md:hidden"
      />
      <AnchoredThreads
        editor={editor}
        threads={threads}
        className="w-[350px] hidden sm:block"
      />
    </>
  );
}
```

```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-tiptap";
import { Editor } from "@tiptap/react";

function ThreadOverlay({ editor }: { editor: Editor | null }) {
  const { threads } = useThreads({ query: { resolved: false } });
  // +++
  const isMobile = useIsMobile();
  // +++

  // +++
  if (isMobile) {
    return (
      <FloatingThreads
        editor={editor}
        threads={threads}
        style={{ width: "350px" }}
      />
    );
  }
  // +++

  // +++
  return (
    <AnchoredThreads
      editor={editor}
      threads={threads}
      style={{ width: "350px" }}
    />
  );
  //+++
}

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
<div>
  <EditorContent editor={editor} />
  <FloatingComposer editor={editor} style={{ width: "350px" }} />
  // +++
  <ClientSideSuspense fallback={null}>
    <ThreadOverlay editor={editor} />
  </ClientSideSuspense>
  // +++
</div>
```

#### 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
<AnchoredThreads
  editor={editor}
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
/>
```

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";

<AnchoredThreads
  editor={editor}
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
  // +++
  components={{
    Thread: (props) => (
      <Thread
        {...props}
        className="border shadow"
        style={{ background: "white" }}
      />
    ),
  }}
  // +++
/>;
```

You can return any custom `ReactNode` here, including anything from a simple
wrapper around `Thread`, up to a full custom `Thread` component built using our
[Comment primitives](/docs/api-reference/liveblocks-react-ui#primitives-Comment).

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

<AnchoredThreads
  editor={editor}
  threads={threads}
  style={{ width: "350px" }}
  className="my-anchored-thread"
  components={{
    Thread: (props) => (
      // +++
      <div>
        {props.thread.comments.map((comment) => (
          <Comment.Body
            key={comment.id}
            body={comment.body}
            components={/* ... */}
          />
        ))}
      </div>
      // +++
    ),
  }}
/>;
```

##### 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]

<PropertiesList>
  <PropertiesListItem name="threads" type="ThreadData[]" required>
    The threads to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="components"
    type="Partial<AnchoredThreadsComponents>"
  >
    Override the component’s components.
  </PropertiesListItem>
  <PropertiesListItem
    name="components.Thread"
    type="(props: ThreadProps) => ReactNode"
  >
    Override the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread)
    component.
  </PropertiesListItem>
</PropertiesList>

### HistoryVersionPreview [@badge=beta]

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

The `HistoryVersionPreview` component allows you to display a preview of a
specific version of your Tiptap editor's content. It also contains a button and
logic for restoring. It must be used inside the `<LiveblocksPlugin>` context. 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-tiptap";

function VersionPreview({ selectedVersion, onVersionRestore }) {
  return (
    <HistoryVersionPreview
      version={selectedVersion}
      onVersionRestore={onVersionRestore}
    />
  );
}
```

#### Props [#HistoryVersionPreview-props]

<PropertiesList>
  <PropertiesListItem name="version" type="HistoryVersion" required>
    The version of the editor content to preview.
  </PropertiesListItem>
  <PropertiesListItem
    name="onVersionRestore"
    type="(version: HistoryVersion) => void"
  >
    Callback function called when the user chooses to restore this version.
  </PropertiesListItem>
</PropertiesList>

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.

### AiToolbar [@badge=beta]

<Banner title="Private beta">

AI Copilots is currently in private beta. If you would like access to the beta,
please [contact us](https://liveblocks.io/contact/sales). We’d love to hear from
you.

</Banner>

Displays a floating AI toolbar near the current Tiptap selection, allowing you
to use AI to apply changes to the document or ask questions about it.

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

Pass your Tiptap `editor` to use the component, and enable (or customize) the AI
option in [`useLiveblocksExtension`][].

```tsx
import {
  useLiveblocksExtension,
  // +++
  AiToolbar,
  // +++
  FloatingToolbar,
} from "@liveblocks/react-tiptap";
import { useEditor, EditorContent } from "@tiptap/react";

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    // +++
    ai: true,
    // +++
  });

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
      // +++
      <AiToolbar editor={editor} />
      // +++
      <FloatingToolbar editor={editor} />
    </div>
  );
}
```

#### Opening the toolbar [#AiToolbar-opening]

To open the `AiToolbar`, you need to call the `askAi`
[command](https://tiptap.dev/docs/editor/api/commands) added by Liveblocks.

```tsx
import { Editor } from "@tiptap/react";

function Toolbar({ editor }: { editor: Editor | null }) {
  if (!editor) {
    return null;
  }

  return (
    <button
      onClick={() => {
        // +++
        editor.chain().focus().askAi().run();
        // +++
      }}
    >
      ✨ Ask AI
    </button>
  );
}
```

You can also pass a prompt to the `askAi` command and it will directly request
it when opening the toolbar.

```tsx
<button
  onClick={() => {
    // +++
    editor.chain().focus().askAi("Add emojis to the text").run();
    // +++
  }}
>
  😃 Emojify
</button>
```

#### Customizing suggestions [#AiToolbar-suggestions]

By default, the AI toolbar displays a list of suggestions (e.g. “Fix mistakes”,
“Explain”, etc). These can be customized via the `suggestions` prop and the
[`AiToolbar.Suggestion`][] component.

```tsx
<AiToolbar
  editor={editor}
  // +++
  suggestions={
    <>
      <AiToolbar.SuggestionsLabel>Suggested</AiToolbar.SuggestionsLabel>
      <AiToolbar.Suggestion>Fix mistakes</AiToolbar.Suggestion>
      <AiToolbar.Suggestion prompt="Add emojis to the text">
        Emojify
      </AiToolbar.Suggestion>
      <AiToolbar.SuggestionsSeparator />
      <AiToolbar.Suggestion icon={<Icon.Sparkles />}>
        Continue writing
      </AiToolbar.Suggestion>
    </>
  }
  // +++
/>
```

Doing so will override the default suggestions, instead you can use a function
to keep them while adding your own.

```tsx
<AiToolbar
  editor={editor}
  // +++
  suggestions={({ children }) => (
    <>
      {children}
      // +++
      <AiToolbar.SuggestionsSeparator />
      <AiToolbar.SuggestionsLabel>Custom</AiToolbar.SuggestionsLabel>
      <AiToolbar.Suggestion>Custom suggestion</AiToolbar.Suggestion>
    </>
  )}
/>
```

#### Props [#AiToolbar-props]

<PropertiesList>
  <PropertiesListItem name="editor" type="Editor | null" required>
    The Tiptap editor.
  </PropertiesListItem>
  <PropertiesListItem name="offset" type="number">
    The vertical offset of the AI toolbar from the selection.
  </PropertiesListItem>
  <PropertiesListItem name="suggestions" type="ReactNode">
    The prompt suggestions to display below the AI toolbar.
  </PropertiesListItem>
</PropertiesList>

#### AiToolbar.Suggestion

A prompt suggestion displayed below the AI toolbar.

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

<AiToolbar
  editor={editor}
  suggestions={
    <>
      // +++
      <AiToolbar.Suggestion>Fix mistakes</AiToolbar.Suggestion>
      // +++
    </>
  }
/>;
```

By default, selecting a suggestion will use its label from the `children` as the
prompt, this can be overridden with the `prompt` prop. Also optionally takes an
icon.

```tsx
import { AiToolbar } from "@liveblocks/react-tiptap";
import { Icon } from "@liveblocks/react-ui";

// "Translate to French" is displayed in the suggestion and used as the prompt
<AiToolbar.Suggestion>Translate to French</AiToolbar.Suggestion>

// "Emojify" is displayed in the suggestion but "Add emojis to the text" is used as the prompt
<AiToolbar.Suggestion prompt="Add emojis to the text">Emojify</AiToolbar.Suggestion>

// Custom icon
<AiToolbar.Suggestion icon={<div>?</div>}>Explain</AiToolbar.Suggestion>

// Using a Liveblocks icon
<AiToolbar.Suggestion icon={<Icon.QuestionMark />}>Explain</AiToolbar.Suggestion>
```

##### Props [#AiToolbarSuggestion-props]

<PropertiesList>
  <PropertiesListItem name="children" type="ReactNode">
    The suggestion’s label, used as the prompt if the `prompt` prop is not set.
  </PropertiesListItem>
  <PropertiesListItem name="icon" type="ReactNode">
    An optional icon displayed before the label.
  </PropertiesListItem>
  <PropertiesListItem name="prompt" type="string">
    The prompt to use instead of the label.
  </PropertiesListItem>
</PropertiesList>

#### AiToolbar.SuggestionsLabel

A label to describe a group of prompt suggestions displayed in the AI toolbar.

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

<AiToolbar
  editor={editor}
  suggestions={
    <>
      // +++
      <AiToolbar.SuggestionsLabel>Translation</AiToolbar.SuggestionsLabel>
      // +++
      <AiToolbar.Suggestion>Translate in French</AiToolbar.Suggestion>
      <AiToolbar.Suggestion>Translate in English</AiToolbar.Suggestion>
    </>
  }
/>;
```

#### AiToolbar.SuggestionsSeparator

A separator between groups of prompt suggestions displayed in the AI toolbar.

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

<AiToolbar
  editor={editor}
  suggestions={
    <>
      <AiToolbar.Suggestion>Translate in French</AiToolbar.Suggestion>
      <AiToolbar.Suggestion>Translate in English</AiToolbar.Suggestion>
      // +++
      <AiToolbar.SuggestionsSeparator />
      // +++
      <AiToolbar.Suggestion>Custom suggestion</AiToolbar.Suggestion>
    </>
  }
/>;
```

## Hooks

### useLiveblocksExtension

Liveblocks plugin for Tiptap that adds collaboration to your editor.
`liveblocks` should be passed to Tiptap’s `useEditor` as an extension.

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

function TextEditor() {
  // +++
  const liveblocks = useLiveblocksExtension();
  // +++

  const editor = useEditor({
    extensions: [
      // +++
      liveblocks,
      // +++
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
    </div>
  );
}
```

<PropertiesList>
  <PropertiesListItem name="initialContent" type="Content">
    The initial content for the editor, if it’s never been set. [Learn
    more](#Setting-initial-content).
  </PropertiesListItem>
  <PropertiesListItem name="field" type="string">
    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).
  </PropertiesListItem>
  <PropertiesListItem
    name="offlineSupport_experimental"
    defaultValue="false"
    type="boolean"
  >
    Experimental. Enable offline support using IndexedDB. This means the after
    the first load, documents will be stored locally and load instantly. [Learn
    more](#Offline-support).
  </PropertiesListItem>
  <PropertiesListItem name="comments" defaultValue="true" type="boolean">
    Enable comments in the editor.
  </PropertiesListItem>
  <PropertiesListItem name="mentions" defaultValue="true" type="boolean">
    Enable mentions in the editor.
  </PropertiesListItem>
  <PropertiesListItem
    name="ai"
    defaultValue="false"
    type="boolean | AiConfiguration"
  >
    Enable AI in the editor and optionally customize configuration options.
  </PropertiesListItem>
</PropertiesList>

#### 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 { useLiveblocksExtension } from "@liveblocks/react-tiptap";

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    // +++
    initialContent: "<p>Hello world</p>",
    // +++
  });

  // ...
}
```

#### 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 { useLiveblocksExtension } from "@liveblocks/react-tiptap";

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

  // ...
}
```

Here’s an example of how multiple editors may be set up.

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

function TextEditors() {
  return (
    <div>
      // +++
      <TextEditor field="one" />
      <TextEditor field="two" />
      // +++
    </div>
  );
}

function TextEditor({ field }: { field: string }) {
  // +++
  const liveblocks = useLiveblocksExtension({ field });
  // +++

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      <EditorContent editor={editor} />
    </div>
  );
}
```

#### 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 { useLiveblocksExtension } from "@liveblocks/react-tiptap";

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    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 {
  useLiveblocksExtension,
  AnchoredThreads,
  FloatingComposer,
} from "@liveblocks/react-tiptap";
import { Editor, EditorContent, useEditor } from "@tiptap/react";

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

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
    immediatelyRender: false,
  });

  return (
    <>
      <EditorContent editor={editor} />
      <FloatingComposer editor={editor} style={{ width: 350 }} />
      // +++
      <ClientSideSuspense fallback={null}>
        <Threads editor={editor} />
      </ClientSideSuspense>
      // +++
    </>
  );
}

// +++
function Threads({ editor }: { editor: Editor }) {
  const { threads } = useThreads();

  return <AnchoredThreads editor={editor} threads={threads} />;
}
// +++
```

#### Customizing AI components [@badge=beta]

<Banner title="Private beta">

AI Copilots is currently in private beta. If you would like access to the beta,
please [contact us](https://liveblocks.io/contact/sales). We’d love to hear from
you.

</Banner>

By default, AI components like [`AiToolbar`][] use the term `"AI"`. This can be
customized with the `ai.name` option in [`useLiveblocksExtension`][]. This value
will be used throughout the AI components: `"Ask {name}"` in the [`Toolbar`][]/
[`FloatingToolbar`][] default buttons, `"{name} is thinking…"` in the
[`AiToolbar`][], etc.

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

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    ai: {
      // +++
      // "Ask Liveblocks anything…", "Liveblocks is thinking…", etc
      name: "Liveblocks",
      // +++
    },
  });

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  // ...
}
```

If you’re after visual customization, AI components like [`AiToolbar`][]
integrate with the rest of Liveblocks' styles, heavily using tokens like
`--lb-accent` for example. Learn more about [styling](#Stylesheets).

#### Generating AI toolbar responses [@badge=beta]

<Banner title="Private beta">

AI Copilots is currently in private beta. If you would like access to the beta,
please [contact us](https://liveblocks.io/contact/sales). We’d love to hear from
you.

</Banner>

By default, the [`AiToolbar`][] component sends its requests to Liveblocks to
generate its responses. This can be customized via the
`ai.resolveContextualPrompt` option in [`useLiveblocksExtension`][]. This option
accepts an async function which will be called by the AI toolbar whenever a
prompt is requested, it will receive the prompt and some context (the document’s
and selection’s text, the previous request if it’s a follow-up, etc) and is
expected to return the type of response and the text to use.

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

function TextEditor() {
  const liveblocks = useLiveblocksExtension({
    ai: {
      // +++
      resolveContextualPrompt: async ({ prompt, context, signal }) => {
        const response = await fetch("/api/contextual-prompt", {
          method: "POST",
          body: JSON.stringify({ prompt, context }),
          signal,
        });

        return response.json();
      },
      // +++
    },
  });

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  // ...
}
```

### 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-tiptap";

const status = useIsEditorReady();
```

Here’s how it can be used in the context of your editor.

```tsx
import { useLiveblocksExtension } from "@liveblocks/react-tiptap";
// +++
import { useIsEditorReady, useEditor, EditorContent } from "@tiptap/react";
// +++

function TextEditor() {
  const liveblocks = useLiveblocksExtension();
  // +++
  const ready = useIsEditorReady();
  // +++

  const editor = useEditor({
    extensions: [
      liveblocks,
      // ...
    ],
  });

  return (
    <div>
      // +++
      {!ready ? <div>Loading...</div> : <EditorContent editor={editor} />}
      // +++
    </div>
  );
}
```

## Stylesheets

React Tiptap 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-tiptap/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).

[`LiveblocksPlugin`]: #LiveblocksPlugin
[`useLiveblocksExtension`]: #useLiveblocksExtension
[`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
[`Toolbar`]: #Toolbar
[`Toolbar.Button`]: #Toolbar.Button
[`Toolbar.Toggle`]: #Toolbar.Toggle
[`Toolbar.BlockSelector`]: #Toolbar.BlockSelector
[`Toolbar.Separator`]: #Toolbar.Separator
[`Toolbar.SectionHistory`]: #Toolbar.SectionHistory
[`Toolbar.SectionInline`]: #Toolbar.SectionInline
[`Toolbar.SectionCollaboration`]: #Toolbar.SectionCollaboration
[`FloatingToolbar`]: #FloatingToolbar
[`FloatingComposer`]: #FloatingComposer
[`FloatingThreads`]: #FloatingThreads
[`AnchoredThreads`]: #AnchoredThreads
[`AiToolbar`]: #AiToolbar
[`AiToolbar.Suggestion`]: #AiToolbar.Suggestion
[`AiToolbar.SuggestionsLabel`]: #AiToolbar.SuggestionsLabel
[`AiToolbar.SuggestionsSeparator`]: #AiToolbar.SuggestionsSeparator
[`ClientSideSuspense`]: /docs/api-reference/liveblocks-react#ClientSideSuspense

---
meta:
  title: "@liveblocks/react-ui"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/react-ui package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/react-ui` provides you with [React](https://react.dev/) components
to build collaborative experiences. Read our
[Comments](/docs/get-started/comments) and
[Notifications](/docs/get-started/notifications) get started guides to learn
more.

## Comments

### Default components [#Components]

#### Thread

Displays a thread of comments. Each thread has a composer for creating replies.

```tsx
<Thread thread={thread} />
```

<Figure>
  <Image
    src="/assets/comments/thread.png"
    alt="Thread"
    width={768}
    height={446}
  />
</Figure>

Map through `threads` to render a list of the room’s threads and comments.
Threads can be retrieved with
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads).

```tsx highlight="10"
import { Thread } from "@liveblocks/react-ui";
import { useThreads } from "@liveblocks/react/suspense";

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

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

##### Resolved and unresolved threads

A thread can be marked as resolved or unresolved via its `resolved` property.
The `Thread` component automatically handles this through its `resolved` toggle
button displayed by default.

You can additionally use `thread.resolved` to filter the displayed threads for
example. Or if you want to create your own `Thread` component using
[the primitives](/docs/ready-made-features/comments/primitives), you can use
[`useMarkThreadAsResolved`](/docs/api-reference/liveblocks-react#useMarkThreadAsResolved)
and
[`useMarkThreadAsUnresolved`](/docs/api-reference/liveblocks-react#useMarkThreadAsUnresolved)
to update the property.

<Banner title="Resolved in metadata before 2.2">

Before 2.2, `resolved` was an optional property in a thread’s metadata, it’s now
a first-class citizen. If you’re upgrading from a previous version, learn more
about this change in our
[Upgrade Guide for 2.2](https://liveblocks.io/docs/platform/upgrading/2.2).

</Banner>

##### Props [#Thread-props]

<PropertiesList>
  <PropertiesListItem name="thread" type="ThreadData" required>
    The thread to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="showComposer"
    type='boolean | "collapsed"'
    defaultValue='"collapsed"'
  >
    How to show or hide the composer to reply to the thread.
  </PropertiesListItem>
  <PropertiesListItem
    name="showActions"
    type='boolean | "hover"'
    defaultValue='"hover"'
  >
    How to show or hide the actions.
  </PropertiesListItem>
  <PropertiesListItem name="showReactions" type="boolean" defaultValue="true">
    Whether to show reactions.
  </PropertiesListItem>
  <PropertiesListItem name="showAttachments" type="boolean" defaultValue="true">
    Whether to show attachments.
  </PropertiesListItem>
  <PropertiesListItem
    name="showComposerFormattingControls"
    type="boolean"
    defaultValue="true"
  >
    Whether to show the composer’s formatting controls.
  </PropertiesListItem>
  <PropertiesListItem
    name="showResolveAction"
    type="boolean"
    defaultValue="true"
  >
    Whether to show the action to resolve the thread.
  </PropertiesListItem>
  <PropertiesListItem
    name="indentCommentContent"
    type="boolean"
    defaultValue="true"
  >
    Whether to indent the comments’ content.
  </PropertiesListItem>
  <PropertiesListItem
    name="showDeletedComments"
    type="boolean"
    defaultValue="false"
  >
    Whether to show deleted comments.
  </PropertiesListItem>
  <PropertiesListItem
    name="onComposerSubmit"
    type="function"
    detailedType="(comment: ComposerSubmitComment, event: FormEvent<HTMLFormElement>) => Promise<void> | void"
  >
    The event handler called when the composer is submitted.
  </PropertiesListItem>
  <PropertiesListItem
    name="onResolvedChange"
    type="function"
    detailedType="(resolved: boolean) => void"
  >
    The event handler called when changing the resolved status.
  </PropertiesListItem>
  <PropertiesListItem
    name="onThreadDelete"
    type="function"
    detailedType="(thread: ThreadData) => void"
  >
    The event handler called when the thread is deleted. A thread is deleted
    when all its comments are deleted.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCommentEdit"
    type="function"
    detailedType="(comment: CommentData) => void"
  >
    The event handler called when a comment is edited.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCommentDelete"
    type="function"
    detailedType="(comment: CommentData) => void"
  >
    The event handler called when a comment is deleted.
  </PropertiesListItem>
  <PropertiesListItem
    name="onAuthorClick"
    type="function"
    detailedType="(userId: string, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on a comment’s author.
  </PropertiesListItem>
  <PropertiesListItem
    name="onMentionClick"
    type="function"
    detailedType="(userId: string, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on a mention.
  </PropertiesListItem>
  <PropertiesListItem
    name="onAttachmentClick"
    type="function"
    detailedType="(args: CommentAttachmentArgs, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on a comment’s attachment.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & ThreadOverrides & CommentOverrides & ComposerOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
</PropertiesList>

{/* TODO: Document classes and data attributes */}

#### Composer

Displays a composer for creating threads or comments.

```tsx
<Composer />
```

<Figure>
  <Image
    src="/assets/comments/composer.png"
    alt="Composer"
    width={768}
    height={446}
  />
</Figure>

By default, submitting the composer will create a new thread.

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

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

##### Adding thread metadata

If you’d like to attach custom metadata to the newly created thread, you can add
a `metadata` prop.

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

// Creates a new thread with custom metadata
function Component() {
  return (
    <Composer
      metadata={{
        // Custom metadata here, e.g. colors, coordinates
        color: "purple",
        x: 80,
        y: 120,
      }}
    />
  );
}
```

###### Typed metadata

You can use TypeScript to type your custom metadata by editing your config file.
Metadata properties can be `string`, `number`, or `boolean`.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // Set your custom metadata types
    // +++
    ThreadMetadata: {
      // Example types, e.g. colors, coordinates
      color: string;
      x: number;
      y: number;
    };
    // +++

    // Other types
    // ...
  }
}
```

##### Replying to a thread

If you provide a `threadId`, then submitting the composer will add a new reply
to the thread.

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

// Adds a new comment to a thread
function Component({ threadId }) {
  return <Composer threadId={threadId} />;
}
```

##### Modifying a comment

If you provide both a `threadId` and a `commentId`, then submitting the composer
will edit the comment.

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

// Edits an existing comment
function Component({ threadId, commentId }) {
  return <Composer threadId={threadId} commentId={commentId} />;
}
```

##### Custom behavior

If you’d like to customize submission behavior, you can use
`event.preventDefault()` in `onComposerSubmit` to disable the default behavior
and call comment and thread mutation methods manually.

```tsx
import { Composer } from "@liveblocks/react-ui";
import { useEditComment, useAddReaction } from "@liveblocks/react/suspense";

// Custom submission behavior (edits a comment and adds a reaction)
function Component({ threadId, commentId }) {
  const editComment = useEditComment();
  const addReaction = useAddReaction();

  return (
    <Composer
      onComposerSubmit={({ body, attachments }, event) => {
        event.preventDefault();

        // Example mutations
        editComment({ threadId, commentId, body, attachments });
        addReaction({ threadId, commentId, emoji: "✅" });

        // Other custom behavior
        // ...
      }}
    />
  );
}
```

Learn more about mutation hooks under
[`@liveblocks/react`](/docs/api-reference/liveblocks-react#Comments).

##### Props [#Composer-props]

<PropertiesList>
  <PropertiesListItem name="threadId" type="string">
    The ID of the thread to reply to or to edit a comment in.
  </PropertiesListItem>
  <PropertiesListItem name="commentId" type="string">
    The ID of the comment to edit.
  </PropertiesListItem>
  <PropertiesListItem name="metadata" type="ThreadMetadata">
    The metadata of the thread to create.
  </PropertiesListItem>
  <PropertiesListItem
    name="onComposerSubmit"
    type="function"
    detailedType="(comment: ComposerSubmitComment, event: FormEvent<HTMLFormElement>) => Promise<void> | void"
  >
    The event handler called when the composer is submitted.
  </PropertiesListItem>
  <PropertiesListItem name="defaultValue" type="CommentBody">
    The composer’s initial value.
  </PropertiesListItem>
  <PropertiesListItem name="defaultAttachments" type="CommentAttachment[]">
    The composer’s initial attachments.
  </PropertiesListItem>
  <PropertiesListItem name="collapsed" type="boolean">
    Whether the composer is collapsed. Setting a value will make the composer
    controlled.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCollapsedChange"
    type="function"
    detailedType="(collapsed: boolean) => void"
  >
    The event handler called when the collapsed state of the composer changes.
  </PropertiesListItem>
  <PropertiesListItem name="showAttachments" type="boolean" defaultValue="true">
    Whether to show and allow adding attachments.
  </PropertiesListItem>
  <PropertiesListItem
    name="showFormattingControls"
    type="boolean"
    defaultValue="true"
  >
    Whether to show formatting controls (e.g. a floating toolbar with formatting
    toggles when selecting text)
  </PropertiesListItem>
  <PropertiesListItem name="defaultCollapsed" type="boolean">
    Whether the composer is initially collapsed. Setting a value will make the
    composer uncontrolled.
  </PropertiesListItem>
  <PropertiesListItem name="disabled" type="boolean">
    Whether the composer is disabled.
  </PropertiesListItem>
  <PropertiesListItem name="autoFocus" type="boolean">
    Whether to focus the composer on mount.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & ComposerOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
</PropertiesList>

{/* TODO: Document classes and data attributes */}

#### Comment

Displays a single comment.

```tsx
<Comment comment={comment} />
```

<Figure>
  <Image
    src="/assets/comments/comment.png"
    alt="Comment"
    width={768}
    height={446}
  />
</Figure>

Map through `thread.comments` to render each comment in a thread. Threads can be
retrieved with [`useThreads`](/docs/api-reference/liveblocks-react#useThreads).

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

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

##### Custom thread components

[`Comment`](#Comment) can be used in combination with [`Composer`](#Composer) to
create a custom thread component. The composer in this example is used to
[reply to the existing thread](/docs/api-reference/liveblocks-react-ui#Replying-to-a-thread).

```tsx highlight="10"
import { Comment, Composer } from "@liveblocks/react-ui";
import { ThreadData } from "@liveblocks/client";
import { useThreads } from "@liveblocks/react/suspense";

// Renders a list of comments and a composer for adding new comments
function CustomThread({ thread }: { thread: ThreadData }) {
  return (
    <>
      {thread.comments.map((comment) => (
        <Comment key={comment.id} comment={comment} />
      ))}
      <Composer threadId={thread.id} />
    </>
  );
}

// Renders a list of custom thread components
function Component() {
  const { threads } = useThreads();

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

##### Props [#Comment-props]

<PropertiesList>
  <PropertiesListItem name="comment" type="CommentData" required>
    The comment to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="showActions"
    type='boolean | "hover"'
    defaultValue='"hover"'
  >
    How to show or hide the actions.
  </PropertiesListItem>
  <PropertiesListItem name="showReactions" type="boolean" defaultValue="true">
    Whether to show reactions.
  </PropertiesListItem>
  <PropertiesListItem name="showAttachments" type="boolean" defaultValue="true">
    Whether to show attachments.
  </PropertiesListItem>
  <PropertiesListItem
    name="showComposerFormattingControls"
    type="boolean"
    defaultValue="true"
  >
    Whether to show the composer’s formatting controls when editing the comment.
  </PropertiesListItem>
  <PropertiesListItem name="indentContent" type="boolean" defaultValue="true">
    Whether to indent the comment’s content.
  </PropertiesListItem>
  <PropertiesListItem name="showDeleted" type="boolean" defaultValue="false">
    Whether to show the comment if it was deleted. If set to `false`, it will
    render deleted comments as `null`.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCommentEdit"
    type="function"
    detailedType="(comment: CommentData) => void"
  >
    The event handler called when the comment is edited.
  </PropertiesListItem>
  <PropertiesListItem
    name="onCommentDelete"
    type="function"
    detailedType="(comment: CommentData) => void"
  >
    The event handler called when the comment is deleted.
  </PropertiesListItem>
  <PropertiesListItem
    name="onAuthorClick"
    type="function"
    detailedType="(userId: string, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on the author.
  </PropertiesListItem>
  <PropertiesListItem
    name="onMentionClick"
    type="function"
    detailedType="(userId: string, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on a mention.
  </PropertiesListItem>
  <PropertiesListItem
    name="onAttachmentClick"
    type="function"
    detailedType="(args: CommentAttachmentArgs, event: MouseEvent<HTMLElement>) => void"
  >
    The event handler called when clicking on a comment’s attachment.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & CommentOverrides & ComposerOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
</PropertiesList>

{/* TODO: Document classes and data attributes */}

### Primitives

Primitives are unstyled, headless components that can be used to create fully
custom commenting experiences.

<Banner title="Using primitives with TypeScript">

If you run into the
`Cannot find module '@liveblocks/react-ui/primitives' or its corresponding type declarations`
error, you should update your `tsconfig.json`’s `moduleResolution`
[property](https://www.typescriptlang.org/tsconfig#moduleResolution) to
`"node16"` or `"nodenext"` (or `"bundler"` if you’re on TS >=5).

</Banner>

#### Composition

All primitives are composable; they forward their props and refs, merge their
classes and styles, and chain their event handlers.

Inspired by [Radix](https://www.radix-ui.com/) (and powered by its
[`Slot`](https://www.radix-ui.com/primitives/docs/utilities/slot) utility), most
of the primitives also support an `asChild` prop to replace the rendered element
by any provided child, and both set of props will be merged.

```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>;
```

Learn more about this concept on
[Radix’s composition guide](https://www.radix-ui.com/primitives/docs/guides/composition).

#### Composer [#primitives-Composer]

Used to render a composer for creating, or editing, threads and comments.

```tsx
<Composer.Form>
  <Composer.AttachmentsDropArea />
  <Composer.Editor
    components={{
      Mention: () => <Composer.Mention />,
      MentionSuggestions: () => (
        <Composer.Suggestions>
          <Composer.SuggestionsList>
            <Composer.SuggestionsListItem />
          </Composer.SuggestionsList>
        </Composer.Suggestions>
      ),
      Link: () => <Composer.Link />,
    }}
  />
  <Composer.AttachFiles />
  <Composer.Submit />
</Composer.Form>
```

Combine with
[`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread) to
render a composer that creates threads.

```tsx
import {
  Composer,
  CommentBodyLinkProps,
  CommentBodyMentionProps,
  ComposerEditorMentionSuggestionsProps,
  ComposerSubmitComment,
} from "@liveblocks/react-ui/primitives";
import { useCreateThread, useUser } from "@liveblocks/react/suspense";
import { FormEvent } from "react";

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

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

    // Create a new thread
    // +++
    const thread = createThread({
      body,
      attachments,
      metadata: {},
    });
    //+++
  }

  return (
    // +++
    <Composer.Form onComposerSubmit={handleComposerSubmit}>
      <Composer.Editor
        components={{
          Mention,
          MentionSuggestions,
          Link,
        }}
      />
      <Composer.Submit>Create thread</Composer.Submit>
    </Composer.Form>
    // +++
  );
}

// Render a mention in the composer's editor, e.g. "@Emil Joyce"
function Mention({ userId }: CommentBodyMentionProps) {
  return <Comment.Mention>@{userId}</Comment.Mention>;
}

// Render a list of mention suggestions, used after typing "@" in the editor
function MentionSuggestions({
  userIds,
  selectedUserId,
}: ComposerEditorMentionSuggestionsProps) {
  return (
    <Composer.Suggestions>
      <Composer.SuggestionsList>
        {userIds.map((userId) => (
          <MentionSuggestion key={userId} userId={userId} />
        ))}
      </Composer.SuggestionsList>
    </Composer.Suggestions>
  );
}

// Render a single mention suggestion from a `userId`
function MentionSuggestion({ userId }: { userId: string }) {
  const { user } = useUser(userId);

  return (
    <Composer.SuggestionsListItem value={user.id}>
      <img src={user.avatar} alt={user.name} />
      {user.name}
    </Composer.SuggestionsListItem>
  );
}

// Render a link in the composer's editor, e.g. "https://liveblocks.io"
function Link({ href, children }: CommentBodyLinkProps) {
  return <Comment.Link href={href}>{children}</Comment.Link>;
}
```

##### Composer.Form [#primitives-Composer.Form]

Surrounds the composer’s content and handles submissions. By default, no action
occurs when the composer is submitted. You must create your own mutations within
`onComposerSubmit` for
[creating threads](/docs/api-reference/liveblocks-react#useCreateThread),
[creating comments](/docs/api-reference/liveblocks-react#useCreateComment),
[editing comments](/docs/api-reference/liveblocks-react#useEditComment), etc.

```tsx
<Composer.Form
  onComposerSubmit={({ body, attachments }) => {
    // Mutate your comments
    // ...
  }}
>
  {/* ... */}
</Composer.Form>
```

<PropertiesList>
  <PropertiesListItem name="defaultAttachments" type="CommentAttachment[]">
    The composer’s initial attachments.
  </PropertiesListItem>
  <PropertiesListItem
    name="pasteFilesAsAttachments"
    type="boolean"
    defaultValue="false"
  >
    Whether to create attachments when pasting files into the editor.
  </PropertiesListItem>
  <PropertiesListItem
    name="preventUnsavedChanges"
    type="boolean"
    defaultValue="true"
  >
    When `preventUnsavedChanges` is set on your [Liveblocks
    client](/docs/api-reference/liveblocks-client#prevent-users-losing-unsaved-changes)
    on
    [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#prevent-users-losing-unsaved-changes),
    then closing a browser tab will be prevented when there are unsaved changes.
    By default, that will include draft text or attachments that are being
    uploaded via this composer, but not submitted yet. If you want to prevent
    unsaved changes with Liveblocks, but not for this composer, you can opt-out
    this composer instance by setting this prop to `false`.
  </PropertiesListItem>
  <PropertiesListItem
    name="onComposerSubmit"
    type="function"
    detailedType="(comment: ComposerSubmitComment, event: FormEvent<HTMLFormElement>) => Promise<void> | void"
  >
    The event handler called when the form is submitted.
  </PropertiesListItem>
  <PropertiesListItem name="disabled" type="boolean" defaultValue="false">
    Whether the composer is disabled.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.Editor [#primitives-Composer.Editor]

Displays the composer’s editor.

```tsx
<Composer.Editor placeholder="Write a comment…" />
```

<PropertiesList>
  <PropertiesListItem name="defaultValue" type="CommentBody">
    The editor’s initial value.
  </PropertiesListItem>
  <PropertiesListItem name="placeholder" type="string">
    The text to display when the editor is empty.
  </PropertiesListItem>
  <PropertiesListItem name="disabled" type="boolean">
    Whether the editor is disabled.
  </PropertiesListItem>
  <PropertiesListItem name="autoFocus" type="boolean">
    Whether to focus the editor on mount.
  </PropertiesListItem>
  <PropertiesListItem name="dir" type='"ltr" | "rtl"'>
    The reading direction of the editor and related elements.
  </PropertiesListItem>
  <PropertiesListItem
    name="components"
    type="Partial<ComposerEditorComponents>"
  >
    The components displayed within the editor.
  </PropertiesListItem>
</PropertiesList>

<Table columns={["28%", "auto"]}>

| Attribute       | Value                                   |
| --------------- | --------------------------------------- |
| `data-focused`  | Present when the component is focused.  |
| `data-disabled` | Present when the component is disabled. |

</Table>

###### components [#primitives-Composer.Editor-components]

The components displayed within the editor.

<PropertiesList>
  <PropertiesListItem
    name="Mention"
    type="ComponentType<ComposerEditorMentionProps>"
  >
    The component used to display mentions. Defaults to the mention’s `userId`
    prefixed by an @.
  </PropertiesListItem>
  <PropertiesListItem
    name="MentionSuggestions"
    type="ComponentType<ComposerEditorMentionSuggestionProps>"
  >
    The component used to display mention suggestions. Defaults to a list of the
    suggestions’ `userId`.
  </PropertiesListItem>
  <PropertiesListItem name="Link" type="ComponentType<ComposerEditorLinkProps>">
    The component used to display links. Defaults to the link’s `children`
    property.
  </PropertiesListItem>
  <PropertiesListItem
    name="FloatingToolbar"
    type="ComponentType<ComposerEditorFloatingToolbarProps>"
  >
    The component used to display a floating toolbar attached to the selection.
  </PropertiesListItem>
</PropertiesList>

###### Mention [#primitives-Composer.Editor-Mention]

The component used to display mentions.

```tsx
<Composer.Editor
  components={{
    Mention: ({ userId, isSelected }) => (
      <Composer.Mention>@{userId}</Composer.Mention>
    ),
  }}
/>
```

<PropertiesList>
  <PropertiesListItem name="userId" type="string">
    The mention’s user ID.
  </PropertiesListItem>
  <PropertiesListItem name="isSelected" type="boolean">
    Whether the mention is selected.
  </PropertiesListItem>
</PropertiesList>

###### MentionSuggestions [#primitives-Composer.Editor-MentionSuggestions]

The component used to display mention suggestions.

<PropertiesList>
  <PropertiesListItem name="userIds" type="string[]">
    The list of suggested user IDs.
  </PropertiesListItem>
  <PropertiesListItem name="selectedUserId" type="string">
    he currently selected user ID.
  </PropertiesListItem>
</PropertiesList>

```tsx
<Composer.Editor
  components={{
    MentionSuggestions: () => (
      <Composer.Suggestions>
        <Composer.SuggestionsList>
          <Composer.SuggestionsListItem />
        </Composer.SuggestionsList>
      </Composer.Suggestions>
    ),
  }}
/>
```

###### Link [#primitives-Composer.Editor-Link]

The component used to display links.

```tsx
<Composer.Editor
  components={{
    Link: ({ href, children }) => <Composer.Link>{children}</Composer.Link>,
  }}
/>
```

<PropertiesList>
  <PropertiesListItem name="href" type="string">
    The link’s absolute URL.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    The link’s content.
  </PropertiesListItem>
</PropertiesList>

###### FloatingToolbar [#primitives-Composer.Editor-FloatingToolbar]

Displays a floating toolbar attached to the selection within `Composer.Editor`.

```tsx
<Composer.Editor
  components={{
    FloatingToolbar: () => (
      <Composer.FloatingToolbar>
        <Composer.MarkToggle mark="bold">Bold</Composer.MarkToggle>
        <Composer.MarkToggle mark="italic">Italic</Composer.MarkToggle>
      </Composer.FloatingToolbar>
    ),
  }}
/>
```

##### Composer.Mention [#primitives-Composer.Mention]

Displays mentions within `Composer.Editor`.

```tsx
<Composer.Mention>@{userId}</Composer.Mention>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

<Table columns={["28%", "auto"]}>

| Attribute       | Value                                 |
| --------------- | ------------------------------------- |
| `data-selected` | Present when the mention is selected. |

</Table>

##### Composer.Suggestions [#primitives-Composer.Suggestions]

Contains suggestions within `Composer.Editor`.

```tsx
<Composer.Suggestions>{/* ... */}<Composer.Suggestions>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.SuggestionsList [#primitives-Composer.SuggestionsList]

Displays a list of suggestions within `Composer.Editor`.

```tsx
<Composer.SuggestionsList>
  {userIds.map((userId) => (
    <Composer.SuggestionsListItem key={userId} value={userId}>
      @{userId}
    </Composer.SuggestionsListItem>
  ))}
</Composer.SuggestionsList>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.SuggestionsListItem [#primitives-Composer.SuggestionsListItem]

Displays a suggestion within `Composer.SuggestionsList`.

```tsx
<Composer.SuggestionsListItem key={userId} value={userId}>
  @{userId}
</Composer.SuggestionsListItem>
```

<PropertiesList>
  <PropertiesListItem name="value" type="string" required>
    The suggestion’s value.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

<Table columns={["28%", "auto"]}>

| Attribute       | Value                              |
| --------------- | ---------------------------------- |
| `data-selected` | Present when the item is selected. |

</Table>

##### Composer.Link [#primitives-Composer.Link]

Displays links within `Composer.Editor`.

```tsx
<Composer.Link href={href}>{children}</Composer.Link>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.Submit [#primitives-Composer.Submit]

A button to submit the composer.

```tsx
<Composer.Submit>Send</Composer.Submit>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.FloatingToolbar [#primitives-Composer.FloatingToolbar]

Displays a floating toolbar attached to the selection within `Composer.Editor`.

```tsx
<Composer.FloatingToolbar>
  <Composer.MarkToggle mark="bold">Bold</Composer.MarkToggle>
  <Composer.MarkToggle mark="italic">Italic</Composer.MarkToggle>
</Composer.FloatingToolbar>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.MarkToggle

A toggle button which toggles a specific text mark.

```tsx
<Composer.MarkToggle mark="bold">Bold</Composer.MarkToggle>
```

<PropertiesList>
  <PropertiesListItem name="mark" type="ComposerBodyMark" required>
    The text mark to toggle.
  </PropertiesListItem>
  <PropertiesListItem
    name="onValueChange"
    type="function"
    detailedType="(mark: ComposerBodyMark) => void"
  >
    The event handler called when the mark is toggled.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.AttachFiles [#primitives-Composer.AttachFiles]

A button which opens a file picker to create attachments.

```tsx
<Composer.AttachFiles>Attach files</Composer.AttachFiles>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Composer.AttachmentsDropArea [#primitives-Composer.AttachmentsDropArea]

A drop area which accepts files to create attachments.

```tsx
<Composer.AttachmentsDropArea>Drop files here</Composer.AttachmentsDropArea>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

#### Comment [#primitives-Comment]

Used to render a single comment.

```tsx
<Comment.Body
  components={{
    Mention: <Comment.Mention />,
    Link: <Comment.Link />,
  }}
/>
```

Map through `thread.comments` to render each comment in a thread. Threads can be
retrieved with [`useThreads`](/docs/api-reference/liveblocks-react#useThreads).

```tsx highlight="13-21"
import {
  Comment,
  CommentBodyLinkProps,
  CommentBodyMentionProps,
} from "@liveblocks/react-ui/primitives";
import { ThreadData } from "@liveblocks/client";

// Render custom comments in a thread. Pass a thread from `useThreads`.
function MyComments({ thread }: { thread: ThreadData }) {
  return (
    <>
      {thread.comments.map((comment) => (
        <div key={comment.id}>
          <Comment.Body
            body={comment.body}
            components={{
              Mention,
              Link,
            }}
          />
        </div>
      ))}
    </>
  );
}

// Render a mention in the comment, e.g. "@Emil Joyce"
function Mention({ userId }: CommentBodyMentionProps) {
  return <Comment.Mention>@{userId}</Comment.Mention>;
}

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

##### Comment.Body [#primitives-Comment.Body]

Displays a comment body.

```tsx
<Comment.Body body={comment.body} />
```

<PropertiesList>
  <PropertiesListItem name="body" type="CommentBody">
    The comment body to display. If not defined, the component will render
    `null`.
  </PropertiesListItem>
  <PropertiesListItem name="components" type="Partial<CommentBodyComponents>">
    The components displayed within the comment body.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

###### components [#primitives-Comment.Body-components]

The components displayed within the comment body.

<PropertiesList>
  <PropertiesListItem
    name="Mention"
    type="ComponentType<CommentBodyMentionProps>"
  >
    The component used to display mentions. Defaults to the mention’s `userId`
    prefixed by an @.
  </PropertiesListItem>
  <PropertiesListItem name="Link" type="ComponentType<CommentBodyLinkProps>">
    The component used to display links. Defaults to the link’s `children`
    property.
  </PropertiesListItem>
</PropertiesList>

###### Mention [#primitives-Comment.Body-Mention]

The component used to display mentions.

```tsx
<Comment.Body
  components={{
    Mention: ({ userId }) => <Comment.Mention>@{userId}</Comment.Mention>,
  }}
/>
```

<PropertiesList>
  <PropertiesListItem name="userId" type="string">
    The mention’s user ID.
  </PropertiesListItem>
</PropertiesList>

###### Link [#primitives-Comment.Body-Link]

The component used to display links.

```tsx
<Comment.Body
  components={{
    Link: ({ href, children }) => (
      <Comment.Link href={href}>{children}</Comment.Link>
    ),
  }}
/>
```

<PropertiesList>
  <PropertiesListItem name="href" type="string">
    The link’s absolute URL.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode">
    The link’s content.
  </PropertiesListItem>
</PropertiesList>

##### Comment.Mention [#primitives-Comment.Mention]

Displays mentions within `Comment.Body`.

```tsx
<Comment.Mention>@{userId}</Comment.Mention>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

##### Comment.Link [#primitives-Comment.Link]

Displays links within `Comment.Body`.

```tsx
<Comment.Link href={href}>{children}</Comment.Link>
```

<PropertiesList>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

#### Timestamp [#primitives-Timestamp]

Displays a formatted date, and automatically re-renders to support relative
formatting. Defaults to relative formatting for recent dates (e.g. “5 minutes
ago”) and a short absolute formatting for older ones (e.g. “25 Aug”).

```tsx
<Timestamp date={new Date()} />
```

Use with `comment.createdAt`, `comment.editedAt`, or `comment.deletedAt` to
display a human-readable time.

```tsx highlight="8"
import { ThreadData, Timestamp } from "@liveblocks/react-ui";

function MyComments({ thread }: { thread: ThreadData }) {
  return (
    <>
      {thread.comments.map((comment) => (
        <div key={comment.id}>
          <Timestamp date={comment.createdAt} />
          <Comment.Body body={comment.body} components={/* ... */} />
        </div>
      ))}
    </>
  );
}
```

<PropertiesList>
  <PropertiesListItem name="date" type="Date | string | number" required>
    The date to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="children"
    type="function"
    detailedType="(date: Date) => ReactNode"
  >
    A function to format the displayed date. Defaults to a relative date
    formatting function.
  </PropertiesListItem>
  <PropertiesListItem
    name="title"
    type="string | function"
    detailedType="string | ((date: Date) => string)"
  >
    The `title` attribute’s value or a function to format it. Defaults to an
    absolute date formatting function.
  </PropertiesListItem>
  <PropertiesListItem
    name="interval"
    type="number | false"
    defaultValue="30000"
  >
    The interval in milliseconds at which the component will re-render. Can be
    set to `false` to disable re-rendering.
  </PropertiesListItem>
  <PropertiesListItem name="locale" type="string">
    The locale used when formatting the date. Defaults to the browser’s locale.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

#### FileSize [#primitives-FileSize]

Displays a formatted file size.

```tsx
<FileSize size={100000} />
```

Use with `attachment.size` to display a human-readable file size.

```tsx
import { CommentData, FileSize } from "@liveblocks/react-ui";

function MyComment({ comment }: { comment: CommentData }) {
  return (
    <div>
      {/* ... */}

      {comment.attachments.map((attachment) => (
        <div key={attachment.id}>
          {attachment.name}
          // +++
          <FileSize size={attachment.size} />
          // +++
        </div>
      ))}
    </div>
  );
}
```

<PropertiesList>
  <PropertiesListItem name="size" type="number" required>
    The file size to display.
  </PropertiesListItem>
  <PropertiesListItem
    name="children"
    type="function"
    detailedType="(size: number) => ReactNode"
  >
    A function to format the displayed file size. Defaults to a human-readable
    file size formatting function.
  </PropertiesListItem>
  <PropertiesListItem name="locale" type="string">
    The locale used when formatting the file size. Defaults to the browser’s
    locale.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

### Hooks

#### useComposer

Returns states and methods related to the composer. Can only be used within the
[`Composer.Form`](#primitives-Composer.Form) primitive.
[All values listed below](#useComposer-values).

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

const { isEmpty, attachments, submit /* ... */ } = useComposer();
```

##### Custom composer behavior

`useComposer` can be used in combination with
[`Composer` primitives](#primitives-Composer) to create a custom composer, and
control its behavior. For example, `createMention` allows you to create a button
which focuses the editor, adds `@`, and opens the mention suggestions dropdown.

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

function MyComposer() {
  const createThread = useCreateThread();

  return (
    <Composer.Form
      onComposerSubmit={({ body, attachments }) => {
        const thread = createThread({
          body,
          attachments,
          metadata: {},
        });
      }}
    >
      <Editor />
    </Composer.Form>
  );
}

function Editor() {
  // +++
  const { createMention } = useComposer();
  // +++

  return (
    <>
      <Composer.Editor components={/* Your custom component parts */} />
      // +++
      <button onClick={createMention}>Add mention</button>
      // +++
    </>
  );
}
```

##### Handle attachments

When using primitives,
[`Composer.AttachFiles`](#primitives-Composer.AttachFiles) and
[`Composer.AttachmentsDropArea`](#primitives-Composer.AttachmentsDropArea) add
attachments to the composer, but they’re not rendered without `useComposer`. The
`attachments` array can be used to render the current attachments, and
`removeAttachment` allows you to remove them.

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

function MyComposer() {
  const createThread = useCreateThread();

  return (
    <Composer.Form
      onComposerSubmit={({ body, attachments }) => {
        const thread = createThread({
          body,
          attachments,
          metadata: {},
        });
      }}
    >
      <Composer.Editor components={/* Your custom component parts */} />
      // +++
      <MyComposerAttachments />
      // +++
      <Composer.AttachFiles>Attach Files</Composer.AttachFiles>
      <Composer.Submit>Submit</Composer.Submit>
    </Composer.Form>
  );
}

function MyComposerAttachments() {
  // +++
  const { attachments, removeAttachment } = useComposer();
  // +++

  return (
    <div>
      // +++
      {attachments.map((attachment) => (
        <div key={attachment.id}>
          {attachment.name} ({attachment.status})
          <button onClick={() => removeAttachment(attachment.id)}>
            Remove
          </button>
        </div>
      ))}
      // +++
    </div>
  );
}
```

##### Values [#useComposer-values]

<PropertiesList>
  <PropertiesListItem name="isDisabled" type="boolean">
    Whether the composer is currently disabled.
  </PropertiesListItem>
  <PropertiesListItem name="isFocused" type="boolean">
    Whether the editor is currently focused.
  </PropertiesListItem>
  <PropertiesListItem name="isEmpty" type="boolean">
    Whether the editor is currently empty.
  </PropertiesListItem>
  <PropertiesListItem name="canSubmit" type="boolean">
    Whether the composer can currently be submitted.
  </PropertiesListItem>
  <PropertiesListItem name="submit" type="function" detailedType="() => void">
    Submit the editor programmatically.
  </PropertiesListItem>
  <PropertiesListItem name="clear" type="function" detailedType="() => void">
    Clear the editor programmatically.
  </PropertiesListItem>
  <PropertiesListItem name="select" type="function" detailedType="() => void">
    Select the editor programmatically.
  </PropertiesListItem>
  <PropertiesListItem name="focus" type="function" detailedType="() => void">
    Focus the editor programmatically.
  </PropertiesListItem>
  <PropertiesListItem name="blur" type="function" detailedType="() => void">
    Blur the editor programmatically.
  </PropertiesListItem>
  <PropertiesListItem name="marks" type="ComposerBodyMarks">
    Which text marks are currently active and which aren’t.
  </PropertiesListItem>
  <PropertiesListItem
    name="toggleMark"
    type="function"
    detailedType="(mark: ComposerBodyMark) => void"
  >
    Remove an attachment by its ID.
  </PropertiesListItem>
  <PropertiesListItem
    name="createMention"
    type="function"
    detailedType="() => void"
  >
    Start creating a mention at the current selection.
  </PropertiesListItem>
  <PropertiesListItem
    name="insertText"
    type="function"
    detailedType="(text: string) => void"
  >
    Insert text at the current selection.
  </PropertiesListItem>
  <PropertiesListItem
    name="attachFiles"
    type="function"
    detailedType="() => void"
  >
    Open a file picker programmatically to create attachments.
  </PropertiesListItem>
  <PropertiesListItem name="attachments" type="ComposerAttachment[]">
    The composer’s current attachments.
  </PropertiesListItem>
  <PropertiesListItem
    name="removeAttachment"
    type="function"
    detailedType="(attachmentId: string) => void"
  >
    Remove an attachment by its ID.
  </PropertiesListItem>
</PropertiesList>

#### Other hooks

Other Comments hooks are part of
[`@liveblocks/react`](/docs/api-reference/liveblocks-react), you can find them
on the
[React API reference page](/docs/api-reference/liveblocks-react#Comments).

- [`useThreads`](/docs/api-reference/liveblocks-react#useThreads)
- [`useThreadSubscription`](/docs/api-reference/liveblocks-react#useThreadSubscription)
- [`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)
- [`useMarkThreadAsRead`](/docs/api-reference/liveblocks-react#useMarkThreadAsRead)
- [`useCreateComment`](/docs/api-reference/liveblocks-react#useCreateComment)
- [`useEditComment`](/docs/api-reference/liveblocks-react#useEditComment)
- [`useDeleteComment`](/docs/api-reference/liveblocks-react#useDeleteComment)
- [`useAddReaction`](/docs/api-reference/liveblocks-react#useAddReaction)
- [`useRemoveReaction`](/docs/api-reference/liveblocks-react#useRemoveReaction)
- [`useAttachmentUrl`](/docs/api-reference/liveblocks-react#useAttachmentUrl)

## Notifications

### Default components

#### InboxNotification

Displays a single inbox notification.

```tsx
<InboxNotification inboxNotification={inboxNotification} />
```

<Figure>
  <Image
    src="/assets/notifications/inbox-notification.png"
    alt="InboxNotification"
    width={768}
    height={446}
  />
</Figure>

Map through `inboxNotifications` with
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
to render a list of the room’s notifications.

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

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

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

##### Rendering notification kinds differently

Different `kinds` of notifications are available, for example `thread` which is
triggered when using Comments, or `$myCustomNotification` which would be a
custom notification you’ve triggered manually. You can choose to render each
notification differently.

```tsx highlight="4-14"
<InboxNotification
  inboxNotification={inboxNotification}
  kinds={{
    thread: (props) => (
      <InboxNotification.Thread {...props} showRoomName={false} />
    ),
    $myCustomNotification: (props) => (
      <InboxNotification.Custom
        {...props}
        title="New notification"
        aside={<InboxNotification.Icon>❕</InboxNotification.Icon>}
      >
        My custom notification
      </InboxNotification.Custom>
    ),
  }}
/>
```

Adding these two properties to `kinds` will overwrite the default component
that’s displayed for those two notification types. Using
[`InboxNotification.Thread`](/docs/api-reference/liveblocks-react-ui#InboxNotification.Thread)
and
[`InboxNotification.Custom`](/docs/api-reference/liveblocks-react-ui#InboxNotification.Custom)
in this way allow you to easily create components that fit into the existing
design system, whilst still adding lots of customization. However, it’s also
valid to render any custom JSX.

```tsx highlight="3-5"
<InboxNotification
  inboxNotification={inboxNotification}
  kinds={{
    $myCustomNotification: (props) => <div>New notification</div>,
  }}
/>
```

##### 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
    // ...
  }
}
```

Your activities data is now correctly typed in inline functions.

```tsx highlight="5-6"
<InboxNotification
  inboxNotification={inboxNotification}
  kinds={{
    $alert: (props) => {
      // `title` and `message` are correctly typed, as defined in your config
      const { title, message } = props.inboxNotification.activities[0].data;

      return (
        <InboxNotification.Custom
          {...props}
          title={title}
          aside={<InboxNotification.Icon>❗</InboxNotification.Icon>}
        >
          {message}
        </InboxNotification.Custom>
      );
    },
  }}
/>
```

If you’d like to create a typed function elsewhere, you can use
`InboxNotificationCustomProps` with a generic. In the example below we’re using
the `$alert` notification kind as a generic,
`InboxNotificationCustomKindProps<"$alert">`.

```tsx highlight="6-8,25"
import {
  InboxNotification,
  InboxNotificationCustomKindProps,
} from "@liveblocks/react-ui";

function AlertNotification(props: InboxNotificationCustomKindProps<"$alert">) {
  // `title` and `message` are correctly typed, as defined in your config
  const { title, message } = props.inboxNotification.activities[0].data;

  return (
    <InboxNotification.Custom
      {...props}
      title={title}
      aside={<InboxNotification.Icon>❗</InboxNotification.Icon>}
    >
      {message}
    </InboxNotification.Custom>
  );
}

function Notification({ inboxNotification }) {
  return (
    <InboxNotification
      inboxNotification={inboxNotification}
      kinds={{ $alert: AlertNotification }}
    />
  );
}
```

##### Props [#InboxNotification-props]

<PropertiesList>
  <PropertiesListItem
    name="inboxNotification"
    type="InboxNotificationData"
    required
  >
    The inbox notification to display.
  </PropertiesListItem>
  <PropertiesListItem name="href" type="string">
    The URL which the inbox notification links to.
  </PropertiesListItem>
  <PropertiesListItem name="showActions" type='boolean | "hover"'>
    How to show or hide the actions.
  </PropertiesListItem>
  <PropertiesListItem name="kinds" type="Partial<InboxNotificationKinds>">
    Override specific kinds of inbox notifications.
  </PropertiesListItem>
  <PropertiesListItem
    name="overrides"
    type="Partial<GlobalOverrides & InboxNotificationOverrides & CommentOverrides>"
  >
    Override the component’s strings.
  </PropertiesListItem>
  <PropertiesListItem name="components" type="Partial<GlobalComponents>">
    Override the component’s components.
  </PropertiesListItem>
</PropertiesList>

###### kinds [#InboxNotification-kinds]

Override specific kinds of inbox notifications.

<PropertiesList>
  <PropertiesListItem
    name="thread"
    type="ComponentType<InboxNotificationThreadKindProps>"
  >
    The component used to display thread notifications. Defaults to
    `InboxNotification.Thread`.
  </PropertiesListItem>
  <PropertiesListItem
    name="$${string}"
    type="ComponentType<InboxNotificationCustomKindProps>"
  >
    The component used to display a custom notification kind. Custom
    notification kinds must start with a `$`.
  </PropertiesListItem>
</PropertiesList>

###### InboxNotification.Thread [#InboxNotification.Thread]

Displays a thread inbox notification.

```tsx
<InboxNotification
  inboxNotification={inboxNotification}
  kinds={{
    thread: (props) => (
      <InboxNotification.Thread {...props} showRoomName={false} />
    ),
  }}
/>
```

<PropertiesList>
  <PropertiesListItem
    name="inboxNotification"
    type="InboxNotificationThreadData"
    required
  >
    The inbox notification to display.
  </PropertiesListItem>
  <PropertiesListItem name="showActions" type='boolean | "hover"'>
    How to show or hide the actions.
  </PropertiesListItem>
  <PropertiesListItem name="showRoomName" type="boolean" defaultValue="true">
    Whether to show the room name in the title.
  </PropertiesListItem>
  <PropertiesListItem name="showReactions" type="boolean" defaultValue="true">
    Whether to show reactions.
  </PropertiesListItem>
  <PropertiesListItem name="showAttachments" type="boolean" defaultValue="true">
    Whether to show attachments.
  </PropertiesListItem>
</PropertiesList>

###### InboxNotification.Custom [#InboxNotification.Custom]

Displays a custom notification kind.

```tsx
<InboxNotification
  inboxNotification={inboxNotification}
  kinds={{
    $myCustomNotificationKind: (props) => {
      const activityData = props.inboxNotification.activities[0].data;

      return (
        <InboxNotification.Custom
          title={
            <>
              User <strong>{activityData.file}</strong>
            </>
          }
          aside={<InboxNotification.Icon>❌</InboxNotification.Icon>}
          {...props}
        >
          {activityData.errorDescription}
        </InboxNotification.Custom>
      );
    },
  }}
/>
```

<PropertiesList>
  <PropertiesListItem
    name="inboxNotification"
    type="InboxNotificationCustomData"
    required
  >
    The inbox notification to display.
  </PropertiesListItem>
  <PropertiesListItem name="title" type="ReactNode" required>
    The inbox notification’s title.
  </PropertiesListItem>
  <PropertiesListItem name="children" type="ReactNode" required>
    The inbox notification’s content.
  </PropertiesListItem>
  <PropertiesListItem name="showActions" type='boolean | "hover"'>
    How to show or hide the actions.
  </PropertiesListItem>
  <PropertiesListItem name="aside" type="ReactNode">
    The inbox notification’s aside content. Can be combined with{" "}
    <code>InboxNotification.Icon</code> or <code>InboxNotification.Avatar</code>{" "}
    to easily follow default styles.
  </PropertiesListItem>
  <PropertiesListItem name="asChild" type="boolean" defaultValue="false">
    Replace the rendered element by the one passed as a child.
  </PropertiesListItem>
</PropertiesList>

#### InboxNotificationList

Displays inbox notifications as a list. Each
[`InboxNotification`](#InboxNotification) component will be wrapped in a `li`
element.

```tsx
<InboxNotificationList>
  <InboxNotification />
  <InboxNotification />
  <InboxNotification />
</InboxNotificationList>
```

<Figure>
  <Image
    src="/assets/notifications/inbox-notification-list.png"
    alt="InboxNotificationList"
    width={768}
    height={446}
  />
</Figure>

##### Props [#InboxNotificationList-props]

<PropertiesList>
  <PropertiesListItem name="children" type="ReactNode">
    The inbox notifications to display.
  </PropertiesListItem>
</PropertiesList>

### Hooks [#Notification-hooks]

All hooks for Notifications are in
[`@liveblocks/react`](/docs/api-reference/liveblocks-react#Notifications).

## Version History

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

When enabled, version history will automatically create versions of your
[Lexical](https://liveblocks.io/docs/api-reference/liveblocks-react-lexical) or
[Yjs](/docs/api-reference/liveblocks-yjs) document and allow you to restore to
specific versions. These components aid in displaying a list of those versions.

### Default components

### HistoryVersionSummary

Displays a version summary which includes the author and date.

```tsx
<HistoryVersionSummary
  onClick={() => {
    setSelectedVersionId(version.id);
  }}
  version={version}
  selected={version.id === selectedVersionId}
/>
```

##### Props [#HistoryVersionSummary-props]

<PropertiesList>
  <PropertiesListItem name="onClick" type="() => void">
    The function to call when the version summary is clicked.
  </PropertiesListItem>
  <PropertiesListItem name="version" type="Version">
    The version object containing information about the specific version.
  </PropertiesListItem>
  <PropertiesListItem name="selected" type="boolean">
    Whether this version is currently selected.
  </PropertiesListItem>
</PropertiesList>

#### HistoryVersionSummaryList

Displays a list of version summaries for a document’s history including authors
and dates.

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

##### Props [#HistoryVersionSummaryList-props]

<PropertiesList>
  <PropertiesListItem name="children" type="ReactNode">
    The version summaries to display, typically an array of
    HistoryVersionSummary components.
  </PropertiesListItem>
</PropertiesList>

## Utilities

### Components [#utilities-components]

#### Icon

Most icons used in the default components can be exported via `<Icon.* />`.
They’re stroke-based and designed for use at 20×20 pixels.

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

<Icon.QuestionMark />
<Icon.Mention  />
```

Find a full list of available icons in
[our GitHub repo](https://github.com/liveblocks/liveblocks/blob/main/packages/liveblocks-react-ui/src/icon.ts).

#### LiveblocksUIConfig

Set configuration options for all `@liveblocks/react-ui` components, such as
[overrides](#overrides).

```tsx
<LiveblocksUIConfig overrides={{ locale: "fr", USER_UNKNOWN: "Anonyme" }} />
```

##### Props [#LiveblocksUIConfig-props]

<PropertiesList>
  <PropertiesListItem name="overrides" type="Partial<Overrides>">
    Override the components’ strings.
  </PropertiesListItem>
  <PropertiesListItem name="components" type="Partial<Components>">
    Override the components’ components.
  </PropertiesListItem>
  <PropertiesListItem
    name="portalContainer"
    type="HTMLElement"
    defaultValue="document.body"
  >
    The container to render the portal into.
  </PropertiesListItem>
  <PropertiesListItem
    name="preventUnsavedComposerChanges"
    type="boolean"
    defaultValue="true"
  >
    When `preventUnsavedChanges` is set on your Liveblocks client (or set on
    `LiveblocksProvider`), then closing a browser tab will be prevented when
    there are unsaved changes. By default, that will include draft texts or
    attachments that are (being) uploaded via comments/threads composers, but
    not submitted yet. If you want to prevent unsaved changes with Liveblocks,
    but not for composers, you can opt-out by setting this option to `false`.
  </PropertiesListItem>
</PropertiesList>

### Hooks [#Version-History-hooks]

All hooks for Version History are in
[`@liveblocks/react`](/docs/api-reference/liveblocks-react#Version-History).

## Styling and customization

### Default styles

The default components come with default styles. These styles can be imported
into the root of your app or directly into a CSS file with `@import`.

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

### Dark mode

You can also import default dark mode styling. There are two versions to choose
from, the first uses the
[system theme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme).

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

The second uses the `dark` class name, and two commonly used data attributes.

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

{/* TODO: Mention --elevation-background, --elevation-foreground here */}

### CSS variables

The default components are built around a set of customizable CSS variables. Set
these variables within `.lb-root` to globally style your components.

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

<PropertiesList>
  <PropertiesListItem name="--lb-radius" defaultValue="0.5em">
    The border radius scale. `em` values recommended.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-spacing" defaultValue="1em">
    The spacing scale. `em` values recommended.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-accent" defaultValue="#1177ff">
    The accent color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-accent-foreground" defaultValue="#ffffff">
    The foreground color used over the accent color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-destructive" defaultValue="#ff4455">
    The destructive color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-destructive-foreground" defaultValue="#ffffff">
    The foreground color used over the destructive color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-background" defaultValue="#ffffff">
    The main background color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-foreground" defaultValue="#111111">
    The main foreground color.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-line-height" defaultValue="1.5">
    The line height of main elements (e.g. comment bodies).
  </PropertiesListItem>
  <PropertiesListItem name="--lb-icon-size" defaultValue="20px">
    The size of icons.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-icon-weight" defaultValue="1.5px">
    The stroke weight of icons.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-avatar-radius" defaultValue="50%">
    The border radius used for avatars.
  </PropertiesListItem>
  <PropertiesListItem
    name="--lb-button-radius"
    defaultValue="calc(0.75 * var(--lb-radius))"
  >
    The border radius used for buttons.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-transition-duration" defaultValue="0.1s">
    The duration used for transitioned elements.
  </PropertiesListItem>
  <PropertiesListItem
    name="--lb-transition-easing"
    defaultValue="cubic-bezier(0.4, 0, 0.2, 1)"
  >
    The easing function used for transitioned elements.
  </PropertiesListItem>
  <PropertiesListItem
    name="--lb-elevation-shadow"
    defaultValue="0 0 0 1px rgb(0 0 0 / 4%), 0 2px 6px rgb(0 0 0 / 8%),  0 8px 26px rgb(0 0 0 / 12%)"
  >
    The box shadow added to elevated elements.
  </PropertiesListItem>
  <PropertiesListItem
    name="--lb-tooltip-shadow"
    defaultValue="0 2px 4px rgb(0 0 0 / 8%), 0 4px 12px rgb(0 0 0 / 12%)"
  >
    The box shadow added to tooltips.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-accent-contrast" defaultValue="8%">
    Affects the lightness of accent colors. `%` value required.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-destructive-contrast" defaultValue="8%">
    Affects the lightness of destructive colors. `%` value required.
  </PropertiesListItem>
  <PropertiesListItem name="--lb-foreground-contrast" defaultValue="6%">
    Affects the lightness of foreground colors. `%` value required.
  </PropertiesListItem>
</PropertiesList>

{/* TODO: Explain automatic color scales (with a palette-type visual) */}

### Class names

Each default component has a set of predefined class names, which can be helpful
for custom styling, for example.

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

.lb-composer {
  /* Customise composer */
}
```

Additionally, some elements also have data attributes to provide contextual
information, for example:

```css
.lb-button[data-variant="primary"] {
  /* Customise primary buttons */
}

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

<Banner title="Internal classes" type="warning">

Classes containing colons `:` are internal and may change over time.

</Banner>

{/* TODO: Think about adding back the browser support section */}

### Portaled elements

Floating elements within the default components (e.g. tooltips, drowdowns, etc)
are portaled to the end of the document to avoid `z-index` conflicts and
`overflow` issues.

When portaled, those elements are also wrapped in a container to handle their
positioning. These containers don’t have any specific class names or data
attributes so they shouldn’t be targeted or styled directly, but they will
mirror whichever `z-index` value is set on their inner element (which would be
`auto` by default). So if you need to set a specific `z-index` value on floating
elements, you should set it on the floating elements themselves directly,
ignoring their containers. You can either target specific floating elements
(e.g. `.lb-tooltip`, `.lb-dropdown`, etc) or all of them at once via the
`.lb-portal` class name.

```css
/* Target all floating elements */
.lb-portal {
  z-index: 5;
}

/* Target a specific floating element */
.lb-tooltip {
  z-index: 10;
}
```

### Overrides

Overrides can be used to customize components’ strings and localization-related
properties, such as locale and reading direction.

They can be set globally for all components using `LiveblocksUIConfig`:

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

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

Overrides can also be set per-component, and these settings will take precedence
over global settings. This is particularly useful in certain contexts, for
example when you’re using a `<Composer />` component for creating replies to
threads:

```tsx
<Composer
  overrides={{
    COMPOSER_PLACEHOLDER: "Reply to thread…",
    COMPOSER_SEND: "Reply",
  }}
/>
```

---
meta:
  title: "@liveblocks/react"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/react package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/react` provides you with [React](https://react.dev/) bindings for
our realtime collaboration APIs, built on top of WebSockets. Read our
[getting started](/docs/get-started) guides to learn more.

## Suspense

All Liveblocks React components and hooks can be exported from two different
locations, `@liveblocks/react/suspense` and `@liveblocks/react`. This is because
Liveblocks provides two types of hooks; those that support
[React Suspense](https://react.dev/reference/react/Suspense), and those that
don’t.

```tsx
// Import the Suspense hook
import { useThreads } from "@/liveblocks/react/suspense";

// Import the regular hook
import { useThreads } from "@/liveblocks/react";
```

We recommend importing from `@liveblocks/react/suspense` and using Suspense by
default, as it often makes it easier to build your collaborative application.

<Banner title="Enable Suspense with createRoomContext">

If you’re using the non-standard [`createRoomContext`](#createRoomContext)
function to build your hooks, you must
[enable suspense differently](#createRoomContext-Suspense).

</Banner>

### Suspense hooks

Suspense hooks can be wrapped in [`ClientSideSuspense`][], which acts as a
loading spinner for any components below it. When using this, all components
below will only render once their hook contents have been loaded.

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

function App() {
  <ClientSideSuspense fallback={<div>Loading…</div>}>
    <Component />
  </ClientSideSuspense>;
}

function Component() {
  // `animals` is always defined
  const animals = useStorage((root) => root.animals);

  // ...
}
```

Advanced hooks using the `{ ..., error, isLoading }` syntax, such as
[`useThreads`][], can also use
[`ErrorBoundary`](https://github.com/bvaughn/react-error-boundary) to render an
error if the hook runs into a problem.

```tsx
import { ClientSideSuspense, useThreads } from "@liveblocks/react/suspense";
import { ErrorBoundary } from "react-error-boundary";

function App() {
  return (
    <ErrorBoundary fallback={<div>Error</div>}>
      <ClientSideSuspense fallback={<div>Loading…</div>}>
        <Component />
      </ClientSideSuspense>
    </ErrorBoundary>
  );
}

function Component() {
  // `threads` is always defined
  const { threads } = useThreads();

  // ...
}
```

An advantage of Suspense hooks is that you can have multiple different hooks in
your tree, and you only need a single `ClientSideSuspense` component to render a
loading spinner for all of them.

### Regular hooks

Regular hooks often return `null` whilst a component is loading, and you must
check for this to render a loading spinner.

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

function Component() {
  // `animals` is `null` when loading
  const animals = useStorage((root) => root.animals);

  if (!animals) {
    return <div>Loading…</div>;
  }

  // ...
}
```

Advanced hooks using the `{ ..., error, isLoading }` syntax, such as
[`useThreads`][], require you to make sure there isn’t a problem before using
the data.

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

function Component() {
  // Check for `error` and `isLoading` before `threads` is defined
  const { threads, error, isLoading } = useThreads();

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

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

  // ...
}
```

### ClientSideSuspense

Liveblocks provides a component named `ClientSideSuspense` which works as a
replacement for `Suspense`. This is helpful as our Suspense hooks will throw an
error when they’re run on the server, and this component avoids this issue by
always rendering the `fallback` on the server.

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

function Page() {
  return (
    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      <RoomProvider id="my-room-id">
        +++
        <ClientSideSuspense fallback={<div>Loading…</div>}>
          <App />
        </ClientSideSuspense>
        +++
      </RoomProvider>
    </LiveblocksProvider>
  );
}
```

#### Loading spinners

Instead of wrapping your entire Liveblocks application inside a single
`ClientSideSuspense` component, you can use multiple of these components in
different parts of your application, and each will work as a loading fallback
for any components further down your tree.

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

function Page() {
  return (
    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      <RoomProvider id="my-room-id">
        <header>My title</header>

        <main>
          +++
          <ClientSideSuspense fallback={<div>Loading…</div>}>
            <Canvas />
          </ClientSideSuspense>
          +++
        </main>

        <aside>
          +++
          <ClientSideSuspense fallback={<div>Loading…</div>}>
            <LiveAvatars />
          </ClientSideSuspense>
          +++
        </aside>
      </RoomProvider>
    </LiveblocksProvider>
  );
}
```

This is a great way to build a static skeleton around your dynamic collaborative
application.

## Liveblocks

### LiveblocksProvider

Sets up a client for connecting to Liveblocks, and is the recommended way to do
this for React apps. You must define either `authEndpoint` or `publicApiKey`.
Resolver functions should be placed inside here, and a number of other options
are available, which correspond with those passed to [`createClient`][]. Unlike
[`RoomProvider`][], `LiveblocksProvider` doesn’t call Liveblocks servers when
mounted, and it should be placed higher in your app’s component tree.

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

function App() {
  return (
    <LiveblocksProvider
    // publicApiKey=""
    // authEndpoint="/api/liveblocks-auth"
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

```tsx title="All LiveblocksProvider props" isCollapsable isCollapsed
import { LiveblocksProvider } from "@liveblocks/react/suspense";

function App() {
  return (
    <LiveblocksProvider
      // Connect with authEndpoint
      authEndpoint="/api/liveblocks-auth"
      // ---
      // Alternatively, use an authEndpoint callback
      // authEndpoint={async (room) => {
      //   const response = await fetch("/api/liveblocks-auth", {
      //     method: "POST",
      //     headers: {
      //       Authentication: "<your own headers here>",
      //       "Content-Type": "application/json",
      //     },
      //     body: JSON.stringify({ room }),
      //   });
      //   return await response.json();
      // }}
      //
      // Alternatively, use a public key
      // publicApiKey="pk_..."
      //
      // Throttle time (ms) between WebSocket updates
      throttle={100}
      // ---
      // Prevent browser tab from closing while local changes aren’t synchronized yet
      preventUnsavedChanges={false}
      // ---
      // Throw lost-connection event after 5 seconds offline
      lostConnectionTimeout={5000}
      // ---
      // Disconnect users after X (ms) of inactivity, disabled by default
      backgroundKeepAliveTimeout={undefined}
      // ---
      // Resolve user info for Comments and Notifications
      resolveUsers={async ({ userIds }) => {
        const usersData = await __getUsersFromDB__(userIds);

        return usersData.map((userData) => ({
          name: userData.name,
          avatar: userData.avatar.src,
        }));
      }}
      // ---
      // Resolve room info for Notifications
      resolveRoomsInfo={async ({ roomIds }) => {
        const documentsData = await __getDocumentsFromDB__(roomIds);

        return documentsData.map((documentData) => ({
          name: documentData.name,
          // url: documentData.url,
        }));
      }}
      // ---
      // Resolve mention suggestions for Comments
      resolveMentionSuggestions={async ({ text, roomId }) => {
        const workspaceUsers = await __getWorkspaceUsersFromDB__(roomId);

        if (!text) {
          // Show all workspace users by default
          return __getUserIds__(workspaceUsers);
        } else {
          const matchingUsers = __findUsers__(workspaceUsers, text);
          return __getUserIds__(matchingUsers);
        }
      }}
      // ---
      // Polyfill options for non-browser environments
      polyfills={
        {
          // atob,
          // fetch,
          // WebSocket,
        }
      }
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

<PropertiesList title="Props">
  <PropertiesListItem
    name="authEndpoint"
    detailedType="string | async ((room?: string) => CustomAuthenticationResult)"
  >
    The URL of your back end’s [authentication endpoint](/docs/authentication)
    as a string, or an async callback function that returns a Liveblocks token
    result. Either `authEndpoint` or `publicApikey` are required. Learn more
    about [using a URL string](#LiveblocksProviderAuthEndpoint) and [using a
    callback](#LiveblocksProviderCallback).
  </PropertiesListItem>
  <PropertiesListItem name="publicApiKey" type="string">
    The public API key taken from your project’s
    [dashboard](/dashboard/apikeys). Generally not recommended for production
    use. Either `authEndpoint` or `publicApikey` are required. [Learn
    more](#LiveblocksProviderPublicKey).
  </PropertiesListItem>
  <PropertiesListItem name="throttle" type="number" defaultValue="100">
    The throttle time between WebSocket messages in milliseconds, a number
    between `16` and `1000` is allowed. Using `16` means your app will update 60
    times per second. [Learn more](#LiveblocksProviderThrottle).
  </PropertiesListItem>
  <PropertiesListItem
    name="preventUnsavedChanges"
    type="boolean"
    defaultValue="false"
  >
    When set, navigating away from the current page is prevented while
    Liveblocks is still synchronizing local changes. [Learn
    more](#prevent-users-losing-unsaved-changes).
  </PropertiesListItem>
  <PropertiesListItem
    name="lostConnectionTimeout"
    type="number"
    defaultValue="5000"
  >
    After a user disconnects, the time in milliseconds before a
    [`"lost-connection"`](/docs/api-reference/liveblocks-client#Room.subscribe.lost-connection)
    event is fired. [Learn more](#LiveblocksProviderLostConnectionTimeout).
  </PropertiesListItem>
  <PropertiesListItem name="backgroundKeepAliveTimeout" type="number">
    The time before an inactive WebSocket connection is disconnected. This is
    disabled by default, but setting a number will activate it. [Learn
    more](#LiveblocksProviderBackgroundKeepAliveTimeout).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveUsers"
    detailedType='async? (args: ResolveUsersArgs) => (UserMeta["info"] | undefined)[] | undefined'
  >
    A function that resolves user information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `UserMeta["info"]` objects in the same order they arrived. [Learn
    more](#LiveblocksProviderResolveUsers).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveRoomsInfo"
    detailedType="async? (args: ResolveRoomsInfoArgs) => (RoomInfo | undefined)[] | undefined"
  >
    A function that resolves room information in
    [Comments](/docs/ready-made-features/comments). Return an array of
    `RoomInfo` objects in the same order they arrived. [Learn
    more](#LiveblocksProviderResolveRoomsInfo).
  </PropertiesListItem>
  <PropertiesListItem
    name="resolveMentionSuggestions"
    detailedType="async? (args: ResolveMentionSuggestionsArgs) => string[]"
  >
    A function that resolves mention suggestions in
    [Comments](/docs/ready-made-features/comments). Return an array of user IDs.
    [Learn more](#LiveblocksProviderResolveMentionSuggestions).
  </PropertiesListItem>
  <PropertiesListItem name="polyfills">
    Place polyfills for `atob`, `fetch`, and `WebSocket` inside here. Useful
    when using a non-browser environment, such as
    [Node.js](#LiveblocksProviderNode) or [React
    Native](#LiveblocksProviderReactNative).
  </PropertiesListItem>
  <PropertiesListItem
    name="largeMessageStrategy"
    detailedType='"default" | "split" | "experimental-fallback-to-http"'
    defaultValue={`"default"`}
  >
    <div className="-mb-3">
      How to handle WebSocket messages that are larger than the maximum message size. Can be set to one of these values:
    </div>

    - `"default"` Don’t send anything, but log the error to the console.
    - `"split"` Break the message up into chunks each of which is smaller than the maximum message size.
      Beware that using `"split"` will sacrifice atomicity of changes! Depending on your use case, this may or may not be problematic.
    - `"experimental-fallback-to-http"` Try sending the update over HTTP instead of WebSockets (experimental).

  </PropertiesListItem>
  <PropertiesListItem
    name="unstable_streamData"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Stream the initial Storage content over HTTP, instead of
    waiting for a large initial WebSocket message to be sent from the server.
  </PropertiesListItem>
</PropertiesList>

#### LiveblocksProvider with public key [#LiveblocksProviderPublicKey]

When creating a client with a public key, you don’t need to set up an
authorization endpoint. We only recommend using a public key when prototyping,
or on public landing pages, as it makes it possible for end users to access any
room’s data. You should instead use an
[auth endpoint](#LiveblocksProviderAuthEndpoint).

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

function App() {
  return (
    <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
      {/* children */}
    </LiveblocksProvider>
  );
}
```

#### LiveblocksProvider with auth endpoint [#LiveblocksProviderAuthEndpoint]

If you are not using a public key, you need to set up your own `authEndpoint`.
Please refer to our [Authentication guide](/docs/authentication).

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

function App() {
  return (
    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      {/* children */}
    </LiveblocksProvider>
  );
}
```

#### LiveblocksProvider with auth endpoint callback [#LiveblocksProviderCallback]

If you need to add additional headers or use your own function to call your
endpoint, `authEndpoint` can be provided as a custom callback. You should return
the token created with
[`Liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
or [`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens),
learn more in [authentication guide](/docs/rooms/authentication).

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

function App() {
  return (
    <LiveblocksProvider
      authEndpoint={async (room) => {
        // Fetch your authentication endpoint and retrieve your access or ID token
        // ...

        return { token: "..." };
      }}
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

`room` is the room ID that the user is connecting to. When using
[Notifications](/docs/ready-made-features/comments/email-notifications), `room`
can be `undefined`, as the client is requesting a token that grants access to
multiple rooms, rather than a specific room.

##### Fetch your endpoint

Here’s an example of fetching your API endpoint at `/api/liveblocks-auth` within
the callback.

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

function App() {
  return (
    <LiveblocksProvider
      authEndpoint={async (room) => {
        const response = await fetch("/api/liveblocks-auth", {
          method: "POST",
          headers: {
            Authentication: "<your own headers here>",
            "Content-Type": "application/json",
          },
          // Don't forget to pass `room` down. Note that it
          // can be undefined when using Notifications.
          body: JSON.stringify({ room }),
        });
        return await response.json();
      }}
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

##### Token details

You should return the token created with
[`Liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
or [`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens).
These are the values the functions can return.

1. A valid token, it returns a `{ "token": "..." }` shaped response.
1. A token that explicitly forbids access, it returns an
   `{ "error": "forbidden", "reason": "..." }` shaped response. If this is
   returned, the client will disconnect and won't keep trying to authorize.

Any other error will be treated as an unexpected error, after which the client
will retry the request until it receives either 1. or 2.

#### WebSocket throttle [#LiveblocksProviderThrottle]

By default, the client throttles the WebSocket messages sent to one every 100
milliseconds, which translates to 10 updates per second. It’s possible to
override that configuration with the `throttle` option with a value between `16`
and `1000` milliseconds.

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

function App() {
  return (
    <LiveblocksProvider
      throttle={16}

      // Other options
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

This option is helpful for smoothing out realtime animations in your
application, as you can effectively increase the framerate without using any
interpolation. Here are some examples with their approximate frames per second
(FPS) values.

```ts
throttle:  16, // 60 FPS
throttle:  32, // 30 FPS
throttle: 200, //  5 FPS
```

#### Prevent users losing unsaved changes [#prevent-users-losing-unsaved-changes]

Liveblocks usually synchronizes milliseconds after a local change, but if a user
immediately closes their tab, or if they have a slow connection, it may take
longer for changes to synchronize. Enabling `preventUnsavedChanges` will stop
tabs with unsaved changes closing, by opening a dialog that warns users. In
usual circumstances, it will very rarely trigger.

```tsx
function Page() {
  return (
    <LiveblocksProvider
      // highlight-next-line
      preventUnsavedChanges

      // Other options
      // ...
    >
      ...
    </LiveblocksProvider>
  );
}
```

More specifically, this option triggers when:

- There are unsaved changes after calling any hooks or methods, in all of our
  products.
- There are unsaved changes in a
  [Text Editor](/docs/ready-made-features/text-editor).
- There’s an unsubmitted comment in the
  [Composer](/docs/api-reference/liveblocks-react-ui#Composer).
- The user has made changes and is currently offline.

Internally, this option uses the
[beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).

#### Lost connection timeout [#LiveblocksProviderLostConnectionTimeout]

If you’re connected to a room and briefly lose connection, Liveblocks will
reconnect automatically and quickly. However, if reconnecting takes longer than
usual, for example if your network is offline, then the room will emit an event
informing you about this.

How quickly this event is triggered can be configured with the
`lostConnectionTimeout` setting, and it takes a number in milliseconds.
`lostConnectionTimeout` can be set between `1000` and `30000` milliseconds. The
default is `5000`, or 5 seconds.

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

function App() {
  return (
    <LiveblocksProvider
      lostConnectionTimeout={5000}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

You can listen to the event with [`useLostConnectionListener`][]. Note that this
also affects when `others` are reset to an empty array after a disconnection.
This helps prevent temporary flashes in your application as a user quickly
disconnects and reconnects. For a demonstration of this behavior, see our
[connection status example][].

#### Background keep-alive timeout [#LiveblocksProviderBackgroundKeepAliveTimeout]

By default, Liveblocks applications will maintain an active WebSocket connection
to the Liveblocks servers, even when running in a browser tab that’s in the
background. However, if you’d prefer for background tabs to disconnect after a
period of inactivity, then you can use `backgroundKeepAliveTimeout`.

When `backgroundKeepAliveTimeout` is specified, the client will automatically
disconnect applications that have been in an unfocused background tab for _at
least_ the specified time. When the browser tab is refocused, the client will
immediately reconnect to the room and synchronize the document.

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

function App() {
  return (
    <LiveblocksProvider
      // Disconnect users after 15 minutes of inactivity
      backgroundKeepAliveTimeout={15 * 60 * 1000}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

`backgroundKeepAliveTimeout` accepts a number in milliseconds—we advise using a
value of at least a few minutes, to avoid unnecessary disconnections.

#### resolveUsers [#LiveblocksProviderResolveUsers]

[Comments](/docs/ready-made-features/comments) stores user IDs in its system,
but no other user information. To display user information in Comments
components, such as a user’s name or avatar, you need to resolve these IDs into
user objects. This function receives a list of user IDs and you should return a
list of user objects of the same size, in the same order.

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

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        const usersData = await __getUsersFromDB__(userIds);

        return usersData.map((userData) => ({
          name: userData.name,
          avatar: userData.avatar.src,
        }));
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

The name and avatar you return are rendered in
[`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) components.

##### User objects

The user objects returned by the resolver function take the shape of
`UserMeta["info"]`, which contains `name` and `avatar` by default. These two
values are optional, though if you’re using the
[Comments default components](/docs/api-reference/liveblocks-react-ui#Components),
they are necessary. Here’s an example of `userIds` and the exact values
returned.

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

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        // ["marc@example.com", "nimesh@example.com"];
        console.log(userIds);

        return [
          { name: "Marc", avatar: "https://example.com/marc.png" },
          { name: "Nimesh", avatar: "https://example.com/nimesh.png" },
        ];
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

You can also return custom information, for example, a user’s `color`:

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

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        // ["marc@example.com"];
        console.log(userIds);

        return [
          {
            name: "Marc",
            avatar: "https://example.com/marc.png",
            // +++
            color: "purple",
            // +++
          },
        ];
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

##### Accessing user data

You can access any values set within `resolveUsers` with the
[`useUser`](/docs/api-reference/liveblocks-react#useUser) hook.

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

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

  // { name: "Marc", avatar: "https://...", ... }
  console.log(user);
}
```

#### resolveRoomsInfo [#LiveblocksProviderResolveRoomsInfo]

When using
[Notifications](/docs/ready-made-features/comments/email-notifications) with
[Comments](/docs/ready-made-features/comments), room IDs will be used to
contextualize notifications (e.g. “Chris mentioned you in _room-id_”) in the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component. To replace room IDs with more fitting names (e.g. document names,
“Chris mentioned you in _Document A_”), you can provide a resolver function to
the `resolveRoomsInfo` option in [`LiveblocksProvider`](#LiveblocksProvider).

This resolver function will receive a list of room IDs and should return a list
of room info objects of the same size and in the same order.

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

function App() {
  return (
    <LiveblocksProvider
      resolveRoomsInfo={async ({ roomIds }) => {
        const documentsData = await __getDocumentsFromDB__(roomIds);

        return documentsData.map((documentData) => ({
          name: documentData.name,
          // url: documentData.url,
        }));
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

In addition to the room’s name, you can also provide a room’s URL as the `url`
property. If you do so, the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component will automatically use it. It’s possible to use an inbox
notification’s `roomId` property to construct a room’s URL directly in React and
set it on
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
via `href`, but the room ID might not be enough for you to construct the URL ,
you might need to call your backend for example. In that case, providing it via
`resolveRoomsInfo` is the preferred way.

#### resolveMentionSuggestions [#LiveblocksProviderResolveMentionSuggestions]

To enable creating mentions in [Comments](/docs/ready-made-features/comments),
you can provide a resolver function to the `resolveMentionSuggestions` option in
[`LiveblocksProvider`](#LiveblocksProvider). These mentions will be displayed in
the [`Composer`](/docs/api-reference/liveblocks-react-ui#Composer) component.

This resolver function will receive the mention currently being typed (e.g. when
writing “@jane”, `text` will be `jane`) and should return a list of user IDs
matching that text. This function will be called every time the text changes but
with some debouncing.

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

function App() {
  return (
    <LiveblocksProvider
      resolveMentionSuggestions={async ({ text, roomId }) => {
        const workspaceUsers = await __getWorkspaceUsersFromDB__(roomId);

        if (!text) {
          // Show all workspace users by default
          return __getUserIds__(workspaceUsers);
        } else {
          const matchingUsers = __findUsers__(workspaceUsers, text);
          return __getUserIds__(matchingUsers);
        }
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

#### LiveblocksProvider for Node.js [#LiveblocksProviderNode]

To use `@liveblocks/client` in Node.js, you need to provide [`WebSocket`][] and
[`fetch`][] polyfills. As polyfills, we recommend installing [`ws`][] and
[`node-fetch`][].

```bash
npm install ws node-fetch
```

Then, pass them to the `LiveblocksProvider` polyfill option as below.

```tsx
import { LiveblocksProvider } from "@liveblocks/react/suspense";
import fetch from "node-fetch";
import WebSocket from "ws";

function App() {
  return (
    <LiveblocksProvider
      polyfills={{
        fetch,
        WebSocket,
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

Note that `node-fetch` v3+
[does not support CommonJS](https://github.com/node-fetch/node-fetch/blob/main/docs/v3-UPGRADE-GUIDE.md#converted-to-es-module).
If you are using CommonJS, downgrade `node-fetch` to v2.

#### LiveblocksProvider for React Native [#LiveblocksProviderReactNative]

To use `@liveblocks/client` with [React Native](https://reactnative.dev/), you
need to add an [`atob`][] polyfill. As a polyfill, we recommend installing
[`base-64`][].

```bash
npm install base-64
```

Then you can pass the `decode` function to our `atob` polyfill option when you
create the client.

```ts
import { LiveblocksProvider } from "@liveblocks/react/suspense";
import { decode } from "base-64";

function App() {
  return (
    <LiveblocksProvider
      polyfills={{
        atob: decode,
      }}

      // Other props
      // ...
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

### createLiveblocksContext

<Banner title="Not recommended" type="warning">

This used to be the default way to start your app, but now it’s recommended for
advanced usage only. We generally recommend using [`LiveblocksProvider`][] and
following [typing your data with the Liveblocks interface](#Typing-your-data),
unless you need to define multiple room types in your application.

</Banner>

Creates a [`LiveblocksProvider`][] and a set of typed hooks. Note that any
`LiveblocksProvider` created in this way takes no props, because it uses
settings from the `client` instead. We recommend using it in
`liveblocks.config.ts` and re-exporting your typed hooks like below.

While [`createRoomContext`](#createRoomContext) offers APIs for interacting with
rooms (e.g. Presence, Storage, and Comments),
[`createLiveblocksContext`](#createLiveblocksContext) offers APIs for
interacting with Liveblocks features that are not tied to a specific room (e.g.
Notifications).

```tsx file="liveblocks.config.ts"
import { createClient } from "@liveblocks/client";
import { createRoomContext, createLiveblocksContext } from "@liveblocks/react";

const client = createClient({
  // publicApiKey: "",
  // authEndpoint: "/api/liveblocks-auth",
  // throttle: 100,
});

// ...

export const { RoomProvider } = createRoomContext(client);

export const {
  LiveblocksProvider,
  useInboxNotifications,

  // Other hooks
  // ...
} = createLiveblocksContext(client);
```

### useClient [@badge=LiveblocksProvider]

Returns the [`client`](/docs/api-reference/liveblocks-client#Client) of the
nearest [`LiveblocksProvider`][] above in the React component tree.

```ts
import { useClient } from "@liveblocks/react/suspense";

const client = useClient();
```

### useErrorListener [@badge=LiveblocksProvider]

Listen to potential Liveblocks errors. Examples of errors include room
connection errors, errors creating threads, and errors deleting notifications.
Each error has a `message` string, and a `context` object which has different
values for each error type. `context` always contains an error `type` and
`roomId`.

```ts
import { useErrorListener } from "@liveblocks/react/suspense";

useErrorListener((error) => {
  // { message: "You don't have access to this room", context: { ... }}
  console.error(error);
});
```

There are many different errors, and each can be handled separately by checking
the value of `error.context.type`. Below we’ve listed each error and the context
it provides.

```ts title="All error types" isCollapsable isCollapsed
import { useErrorListener } from "@liveblocks/react/suspense";

useErrorListener((error) => {
  switch (error.context.type) {
    // Can happen if you use Presence, Storage, or Yjs
    case "ROOM_CONNECTION_ERROR": {
      const { code } = error.context;
      // -1   = Authentication error
      // 4001 = You don't have access to this room
      // 4005 = Room was full
      // 4006 = Room ID has changed
      break;
    }

    // Can happen if you use Comments or Notifications
    case "CREATE_THREAD_ERROR":
      const { roomId, threadId, commentId, body, metadata } = error.context;
      break;

    case "DELETE_THREAD_ERROR":
      const { roomId, threadId } = error.context;
      break;

    case "EDIT_THREAD_METADATA_ERROR":
      const { roomId, threadId, metadata } = error.context;
      break;

    case "MARK_THREAD_AS_RESOLVED_ERROR":
    case "MARK_THREAD_AS_UNRESOLVED_ERROR":
      const { roomId, threadId } = error.context;
      break;

    case "CREATE_COMMENT_ERROR":
    case "EDIT_COMMENT_ERROR":
      const { roomId, threadId, commentId, body } = error.context;
      break;

    case "DELETE_COMMENT_ERROR":
      const { roomId, threadId, commentId } = error.context;
      break;

    case "ADD_REACTION_ERROR":
    case "REMOVE_REACTION_ERROR":
      const { roomId, threadId, commentId, emoji } = error.context;
      break;

    case "MARK_INBOX_NOTIFICATION_AS_READ_ERROR":
      const { inboxNotificationId, roomId } = error.context;
      break;

    case "DELETE_INBOX_NOTIFICATION_ERROR":
      const { roomId } = error.context;
      break;

    case "MARK_ALL_INBOX_NOTIFICATIONS_AS_READ_ERROR":
    case "DELETE_ALL_INBOX_NOTIFICATIONS_ERROR":
      break;

    case "UPDATE_NOTIFICATION_SETTINGS_ERROR":
      const { roomId } = error.context;
      break;

    default:
      // Ignore any error from the future
      break;
  }
});
```

<Banner title="Hook changes in 2.16">

The behavior of this hook changed in 2.16. Previously, this hook had to be in a
[`RoomProvider`][] context, and would only trigger for connection errors in the
current room. Since 2.16, this hook only requires a [`LiveblocksProvider`][]
context, and will notify about any errors, and for any room. For example,
notifications are not part of rooms, and errors for these will show. See the
[upgrade guide for 2.6](/docs/platform/upgrading/2.16) for more details.

</Banner>

## Room

### RoomProvider

Makes a [`Room`][] available in the component hierarchy below. Joins the room
when the component is mounted, and automatically leaves the room when the
component is unmounted. When using
[Sync Datastore](/docs/ready-made-features/sync-datastore), initial Presence
values for each user, and Storage values for the room can be set.

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

function App() {
  return <RoomProvider id="my-room-id">{/* children */}</RoomProvider>;
}
```

<PropertiesList title="Props">
  <PropertiesListItem name="id" type="string" required>
    The unique ID for the current room. `RoomProvider` will join this room when
    it loads. If the room doesn’t exist already it will automatically create the
    room first then join. After setting up
    [authentication](/docs/authentication) for your app, it can helpful to
    decide on a naming pattern for your room IDs.
  </PropertiesListItem>
  <PropertiesListItem name="initialPresence" type="JsonObject">
    The initial Presence of the user entering the room. Each user has their own
    presence, and this is readable for all other connected users. A user’s
    Presence resets every time they disconnect. This object must be
    JSON-serializable. This value is ignored after the first render. [Learn
    more](#setting-initial-presence).
  </PropertiesListItem>
  <PropertiesListItem name="initialStorage" type="LsonObject">
    The initial Storage structure for the room when it’s joined for the first
    time. This is only set a single time, when the room has not yet been
    populated. This object must contain [conflict-free live
    structures](/docs/api-reference/liveblocks-client#Storage). This value is
    ignored after the first render, and if Storage for the current room has
    already been created. [Learn more](#setting-initial-storage).
  </PropertiesListItem>
  <PropertiesListItem name="autoConnect" type="boolean" defaultValue="true">
    Whether the room immediately connects to Liveblocks servers. This value is
    ignored after the first render.
  </PropertiesListItem>
</PropertiesList>

#### Setting initial Presence [#setting-initial-presence]

Presence is used for storing temporary user-based values, such as a user’s
cursor coordinates, or their current selection. Each user has their own
presence, and this is readable for all other connected users. Set your initial
Presence value by using `initialPresence`.

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

function App() {
  return (
    <RoomProvider
      id="my-room"
      // +++
      initialPresence={{
        cursor: null,
        colors: ["red", "purple"],
        selection: {
          id: 72426,
        },
      }}
      // +++
    >
      {/* children */}
    </RoomProvider>
  );
}
```

Each user’s Presence resets every time they disconnect, as this is only meant
for temporary data. Any JSON-serializable object is allowed (the `JsonObject`
type).

#### Setting initial Storage [#setting-initial-storage]

Storage is used to store permanent data that’s used in your application, such as
shapes on a whiteboard, nodes on a flowchart, or text in a form. The first time
a room is entered, you can set an initial value by using `initialStorage`.
`initialStorage` is only read and set a single time, unless a new top-level
property is added.

```tsx
import { LiveList, LiveObject, LiveMap } from "@liveblocks/client";
import { RoomProvider } from "@liveblocks/react/suspense";

function App() {
  return (
    <RoomProvider
      id="my-room"
      initialPresence={}
      // +++
      initialStorage={{
        title: "Untitled",
        names: new LiveList(["Steven", "Guillaume"]),
        shapes: new LiveMap([
          ["g9shu0", new LiveObject({ type: "rectangle", color: "red" })],
          ["djs3g5", new LiveObject({ type: "circle", color: "yellow" })],
        ]),
      }}
      // +++
    >
      {/* children */}
    </RoomProvider>
  );
}
```

If a new top-level property is added to `initialStorage`, the next time a user
connects, the new property will be created. Other properties will be unaffected.
Any
[conflict-free live structures](/docs/api-reference/liveblocks-client#Storage)
and JSON-serializable objects are allowed (the `LsonObject` type).

### createRoomContext

<Banner>

This used to be the default way to start your app, but now it’s recommend for
advanced usage only. We generally recommend using [`LiveblocksProvider`][] and
following [typing your data with the Liveblocks interface](#Typing-your-data),
unless you need to define multiple room types in your application.

</Banner>

Creates a [`RoomProvider`][] and a set of typed hooks to use in your app. Note
that any `RoomProvider` created in this way does not need to be nested in
[`LiveblocksProvider`][], as it already has access to the `client`. We generally
recommend typing your app using the newer method instead. When using
`createRoomContext` it can be helpful to use it in `liveblocks.config.ts` and
re-export your typed hooks as below.

```tsx file="liveblocks.config.ts"
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  // publicApiKey: "",
  // authEndpoint: "/api/liveblocks-auth",
});

type Presence = {};
type Storage = {};
type UserMeta = {};
type RoomEvent = {};
type ThreadMetadata = {};

// +++
export const {
  RoomProvider,
  useMyPresence,

  // Other hooks
  // ...
} = createRoomContext<Presence, Storage, UserMeta, RoomEvent, ThreadMetadata>(
  client
);
// +++
```

#### Suspense with createRoomContext [#createRoomContext-Suspense]

To use the React suspense version of our hooks with `createRoomContext`, you can
export from the `suspense` property instead.

```tsx file="liveblocks.config.ts"
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  // publicApiKey: "",
  // authEndpoint: "/api/liveblocks-auth",
});

type Presence = {};
type Storage = {};
type UserMeta = {};
type RoomEvent = {};
type ThreadMetadata = {};

export const {
  // +++
  suspense: {
    RoomProvider,
    useMyPresence,

    // Other suspense hooks
    // ...
  },
  // +++
} = createRoomContext<Presence, Storage, UserMeta, RoomEvent, ThreadMetadata>(
  client
);
```

#### Typing createRoomContext

To type your hooks, you can pass multiple different types to
`createRoomContext`. A full explanation is in the code snippet below.

```tsx file="liveblocks.config.ts" isCollapsable isCollapsed
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  // publicApiKey: "",
  // authEndpoint: "/api/liveblocks-auth",
});

// Presence represents the properties that 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 = {
  // animals: LiveList<string>,
  // ...
};

// Optionally, UserMeta represents static/readonly metadata on each user, as
// provided by your own custom auth back end (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 broadcast and listened to in this
// room. Use a union for multiple events. Must be JSON-serializable.
// type RoomEvent = {};

// Optionally, when using Comments, ThreadMetadata represents metadata on
// each thread. Can only contain booleans, strings, and numbers.
// export type ThreadMetadata = {
//   pinned: boolean;
//   quote: string;
//   time: number;
// };

export const {
  RoomProvider,
  useMyPresence,
  useStorage,

  // Other hooks
  // ...
} = createRoomContext<
  Presence,
  Storage
  /* UserMeta, RoomEvent, ThreadMetadata */
>(client);
```

### useRoom [@badge=RoomProvider]

Returns the [`Room`][] of the nearest [`RoomProvider`][] above in the React
component tree.

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

const room = useRoom();
```

Will throw when used outside of a [`RoomProvider`][]. If you don’t want this
hook to throw when used outside of a Room context (for example to write
components in a way that they can be used both inside and outside of a
Liveblocks room), you can use the `{ allowOutsideRoom }` option:

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

const room = useRoom({ allowOutsideRoom: true }); // Possibly `null`
```

### useIsInsideRoom [@badge=Both]

Returns a boolean, `true` if the hook was called inside a
[`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider) context, and
`false` otherwise.

```ts
import { useIsInsideRoom } from "@liveblocks/react/suspense";

const isInsideRoom = useIsInsideRoom();
```

#### Displaying different components inside rooms

`useIsInsideRoom` is helpful for rendering different components depending on
whether they’re inside a room, or not. One example is a header component that
only displays a live avatar stack when users are connected to the room.

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

function Header() {
  // +++
  const isInsideRoom = useIsInsideRoom();
  // +++

  return (
    <div>
      // +++
      {isInsideRoom ? <LiveAvatars /> : null}
      // +++
      <MyAvatar />
    </div>
  );
}

function LiveAvatars() {
  const others = useOthers();
  return others.map((other) => <img src={other.info.picture} />);
}
```

Here’s how the example above would render in three different
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
and [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider)
contexts.

```tsx
// 👥👤 Live avatar stack and your avatar
<LiveblocksProvider /* ... */>
  <RoomProvider /* ... */>
    <Header />
  </RoomProvider>
</LiveblocksProvider>


// 👤 Just your avatar
<LiveblocksProvider /* ... */>
  <Header />
</LiveblocksProvider>

// 👤 Just your avatar
<Header />
```

### useStatus [@badge=RoomProvider]

Returns the current WebSocket connection status of the room, and will re-render
your component whenever it changes.

```ts
import { useStatus } from "@liveblocks/react/suspense";

const status = useStatus();
```

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

### useStorageStatus [@badge=RoomProvider]

<Banner title="Deprecated">

Deprecated. Starting with 2.12.0, we recommend using [`useSyncStatus`][] instead
for tracking sync status, because it will reflect sync status of all parts of
Liveblocks, not just Storage.

</Banner>

Returns the current storage status of the room, and will re-render your
component whenever it changes. A `{ smooth: true }` option is also available,
which prevents quick changes between states, making it ideal for
[rendering a synchronization badge in your app](#display-synchronization-badge).

```ts
import { useStorageStatus } from "@liveblocks/react";

const storageStatus = useStorageStatus();

// "not-loaded" | "loading" | "synchronizing" | "synchronized"
console.log(storageStatus);
```

👉 A [Suspense version][] of this hook is also available.

```ts
import { useStorageStatus } from "@liveblocks/react/suspense";

const storageStatus = useStorageStatus();

// "synchronizing" | "synchronized"
console.log(storageStatus);
```

### useSyncStatus [@badge=Both]

Returns the current synchronization status of Liveblocks, and will re-render
your component whenever it changes. This includes any part of Liveblocks that
may be synchronizing local changes to the server, including (any room’s)
Storage, text editors, threads, or notifications.

A `{ smooth: true }` option is also available, which prevents quick changes
between states, making it ideal for
[rendering a synchronization badge in your app](#display-synchronization-badge).

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

const syncStatus = useSyncStatus();
// "not-loaded" | "loading" | "synchronizing" | "synchronized"
```

👉 A [Suspense version][] of this hook is also available.

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

const syncStatus = useSyncStatus();
// "synchronizing" | "synchronized"
```

#### Display a synchronization badge [#display-synchronization-badge]

Passing `{ smooth: true }` prevents the status changing from `"synchronizing"`
to `"synchronized"` until 1 second has passed after the final change. This means
it’s ideal for rendering a synchronization status badge, as it won’t flicker in
a distracting manner when changes are made in quick succession.

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

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

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

#### Prevent users losing unsaved changes [#use-sync-status-prevent-users-losing-unsaved-changes]

Liveblocks usually synchronizes milliseconds after a local change, but if a user
immediately closes their tab, or if they have a slow connection, it may take
longer for changes to synchronize. Enabling `preventUnsavedChanges` will stop
tabs with unsaved changes closing, by opening a dialog that warns users. In
usual circumstances, it will very rarely trigger.

```tsx
function Page() {
  return (
    <LiveblocksProvider
      // highlight-next-line
      preventUnsavedChanges

      // Other options
      // ...
    >
      ...
    </LiveblocksProvider>
  );
}
```

More specifically, this option triggers when:

- There are unsaved changes after calling any hooks or methods, in all of our
  products.
- There are unsaved changes in a
  [Text Editor](/docs/ready-made-features/text-editor).
- There’s an unsubmitted comment in the
  [Composer](/docs/api-reference/liveblocks-react-ui#Composer).
- The user has made changes and is currently offline.

Internally, this option uses the
[beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).

### useOthersListener [@badge=RoomProvider]

Calls the given callback when an “others” event occurs. Possible event types
are:

- `enter` – A user has entered the room.
- `leave` – A user has left the room.
- `reset` – The others list has been emptied. This is the first event that
  occurs when the room is entered. It also occurs when you’ve lost connection to
  the room.
- `update` – A user’s presence data has been updated.

```ts
function App() {
  useOthersListener(({ type, user, others }) => {
    switch (type) {
      case "enter":
        // `user` has entered the room
        break;

      case "leave":
        // `user` has left the room
        break;

      case "update":
        // Presence for `user` has updated
        break;

      case "reset":
        // Others list has been emptied
        break;
    }
  });
}
```

### useLostConnectionListener [@badge=RoomProvider]

Calls the given callback in the exceptional situation that a connection is lost
and reconnecting does not happen quickly enough.

This event allows you to build high-quality UIs by warning your users that the
app is still trying to re-establish the connection, for example through a toast
notification. You may want to take extra care in the mean time to ensure their
changes won’t go unsaved.

When this happens, this callback is called with the event `lost`. Then, once the
connection restores, the callback will be called with the value `restored`. If
the connection could definitively not be restored, it will be called with
`failed` (uncommon).

The [`lostConnectionTimeout`][] client option will determine how quickly this
event will fire after a connection loss (default: 5 seconds).

```ts
import { toast } from "my-preferred-toast-library";

function App() {
  useLostConnectionListener((event) => {
    switch (event) {
      case "lost":
        toast.warn("Still trying to reconnect...");
        break;

      case "restored":
        toast.success("Successfully reconnected again!");
        break;

      case "failed":
        toast.error("Could not restore the connection");
        break;
    }
  });
}
```

Automatically unsubscribes when the component is unmounted.

For a demonstration of this behavior, see our [connection status example][].

## Presence

<Banner title="Need help troubleshooting presence?">

Try the [Liveblocks DevTools extension](/devtools) to visualize your
collaborative experiences as you build them, in realtime.

</Banner>

### useMyPresence [@badge=RoomProvider]

Return the presence of the current user, and a function to update it.
Automatically subscribes to updates to the current user’s presence.

Note that the `updateMyPresence` setter function is different to the setter
function returned by React’s `useState` hook. Instead, you can pass a partial
presence object to `updateMyPresence`, and any changes will be merged into the
current presence. It will not replace the entire presence object.

```ts
import { useMyPresence } from "@liveblocks/react/suspense";

const [myPresence, updateMyPresence] = useMyPresence();
updateMyPresence({ x: 0 });
updateMyPresence({ y: 0 });

// At the next render, "myPresence" will be equal to "{ x: 0, y: 0 }"
```

This is roughly equal to:

```tsx
const myPresence = useSelf((me) => me.presence);
const updateMyPresence = useUpdateMyPresence();
```

`updateMyPresence` accepts an optional argument to add a new item to the
undo/redo stack. See [`room.history`][] for more information.

```ts
updateMyPresence({ selectedId: "xxx" }, { addToHistory: true });
```

### useUpdateMyPresence [@badge=RoomProvider]

Returns a setter function to update the current user’s presence.

Use this if you don’t need the current user’s presence in your component, but
you need to update it (e.g. live cursor). It’s better to use
`useUpdateMyPresence` because it won’t subscribe your component to get
rerendered when the presence updates.

Note that the `updateMyPresence` setter function is different to the setter
function returned by React’s `useState` hook. Instead, you can pass a partial
presence object to `updateMyPresence`, and any changes will be merged into the
current presence. It will not replace the entire presence object.

```ts
import { useUpdateMyPresence } from "@liveblocks/react/suspense";

const updateMyPresence = useUpdateMyPresence();

updateMyPresence({ y: 0 });
```

`updateMyPresence` accepts an optional argument to add a new item to the
undo/redo stack. See [`room.history`][] for more information.

```ts
updateMyPresence({ selectedId: "xxx" }, { addToHistory: true });
```

### useSelf [@badge=RoomProvider]

Returns the current user once it is connected to the room, and automatically
subscribes to updates to the current user.

```ts
import { useSelf } from "@liveblocks/react/suspense";

const currentUser = useSelf();
// {
//   connectionId: 1,
//   presence: { cursor: { x: 27, y: -8 } },
// }

const currentUser = useSelf((me) => me.presence.cursor);
// { x: 27, y: -8 }
```

The benefit of using a selector is that it will only update your component if
that particular selection changes. For full details, see [how selectors work][].

👉 A [Suspense version][] of this hook is also available, which will never return
`null`.

### useOthers [@badge=RoomProvider]

Extracts data from the list of other users currently in the same Room, and
automatically subscribes to updates on the selected data. For full details, see
[how selectors work][].

The `others` argument to the `useOthers` selector function is an _immutable_
array of Users.

```tsx
// ✅ Rerenders only if the number of users changes
const numOthers = useOthers((others) => others.length);

// ✅ Rerenders only if someone starts or stops typing
const isSomeoneTyping = useOthers((others) =>
  others.some((other) => other.presence.isTyping)
);

// ✅ Rerenders only if actively typing users are updated
const typingUsers = useOthers(
  (others) => others.filter((other) => other.presence.isTyping),
  shallow // 👈
);
```

👉 A [Suspense version][] of this hook is also available, which will never return
`null`.

One caveat with this API is that selecting a subset of data for each user
quickly becomes tricky. When you want to select and get updates for only a
particular subset of each user’s data, we recommend using the
[`useOthersMapped`][] hook instead, which is optimized for this use case.

```tsx
// ❌ Mapping is hard to get right with this hook
const cursors = useOthers(
  (others) => others.map((other) => other.presence.cursor),
  shallow
);

// ✅ Better to use useOthersMapped
const cursors = useOthersMapped((other) => other.presence.cursor);
```

When called without arguments, returns the user list and updates your component
whenever _anything_ in it changes. This might be way more often than you want!

```tsx
const others = useOthers(); // ⚠️ Caution, might rerender often!
// [
//   { connectionId: 2, presence: { cursor: { x: 27, y: -8 } } },
//   { connectionId: 3, presence: { cursor: { x: 0, y: 19 } } },
// ]
```

<Banner type="error" title="Caution">

In production-ready apps, you likely want to avoid calling `useOthers` without
arguments.

</Banner>

### useOthersMapped [@badge=RoomProvider]

Extract data using a [selector][] for every user in the room, and subscribe to
all changes to the selected data. A [Suspense version][] of this hook is also available.

The key difference with [`useOthers`][] is that the selector (and the optional
comparison function) work at the _item_ level, like doing a `.map()` over the
others array.

```tsx
// Example 1
const others = useOthersMapped((other) => other.presence.cursor);
// [
//   [2, { x: 27, y: -8 }],
//   [3, { x: 0, y: 19 }],
// ]

// Example 2
const others = useOthersMapped(
  (other) => ({
    avatar: other.info.avatar,
    isTyping: other.presence.isTyping,
  }),
  shallow // 👈
);

// [
//   [2, { avatar: 'https://...', isTyping: true }],
//   [3, { avatar: null, isTyping: false }],
// ]
```

Returns an array where each item is a pair of `[connectionId, data]`. For
pragmatic reasons, the results are keyed by the `connectionId`, because in most
cases you’ll want to iterate over the results and draw some UI for each, which
in React requires you to use a `key={connectionId}` prop.

```tsx
const others = useOthersMapped((other) => other.presence.cursor);

// In JSX
return (
  <>
    {others.map(([connectionId, cursor]) => (
      <Cursor key={connectionId} x={cursor.x} y={cursor.y} />
    ))}
  </>
);
```

### useOthersConnectionIds [@badge=RoomProvider]

Returns an array of connection IDs (numbers), and rerenders automatically when
users join or leave. This hook is useful in particular in combination with the
[`useOther`][] (singular) hook, to implement high-frequency rerendering of
components for each user in the room, e.g. cursors. See the [`useOther`][]
(singular) documentation below for a full usage example.

```tsx
useOthersConnectionIds(); // [2, 4, 7]
```

Roughly equivalent to:

```tsx
useOthers((others) => others.map((other) => other.connectionId), shallow);
```

👉 A [Suspense version][] of this hook is also available.

### useOther [@badge=RoomProvider]

Extract data using a [selector][] for one specific user in the room, and
subscribe to all changes to the selected data. A [Suspense version][] of this hook
is also available.

```tsx
// ✅ Rerenders when this specific user’s isTyping changes (but not when their cursor changes)
const isTyping = useOther(
  3, // User with connectionId 3
  (user) => user.presence.isTyping
);
```

The reason this hook exists is to enable the most efficient rerendering model
for high-frequency updates to other’s presences, which is the following
structure:

```tsx file="Cursors.tsx"
const Cursors =
  // +++
  // (1) Wrap parent component in a memo and make sure it takes no props
  React.memo(function () {
    const othersConnectionIds = useOthersConnectionIds(); // (2)
    // +++
    return (
      <>
        {othersConnectionIds.map((connectionId) => (
          <Cursor
            // +++
            key={connectionId} // (3)
            // +++
            connectionId={connectionId}
          />
        ))}
      </>
    );
  });
```

```tsx file="Cursor.tsx"
function Cursor({ connectionId }) {
  // +++
  const { x, y } = useOther(connectionId, (other) => other.presence.cursor); // (4)
  // +++
  return <Cursor x={x} y={y} />;
}
```

1. Makes sure this whole component tree will never rerender beyond the first
   time.
2. Makes sure the parent component only rerenders when users join/leave.
3. Makes sure each cursor remains associated to the same connection.
4. Makes sure each cursor rerenders whenever _its_ data changes only.

👉 A [Suspense version][] of this hook is also available, which will never return
`null`.

## Broadcast

### useBroadcastEvent [@badge=RoomProvider]

Returns a callback that lets you broadcast custom events to other users in the
room.

```ts
import { useBroadcastEvent } from "@liveblocks/react/suspense";

// +++
// On client A
const broadcast = useBroadcastEvent();
broadcast({ type: "EMOJI", emoji: "🔥" });
// +++

// On client B
useEventListener(({ event, user, connectionId }) => {
  //                       ^^^^ Will be Client A
  if (event.type === "EMOJI") {
    // Do something
  }
});
```

### useEventListener [@badge=RoomProvider]

Listen to custom events sent by other people in the room via
[`useBroadcastEvent`][]. Provides the `event` along with the `connectionId` of
the user that sent the message. If an event was sent from the
[Broadcast to a room](/docs/api-reference/rest-api-endpoints#post-broadcast-event)
REST API, `connectionId` will be `-1`.

```ts
import { useEventListener } from "@liveblocks/react/suspense";

// On client A
const broadcast = useBroadcastEvent();
broadcast({ type: "EMOJI", emoji: "🔥" });

// +++
// On client B
useEventListener(({ event, user, connectionId }) => {
  //                       ^^^^ Will be Client A
  if (event.type === "EMOJI") {
    // Do something
  }
});
// +++
```

The `user` property will indicate which User instance sent the message. This
will typically be equal to one of the others in the room, but it can also be
`null` in case this event was broadcasted from the server, using the
[Broadcast Event API](https://liveblocks.io/docs/api-reference/rest-api-endpoints#post-broadcast-event).

Automatically unsubscribes when the component is unmounted.

## Storage

Each room contains Storage, a conflict-free data store that multiple users can
edit at the same time. When users make edits simultaneously, conflicts are
resolved automatically, and each user will see the same state. Storage is ideal
for storing permanent document state, such as shapes on a canvas, notes on a
whiteboard, or cells in a spreadsheet.

### Data structures

Storage provides three different conflict-free data structures, which you can
use to build your application. All structures are permanent and persist when all
users have left the room, unlike [Presence](/docs/ready-made-features/presence)
which is temporary.

- [`LiveObject`][] - Similar to JavaScript object. Use this for storing records
  with fixed key names and where the values don’t necessarily have the same
  types. For example, a `Person` with a `name: string` and an `age: number`
  field. If multiple clients 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. Use this for indexing values that
  all have the same structure. For example, to store an index of `Person` values
  by their name. If multiple users update the same property simultaneously, the
  last modification received by the Liveblocks servers is the winner.

### Typing Storage [#typing-storage]

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

```ts
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: {
      animals: LiveList<string>;
    };
  }
}
```

You can then set an initial value in [`RoomProvider`][].

```tsx
import { LiveList } from "@liveblocks/client";
import { RoomProvider } from "@liveblocks/react/suspense";

function App() {
  return (
    <RoomProvider
      id="my-room-name"
      // +++
      initialStorage={{ animals: new LiveList(["Fido"]) }}
      // +++
    >
      {/* children */}
    </RoomProvider>
  );
}
```

The type received in your Storage will match the type passed. Learn more under
[typing your data](#typing-your-data).

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

function App() {
  const addAnimal = useMutation(({ storage }) => {
    const animals = storage.get("animals");

    // LiveList<["Fido"]>
    console.log(animals);

    animals.push("Felix");

    // LiveList<["Fido", "Felix"]>
    console.log(animals);
  });

  return <button onClick={addAnimal}>Add animal</button>;
}
```

[`useStorage`][] will return an immutable copy of the data, for example a
`LiveList` is converted to an `array`, which makes it easy to render.

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

function App() {
  const animals = useStorage((root) => root.animals);

  // ["Fido", "Felix"]
  console.log(animals);

  return (
    <ul>
      {animals.map((animal) => (
        <li key={animal}>{animal}</li>
      ))}
    </ul>
  );
}
```

### Nesting data structures

All Storage data structures can be nested, allowing you to create complex trees
of conflict-free data.

```ts
import { LiveObject, LiveList, LiveMap } from "@liveblocks/client";

type Person = LiveObject<{
  name: string;
  pets: LiveList<string>;
}>;

declare global {
  interface Liveblocks {
    Storage: {
      people: LiveMap<string, Person>;
    };
  }
}
```

Here’s an example of setting `initialStorage` for this type.

```tsx
import { LiveObject, LiveList, LiveMap } from "@liveblocks/client";
import { RoomProvider } from "@liveblocks/react/suspense";

function App() {
  return (
    <RoomProvider
      id="my-room-name"
      initialStorage={{
        // +++
        people: new LiveMap([
          [
            "alicia",
            new LiveObject({
              name: "Alicia",
              pets: new LiveList(["Fido", "Felix"]),
            }),
          ],
        ]),
        // +++
      }}
    >
      {/* children */}
    </RoomProvider>
  );
}
```

<Banner title="Need help troubleshooting Storage?">

Get the [Liveblocks DevTools extension](/devtools) to develop and debug your
application as you build it.

</Banner>

### useStorage [@badge=RoomProvider]

Extracts data from Liveblocks Storage state and automatically subscribes to
updates to that selected data. For full details, see [how selectors work][].

```tsx
// ✅ Rerenders if todos (or their children) change
const items = useStorage((root) => root.todos);

// ✅ Rerenders when todos are added or deleted
const numTodos = useStorage((root) => root.todos.length);

// ✅ Rerenders when the value of allDone changes
const allDone = useStorage((root) => root.todos.every((item) => item.done));

// ✅ Rerenders if any _unchecked_ todo items change
const uncheckedItems = useStorage(
  (root) => root.todos.filter((item) => !item.done),
  shallow // 👈
);
```

The `root` argument to the `useStorage` selector function is an _immutable_ copy
of your entire Liveblocks Storage tree. Think of it as the value you provided in
the `initialStorage` prop at the [`RoomProvider`][] level, but then
(recursively) converted to their “normal” JavaScript equivalents (objects,
arrays, maps) that are read-only.

From that immutable `root`, you can select or compute any value you like. Your
component will automatically get rerendered if the value you return differs from
the last rendered value.

This hook returns `null` while storage is still loading. To avoid that, use the
[Suspense version][].

<Banner type="success" title="Avoiding unnecessary rerenders">

It’s recommended to select only the subset of Storage data that your component
needs. This will avoid unnecessary rerenders that happen with overselection.

In order to select one item from a LiveMap within the storage tree with the
`useStorage` method, you can use the example below:

```ts
const key = "errands";
const myTodos = useStorage((root) => root.todoMap.get(key));
```

In order to query a LiveMap, and filter for specific values:

```ts
const myTodos = useStorage(
  root => Array.from(root.todoMap.values()).filter(...),
  shallow,
);
```

</Banner>

### useBatch [@badge=RoomProvider]

<Banner title="Deprecated">

Deprecated, starting with 0.18, we recommend using [`useMutation`][] for writing
to Storage, which will automatically batch all mutations.

</Banner>

Returns a function that batches Storage and Presence modifications made during
the given function. Each modification is grouped together, which means that
other clients receive the changes as a single message after the batch function
has run. Every modification made during the batch is merged into a single
history item (undo/redo).

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

const batch = useBatch();
batch(() => {
  // All modifications made in this callback are batched
});
```

Note that `batch` cannot take an `async` function.

```tsx
// ❌ Won't work
batch(async () => /* ... */);

// ✅ Will work
batch(() => /*... */);
```

### useHistory [@badge=RoomProvider]

Returns the room’s history. See [`Room.history`][] for more information.

```ts
import { useHistory } from "@liveblocks/react/suspense";

const { undo, redo, pause, resume } = useHistory();
```

### useUndo [@badge=RoomProvider]

Returns a function that undoes the last operation executed by the current
client. It does not impact operations made by other clients.

```ts
import { useUndo } from "@liveblocks/react/suspense";

const undo = useUndo();
```

### useRedo [@badge=RoomProvider]

Returns a function that redoes the last operation executed by the current
client. It does not impact operations made by other clients.

```ts
import { useRedo } from "@liveblocks/react/suspense";

const redo = useRedo();
```

### useCanUndo [@badge=RoomProvider]

Returns whether there are any operations to undo.

```ts
import { useCanUndo, useUpdateMyPresence } from "@liveblocks/react/suspense";

const updateMyPresence = useUpdateMyPresence();
const canUndo = useCanUndo();

updateMyPresence({ y: 0 });

// At the next render, "canUndo" will be true
```

### useCanRedo [@badge=RoomProvider]

Returns whether there are any operations to redo.

```ts
import {
  useCanRedo,
  useUndo,
  useUpdateMyPresence,
} from "@liveblocks/react/suspense";

const updateMyPresence = useUpdateMyPresence();
const undo = useUndo();
const canRedo = useCanRedo();

updateMyPresence({ y: 0 });
undo();

// At the next render, "canRedo" will be true
```

### useMutation [@badge=RoomProvider]

Creates a callback function that lets you mutate Liveblocks state.

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

const fillWithRed = useMutation(
  // Mutation context is passed as the first argument
  ({ storage, setMyPresence }) => {
    // Mutate Storage
    storage.get("shapes").get("circle1").set("fill", "red");
    //                                   ^^^

    // ...or Presence
    setMyPresence({ lastUsedColor: "red" });
  },
  []
);

// JSX
return <button onClick={fillWithRed} />;
```

To make the example above more flexible and work with _any_ color, you have two
options:

1. Close over a local variable and
   [adding it to the dependency array](#useMutation-dep-arrays), or
2. Have it take [an extra callback parameter](#useMutation-extra-params).

Both are equally fine, just a matter of preference.

#### With dependency arrays [#useMutation-dep-arrays]

```tsx
// Local state maintained outside Liveblocks
const [currentColor, setCurrentColor] = useState("red");

const fillWithCurrentColor = useMutation(
  ({ storage, setMyPresence }) => {
    storage.get("shapes").get("circle1").set("fill", currentColor);
    setMyPresence({ lastUsedColor: currentColor });
  },
  // +++
  [currentColor] // Works just like it would in useCallback
  // +++
);

// JSX
return <button onClick={fillWithCurrentColor} />;
```

<Banner type="success" title="Tip! Let ESLint check your dependencies">

If you use ESLint, we recommend to
[configure it to enforce](/docs/api-reference/liveblocks-react#useMutation-lint-rule)
the correct use of your dependency arrays.

</Banner>

#### With extra callback parameters [#useMutation-extra-params]

Alternatively, you can add extra parameters to your callback function:

```tsx
const fill = useMutation(
  // +++
  // Note the second argument
  ({ storage, setMyPresence }, color: string) => {
    // +++
    storage.get("shapes").get("circle1").set("fill", color);
    setMyPresence({ lastUsedColor: color });
  },
  []
);

// JSX
// +++
return <button onClick={() => fill("red")} />;
//                            ^^^^^^^^^^^ Now fill takes a color argument
// +++
```

#### Depending on current presence [#useMutation-presence]

For convenience, the mutation context also receives `self` and `others`
arguments, which are _immutable_ values reflecting the current Presence state,
in case your mutation depends on it.

For example, here’s a mutation that will delete all the shapes selected by the
current user.

```tsx
const deleteSelectedShapes = useMutation(
  // You can use current "self" or "others" state in the mutation
  // +++
  ({ storage, self, others, setMyPresence }) => {
    // +++
    // Delete the selected shapes
    const shapes = storage.get("shapes");
    // +++
    for (const shapeId of self.presence.selectedShapeIds) {
      // +++
      shapes.delete(shapeId);
    }

    // Clear the current selection
    setMyPresence({ selectedShapeIds: [] });
  },
  []
);

// JSX
return <button onClick={deleteSelectedShapes} />;
```

Mutations are automatically batched, so when using `useMutation` there’s no need
to use `useBatch`, or call `room.batch()` manually.

#### ESLint rule [#useMutation-lint-rule] [@keywords=["exhaustive-deps", "additionalHooks", "eslint-plugin-react-hooks"]]

If you are using ESLint in your project, and are using
[the React hooks plugin](https://reactjs.org/docs/hooks-rules.html#eslint-plugin),
we recommend to add a check for "additional hooks", so that it will also check
the dependency arrays of your `useMutation` calls:

```js
{
  "rules": {
    // ...
    "react-hooks/exhaustive-deps": ["warn", {
      "additionalHooks": "useMutation"
    }]
  }
}
```

## Comments

### useThreads [@badge=RoomProvider]

Returns the threads within the current room.

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

const { threads, error, isLoading } = useThreads();
```

`useThreads` supports a few options as its first argument, one is `query` and it
can be used to filter threads based on their metadata or resolved status.

```tsx
// Returns threads that match the entire `query`, e.g. { color: "blue", pinned: true, ... }
const { threads } = useThreads({
  query: {
    // Filter for unresolved threads
    resolved: false,

    metadata: {
      // Filter for threads that contain specific string, boolean, and number data
      color: "blue",
      pinned: true,
      priority: 3,

      // Filter for threads with string metadata that starts with a certain value
      organization: {
        startsWith: "liveblocks:",
      },
    },
  },
});
```

Another option is `scrollOnLoad`, which is enabled by default. When enabled, if
the URL’s hash is set to a comment ID (e.g.
`https://example.com/my-room#cm_xxx`), the page will scroll to that comment once
the threads are loaded.

By default, the `useThreads` hook returns up to 50 threads. To fetch more, the
hook (along with [`useInboxNotifications`][]) provides additional fields for
pagination.

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

const {
  isLoading,
  error,
  threads,

  +++
  // Available in Liveblocks 2.9
  fetchMore,
  isFetchingMore,
  hasFetchedAll,
  fetchMoreError,
  +++
} = useThreads({ query });
```

The `hasFetchedAll` field indicates whether all available threads have been
fetched since the initial load. To load more threads, you can call the
`fetchMore` function. This function is safe to call even if no more threads are
available or a fetch is already in progress—it simply won't do anything in that
case. Therefore, you don't need to check `hasFetchedAll` or `isFetchingMore`
before calling `fetchMore`.

The following example demonstrates how to use the `fetchMore` function to
implement a "Load More" button, which fetches additional threads when clicked.
The button is disabled while fetching is in progress.

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

  {hasFetchedAll ? (
    <div>🎉 You're all caught up!</div>
  ) : (
    <button disabled={isFetchingMore} onClick={fetchMore}>
      Load more
    </button>
  )}
</div>
```

Error handling is another important aspect to consider when using the
`useThreads` hook. The `error` and `fetchMoreError` fields provide information
about any errors that occurred during the initial fetch or subsequent fetch
operations, respectively. You can use these fields to display appropriate error
messages to the user and implement retry mechanisms if needed.

The following example shows how to display error messages for both initial
loading errors and errors that occur when fetching more threads.

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

const { threads, error, fetchMore, fetchMoreError } = useThreads();

// Handle error if the initial load failed.
// The `error` field is not returned by the Suspense hook as the error is thrown to nearest ErrorBoundary
if (error) {
  return (
    <div>
      <p>Error loading threads: {error.message}</p>
    </div>
  );
}

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

    {fetchMoreError && (
      <div>
        <p>Error loading more threads: {fetchMoreError.message}</p>
        <button onClick={fetchMore}>Retry</button>
      </div>
    )}
  </div>
);
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw error to the nearest ErrorBoundary if initial load
failed.

### useThreadSubscription [@badge=RoomProvider]

Returns the subscription status of a thread.

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

const { status, unreadSince } = useThreadSubscription("th_xxx");
```

### useCreateThread [@badge=RoomProvider]

Returns a function that creates a thread with an initial comment, and optionally
some metadata.

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

const createThread = useCreateThread();
const thread = createThread({ body: {}, attachments: [], metadata: {} });
```

### useDeleteThread [@badge=RoomProvider]

Returns a function that deletes a thread and all its associated comments by ID.
Only the thread creator can delete the thread.

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

const deleteThread = useDeleteThread();
deleteThread("th_xxx");
```

### useEditThreadMetadata [@badge=RoomProvider]

Returns a function that edits a thread’s metadata.

<Banner title="Deleting properties">

To delete an existing metadata property, set its value to `null`. Passing
`undefined` for a metadata property will ignore it.

</Banner>

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

const editThreadMetadata = useEditThreadMetadata();
editThreadMetadata({ threadId: "th_xxx", metadata: {} });
```

### useMarkThreadAsResolved [@badge=RoomProvider]

Returns a function that marks a thread as resolved.

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

const markThreadAsResolved = useMarkThreadAsResolved();
markThreadAsResolved("th_xxx");
```

### useMarkThreadAsUnresolved [@badge=RoomProvider]

Returns a function that marks a thread as unresolved.

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

const markThreadAsUnresolved = useMarkThreadAsUnresolved();
markThreadAsUnresolved("th_xxx");
```

### useMarkThreadAsRead [@badge=RoomProvider]

Returns a function that marks a thread as read.

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

const markThreadAsRead = useMarkThreadAsRead();
markThreadAsRead("th_xxx");
```

### useCreateComment [@badge=RoomProvider]

Returns a function that adds a comment to a thread.

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

const createComment = useCreateComment();
const comment = createComment({
  threadId: "th_xxx",
  body: {},
  attachments: [],
});
```

### useEditComment[@badge=RoomProvider]

Returns a function that edits a comment’s body.

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

const editComment = useEditComment();
editComment({
  threadId: "th_xxx",
  commentId: "cm_xxx",
  body: {},
  attachments: [],
});
```

### useDeleteComment [@badge=RoomProvider]

Returns a function that deletes a comment. If it is the last non-deleted
comment, the thread also gets deleted.

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

const deleteComment = useDeleteComment();
deleteComment({ threadId: "th_xxx", commentId: "cm_xxx" });
```

### useAddReaction [@badge=RoomProvider]

Returns a function that adds a reaction to a comment.

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

const addReaction = useAddReaction();
addReaction({ threadId: "th_xxx", commentId: "cm_xxx", emoji: "👍" });
```

### useRemoveReaction [@badge=RoomProvider]

Returns a function that removes a reaction from a comment.

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

const removeReaction = useRemoveReaction();
removeReaction({ threadId: "th_xxx", commentId: "cm_xxx", emoji: "👍" });
```

### useAttachmentUrl [@badge=RoomProvider]

Returns a presigned URL for an attachment by its ID.

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

const { url, error, isLoading } = useAttachmentUrl("at_xxx");
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw when there’s an error.

## Notifications

### useInboxNotifications [@badge=LiveblocksProvider]

Returns the inbox notifications for the current user. Inbox notifications are
[project-based](/docs/ready-made-features/notifications/concepts#Project-based),
meaning notifications from outside the current room are received.

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

const { inboxNotifications, error, isLoading } = useInboxNotifications();
```

By default, the `useInboxNotifications` hook returns up to 50 notifications. To
fetch more, the hook provides additional fields for pagination, similar to
[`useThreads`][].

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

const {
  inboxNotifications,
  isLoading,
  error,

  +++
  hasFetchedAll,
  fetchMore,
  isFetchingMore,
  fetchMoreError,
  +++
} = useInboxNotifications();
```

- `hasFetchedAll` indicates whether all available inbox notifications have been
  fetched.
- `fetchMore` loads up to 50 more notifications, and is always safe to call.
- `isFetchingMore` indicates whether more notifications are being fetched.
- `fetchMoreError` returns error statuses resulting from fetching more.

#### Pagination [#useInboxNotifications-pagination]

The following example demonstrates how to use the `fetchMore` function to
implement a “Load More” button, which fetches additional inbox notifications
when clicked. The button is disabled while fetching is in progress.

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

function Inbox() {
  const { inboxNotifications, hasFetchedAll, fetchMore, isFetchingMore } =
    useInboxNotifications();

  return (
    <div>
      {inboxNotifications.map((notification) => (
        <InboxNotification key={notification.id}>...</InboxNotification>
      ))}
      // +++
      {hasFetchedAll ? (
        <div>🎉 You're all caught up!</div>
      ) : (
        <button disabled={isFetchingMore} onClick={fetchMore}>
          Load more
        </button>
      )}
      // +++
    </div>
  );
}
```

#### Error handling [#useInboxNotifications-error-handling]

Error handling is another important aspect to consider when using the
`useInboxNotifications` hook. The `error` and `fetchMoreError` fields provide
information about any errors that occurred during the initial fetch or
subsequent fetch operations, respectively. You can use these fields to display
appropriate error messages to the user and implement retry mechanisms if needed.

The following example shows how to display error messages for both initial
loading errors and errors that occur when fetching more inbox notifications.

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

function Inbox() {
  const { inboxNotifications, error, fetchMore, fetchMoreError } =
    useInboxNotifications();

  // Handle error if the initial load failed.
  // The `error` field is not returned by the Suspense hook as the error is thrown to nearest ErrorBoundary
  // +++
  if (error) {
    return (
      <div>
        <p>Error loading inbox notifications: {error.message}</p>
      </div>
    );
  }
  // +++

  return (
    <div>
      {inboxNotifications.map((notification) => (
        <InboxNotification key={notification.id}>...</InboxNotification>
      ))}

      {fetchMoreError && (
        <div>
          <p>
            Error loading more inbox notifications: {fetchMoreError.message}
          </p>
          <button onClick={fetchMore}>Retry</button>
        </div>
      )}
    </div>
  );
}
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw error to the nearest ErrorBoundary if initial load
failed.

### useUnreadInboxNotificationsCount [@badge=LiveblocksProvider]

Returns the number of unread inbox notifications for the current user.

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

const { count, error, isLoading } = useUnreadInboxNotificationsCount();
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw when there’s an error.

### useMarkInboxNotificationAsRead [@badge=LiveblocksProvider]

Returns a function that marks an inbox notification as read for the current
user.

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

const markInboxNotificationAsRead = useMarkInboxNotificationAsRead();
markInboxNotificationAsRead("in_xxx");
```

### useMarkAllInboxNotificationsAsRead [@badge=LiveblocksProvider]

Returns a function that marks all of the current user‘s inbox notifications as
read.

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

const markAllInboxNotificationsAsRead = useMarkAllInboxNotificationsAsRead();
markAllInboxNotificationsAsRead();
```

### useDeleteInboxNotification [@badge=LiveblocksProvider]

Returns a function that deletes an inbox notification for the current user.

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

const deleteInboxNotification = useDeleteInboxNotification();
deleteInboxNotification("in_xxx");
```

### useDeleteAllInboxNotifications [@badge=LiveblocksProvider]

Returns a function that deletes all of the current user‘s inbox notifications.

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

const deleteAllInboxNotifications = useDeleteAllInboxNotifications();
deleteAllInboxNotifications();
```

### useInboxNotificationThread [@badge=LiveblocksProvider]

Returns the thread associated with a `"thread"` inbox notification.

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

const thread = useInboxNotificationThread("in_xxx");
```

It can **only** be called with IDs of `"thread"` inbox notifications, so we
recommend only using it
[when customizing the rendering](/docs/api-reference/liveblocks-react-ui#Rendering-notification-kinds-differently)
or in other situations where you can guarantee the kind of the notification.

<Banner type="info" title="No fetching and waterfalls">

When `useInboxNotifications` returns `"thread"` inbox notifications, it also
receives the associated threads and caches them behind the scenes. When you call
`useInboxNotificationThread`, it simply returns the cached thread for the inbox
notification ID you passed to it, without any fetching or waterfalls.

</Banner>

### useRoomNotificationSettings [@badge=RoomProvider]

Returns the user’s notification settings for the current room and a function to
update them. Updating this setting will change which
[`inboxNotifications`](#useInboxNotifications) the current user receives in the
current room.

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

const [{ settings }, updateSettings] = useRoomNotificationSettings();

// { threads: "replies_and_mentions" }
console.log(settings);

// No longer receive thread notifications in this room
updateSettings({
  threads: "none",
});
```

These are the three possible values that can be set:

- `"all"` Receive notifications for every activity.
- `"replies_and_mentions"` Receive notifications for mentions and thread you’re
  participating in.
- `"none"` No notifications are received.

### useUpdateRoomNotificationSettings [@badge=RoomProvider]

Returns a function that updates the user’s notification settings for the current
room. Updating this setting will change which
[`inboxNotifications`](#useInboxNotifications) the current user receives in the
current room.

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

const updateRoomNotificationSettings = useUpdateRoomNotificationSettings();

// No longer receive thread notifications in this room
updateSettings({
  threads: "none",
});
```

These are the three possible values that can be set:

- `"all"` Receive notifications for every activity.
- `"replies_and_mentions"` Receive notifications for mentions and thread you’re
  participating in.
- `"none"` No notifications are received.

Works the same as `updateSettings` in
[`useRoomNotificationSettings`](#useRoomNotificationSettings).

### useNotificationSettings [@badge=LiveblocksProvider]

<Banner>

User notification settings is currently in beta.

</Banner>

Returns the user’s notification settings in the current project, in other words
which [notification webhook events](/docs/platform/webhooks#NotificationEvent)
will be sent for the current user. User notification settings are project-based,
which means that `settings` and `updateSettings` are for the current user’s
settings in every room. Useful for creating a
[notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).

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

const [{ isLoading, error, settings }, updateSettings] =
  useNotificationSettings();

// Current user receives thread notifications on the email channel
// { email: { thread: true, ... }, ... }
console.log(settings);

// Disabling thread notifications on the email channel
updateSettings({
  email: {
    thread: false,
  },
});
```

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 [{ isLoading, error, settings }, updateSettings] =
  useNotificationSettings();

// { email: null, ... }
console.log(settings);
```

#### Updating notification settings [#useNotificationSettings-updating-notification-settings]

The `updateSettings` function can be used to update the current user’s
notification settings, changing their settings for every room in the project.
Each notification `kind` must first be enabled on your project’s notification
dashboard page before settings can be used.

```tsx
// You only need to pass partials
updateSettings({
  email: { thread: true },
});

// Enabling a custom notification on the slack channel
updateSettings({
  slack: { $myCustomNotification: true },
});

// Setting complex settings
updateSettings({
  email: {
    thread: true,
    textMention: false,
    $newDocument: true,
  },
  slack: {
    thread: false,
    $fileUpload: false,
  },
  teams: {
    thread: true,
  },
});
```

#### Error handling [#useNotificationSettings-error-handling]

Error handling is an important aspect to consider when using the
`useNotificationSettings` hook. The `error` fields provides information about
any error that occurred during the fetch operation.

The following example shows how to display error messages for both initial
loading errors and errors that occur when fetching more inbox notifications.

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

const [{ isLoading, error, settings }, updateSettings] =
  useNotificationSettings();

if (error) {
  return (
    <div>
      <p>Error loading user notification settings: {error.message}</p>
    </div>
  );
}
```

####

👉🏻 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw and error to the nearest `ErrorBoundary` if initial
load failed.

### useUpdateNotificationSettings [@badge=LiveblocksProvider]

<Banner>

User notification settings is currently in beta.

</Banner>

Returns a function that updates user’s notification settings, which affects
which [notification webhook events](/docs/platform/webhooks#NotificationEvent)
will be sent for the current user. User notification settings are project-based,
which means that `updateSettings` modifies the current 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. Useful for creating a
[notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).

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

const updateSettings = useUpdateNotificationSettings();

// Disabling thread notifications on the email channel
updateSettings({
  email: { thread: false },
});
```

Works the same as `updateSettings` in
[`useNotificationSettings`](#useNotificationSettings). You can pass a partial
object, or many settings at once.

```tsx
// You only need to pass partials
updateSettings({
  email: { thread: true },
});

// Enabling a custom notification on the slack channel
updateSettings({
  slack: { $myCustomNotification: true },
});

// Setting complex settings
updateSettings({
  email: {
    thread: true,
    textMention: false,
    $newDocument: true,
  },
  slack: {
    thread: false,
    $fileUpload: false,
  },
  teams: {
    thread: true,
  },
});
```

## Version History

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

### useHistoryVersions [@badge=RoomProvider]

Returns the versions of the room. See
[Version History Components](/docs/api-reference/liveblocks-react-ui#Version-history-components)
for more information on how to display versions.

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

const { versions, error, isLoading } = useHistoryVersions();
```

## Miscellaneous

### useUser [@badge=Both]

Returns user info from a given user ID.

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

const { user, error, isLoading } = useUser("user-id");
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw when there’s an error.

<Banner title="Providing a resolver function">

To use `useUser`, you should provide a resolver function to the
[`resolveUsers`][] option in [`createClient`][].

</Banner>

### useRoomInfo [@badge=Both]

Returns room info from a given room ID.

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

const { info, error, isLoading } = useRoomInfo("room-id");
```

👉 A [Suspense version][] of this hook is also available, which will never return
a loading state and will throw when there’s an error.

<Banner title="Providing a resolver function">

To use `useRoomInfo`, you should provide a resolver function to the
[`resolveRoomsInfo`][] option in [`createClient`][].

</Banner>

## TypeScript

### Typing your data

It’s possible to have automatic types flow through your application by defining
a global `Liveblocks` interface. We recommend doing this in a
`liveblocks.config.ts` file in the root of your app, so it’s easy to keep track
of your types. Each type (`Presence`, `Storage`, etc.), is optional, but it’s
recommended to make use of them.

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // Each user's Presence, for useMyPresence, useOthers, etc.
    Presence: {};

    // The Storage tree for the room, for useMutation, useStorage, etc.
    Storage: {};

    UserMeta: {
      id: string;
      // Custom user info set when authenticating with a secret key
      info: {};
    };

    // Custom events, for useBroadcastEvent, useEventListener
    RoomEvent: {};

    // Custom metadata set on threads, for useThreads, useCreateThread, etc.
    ThreadMetadata: {};

    // Custom room info set with resolveRoomsInfo, for useRoomInfo
    RoomInfo: {};

    // Custom activities data for custom notification kinds
    ActivitiesData: {};
  }
}

// Necessary if you have no imports/exports
export {};
```

Here are some example values that might be used.

```ts file="liveblocks.config.ts"
import { LiveList } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    // Each user's Presence, for useMyPresence, useOthers, etc.
    Presence: {
      // Example, real-time cursor coordinates
      cursor: { x: number; y: number };
    };

    // The Storage tree for the room, for useMutation, useStorage, etc.
    Storage: {
      // Example, a conflict-free list
      animals: LiveList<string>;
    };

    UserMeta: {
      id: string;
      // Custom user info set when authenticating with a secret key
      info: {
        // Example properties, for useSelf, useUser, useOthers, etc.
        name: string;
        avatar: string;
      };
    };

    // Custom events, for useBroadcastEvent, useEventListener
    // Example has two events, using a union
    RoomEvent: { type: "PLAY" } | { type: "REACTION"; emoji: "🔥" };

    // Custom metadata set on threads, for useThreads, useCreateThread, etc.
    ThreadMetadata: {
      // Example, attaching coordinates to a thread
      x: number;
      y: number;
    };

    // Custom room info set with resolveRoomsInfo, for useRoomInfo
    RoomInfo: {
      // Example, rooms with a title and url
      title: string;
      url: string;
    };

    // Custom activities data for custom notification kinds
    ActivitiesData: {
      // Example, a custom $alert kind
      $alert: {
        title: string;
        message: string;
      };
    };
  }
}

// Necessary if you have no imports/exports
export {};
```

### Typing with createRoomContext

Before Liveblocks 2.0, it was recommended to create your hooks using
[`createRoomContext`][], and manually pass your types to this function. This is
no longer [the recommended method](#Typing-your-data) for setting up Liveblocks,
but it can still be helpful, for example you can use `createRoomContext`
multiple times to create different room types, each with their own correctly
typed hooks.

```tsx file="liveblocks.config.ts" isCollapsable isCollapsed
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  // publicApiKey: "",
  // authEndpoint: "/api/liveblocks-auth",
});

// Presence represents the properties that 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 = {
  // animals: LiveList<string>,
  // ...
};

// Optionally, UserMeta represents static/readonly metadata on each user, as
// provided by your own custom auth back end (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 broadcast and listened to in this
// room. Use a union for multiple events. Must be JSON-serializable.
// type RoomEvent = {};

// Optionally, when using Comments, ThreadMetadata represents metadata on
// each thread. Can only contain booleans, strings, and numbers.
// export type ThreadMetadata = {
//   pinned: boolean;
//   quote: string;
//   time: number;
// };

export const {
  RoomProvider,
  useMyPresence,
  useStorage,

  // Other hooks
  // ...
} = createRoomContext<
  Presence,
  Storage
  /* UserMeta, RoomEvent, ThreadMetadata */
>(client);
```

To upgrade to Liveblocks 2.0 and the new typing system, follow the
[2.0 migration guide](/docs/platform/upgrading/2.0).

## Helpers

### shallow

Compares two values shallowly. This can be used as the second argument to
selector based functions to loosen the equality check:

```tsx
const redShapes = useStorage(
  (root) => root.shapes.filter((shape) => shape.color === "red"),
  shallow // 👈 here
);
```

The default way [selector results](#selectors-return-arbitrary-values) are
compared is by checking referential equality (`===`). If your selector returns
computed arrays (like in the example above) or objects, this will not work.

By passing `shallow` as the second argument, you can “loosen” this check. This
is because `shallow` will shallowly compare the members of an array (or values
in an object):

```tsx
// Comparing arrays
shallow([1, 2, 3], [1, 2, 3]); // true

// Comparison objects
shallow({ a: 1 }, { a: 1 }); // true
```

Please note that this will only do a shallow (one level deep) check. Hence the
name. If you need to do an arbitrarily deep equality check, you’ll have to write
a custom equality function or use a library like Lodash for that.

## How selectors work [#selectors] [@keywords=["useStorage", "useSelf", "useOthers", "useOther", "useOthersMapped", "useOthersConnectionIds", "selectors", "comparison"]]

The concepts and behaviors described in this section apply to all of our
selector hooks: [`useStorage`][] , [`useSelf`][] , [`useOthers`][] ,
[`useOthersMapped`][], and [`useOther`][] (singular).

```tsx file="Component.tsx"
const child = useStorage((root) => root.child);
const nested = useStorage((root) => root.child.nested);
const total = useStorage((root) => root.x + root.y);
const merged = useStorage((root) => [...root.items, ...root.more], shallow);
```

<Banner title="Examples are illustrated via useStorage">

In this section, `useStorage` is used as the canonical example. This is for
illustration purposes only. The described concepts and behaviors apply equally
to the other selector hooks.

</Banner>

In a nutshell, the key behaviors for all selector APIs are:

- They [receive immutable data](#selectors-receive-immutable-data)
- They [return arbitrary values](#selectors-return-arbitrary-values)
- They [auto-subscribe to updates](#selectors-subscribe-to-updates)

Let’s go over these traits and responsibilities in the next few sections.

### Selectors receive immutable data [#selectors-receive-immutable-data]

The received input to all selector functions is a **read-only** and
**immutable** top level context value that differs for each hook:

- `useStorage((root) => ...)` receives the Storage root
- `useSelf((me) => ...)` receives the current user
- `useOthers((others) => ...)` receives a list of other users in the room
- `useOthersMapped((other) => ...)` receives each individual other user in the
  room
- `useOther(connectionId, (other) => ...)` receives a specific user in the room

For example, suppose you have set up Storage in the typical way by setting
`initialStorage` in your [`RoomProvider`][] to a tree that describes your app’s
data model using `LiveList`, `LiveObject`, and `LiveMap`. The "root" argument
for your selector function, however, will receive **an immutable and read-only
representation** of that Storage tree, consisting of "normal" JavaScript
datastructures. This makes consumption much easier.

```tsx file="Component.tsx"
function Component() {
  useStorage((root) => ...);
  //          ^^^^
  //          Read-only. No mutable Live structures in here.
  //
  //          {
  //            animals: ["🦁", "🦊", "🐵"],
  //            mathematician: { firstName: "Ada", lastName: "Lovelace" },
  //            fruitsByName: new Map([
  //              ["apple", "🍎"],
  //              ["banana", "🍌"],
  //              ["cherry", "🍒"],
  //            ])
  //          }
  //
}
```

Internally, these read-only trees use a technique called **structural sharing**.
This means that between rerenders, if nodes in the tree did not change, they
will **guarantee** to return the same memory instance. Selecting and returning
these nodes directly is therefore safe and considered a good practice, because
they are stable references by design.

### Selectors return arbitrary values [#selectors-return-arbitrary-values] [@keywords=["shallow"]]

```tsx file="Component.tsx"
const animals = useStorage((root) => root.animals);
// ["🦁", "🦊", "🐵"]

const ada = useStorage((root) => root.mathematician);
// { firstName: "Ada", lastName: "Lovelace" }

const fullname = useStorage(
  (root) => `${root.mathematician.firstName} ${root.mathematician.lastName}`
);
// "Ada Lovelace"

const fruits = useStorage((root) => [...root.fruitsByName.values()], shallow);
// ["🍎", "🍌", "🍒"]
```

Selectors you write can return _any_ value. You can use it to “just” select
nodes from the root tree (first two examples above), but you can also return
computed values, like in the last two examples.

#### Selector functions must return a stable result

One important rule is that selector functions **must return a stable result** to
be efficient. This means calling the same selector twice with the same argument
should return two results that are _referentially equal_. Special care needs to
be taken when filtering or mapping over arrays, or when returning object
literals, because those operations create new array or object instances on every
call (the reason why is detailed
[in the next section](#selectors-subscribe-to-updates)).

#### Examples of stable results

<dl>
  <dt>✅ `(root) => root.animals` is stable</dt>
  <dd>
    Liveblocks guarantees this. All nodes in the Storage tree are stable
    references as long as their contents don’t change.
  </dd>
  <dt>️️⚠️ `(root) => root.animals.map(...)` is not stable</dt>
  <dd>
    Because `.map()` creates a new array instance every time. You’ll need to use
    [`shallow`][] here.
  </dd>
  <dt>✅ `(root) => root.animals.map(...).join(", ")` is stable</dt>
  <dd>
    Because `.join()` ultimately returns a string and all primitive values are
    always stable.
  </dd>
</dl>

#### Use a shallow comparison if the result isn’t stable

If your selector function doesn’t return a stable result, it will lead to an
explosion of unnecessary rerenders. In most cases, you can use a [`shallow`][]
comparison function to loosen the check:

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

// ❌ Bad - many unnecessary rerenders
const uncheckedItems = useStorage((root) =>
  root.todos.filter((item) => !item.done)
);

// ✅ Great
const uncheckedItems = useStorage(
  (root) => root.todos.filter((item) => !item.done),
  shallow // 👈 The fix!
);
```

If your selector function constructs complex objects, then a [`shallow`][]
comparison may not suffice. In those advanced cases, you can provide your own
custom comparison function, or use `_.isEqual` from Lodash.

### Selectors auto-subscribe to updates [#selectors-subscribe-to-updates]

Selectors effectively automatically subscribe your components to updates to the
selected or computed values. This means that your component will **automatically
rerender** when the selected value changes.

Using **multiple selector hooks** within a single React component is perfectly
fine. Each such hook will individually listen for data changes. The component
will rerender if _at least one_ of the hooks requires it. If more than one
selector returns a new value, the component _still only rerenders once_.

Technically, deciding if a rerender is needed works by re-running your selector
function `(root) => root.child` every time something changes inside Liveblocks
storage. Anywhere. That happens often in a busy multiplayer app! The reason why
this is still no problem is that even though `root` will be a different value on
every change, `root.child` will not be if it didn’t change (due to how
Liveblocks internally uses structural sharing).

Only once the returned value is different from the previously returned value,
the component will get rerendered. Otherwise, your component will just remain
idle.

Consider the case:

```tsx
function Component() {
  const animals = useStorage((root) => root.animals);
}
```

And the following timeline:

- First render, `root.animals` initially is `["🦁", "🦊", "🐵"]`.
- Then, something unrelated elsewhere in Storage is changed. In response to the
  change, `root.animals` gets re-evaluated, but it still returns the same
  (unchanged) array instance.
- Since the value didn’t change, no rerender is needed.
- Then, someone removes an animal from the list. In response to the change,
  `root.animals` gets re-evaluated, and now it returns `["🦁", "🦊"]`.
- Because the previous value and this value are different, the component will
  rerender, seeing the updated value.

[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`lostconnectiontimeout`]:
  /docs/api-reference/liveblocks-client#createClientLostConnectionTimeout
[`room.history`]: /docs/api-reference/liveblocks-client#Room.history
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`liveblocksprovider`]: /docs/api-reference/liveblocks-react#LiveblocksProvider
[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation
[`usestorage`]: /docs/api-reference/liveblocks-react#useStorage
[`useself`]: /docs/api-reference/liveblocks-react#useSelf
[`useothers`]: /docs/api-reference/liveblocks-react#useOthers
[`useothersmapped`]: /docs/api-reference/liveblocks-react#useOthersMapped
[`useothersconnectionids`]:
  /docs/api-reference/liveblocks-react#useOthersConnectionIds
[`useother`]: /docs/api-reference/liveblocks-react#useOther
[`uselostconnectionlistener`]:
  /docs/api-reference/liveblocks-react#useLostConnectionListener
[`clientsidesuspense`]: /docs/api-reference/liveblocks-react#ClientSideSuspsnse
[`usebroadcastevent`]: /docs/api-reference/liveblocks-react#useBroadcastEvent
[`usethreads`]: /docs/api-reference/liveblocks-react#useThreads
[`useinboxnotifications`]:
  /docs/api-reference/liveblocks-react#useInboxNotifications
[`usesyncstatus`]: /docs/api-reference/liveblocks-react#useSyncStatus
[`useerrorlistener`]: /docs/api-reference/liveblocks-react#useErrorListener
[`room`]: /docs/api-reference/liveblocks-client#Room
[`shallow`]: /docs/api-reference/liveblocks-react#shallow
[`resolveusers`]: /docs/api-reference/liveblocks-client#resolveUsers
[`resolveroomsinfo`]: /docs/api-reference/liveblocks-client#resolveRoomsInfo
[selector]: /docs/api-reference/liveblocks-react#selectors
[how selectors work]: /docs/api-reference/liveblocks-react#selectors
[suspense version]: /docs/api-reference/liveblocks-react#Suspense
[connection status example]:
  https://liveblocks.io/examples/connection-status/nextjs
[`atob`]: https://developer.mozilla.org/en-US/docs/Web/API/atob
[`base-64`]: https://www.npmjs.com/package/base-64
[`websocket`]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
[`ws`]: https://www.npmjs.com/package/ws
[`fetch`]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
[`node-fetch`]: https://npmjs.com/package/node-fetch

---
meta:
  title: "@liveblocks/redux"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/redux package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/redux` provides you with [Redux](https://react-redux.js.org/)
bindings for our realtime collaboration APIs, built on top of WebSockets. Read
our [getting started](/docs/get-started) guides to learn more.

## Enhancer

Enhancer that lets you connect a Redux state to Liveblocks Presence and Storage
features.

```js
import { liveblocksEnhancer } from "@liveblocks/redux";
import { configureStore } from "@reduxjs/toolkit";

const store = configureStore({
  reducer: /* reducer */,
  enhancers: [
    liveblocksEnhancer({
      client,
      storageMapping: {},
      presenceMapping: {},
    }),
  ],
});
```

### client [#enhancer-option-client]

See different authentication methods in the [`createClient`][] method.

```js highlight="1,4-6,12"
import { createClient } from "@liveblocks/client";
import { liveblocksEnhancer } from "@liveblocks/redux";

const client = createClient({
  authEndpoint: "/api/liveblocks-auth",
});

const store = configureStore({
  reducer: /* reducer */,
  enhancers: [
    liveblocksEnhancer({
      client,
    }),
  ],
});
```

### presenceMapping [#enhancer-option-presence-mapping]

Mapping used to synchronize a part of your Redux state with one Liveblocks room
presence.

```js highlight="20"
import { liveblocksEnhancer } from "@liveblocks/redux";

const initialState = {
  cursor: { x: 0, y: 0 },
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    /* reducers */
  },
});

const store = configureStore({
  reducer: slice.reducer,
  enhancers: [
    liveblocksEnhancer({
      client,
      presenceMapping: { cursor: true },
    }),
  ],
});
```

### storageMapping [#enhancer-option-storage-mapping]

Mapping used to synchronize a part of your Redux state with one Liveblocks Room
storage.

```js highlight="20"
import { liveblocksEnhancer } from "@liveblocks/redux";

const initialState = {
  scientist: { name: "" },
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    /* reducers */
  },
});

const store = configureStore({
  reducer: slice.reducer,
  enhancers: [
    liveblocksEnhancer({
      client,
      storageMapping: { scientist: true },
    }),
  ],
});
```

## Actions

### ENTER [#actions-enter]

Dispatch `enterRoom` action to enter a room and start sync it with Redux state.

- `roomId`: The room’s ID.

```js
import { actions } from "@liveblocks/redux";
import { useDispatch, useSelector } from "react-redux";

const dispatch = useDispatch();

dispatch(actions.enterRoom("roomId"));
```

### LEAVE [#actions-leave]

Dispatch `leaveRoom` action to leave the current room and stop syncing it with
Redux state.

```js
import { actions } from "@liveblocks/redux";
import { useDispatch, useSelector } from "react-redux";

const dispatch = useDispatch();

dispatch(actions.leaveRoom());
```

## state.liveblocks [#liveblocks-state]

Liveblocks extra state attached by the enhancer.

### others [#liveblocks-state-others]

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

```js
const others = useSelector((state) => state.liveblocks.others);
```

### isStorageLoading [#liveblocks-state-is-storage-loading]

Whether the room storage is currently loading.

```js
const connection = useSelector((state) => state.liveblocks.isStorageLoading);
```

### status [#liveblocks-state-status]

Gets the current WebSocket connection status of the room.

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

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

[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[`status`]: /docs/api-reference/liveblocks-redux#liveblocks-state-status

---
meta:
  title: "@liveblocks/yjs"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/yjs package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/yjs` is a [Yjs](https://yjs.dev/) provider enabling you to use
Liveblocks as the hosted back end of your realtime collaborative application.
Read our [getting started](/docs/get-started) guides to learn more.

## Setup

To set up Yjs, it’s recommended to use [`getYjsProviderForRoom`][]. It’s no
longer recommended to use [`LiveblocksYjsProvider`][] directly, as issues may
happen when dynamically switching between rooms.

### React

In React, pass your room object with [`useRoom`][]. It’s fine to use this
function in your React components. From here, you can access your `Y.Doc`.

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

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

  // ...
}
```

### JavaScript

In JavaScript, pass the room retrieved with [`client.enterRoom`][].

```tsx
import { createClient } from "@liveblocks/client";
import { getYjsProviderForRoom } from "@liveblocks/yjs";

const client = createClient({
  // Options
  // ...
});

const { room, leave } = client.enterRoom("my-room-id", {
  // Options
  // ...
});

const yProvider = getYjsProviderForRoom(room);
const yDoc = yProvider.getYDoc();
```

## getYjsProviderForRoom [#getYjsProviderForRoom]

Gets the current or creates a new [`LiveblocksYjsProvider`][] for a room—this is
the recommended way to use Yjs. This provider will automatically be cleaned up
when the room is destroyed, so you don’t need to destroy the provider manually.
The second argument is the [`LiveblocksYjsProvider`][] options.

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

const yProvider = getYjsProviderForRoom(room, {
  // Options
  // ...
});

const yDoc = yProvider.getYDoc();
```

<PropertiesList title="Returns">
  <PropertiesListItem name="yProvider" type="LiveblocksYjsProvider">
    The [`LiveblocksYjsProvider`][] for the room. The provider is automatically
    cleaned up and destroyed when necessary. Fetch your [`Y.Doc`][] with
    [`LiveblocksYjsProvider.getYDoc`](#LiveblocksYjsProvider.getYDoc).
  </PropertiesListItem>
</PropertiesList>

<PropertiesList title="Arguments">
  <PropertiesListItem name="room" type="Room" required>
    The Liveblocks room, retrieved with [`useRoom`][] or [`client.enterRoom`][].
  </PropertiesListItem>
  <PropertiesListItem
    name="options.autoloadSubdocs"
    type="boolean"
    defaultValue="false"
  >
    This option will load subdocs automatically.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.enablePermanentUserData"
    type="boolean"
    defaultValue="false"
  >
    This option enables Yjs permanent user data class used by some libraries for
    tracking changes by author.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.offlineSupport_experimental"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Enable offline support using IndexedDB. This means the after
    the first load, documents will be stored locally and load instantly.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.useV2Encoding_experimental"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Use V2 encoding.
  </PropertiesListItem>
</PropertiesList>

## LiveblocksYjsProvider [#LiveblocksYjsProvider]

`LiveblocksYjsProvider` is a
[Yjs provider](https://github.com/yjs/yjs#providers) that allows you to connect
a Yjs document to Liveblocks. Any changes you make to the document will be
stored on Liveblocks servers and synchronized with other clients in the room.

<Banner title="Not recommended to use directly" type="warning">

We generally recommend getting your Liveblocks Yjs provider with
[`getYjsProviderForRoom`][] as it overcomes problems caused when dynamically
switching between rooms.

</Banner>

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

```ts highlight="13-15"
import * as Y from "yjs";
import { createClient } from "@liveblocks/client";
import { LiveblocksYjsProvider } from "@liveblocks/yjs";

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const { room, leave } = client.enterRoom("your-room-id");

// Create Yjs document and provider
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, yDoc, {
  // Options
  // ...
});
```

<PropertiesList title="Arguments">
  <PropertiesListItem name="room" type="Room" required>
    The Liveblocks room, retrieved with [`useRoom`][] or [`client.enterRoom`][].
  </PropertiesListItem>
  <PropertiesListItem name="yDoc" type="Y.Doc" required>
    The [`Y.Doc`][] for the document.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.autoloadSubdocs"
    type="boolean"
    defaultValue="false"
  >
    This option will load subdocs automatically.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.enablePermanentUserData"
    type="boolean"
    defaultValue="false"
  >
    This option enables Yjs permanent user data class used by some libraries for
    tracking changes by author.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.offlineSupport_experimental"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Enable offline support using IndexedDB. This means the after
    the first load, documents will be stored locally and load instantly.
  </PropertiesListItem>
  <PropertiesListItem
    name="options.useV2Encoding_experimental"
    type="boolean"
    defaultValue="false"
  >
    Experimental. Use V2 encoding.
  </PropertiesListItem>
</PropertiesList>

### LiveblocksYjsProvider.getYDoc

Returns the current room’s root [`Y.Doc`][].

```ts
// Root Y.Doc for the room
const yDoc = yProvider.getYDoc();
```

### LiveblocksYjsProvider.awareness [#LiveblocksYjsProvider.awareness]

The [awareness](#Awareness) instance attached to the provider.

```ts
// Yjs awareness
const awareness = yProvider.awareness;
```

### LiveblocksYjsProvider.destroy

Cleanup function. Destroys the [`LiveblocksYjsProvider`][] instance and removes
all resources.

```ts
// Clean up yProvider
yProvider.destroy();
```

### LiveblocksYjsProvider.on("sync") [#LiveblocksYjsProvider.on.sync]

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

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

Aliased by `LiveblocksYjsProvider.on("synced")`.

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

### LiveblocksYjsProvider.off("sync") [#LiveblocksYjsProvider.off.sync]

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

```ts
const handleSync = (synced: boolean) => {};
yProvider.on("sync", handleSync);

// Clean up sync event
yProvider.off("sync", handleSync);
```

Aliased by `LiveblocksYjsProvider.on("synced")`.

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

### LiveblocksYjsProvider.once("sync") [#LiveblocksYjsProvider.once.sync]

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

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

Aliased by `LiveblocksYjsProvider.once("synced")`.

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

### LiveblocksYjsProvider.emit("sync") [#LiveblocksYjsProvider.emit.sync]

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

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

Aliased by `LiveblocksYjsProvider.emit("synced")`.

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

### LiveblocksYjsProvider.synced [#LiveblocksYjsProvider.synced]

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

```ts
// Check if Yjs content is synchronized with the server
const isSynced: boolean = yProvider.synced;
```

### LiveblocksYjsProvider.connect [#LiveblocksYjsProvider.connect]

Does nothing, added for compatibility. Connections are handled by the
[Liveblocks client](https://liveblocks.io/docs/api-reference/liveblocks-client#createClient).

### LiveblocksYjsProvider.disconnect [#LiveblocksYjsProvider.disconnect]

Does nothing, added for compatibility. Connections are handled by the
[Liveblocks client](https://liveblocks.io/docs/api-reference/liveblocks-client#createClient).

## Awareness [#Awareness]

[`LiveblocksYjsProvider`][] instances have an `awareness` property, which is
powered by
[Liveblocks Presence](/docs/api-reference/liveblocks-client#Room.getPresence).
You can pass it to various bindings which implement awareness, for example
plugins that enable multiplayer cursors in text editors.

```ts
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, yDoc);

// Yjs awareness
const awareness = yProvider.awareness;
```

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

```ts
// Yjs awareness
const awareness = room.getPresence().__yjs;
```

### Awareness.doc [#Awareness.doc]

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

```ts
// The current Yjs document
const yDoc: Y.Doc = awareness.doc;
```

### Awareness.clientId [#Awareness.clientId]

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

```ts
// A unique number representing the current user
const clientId: number = awareness.clientId;
```

### Awareness.getLocalState [#Awareness.getLocalState]

Get the current user’s awareness state.

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

### Awareness.setLocalState [#Awareness.setLocalState]

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

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

### Awareness.setLocalStateField [#Awareness.setLocalStateField]

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

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

### Awareness.getStates [#Awareness.getStates]

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

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

### Awareness.states [#Awareness.states]

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

```ts
// A Map of each user’s awareness state
const states: Map<number, unknown> = awareness.states;
```

### Awareness.meta [#Awareness.meta]

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

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

### Awareness.destroy [#Awareness.destroy]

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

```ts
// Cleanup function
awareness.destroy();
```

### Awareness.on("destroyed") [#Awareness.on.destroyed]

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

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

### Awareness.off("destroyed") [#Awareness.off.destroyed]

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

```ts
const handleDestroy = () => {};
awareness.on("destroyed", handleDestroy);

// Clean up destroy event
awareness.off("destroyed", handleDestroy);
```

### Awareness.once("destroyed") [#Awareness.once.destroyed]

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

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

### Awareness.emit("destroyed") [#Awareness.emit.destroyed]

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

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

[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`useRoom`]: /docs/api-reference/liveblocks-react#useRoom
[`room.getPresence`]: /docs/api-reference/liveblocks-client#Room.getPresence
[`client.enterRoom`]: /docs/api-reference/liveblocks-client#Client.enterRoom
[`useMyPresence`]: /docs/api-reference/liveblocks-react#useMyPresence
[`getYjsProviderForRoom`]: #getYjsProviderForRoom
[`LiveblocksYjsProvider`]: #LiveblocksYjsProvider
[`LiveblocksYjsProvider.awareness]: #LiveblocksYjsProvider.awareness
[`LiveblocksYjsProvider.destroy]: #LiveblocksYjsProvider.destroy
[`LiveblocksYjsProvider.on("sync")`]: #LiveblocksYjsProvider.on.sync
[`LiveblocksYjsProvider.off("sync")`]: #LiveblocksYjsProvider.off.sync
[`LiveblocksYjsProvider.once("sync")`]: #LiveblocksYjsProvider.once.sync
[`LiveblocksYjsProvider.emit("sync")`]: #LiveblocksYjsProvider.emit.sync
[`LiveblocksYjsProvider.synced`]: #LiveblocksYjsProvider.synced
[`LiveblocksYjsProvider.connect`]: #LiveblocksYjsProvider.connect
[`LiveblocksYjsProvider.disconnect`]: #LiveblocksYjsProvider.disconnect
[`Awareness`]: #Awareness
[`Awareness.doc`]: #Awareness.doc
[`Awareness.clientId]: #Awareness.clientId
[`Awareness.getLocalState`]: #Awareness.getLocalState
[`Awareness.setLocalState`]: #Awareness.setLocalState
[`Awareness.setLocalStateField`]: #Awareness.setLocalStateField
[`Awareness.getStates`]: #Awareness.getStates
[`Awareness.states`]: #Awareness.states
[`Awareness.destroy`]: #Awareness.destroy
[`Awareness.meta`]: #Awareness.meta
[`Awareness.on("destroyed")`]: #Awareness.on.destroyed
[`Awareness.off("destroyed")`]: #Awareness.off.destroyed
[`Awareness.once("destroyed")`]: #Awareness.once.destroyed
[`Awareness.emit("destroyed")`]: #Awareness.emit.destroyed
[`Y.Doc`]: https://docs.yjs.dev/api/y.doc

---
meta:
  title: "@liveblocks/zustand"
  parentTitle: "API Reference"
  description: "API Reference for the @liveblocks/zustand package"
alwaysShowAllNavigationLevels: false
---

`@liveblocks/zustand` provides you with [Zustand](https://docs.pmnd.rs/zustand)
bindings for our realtime collaboration APIs, built on top of WebSockets. Read
our [getting started](/docs/get-started) guides to learn more.

## Middleware

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

```js highlight="2,5,9-13"
import create from "zustand";
import { liveblocks } from "@liveblocks/zustand";

const useStore = create(
  liveblocks(
    (set) => ({
      /* state and actions */
    }),
    {
      client,
      presenceMapping: {},
      storageMapping: {},
    }
  )
);
```

### client [#middleware-option-client]

See different authentication methods in the [`createClient`][] method.

```js
import { createClient } from "@liveblocks/client";
import { liveblocks } from "@liveblocks/zustand";

const client = createClient({
  authEndpoint: "/api/liveblocks-auth",
});

liveblocks(/* Zustand config */, { client })
```

### presenceMapping [#middleware-option-presence-mapping]

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

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

### storageMapping [#middleware-option-storage-mapping]

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

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

## state.liveblocks [#liveblocks-state]

Liveblocks extra state attached by the liveblocks.

### enterRoom [#liveblocks-state-enter-room]

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

- `roomId`: The room’s ID.

```js
const {
  liveblocks: { enterRoom },
} = useStore();

enterRoom("roomId");
```

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

### leaveRoom [#liveblocks-state-leave-room]

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

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

leaveRoom();
```

### room [#liveblocks-state-room]

The [`Room`][] currently synced to your Zustand state.

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

### others [#liveblocks-state-others]

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

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

### isStorageLoading [#liveblocks-state-is-storage-loading]

Whether or not the room storage is currently loading.

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

### status [#liveblocks-state-status]

Gets the current WebSocket connection status of the room.

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

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

[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[`room`]: /docs/api-reference/liveblocks-client#room
[`status`]: /docs/api-reference/liveblocks-zustand#liveblocks-state-status

---
meta:
  title: "API v1 Endpoints"
  parentTitle: "API Reference"
  description: "API Reference for the REST v1 endpoints"
---

Manage a room and its storage using the Liveblocks REST API endpoints. They’ll
help you manage your data and extend Liveblocks’ functionality. You’ll find the
API base URL below.

```bash
https://liveblocks.net/api/v1/
```

<Banner title="API v1 is deprecated">

This is the API v1 reference, learn more about the latest version on the [API v2
reference][].

</Banner>

## Authentication

To use the API, you need to add a JWT token to the request’s authorization
header:

```bash
curl https://liveblocks.net/api/v1/* \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

You can get a JWT token by calling our authorization endpoint, using your secret
key (accessible from the dashboard). The token will be valid for one hour.

```bash
curl https://liveblocks.io/api/authorize \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

### Example response [@hidden]

```json
{ "token": "YOUR_JWT_TOKEN" }
```

## Get room storage

Get the room storage data as a JSON using the endpoint below.

<EndpointBlock
  method="GET"
  endpoint="https://liveblocks.net/api/v1/room/:roomId/storage"
/>

### Some implementation details [@hidden]

- Each Liveblocks data structure is represented by a JSON element having two
  properties:
  - `"liveblocksType"`: [`"LiveObject"`][] | [`"LiveList"`][] | [`"LiveMap"`][]
  - `"data"` => contains the nested data structures (children) and data.
- The root is always a `LiveObject`.

### Example response [@hidden]

```json
{
  "liveblocksType": "LiveObject",
  "data": {
    "aLiveObject": {
      "liveblocksType": "LiveObject",
      "data": {
        "a": 1
      }
    },
    "aLiveList": {
      "liveblocksType": "LiveList",
      "data": ["a", "b"]
    },
    "aLiveMap": {
      "liveblocksType": "LiveMap",
      "data": {
        "a": 1,
        "b": 2
      }
    }
  }
}
```

## Initialize room storage

Initialize a room storage using the following endpoint. The storage of the room
you’re initializing must be empty. The new storage data can be passed as a JSON
in the request body.

<EndpointBlock
  method="POST"
  endpoint="https://liveblocks.net/api/v1/room/:roomId/storage"
/>

### Some implementation details [@hidden]

- The format of the request body is the same as what's returned by the get
  storage endpoint.
- For each Liveblocks data structure that you want to create, you need a JSON
  element having two properties:

  - `"liveblocksType"`: [`"LiveObject"`][] | [`"LiveList"`][] | [`"LiveMap"`][]
  - `"data"` => contains the nested data structures (children) and data.

- The root's type can only be `LiveObject`.

### Example request body [@hidden]

```json
{
  "liveblocksType": "LiveObject",
  "data": {
    "aLiveObject": {
      "liveblocksType": "LiveObject",
      "data": {
        "a": 1
      }
    },
    "aLiveList": {
      "liveblocksType": "LiveList",
      "data": ["a", "b"]
    },
    "aLiveMap": {
      "liveblocksType": "LiveMap",
      "data": {
        "a": 1,
        "b": 2
      }
    }
  }
}
```

## Delete room storage

Delete all elements of the room storage using the following endpoint.

<EndpointBlock
  method="DELETE"
  endpoint="https://liveblocks.net/api/v1/room/:roomId/storage"
/>

## Get room users

Get the current list of users connected to a room.

<EndpointBlock
  method="GET"
  endpoint="https://liveblocks.net/api/v1/room/:roomId/users"
/>

### Some implementation details [@hidden]

- User's custom properties `id` and `info` can be set during the authentication
  to the room, see [`authorize`][].

### Example response [@hidden]

```json
{
  "data": [
    {
      "type": "user",
      "connectionId": 0,
      "id": "customUserId",
      "info": {}
    }
  ]
}
```

[api v2 reference]: /docs/api-reference/rest-api-endpoints
[`"livelist"`]: /docs/api-reference/liveblocks-client#LiveList
[`"livemap"`]: /docs/api-reference/liveblocks-client#LiveMap
[`"liveobject"`]: /docs/api-reference/liveblocks-client#LiveObject
[`authorize`]: /docs/api-reference/liveblocks-node#authorize

---
meta:
  title: "Authentication"
  description: "Learn more about authenticating your Liveblocks application"
---

Liveblocks provides different methods to authenticate your application using
your public and secret API keys. For any production application, you should use
your secret key to enable [access token](#access-tokens) or
[ID token](#id-tokens) authentication. These methods can be used to control
access to your rooms and data.

<Banner title="Public key is only for prototyping and landing pages" type="warning">

We don’t recommend using your public API key in production, as it makes it
possible for end users to access any room’s data. It’s also difficult for us to
accurately measure your monthly collaborating users without any user
information. We recommend using your secret key instead, see below.

</Banner>

## Authentication methods

Secret key authentication in Liveblocks relies on generating
[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWTs), and then
passing these to your client. There are two different types of authentication
tokens you can generate and it’s important to decide on which you need before
setting up your application.

### Access tokens [#access-tokens]

[Access token](/docs/authentication/access-token) authentication allows you to
handle permissions yourself. When a user authenticates, it’s up to you to let
Liveblocks know which rooms they should be allowed inside. This means that you
need to manually keep track of which users should be allowed in which rooms, and
apply these permissions yourself each time a user connects.

<Figure>
  <Image
    src="/assets/authentication/access-token-enter-room.png"
    alt="An access token granting entry to a room"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

In the diagram above, you can see that `olivier@example.com`’s access token is
allowing him into the `Vu78Rt:design:9Hdu73` room. A naming pattern like this is
necessary for your rooms when using access tokens, and it works well for simple
permissions. However, if you need complex permissions, we recommend ID tokens.

### ID tokens [#id-tokens]

[ID token](/docs/authentication/id-token) authentication allows Liveblocks to
handle permissions for you. This means that when you create or modify a room,
you can set a user’s permissions on the room itself, this acting as a source of
truth. Later, when a user tries to enter a room, Liveblocks will automatically
check if the user has permission, and deny them access if the permissions aren’t
set.

<Figure>
  <Image
    src="/assets/authentication/id-token-enter-room.png"
    alt="An ID token granting entry to a room"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

In the diagram above, `olivier@example.com`’s ID token verifies his identity,
and when he tries to enter the `a32wQXid4A9` room, his permissions are then
checked on the room itself. ID tokens are best if you need complex permissions
set on different levels (e.g. workspace → team → user).

## Choose a method

- **Access token authentication** is best for prototyping, as it’s easy to set
  up. It’s also ideal if you only need simple permissions, and you’d prefer
  handle these without relying on Liveblocks.
- **ID token authentication** is best if you’d like Liveblocks to automatically
  prevent access to the wrong users. It allows you to set different levels of
  permissions on different users and groups.

<ListGrid columns={2}>
  <DocsCard
    title="Access token authentication"
    href="/docs/authentication/access-token"
    type="image"
    description="Simple and flexible global permission rules"
    center={false}
    visual={
      <Image
        src="/assets/authentication/access-token-enter-room.png"
        alt="An access token granting entry to a room"
        width={1494}
        height={840}
        quality={100}
      />
    }
  />
  <DocsCard
    title="ID token authentication"
    href="/docs/authentication/id-token"
    type="image"
    description="Fine grained permissions at the room level"
    center={false}
    visual={
      <Image
        src="/assets/authentication/id-token-enter-room.png"
        alt="An ID token granting entry to a room"
        width={1494}
        height={840}
        quality={100}
      />
    }
  />
</ListGrid>

---
meta:
  title: "Authenticate with access tokens"
  parentTitle: "Authentication"
  description: "Learn more about access token permissions"
---

Access token authentication allows you to handle permissions yourself. When a
user authenticates, it’s up to you to let Liveblocks know which rooms they
should be allowed inside. This means that you need to manually keep track of
which users should be allowed in which rooms, and apply these permissions
yourself each time a user connects.

<Figure>
  <Image
    src="/assets/authentication/access-token-enter-room.png"
    alt="An access token granting entry to a room"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

<Banner title="Looking for more complex permissions?" type="warning">

If you’re looking to build an application with permissions at organization,
group, and user levels, we recommend using
[ID tokens](/docs/authentication/id-token) instead. Access tokens have
[limitations when granting nested permissions](#limitations).

</Banner>

## Authenticating

Authenticating with access tokens means creating a
[JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWT) that grants
the current user permission to enter certain rooms when connecting to
Liveblocks. An access token is created by calling
[`liveblocks.prepareSession`](/docs/api-reference/liveblocks-node#access-tokens)
then by allowing access to certain rooms.

```ts
const session = liveblocks.prepareSession("olivier@example.com");

// Giving write access to one room, then read access to multiple rooms with a wildcard
session.allow("Vu78Rt:design:9Hdu73", session.FULL_ACCESS);
session.allow("Vu78Rt:product:*", session.READ_ACCESS);

const { body, status } = await session.authorize();

// '{ token: "j6Fga7..." }'
console.log(body);
```

**Before using access tokens, it’s recommended to read through this entire
page**, as it explains helpful practices for granting access to rooms. However,
if you’d like to get set up now, you can select your framework and read more
later.

<ListGrid columns={3}>
  <DocsCard
    title="Next.js"
    href="/docs/authentication/access-token/nextjs"
    visual={<DocsNextjsIcon />}
  />
  <DocsCard
    title="Remix"
    href="/docs/authentication/access-token/remix"
    visual={<DocsRemixIcon />}
  />
  <DocsCard
    title="SvelteKit"
    href="/docs/authentication/access-token/sveltekit"
    visual={<DocsSvelteIcon />}
  />
  <DocsCard
    title="Nuxt.js"
    href="/docs/authentication/access-token/nuxtjs"
    visual={<DocsNuxtjsIcon />}
  />
  <DocsCard
    title="Express"
    href="/docs/authentication/access-token/express"
    visual={<DocsExpressIcon />}
  />
  <DocsCard
    title="Firebase"
    href="/docs/authentication/access-token/firebase"
    visual={<DocsFirebaseIcon />}
  />
</ListGrid>

## Permissions [#permissions]

### Default permissions

When creating rooms automatically with
[`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider) **every room
is publicly available**. If you’d like to prevent unauthenticated access to your
room data, you must instead set permissions on your back end using the
[Liveblocks Node.js package](/docs/api-reference/rest-api-endpoints), or the
[REST API](/docs/api-reference/rest-api-endpoints).

#### Permission types [#permission-types]

There are three permission values that you can set as default on rooms.

<dl>
  <dt>`["room:write"]`</dt>
  <dd>
    Full access. Enables people to view and edit the room. `isReadOnly` is
    `false`. Also known as `session.FULL_ACCESS`.
  </dd>
  <dt>`["room:read", "room:presence:write"]`</dt>
  <dd>
    Read access with presence. Enables people to edit their presence, but only
    view the room&rsquo;s storage. `isReadOnly` is `true`. Also known as
    `session.READ_ACCESS`.
  </dd>
  <dt>`[]`</dt>
  <dd>
    Private. Only users that have been given explicit access can enter the room.
  </dd>
</dl>

#### Setting default permissions

The `defaultAccesses` level is used to set the default permissions of the entire
room.

<Figure>
  <Image
    src="/assets/managing-rooms/rooms-access-denied.png"
    alt="Access denied illustration"
    width={820}
    height={412}
  />
</Figure>

We can use the
[`liveblocks.createRoom`](/docs/api-reference/rest-api-endpoints#post-rooms) to
create a new room with private access by default:

```ts highlight="2"
const room = await liveblocks.createRoom("Vu78Rt:design:9Hdu73", {
  defaultAccesses: [],
});
```

We could also later modify the value with
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#post-rooms-roomId),
in this example turning the room read-only:

```ts highlight="2"
const room = await liveblocks.updateRoom("Vu78Rt:design:9Hdu73", {
  defaultAccesses: ["room:read", "room:presence:write"],
});
```

### Advanced permissions

Along with default permissions, you can assign advanced permissions to
individual users. These permissions will override any default permissions.

When granting advanced permissions using access tokens, it’s recommended to use
a naming pattern for your room IDs. This makes it easy to use wildcard
permissions, allowing you to authenticate access to multiple rooms at once. One
scenario where this is helpful, is when rooms and users in your app are part of
an organization (or workspace), and you need to permit users entry to each room
that’s part of this.

#### Organization hierarchy

Let’s picture an organization, a customer in your product. This organization has
a number of groups (or teams), and each group can create documents that other
members of the group can view.

<Figure>
  <Image
    src="/assets/authentication/room-organizations.png"
    srcDark="/assets/authentication/room-organizations-dark.png"
    alt="An organization with documents in different teams"
    width={1536}
    height={864}
    quality={100}
  />
</Figure>

In your application, each organization, group, and document has a unique ID, and
we can use these to create a naming pattern for your rooms. For example, in the
diagram above, the Acme organization (`Vu78Rt`) has a Product group (`product`)
with two documents inside (`6Dsw12`, `L2hr8p`).

#### Naming pattern

An example of a naming pattern would be to combine the three IDs into a unique
room ID separating them with symbols, such as
`<organization_id>:<group_id>:<document_id>`. A room ID following this pattern
may look like `Vu78Rt:product:6Dsw1z`.

<Figure>
  <Image
    src="/assets/authentication/room-name-pattern.png"
    srcDark="/assets/authentication/room-name-pattern-dark.png"
    alt="Splitting a room ID into the pattern detailed above"
    width={1536}
    height={864}
    quality={100}
  />
</Figure>

<Banner title="Example pattern">

This example is not a strict naming pattern you must follow, and you can use any
pattern you like. Take care to avoid using your separator character in any other
part of the room ID.

</Banner>

#### Wildcard permissions

Assuming you’re using the naming pattern displayed above, you can then grant
access to multiple rooms at once using wildcards.

<Figure>
  <Image
    src="/assets/authentication/access-token-room-naming.png"
    alt="An access token using a wildcard to access multiple rooms"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

In the image above, you can see that _Olivier_ has access to multiple _product_
rooms, thanks to the `Vu78Rt:product:*` wildcard rule. This is how he was
authorized:

```ts
const session = liveblocks.prepareSession("olivier@example.com");

// Giving full access to one room
session.allow("Vu78Rt:design:9Hdu73", session.FULL_ACCESS);

// Give full access to every room with an ID beginning with "Vu78Rt:product:"
session.allow("Vu78Rt:product:*", session.FULL_ACCESS);

const { body, status } = await session.authorize();
```

Note that you can only use a wildcard at the end of a room ID.

```jsx
// ❌ Wildcard must be at the end of the room ID
session.allow("Vu78Rt:*:product", session.FULL_ACCESS);

// ✅ Valid wildcard
session.allow("Vu78Rt:product:*", session.FULL_ACCESS);
```

#### Read-only access

Should we wish to grant read-only access to each room in the organization, we
then add another line to enable this.

```ts highlight="9-10"
const session = liveblocks.prepareSession("olivier@example.com");

// Giving full access to one room
session.allow("Vu78Rt:design:9Hdu73", session.FULL_ACCESS);

// Give full access to every room with an ID beginning with "Vu78Rt:product:"
session.allow("Vu78Rt:product:*", session.FULL_ACCESS);

// Give read-only access to every room in the `Vu78Rt` organization
session.allow("Vu78Rt:*", session.READ_ACCESS);

const { body, status } = await session.authorize();
```

#### Limitations [#limitations]

There’s a limitation with access tokens related to granting access to individual
rooms that are part of groups. Let’s say a user has been given access to every
`product` room in their organization.

```tsx
// Access to every `product` room
session.allow("Vu78Rt:product:*", session.FULL_ACCESS);
```

This user is able to enter `product` rooms, but has no access to any `design`
rooms.

<Figure>
  <Image
    src="/assets/authentication/access-token-product-access.png"
    alt="An access token using a wildcard to access product rooms"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

Let’s say the user is invited to a `design` room via share menu—how would we
grant them access?

<Figure>
  <Image
    src="/assets/authentication/access-token-room-invite.png"
    alt="Inviting Olivier to the `Vu78Rt:design:9Hdu73` room"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

We can’t give them access to _every_ `design` room with a wildcard, as they
should only have permission for _one_.

```tsx
// ❌ Access to every `design` room
session.allow("Vu78Rt:design:*", session.FULL_ACCESS);
```

Instead, we would have to manually find the exact room ID without a wildcard,
and apply it ourselves—the naming pattern doesn’t work for this room.

```tsx
// Access to just this `design` room, but not scalable
session.allow("Vu78Rt:design:9Hdu73", session.FULL_ACCESS);
```

To use access tokens you’d have to manually keep track of every room ID where
the naming pattern doesn’t apply. This isn’t ideal, and it also doesn’t scale,
as the token will need to be refreshed whenever access is granted to new rooms
for this to work correctly.

##### Building more complex permissions

For this reason,
**[we recommend using ID tokens for complex permissions](/docs/authentication/id-token)**.
ID token authentication allows you to attach permissions to each room when it’s
created or modified, which means you don’t need to check permissions yourself,
and no naming pattern is required.

#### Migrating your current rooms IDs

If your application already has rooms, it’s possible to rename their IDs to be
compatible with a naming pattern. Learn more in our
[room ID migration guide](/docs/guides/how-to-rename-room-ids-and-successfully-migrate-users).

## Select your framework [#select-your-framework]

Select your framework for specific instructions on setting up access token
authentication.

<ListGrid columns={3}>
  <DocsCard
    title="Next.js"
    href="/docs/authentication/access-token/nextjs"
    visual={<DocsNextjsIcon />}
  />
  <DocsCard
    title="Remix"
    href="/docs/authentication/access-token/remix"
    visual={<DocsRemixIcon />}
  />
  <DocsCard
    title="SvelteKit"
    href="/docs/authentication/access-token/sveltekit"
    visual={<DocsSvelteIcon />}
  />
  <DocsCard
    title="Nuxt.js"
    href="/docs/authentication/access-token/nuxtjs"
    visual={<DocsNuxtjsIcon />}
  />
  <DocsCard
    title="Express"
    href="/docs/authentication/access-token/express"
    visual={<DocsExpressIcon />}
  />
  <DocsCard
    title="Firebase"
    href="/docs/authentication/access-token/firebase"
    visual={<DocsFirebaseIcon />}
  />
</ListGrid>

---
meta:
  title: "Set up access token permissions with Express"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with Express."
---

Follow the following steps to start configure your authentication endpoint where

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>

      Users need permission to interact with rooms, and you can
      permit access in an `api/liveblocks-auth` endpoint by
      creating the `liveblocks-auth.ts` file with the
      following code. In here you can implement your security and define
      the rooms that your user can enter.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.


      ```ts file="liveblocks-auth.ts"
      const express = require("express");
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const app = express();
      app.use(express.json());

      app.post("/api/liveblocks-auth", (req, res) => {
        // Get the current user from your database
        const user = __getUserFromDB__(req);

        // Start an auth session inside your endpoint
        const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.metadata },  // Optional
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return res.status(status).end(body);
      });
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your JavaScript application as
such:

```ts
const self = room.getSelf(); // or useSelf() in React
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up access token permissions with Firebase"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with Firebase."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>
      Let’s first install the `@liveblocks/node` package in your
      Firebase functions project.

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>

      Users need permission to interact with rooms, and you can
      permit access by creating a new Firebase [callable function](https://firebase.google.com/docs/functions/callable)
      as shown below. In here you can implement your security and define
      the rooms that your user can enter.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.


      ```js
      const functions = require("firebase-functions");
      const { Liveblocks } = require("@liveblocks/node");

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      exports.auth = functions.https.onCall(async (data, context) => {
        // Get the current user from your database
        const user = __getUserFromDB__(data);

        // Start an auth session inside your endpoint
        const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.metadata },  // Optional
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return JSON.parse(body);
      });
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).


    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```js
      import { createClient } from "@liveblocks/client";
      import firebase from "firebase";
      import "firebase/functions";

      firebase.initializeApp({
        /* Firebase config */
      });

      const auth = firebase.functions().httpsCallable("liveblocks-auth");

      // Create a Liveblocks client
      const client = createClient({
        authEndpoint: async (room) => (await auth({ room })).data,
      });
      ```

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your JavaScript application as
such:

```ts
const self = room.getSelf(); // or useSelf() in React
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up access token permissions with Next.js"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with Next.js."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic in Next.js’ `/app` directory.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users need permission to interact with rooms, and you can
      permit access in an `api/liveblocks-auth` endpoint by
      creating the following `app/api/liveblocks-auth/route.ts`
      file. In here you can implement your security and define
      the rooms that your user can enter.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.

      ```ts file="app/api/liveblocks-auth/route.ts"
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export async function POST(request: Request) {
        // 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
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return new Response(body, { status });
      }
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      prop on [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
      with `authEndpoint` pointing to the endpoint you just created.

      ```tsx
      <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#LiveblocksProviderCallback)
      instead.

      ```tsx title="Pass custom headers" isCollapsed isCollapsable
      <LiveblocksProvider
        authEndpoint={async (room) => {
          // Passing custom headers and body to your endpoint
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        }}
      />
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Attach metadata to users</StepTitle>
      <StepContent>
        Optionally, you can attach static metadata to each user, which will
        be accessible in your app. First you need to define the types in
        your config file, under `UserMeta["info"]`.

        ```ts file="liveblocks.config.ts" highlight="7-11"
        declare global
          interface Liveblocks {
            UserMeta: {
              id: string;

              // Example, use any JSON-compatible data in your metadata
              info: {
                name: string;
                avatar: string;
                colors: string[];
              }
            }

            // Other type definitions
            // ...
          }
        }
        ```

        When authenticating, you can then pass the user’s metadata to
        `prepareSession` in the endpoint we’ve just created.

        ```ts file="app/api/liveblocks-auth/route.ts" highlight="8-12"
        // 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: {
              name: user.name,
              avatar: user.avatarUrl,
              colors: user.colorArray,
            }
          }
        );
        ```

        User metadata has now been set! You can access this information in your app through
        [`useSelf`](/docs/api-reference/liveblocks-react#useSelf).

        ```tsx highlight="4"
        export { useSelf } from "@liveblocks/react/suspense";

        function Component() {
          const { name, avatar, colors } = useSelf((me) => me.info);
        }
        ```

        Bear in mind that if you’re using the [default Comments components](/docs/api-reference/liveblocks-react-ui#Components),
        you must specify a `name` and `avatar` in `userInfo`.
      </StepContent>

    </Step>

</Steps>

## More information

Both `userId` and `userInfo` can then be used in your React application as such:

```ts
const self = useSelf();
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up access token permissions with Nuxt.js"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with Nuxt.js."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users need permission to interact with rooms, and you can
      permit access in an `api/liveblocks-auth` endpoint by
      creating the `server/api/liveblocks-auth.ts` file with the
      following code. This is where you will implement your security and
      define the rooms that the user has access to.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.

      ```ts file="server/api/liveblocks-auth.ts"
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export default defineEventHandler(async (event) => {
      // Get the current user from your database
        const user = __getUserFromDB__(event);

        // Start an auth session inside your endpoint
        const session = liveblocks.prepareSession(
          user.id,
          { userInfo: user.metadata },  // Optional
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return body;
      })
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your Vue.js application as
such:

```ts
const self = ref(room.getSelf());
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up access token permissions with Remix"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with Remix."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users need permission to interact with rooms, and you can
      permit access in an `api/liveblocks-auth` endpoint by
      creating the `app/routes/api/liveblocks-auth.ts` file with the
      following code. In here you can implement your security and define
      the rooms that your user can enter.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.


      ```ts file="app/routes/api/liveblocks-auth.ts"
      import type { ActionFunction } from "@remix-run/node";
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export const action: ActionFunction = async ({ request }) => {
        // 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
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return new Response(body, { status });
      }
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      prop on [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
      with `authEndpoint` pointing to the endpoint you just created.

      ```tsx
      <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#LiveblocksProviderCallback)
      instead.

      ```tsx title="Pass custom headers" isCollapsed isCollapsable
      <LiveblocksProvider
        authEndpoint={async (room) => {
          // Passing custom headers and body to your endpoint
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        }}
      />
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Attach metadata to users</StepTitle>
      <StepContent>
        Optionally, you can attach static metadata to each user, which will
        be accessible in your app. First you need to define the types in
        your config file, under `UserMeta["info"]`.

        ```ts file="liveblocks.config.ts" highlight="7-11"
        declare global
          interface Liveblocks {
            UserMeta: {
              id: string;

              // Example, use any JSON-compatible data in your metadata
              info: {
                name: string;
                avatar: string;
                colors: string[];
              }
            }

            // Other type definitions
            // ...
          }
        }
        ```

        When authenticating, you can then pass the user’s metadata to
        `prepareSession` in the endpoint we’ve just created.

        ```ts file="app/routes/api/liveblocks-auth.ts" highlight="8-12"
        // 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: {
              name: user.name,
              avatar: user.avatarUrl,
              colors: user.colorArray,
            }
          }
        );
        ```

        User metadata has now been set! You can access this information in your app through
        [`useSelf`](/docs/api-reference/liveblocks-react#useSelf).

        ```tsx highlight="4"
        export { useSelf } from "../liveblocks.config.ts";

        function Component() {
          const { name, avatar, colors } = useSelf((me) => me.info);
        }
        ```

        Bear in mind that if you’re using the [default Comments components](/docs/api-reference/liveblocks-react-ui#Components),
        you must specify a `name` and `avatar` in `userInfo`.
      </StepContent>

    </Step>

</Steps>

## More information

Both `userId` and `userInfo` can then be used in your React application as such:

```ts
const self = useSelf();
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up access token permissions with SvelteKit"
  parentTitle: "Authentication"
  description: "Learn how to setup access token permissions with SvelteKit."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users need permission to interact with rooms, and you can
      permit access in an `api/liveblocks-auth` endpoint by
      creating the `src/routes/api/liveblocks-auth/+server.ts` file with the
      following code. In here you can implement your security and define
      the rooms that your user can enter.

      With access tokens, you should always use a [naming pattern](/docs/authentication/access-token#permissions)
      for your room IDs, as this enables you to easily allow
      access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard `*`
      to give the user access to every room in their organization, and every room in their group.


      ```ts file="src/routes/api/liveblocks-auth/+server.ts"
      import { type RequestEvent } from "@sveltejs/kit";
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export async function POST({ request }: RequestEvent) {
        // 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
        );

        // Use a naming pattern to allow access to rooms with wildcards
        // Giving the user read access on their org, and write access on their group
        session.allow(`${user.organization}:*`, session.READ_ACCESS);
        session.allow(`${user.organization}:${user.group}:*`, session.FULL_ACCESS);

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        return new Response(body, { status });
      }
      ```

      Read
      [access token permission](/docs/authentication/access-token#permissions)
      to learn more about naming rooms and granting permissions with wildcards.
      Note that if a naming pattern doesn’t work for every room in your application, you can
      [grant access to individual rooms too](/docs/guides/how-to-grant-access-to-individual-rooms-with-access-tokens).

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your Svelte application as
such:

```ts
const self = room.getSelf();
console.log(self.id);
console.log(self.info.color);
```

<Figure>
  <Image
    src="/assets/access-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Authenticate with ID tokens"
  parentTitle: "Authentication"
  description: "Learn more about ID token permissions"
---

ID token authentication allows Liveblocks to handle permissions for you. This
means that when you create or modify a room, you can set a user’s permissions on
the room itself. This means the room acts as a source of truth. Later, when a
user tries to enter a room, Liveblocks will automatically check if the user has
permission, and deny them access if the permissions aren’t set.

Permissions aren’t just for individual users, but can also be set for groups of
users, or for the whole room at once.

<Figure>
  <Image
    src="/assets/authentication/id-token-enter-room.png"
    alt="An ID token granting entry to a room"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

<Banner title="Don’t need complex permissions?">

If you don’t need fine-grained permissions, or if you’d prefer storing
individual room permissions in your own system, we recommend using simpler
[access tokens](/docs/authentication/access-token) instead.

</Banner>

## Authenticating

Authenticating with ID tokens means creating a
[JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWT) that’s used
to verify the identity of the current user when connecting to a Liveblocks room.
This token is created using
[`liveblocks.identifyUser`](/docs/api-reference/liveblocks-node#id-tokens).

```ts
const { body, status } = await liveblocks.identifyUser({
  userId: "olivier@example.com",
});

// '{ token: "eyJga7..." }'
console.log(body);
```

**Before using ID tokens, it’s recommended to read this entire page**, as it
explains how to set up permissions in your Liveblocks app. However, if you’d
like to quickly set up Liveblocks, you can select your framework and read more
later.

<ListGrid columns={3}>
  <DocsCard
    title="Next.js"
    href="/docs/authentication/id-token/nextjs"
    visual={<DocsNextjsIcon />}
  />
  <DocsCard
    title="Remix"
    href="/docs/authentication/id-token/remix"
    visual={<DocsRemixIcon />}
  />
  <DocsCard
    title="SvelteKit"
    href="/docs/authentication/id-token/sveltekit"
    visual={<DocsSvelteIcon />}
  />
  <DocsCard
    title="Nuxt.js"
    href="/docs/authentication/id-token/nuxtjs"
    visual={<DocsNuxtjsIcon />}
  />
  <DocsCard
    title="Express"
    href="/docs/authentication/id-token/express"
    visual={<DocsExpressIcon />}
  />
  <DocsCard
    title="Firebase"
    href="/docs/authentication/id-token/firebase"
    visual={<DocsFirebaseIcon />}
  />
</ListGrid>

## Permissions [#permissions]

ID token authentication allows you to set different permission types on rooms,
assigned at three different levels: default, groups, and users. The system is
flexible enough to enable you to build a permission system that’s helpful for
building invite dialogs, workspaces, and more.

<Figure>
  <img
    src="/assets/managing-rooms/rooms-share-dialog.png"
    alt="Share dialog illustration"
  />
</Figure>

To set room permissions, you can
[create](/docs/api-reference/liveblocks-node#post-rooms) or
[update](/docs/api-reference/liveblocks-node#post-rooms-roomId) a room, passing
permission information in the options.

```ts
const room = await liveblocks.createRoom("a32wQXid4A9", {
  // This is a private room
  defaultAccesses: [],

  // But Olivier can enter
  usersAccesses: {
    "olivier@example.com": ["room:read"],
  },
});
```

### Permission types [#permission-types]

There are three permission values that you can set on rooms.

<dl>
  <dt>`["room:write"]`</dt>
  <dd>
    Full access. Enables people to view and edit the room. `isReadOnly` is
    `false`.
  </dd>
  <dt>`["room:read", "room:presence:write"]`</dt>
  <dd>
    Read access with presence. Enables people to edit their presence, but only
    view the room&rsquo;s storage. `isReadOnly` is `true`.
  </dd>
  <dt>`[]`</dt>
  <dd>Private. No one can enter the room.</dd>
</dl>

### Permission levels [#permission-types]

Permission types can be applied at three different levels, enabling complex
entry systems.

<dl>
  <dt>defaultAccesses</dt>
  <dd>The default permission types to apply to the entire room.</dd>
  <dt>groupsAccesses</dt>
  <dd>Permission types to apply to specific groups of users.</dd>
  <dt>usersAccesses</dt>
  <dd>Permission types to apply to specific users.</dd>
</dl>

Each level further down will override access levels defined above, for example a
room with private access will allow a user with `room:write` access to enter.

### Default room permissions

The `defaultAccesses` level is used to set the default permissions of the entire
room.

<Figure>
  <Image
    src="/assets/managing-rooms/rooms-access-denied.png"
    alt="Access denied illustration"
    width={820}
    height={412}
  />
</Figure>

When used in our APIs, this property takes an array, with an empty array `[]`
signifying no access. Add permission types to this array to define the default
access level to your room.

```ts
// Private - no one has access by default
"defaultAccesses": []

// Public - everyone can edit and view the room
"defaultAccesses": ["room:write"]

// Read-only - everyone can view the room, but only presence can be edited
"defaultAccesses": ["room:read", "room:presence:write"]
```

#### Setting room access

We can use the
[`liveblocks.createRoom`](/docs/api-reference/rest-api-endpoints#post-rooms) to
create a new room with public access levels:

```ts highlight="2"
const room = await liveblocks.createRoom("a32wQXid4A9", {
  defaultAccesses: ["room:write"],
});
```

The default permission types can later be modified with
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#post-rooms-roomId),
in this example turning the room private:

```ts highlight="2"
const room = await liveblocks.updateRoom("a32wQXid4A9", {
  defaultAccesses: [],
});
```

### Groups permissions

The `groupsAccesses` level is used to set the default permissions of any given
group within room.

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/managing-rooms/rooms-groups.mp4" type="video/mp4" />
  </video>
</Figure>

Groups are represented by a `groupId`—a custom string that represents a
selection of users in your app. Groups can be attached to a user by passing an
array of `groupId` values in `groupIds`, during authentication.

```js highlight="10"
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST(request: Request) {
  const { status, body } = await liveblocks.identifyUser({
    userId: "marie@example.com",
    groupIds: ["engineering"]
  });

  return new Response(body, { status });
}
```

In our APIs you can then set group accesses by using the `groupId` as the key,
and an array of permissions as the value.

```ts
// "engineering" group has access to view and edit
"groupsAccesses": {
  "engineering": ["room:write"],
}
```

#### Modifying group access [#permissions-levels-groups-accesses-example]

To allow an “engineering” group access to view a room, and modify their
presence, we can use
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#post-rooms-roomId)
with `engineering` as a `groupId`:

```ts highlight="3"
const room = await liveblocks.updateRoom("a32wQXid4A9", {
  groupsAccesses: {
    engineering: ["room:read", "room:presence:write"],
  },
});
```

After calling this, every user in the “engineering” group will have read-only
access. To remove a group’s permissions, we can use
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#post-rooms-roomId)
again, and set the permission type to `null`:

```ts highlight="7"
const room = await liveblocks.updateRoom("a32wQXid4A9", {
  groupsAccesses: {
    engineering: null,
  },
});
```

### User permissions

The `usersAccesses` level is used to set permissions of any give user within a
room.

<Figure>
  <Image
    src="/assets/managing-rooms/rooms-share-dialog.png"
    alt="Share dialog illustration"
    width={820}
    height={412}
  />
</Figure>

To use this, first a user is given a `userId` during authentication.

```js highlight="9"
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export async function POST(request: Request) {
  const { status, body } = await liveblocks.identifyUser({
    userId: "ellen@acme.inc"
  });

  return new Response(body, { status });
}
```

Then, if you want the user with the `userId` id to make edits, set `userId` to
`["room:write"]` within `usersAccesses` when creating or updating a room.

```ts
// user with userId "ellen@acme.inc" has access to view and edit
"usersAccesses": {
  "ellen@acme.inc": ["room:write"]
}
```

#### Checking user access [#permissions-levels-users-accesses-example]

To give them room permission, we can use
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#post-rooms-roomId),
setting write access on their `userId`:

```ts highlight="3"
const room = await liveblocks.updateRoom("a32wQXid4A9", {
  usersAccesses: {
    "ellen@acme.inc": ["room:write"],
  },
});
```

To check a user’s assigned permission types for this room, we can then use
[`liveblocks.updateRoom`](/docs/api-reference/liveblocks-node#get-rooms-roomId)
and check `usersAccesses`:

```ts
const room = await liveblocks.getRoom("a32wQXid4A9");

// { "ellen@acme.inc": ["room:write"] }
console.log(room.data.usersAccesses);
```

## Select your framework [#select-your-framework]

Select your framework for specific instructions on setting up ID token
authentication.

<ListGrid columns={3}>
  <DocsCard
    title="Next.js"
    href="/docs/authentication/id-token/nextjs"
    visual={<DocsNextjsIcon />}
  />
  <DocsCard
    title="Remix"
    href="/docs/authentication/id-token/remix"
    visual={<DocsRemixIcon />}
  />
  <DocsCard
    title="SvelteKit"
    href="/docs/authentication/id-token/sveltekit"
    visual={<DocsSvelteIcon />}
  />
  <DocsCard
    title="Nuxt.js"
    href="/docs/authentication/id-token/nuxtjs"
    visual={<DocsNuxtjsIcon />}
  />
  <DocsCard
    title="Express"
    href="/docs/authentication/id-token/express"
    visual={<DocsExpressIcon />}
  />
  <DocsCard
    title="Firebase"
    href="/docs/authentication/id-token/firebase"
    visual={<DocsFirebaseIcon />}
  />
</ListGrid>

---
meta:
  title: "Set up ID token permissions with Express"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with Express."
---

Follow the following steps to start configure your authentication endpoint where

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>

      Users can only interact with rooms they have access to. You can
      configure permission access in an `api/liveblocks-auth` endpoint by
      creating the `liveblocks-auth.ts` file with the
      following code. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```ts file="liveblocks-auth.ts"
      const express = require("express");
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const app = express();
      app.use(express.json());

      app.post("/api/liveblocks-auth", (req, res) => {
        // Get the current user from your database
        const user = __getUserFromDB__(req);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        return res.status(status).end(body);
      });
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

        const liveblocks = new Liveblocks({
          secret: "{{SECRET_KEY}}",
        });

        const room = await liveblocks.createRoom("my-room-id", {
          defaultAccesses: ["room:read", "room:presence:write"],
          groupsAccesses: {
            "my-group-id": ["room:write"],
          },
          usersAccesses: {
            "my-user-id": ["room:write"],
          },
        });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your JavaScript application as
such:

```ts
const self = room.getSelf(); // or useSelf() in React
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up ID token permissions with Firebase"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with Firebase."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>
      Let’s first install the `@liveblocks/node` package in your
      Firebase functions project.

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>

      Create a new Firebase [callable function](https://firebase.google.com/docs/functions/callable)
      as shown below. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```js
      const functions = require("firebase-functions");
      const { Liveblocks } = require("@liveblocks/node");

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      exports.auth = functions.https.onCall(async (data, context) => {
        // Get the current user from your database
        const user = __getUserFromDB__(data);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        return JSON.parse(body);
      });
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```js
      import { createClient } from "@liveblocks/client";
      import firebase from "firebase";
      import "firebase/functions";

      firebase.initializeApp({
        /* Firebase config */
      });

      const auth = firebase.functions().httpsCallable("liveblocks-auth");

      // Create a Liveblocks client
      const client = createClient({
        authEndpoint: async (room) => (await auth({ room })).data,
      });
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const room = await liveblocks.createRoom("my-room-id", {
        defaultAccesses: ["room:read", "room:presence:write"],
        groupsAccesses: {
          "my-group-id": ["room:write"],
        },
        usersAccesses: {
          "my-user-id": ["room:write"],
        },
      });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your JavaScript application as
such:

```ts
const self = room.getSelf(); // or useSelf() in React
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up ID token permissions with Next.js"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with Next.js."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic in Next.js’ `/app` directory.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users can only interact with rooms they have access to. You can
      configure permission access in an `api/liveblocks-auth` endpoint by
      creating the `app/api/liveblocks-auth/route.ts` file with the
      following code. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```ts file="app/api/liveblocks-auth/route.ts"
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export async function POST(request: Request) {
        // Get the current user from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        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 from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        // Authorize the user and return the result
        const { status, body } = await session.authorize();
        response.status(status).send(body);
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      prop on [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
      with `authEndpoint` pointing to the endpoint you just created.

      ```tsx
      <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#LiveblocksProviderCallback)
      instead.

      ```tsx title="Pass custom headers" isCollapsed isCollapsable
      <LiveblocksProvider
        authEndpoint={async (room) => {
          // Passing custom headers and body to your endpoint
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        }}
      />
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const room = await liveblocks.createRoom("my-room-id", {
        defaultAccesses: ["room:read", "room:presence:write"],
        groupsAccesses: {
          "my-group-id": ["room:write"],
        },
        usersAccesses: {
          "my-user-id": ["room:write"],
        },
      });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Attach metadata to users</StepTitle>
      <StepContent>
        Optionally, you can attach static metadata to each user, which will
        be accessible in your app. First you need to define the types in
        your config file, under `UserMeta["info"]`.

        ```ts file="liveblocks.config.ts" highlight="7-11"
        declare global
          interface Liveblocks {
            UserMeta: {
              id: string;

              // Example, use any JSON-compatible data in your metadata
              info: {
                name: string;
                avatar: string;
                colors: string[];
              }
            }

            // Other type definitions
            // ...
          }
        }
        ```

        When authenticating, you can then pass the user’s metadata to
        `prepareSession` in the endpoint we’ve just created.

        ```ts file="app/api/liveblocks-auth/route.ts" highlight="11-15"
        // Get the current user from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          {
            userInfo: {
              name: user.name,
              avatar: user.avatarUrl,
              colors: user.colorArray,
            }
          },
        );
        ```

        User metadata has now been set! You can access this information in your app through
        [`useSelf`](/docs/api-reference/liveblocks-react#useSelf).

        ```tsx highlight="4"
        export { useSelf } from "@liveblocks/react/suspense";

        function Component() {
          const { name, avatar, colors } = useSelf((me) => me.info);
        }
        ```

        Bear in mind that if you’re using the [default Comments components](/docs/api-reference/liveblocks-react-ui#Components),
        you must specify a `name` and `avatar` in `userInfo`.
      </StepContent>

    </Step>

</Steps>

## More information

Both `userId` and `userInfo` can then be used in your React application as such:

```ts
const self = useSelf();
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up ID token permissions with Nuxt.js"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with Nuxt.js."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users can only interact with rooms they have access to. You can
      configure permission access in an `api/liveblocks-auth` endpoint by
      creating the `server/api/liveblocks-auth.ts` file with the
      following code. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```ts file="server/api/liveblocks-auth.ts"
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export default defineEventHandler(async (event) => {
        // Get the current user from your database
        const user = __getUserFromDB__(event);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );
        return body;
      })
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const room = await liveblocks.createRoom("my-room-id", {
        defaultAccesses: ["room:read", "room:presence:write"],
        groupsAccesses: {
          "my-group-id": ["room:write"],
        },
        usersAccesses: {
          "my-user-id": ["room:write"],
        },
      });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your Vue.js application as
such:

```ts
const self = ref(room.getSelf());
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up ID token permissions with Remix"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with Remix."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users can only interact with rooms they have access to. You can
      configure permission access in an `api/liveblocks-auth` endpoint by
      creating the `app/routes/api/liveblocks-auth.ts` file with the
      following code. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```ts file="app/routes/api/liveblocks-auth.ts"
      import type { ActionFunction } from "@remix-run/node";
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export const action: ActionFunction = async ({ request }) => {
        // Get the current user from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        return new Response(body, { status });
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      prop on [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
      with `authEndpoint` pointing to the endpoint you just created.

      ```tsx
      <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#LiveblocksProviderCallback)
      instead.

      ```tsx title="Pass custom headers" isCollapsed isCollapsable
      <LiveblocksProvider
        authEndpoint={async (room) => {
          // Passing custom headers and body to your endpoint
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        }}
      />
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const room = await liveblocks.createRoom("my-room-id", {
        defaultAccesses: ["room:read", "room:presence:write"],
        groupsAccesses: {
          "my-group-id": ["room:write"],
        },
        usersAccesses: {
          "my-user-id": ["room:write"],
        },
      });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Attach metadata to users</StepTitle>
      <StepContent>
        Optionally, you can attach static metadata to each user, which will
        be accessible in your app. First you need to define the types in
        your config file, under `UserMeta["info"]`.

        ```ts file="liveblocks.config.ts" highlight="7-11"
        declare global
          interface Liveblocks {
            UserMeta: {
              id: string;

              // Example, use any JSON-compatible data in your metadata
              info: {
                name: string;
                avatar: string;
                colors: string[];
              }
            }

            // Other type definitions
            // ...
          }
        }
        ```

        When authenticating, you can then pass the user’s metadata to
        `prepareSession` in the endpoint we’ve just created.

        ```ts file="app/routes/api/liveblocks-auth.ts" highlight="11-15"
        // Get the current user from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          {
            userInfo: {
              name: user.name,
              avatar: user.avatarUrl,
              colors: user.colorArray,
            }
          },
        );
        ```

        User metadata has now been set! You can access this information in your app through
        [`useSelf`](/docs/api-reference/liveblocks-react#useSelf).

        ```tsx highlight="4"
        export { useSelf } from "@liveblocks/react/suspense";

        function Component() {
          const { name, avatar, colors } = useSelf((me) => me.info);
        }
        ```

        Bear in mind that if you’re using the [default Comments components](/docs/api-reference/liveblocks-react-ui#Components),
        you must specify a `name` and `avatar` in `userInfo`.
      </StepContent>

    </Step>

</Steps>

## More information

Both `userId` and `userInfo` can then be used in your React application as such:

```ts
const self = useSelf();
console.log(self.id);
console.log(self.info);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "Set up ID token permissions with SvelteKit"
  parentTitle: "Authentication"
  description: "Learn how to setup ID token permissions with SvelteKit."
---

Follow the following steps to start configure your authentication endpoint and
start building your own security logic.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install the `liveblocks/node` package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up authentication endpoint</StepTitle>
    <StepContent>
      Users can only interact with rooms they have access to. You can
      configure permission access in an `api/liveblocks-auth` endpoint by
      creating the `src/routes/api/liveblocks-auth/+server.ts` file with the
      following code. This is where you will implement your security and
      define if the current user has access to a specific room.

      ```ts file="src/routes/api/liveblocks-auth/+server.ts"
      import { type RequestEvent } from "@sveltejs/kit";
      import { Liveblocks } from "@liveblocks/node";

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      export async function POST({ request }: RequestEvent) {
        // Get the current user from your database
        const user = __getUserFromDB__(request);

        // Identify the user and return the result
        const { status, body } = await liveblocks.identifyUser(
          {
            userId: user.id,
            groupIds, // Optional
          },
          { userInfo: user.metadata },
        );

        return new Response(body, { status });
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the client</StepTitle>
    <StepContent>
      On the front end, you can now replace the `publicApiKey`
      option with `authEndpoint` pointing to the endpoint you
      just created.

      ```ts file="liveblocks.config.ts"
      import { createClient } from "@liveblocks/client";

      const client = createClient({
        authEndpoint: "/api/liveblocks-auth",
      });
      ```

      If you need to pass custom headers or data to your endpoint, you can
      use
      [authEndpoint as a callback](/docs/api-reference/liveblocks-client#createClientCallback)
      instead.

      ```ts file="liveblocks.config.ts" isCollapsed isCollapsable
      import { createClient } from "@liveblocks/client";

      // Passing custom headers and body to your endpoint
      const client = createClient({
        authEndpoint: async (room) => {
          const headers = {
            // Custom headers
            // ...

            "Content-Type": "application/json",
          };

          const body = JSON.stringify({
            // Custom body
            // ...

            room,
          });

          const response = await fetch("/api/liveblocks-auth", {
            method: "POST",
            headers,
            body,
          });

          return await response.json();
        },
      });
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Set permission accesses to a room</StepTitle>
    <StepContent>
      A room can have `defaultAccesses`, `usersAccesses`, and `groupsAccesses` defined.
      Permissions are then checked when users try to connect to a room. For security purposes,
      [room permissions](/docs/authentication/id-token#permissions) can only be set on the back-end through `@liveblocks/node` or our REST API.
      For instance, you can use [`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms)
      to create a new room with read-only public access levels while giving write access to specific groups and users.

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

      const liveblocks = new Liveblocks({
        secret: "{{SECRET_KEY}}",
      });

      const room = await liveblocks.createRoom("my-room-id", {
        defaultAccesses: ["room:read", "room:presence:write"],
        groupsAccesses: {
          "my-group-id": ["room:write"],
        },
        usersAccesses: {
          "my-user-id": ["room:write"],
        },
      });
      ```

      For more information, make sure to read the section on [room permissions](/docs/authentication/id-token#permissions).

    </StepContent>

  </Step>
</Steps>

## More information

Both `userId` and `userInfo` can then be used in your Svelte application as
such:

```ts
const self = room.getSelf();
console.log(self.id);
console.log(self.info.color);
```

<Figure>
  <Image
    src="/assets/id-token-auth-diagram.png"
    alt="Auth diagram"
    width={768}
    height={576}
  />
</Figure>

---
meta:
  title: "How Liveblocks works"
  parentTitle: "Concepts"
  description:
    "Liveblocks is a realtime collaboration infrastructure for building
    performant collaborative experiences."
---

Liveblocks provides customizable pre-built features for human and AI
collaboration, used to make your product multiplayer, engaging, and AI‑ready

## Ready-made features

Liveblocks provides ready‑to‑use features through customizable pre‑built
components that can easily be dropped into your product to boost growth:
[Comments](/docs/ready-made-features/comments),
[Text Editor](/docs/ready-made-features/text-editor),
[AI Copilots](/docs/ready-made-features/ai-copilots),
[Presence](/docs/ready-made-features/presence), and
[Notifications](/docs/ready-made-features/notifications). You can decide
features you want to use based on your requirements and collaborative
experiences you’re looking to add.

If you have more advanced needs, you can also leverage Liveblocks to
[host and scale local-first sync engines](/docs/platform/sync-datastore) such as
Liveblocks Storage and Yjs.

<Figure highlight>
  <Image
    src="/assets/concepts/ready-made-features.png"
    alt="How Liveblocks works - Ready-made features"
    width={768}
    height={440}
  />
</Figure>

## Rooms

A room is the digital space in which people collaborate. You can require your
users to be [authenticated](/docs/authentication) to interact with rooms, and
each room can have specific [permissions](/docs/authentication) and
[metadata](/docs/rooms/metadata) associated with them.

<Figure highlight>
  <Image
    src="/assets/concepts/rooms.png"
    alt="How Liveblocks works - Rooms"
    width={768}
    height={440}
  />
</Figure>

## Projects

A project in your dashboard represents an application which has [rooms](#rooms).
Most Liveblocks products are room-based, however
[Notifications](/docs/ready-made-features/notifications) is project-based
instead, so that users can receive notifications from other rooms.

<Figure highlight>
  <Image
    src="/assets/concepts/project.png"
    alt="How Liveblocks works - Project"
    width={768}
    height={440}
  />
</Figure>

## Packages and SDKs

Integrations for specific libraries and frameworks to add Liveblocks-powered
collaborative experiences to your product:
[JavaScript](/docs/api-reference/liveblocks-client),
[React](/docs/api-reference/liveblocks-react),
[React UI](/docs/api-reference/liveblocks-react-ui),
[React Lexical](/docs/api-reference/liveblocks-react-lexical),
[Node.js Lexical](/docs/api-reference/liveblocks-node-lexical),
[Redux](/docs/api-reference/liveblocks-redux),
[Zustand](/docs/api-reference/liveblocks-zustand),
[Yjs](/docs/api-reference/liveblocks-yjs), and
[Node.js](/docs/api-reference/liveblocks-node). Integrations are designed to
serve various collaboration use cases such as collaborative text editors,
comments, notifications, and more.

<Figure highlight>
  <Image
    src="/assets/concepts/packages-sdk.png"
    alt="How Liveblocks works - Packages and SDKs"
    width={768}
    height={440}
  />
</Figure>

- [`@liveblocks/client`](https://liveblocks.io/docs/api-reference/liveblocks-client)
- [`@liveblocks/react`](https://liveblocks.io/docs/api-reference/liveblocks-react)
- [`@liveblocks/react-ui`](https://liveblocks.io/docs/api-reference/liveblocks-react-ui)
- [`@liveblocks/react-tiptap`](https://liveblocks.io/docs/api-reference/liveblocks-react-tiptap)
- [`@liveblocks/react-lexical`](https://liveblocks.io/docs/api-reference/liveblocks-react-lexical)
- [`@liveblocks/node-lexical`](https://liveblocks.io/docs/api-reference/liveblocks-node-lexical)
- [`@liveblocks/redux`](https://liveblocks.io/docs/api-reference/liveblocks-redux)
- [`@liveblocks/zustand`](https://liveblocks.io/docs/api-reference/liveblocks-zustand)
- [`@liveblocks/yjs`](https://liveblocks.io/docs/api-reference/liveblocks-yjs)
- [`@liveblocks/node`](https://liveblocks.io/docs/api-reference/liveblocks-node)
- [`@liveblocks/emails`](https://liveblocks.io/docs/api-reference/liveblocks-emails)

## Platform

Liveblocks provides a fully-hosted platform built around a
[WebSocket infrastructure](/docs/platform/websocket-infrastructure) that scales
effortlessly to millions of users. The platform equips you with a set of
powerful tools such as our [sync datastore](/docs/platform/sync-datastore),
[REST API](/docs/api-reference/rest-api-endpoints),
[webhooks](/docs/platform/webhooks),
[schema validation](/docs/platform/schema-validation),
[analytics](/docs/platform/analytics), and more.

---
meta:
  title: "Why Liveblocks"
  parentTitle: "Concepts"
  description:
    "Liveblocks is a realtime collaboration infrastructure for building
    performant collaborative experiences."
---

At Liveblocks, we firmly believe that flexible office policies are here to stay,
and that as a result, all SaaS products will eventually need realtime
collaboration. Every project we undertake at Liveblocks stems from this belief,
and the belief that we can empower people to work better together, and feel more
closely connected with one another.

## Why collaboration

In 2006, following years of development, Google launched their browser-based
realtime collaborative Microsoft Word competitor. This approach transformed the
way people work together enabling them to collaborate efficiently in realtime
but also asynchronously via comments—no more disjointed email threads with files
being passed around. As Google were gaining market shares, Microsoft were forced
to build similar collaboration features directly into Microsoft Word and the
broader Microsoft Office ecosystem in order to compete.

<Figure highlight>
  <Image
    src="/assets/concepts/why-liveblocks-google.png"
    alt="Why Liveblocks - Google"
    width={768}
    height={440}
  />
</Figure>

Around a decade later, Figma flipped the whole software design industry on its
head with their browser-based tool for multiplayer design, and subsequently left
leading companies behind. Few designers believed a quality design tool could be
built into the browser, and no designers wanted to have their peers and managers
looking over their shoulders while designing. Yet, the Figma team proved
everybody wrong and a majority of designers started to use their product. And
because Figma was built with collaboration at its core, engineers, product
managers, executives, marketers, and copywriters quickly followed.

<Figure highlight>
  <Image
    src="/assets/concepts/why-liveblocks-figma.png"
    alt="Why Liveblocks - Figma"
    width={768}
    height={440}
  />
</Figure>

Those companies had the technical expertise, along with millions of dollars, to
pull this off. A handful of forward-looking companies were also able to build
incredible collaborative products and became leaders in their respective
markets: Notion, Pitch, Canva, Miro, Mural, Linear, to mention a few. While more
and more companies are becoming aware of the importance of collaboration, only
the ones that have gone through this process truly understand how painful and
expensive it is to build and maintain.

<Figure highlight>
  <Image
    src="/assets/concepts/why-liveblocks-collaboration-pioneers.png"
    alt="Why Liveblocks - Figma"
    width={768}
    height={440}
  />
</Figure>

## Why choose Liveblocks

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. We focus on the following five core pillars to enable
companies to build awesome collaborative experiences in a matter of days, not
months:

- A complete modular collaboration toolkit
- Deep integrations with your stack
- Pre-built components and examples
- Developer-centric tooling
- Fully-hosted solution

### A complete modular collaboration toolkit

Liveblocks is a complete modular toolkit for embedding collaborative experiences
into your product, enabling you to pick and choose the parts you need depending
on the type of collaborative experience you’re trying to build and its
requirements.

### Deep integrations with your stack

Liveblocks integrates deeply with popular frontend frameworks and libraries,
making it easy to embed real‑time collaborative experiences into any product
quickly.

### Pre-built components and examples

Liveblocks provides you with powerful open‑source examples and components that
can be used modularly, enabling you to move fast while focusing on your core
product.

### Developer-centric tooling

Liveblocks accelerates your productivity with a great developer experience
throughout, including [DevTools](/docs/platform/devtools), and analytics to
understand how your users are using your product’s collaborative features.

### Fully-hosted solution

No more monitoring WebSocket servers, worrying about scale and maintenance of
legacy systems. Liveblocks is fully hosted so you can focus on your core
product.

---
meta:
  title:
    "At least one of the custom notification kinds you provided for
    'ActivitiesData' does not match its requirements"
  parentTitle: "Error"
  description: "Your 'ActivitiesData' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `ActivitiesData` type for your application, but the
type you provided isn’t a (completely) valid definition.

```ts highlight="4-8"
declare global {
  interface Liveblocks {
    ActivitiesData: {
      // Your custom notification kinds go here...
      $error: {
        code: number;
        date: Date; // ❌ Values must simple
      };
      // ❌ Custom notification kinds must start with $
      success: {
        message: string;
      };
    };
  }
}
```

In the example above, there are two problems. Activities data may only contain
simple key/value pairs, where the values must always be assignable to
`string | number | boolean | undefined` and custom notification kinds must start
with `$`.

## How to fix it

You’ll need to figure out what part of your provided `ActivitiesData` type
definition isn’t valid. The example above could be fixed as such:

```ts highlight="6-8"
declare global {
  interface Liveblocks {
    ActivitiesData: {
      // Your custom notification kinds go here...
      $error: {
        code: number;
        date: string;
      };
      $success: {
        message: string;
      };
    };
  }
}
```

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { BaseActivitiesData } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    ActivitiesData: MyActivitiesData;
  }
}

// Quick debugging snippet to find root cause
const xxx: BaseActivitiesData = {} as MyActivitiesData;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid:

```error showLineNumbers={false}
Type 'MyActivitiesData' is not assignable to type 'BaseActivitiesData'.
  Property 'date' is incompatible with index signature.
    Type 'Date' is not assignable to type 'string | number | boolean | undefined'.
```

---
meta:
  title: "The type you provided for 'Presence' is not a valid JSON object"
  parentTitle: "Error"
  description: "Your 'Presence' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `Presence` type for your application, but the type
you provided isn’t a (completely) valid JSON object. Values like `Date`, `Map`,
`Set`, functions, classes, or `unknown` aren’t valid JSON.

```ts highlight="4-7"
declare global {
  interface Liveblocks {
    Presence: {
      // Your own fields go here...
      cursor: { x: number; y: number } | null;
      selection: string[];
      lastActivity: Date; // ❌ The issue is here
    };
  }
}
```

In the example above, the problem is in the `Date` field, because a `Date` isn’t
a valid JSON value.

## How to fix it

You’ll need to figure out what part of your provided `Presence` type definition
isn’t valid JSON. Sometimes this is immediately obvious, like in the example
above.

Sometimes the issue may be a bit less obvious:

```ts highlight="6-7"
import type { Json } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Presence: {
      cursor: unknown; // ❌ Unknowns could contain non-JSON
      cursor: Json; // ✅ Prefer using Json
    };
  }
}
```

By using `Json`, you can still work with unknown or unspecified values, but
still ensure they will be valid JSON.

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { JsonObject } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Presence: MyPresence;
  }
}

// Quick debugging snippet to find root cause
const xxx: JsonObject = {} as MyPresence;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid JSON:

```error showLineNumbers={false}
Type 'MyPresence' is not assignable to type 'JsonObject'.
 Property 'lastActivity' is incompatible with index signature.
   Type 'Date' is not assignable to type 'Json | undefined'.
     Type 'Date' is not assignable to type 'JsonObject'.
       Index signature for type 'string' is missing in type 'Date'.
```

---
meta:
  title: "The type you provided for 'RoomEvent' is not a valid JSON value"
  parentTitle: "Error"
  description: "Your 'RoomEvent' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `RoomEvent` type for your application, but the type
you provided isn’t a (completely) valid JSON value. Values like `Date`, `Map`,
`Set`, functions, classes, or `unknown` aren’t valid JSON.

For example, suppose you have defined three broadcastable events for your
application:

```ts highlight="4-7"
declare global {
  interface Liveblocks {
    RoomEvent:
      | { type: "beep" }
      | { type: "boop"; target: HtmlElement }
      //                        ^^^^^^^^^^^ ❌ The issue is here
      | { type: "buzz"; volume: number };
  }
}
```

In the example above, the problem is in the `HTMLElement` field, because a
`HTMLElement` isn’t a valid JSON value.

## How to fix it

You’ll need to figure out what part of your provided `RoomEvent` type definition
isn’t valid JSON. Sometimes this is immediately obvious, but sometimes the issue
may be a bit less obvious.

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { Json } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    RoomEvent: MyRoomEvent;
  }
}

// Quick debugging snippet to find root cause
const xxx: Json = {} as MyRoomEvent;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid JSON:

```error showLineNumbers={false}
Type 'MyRoomEvent' is not assignable to type 'Json'.
  Type '{ type: "boop"; target: HTMLElement; }' is not assignable to type 'Json'.
    Type '{ type: "boop"; target: HTMLElement; }' is not assignable to type 'JsonObject'.
      Property 'target' is incompatible with index signature.
        Type 'HTMLElement' is not assignable to type 'Json | undefined'.
          Type 'HTMLElement' is not assignable to type 'JsonObject'.
            Index signature for type 'string' is missing in type 'HTMLElement'.
```

---
meta:
  title: "The type you provided for 'RoomInfo' does not match its requirements"
  parentTitle: "Error"
  description: "Your 'RoomInfo' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `RoomInfo` type for your application, but the type
you provided isn’t a (completely) valid definition.

```ts highlight="4-10"
declare global {
  interface Liveblocks {
    RoomInfo: {
      // Your custom fields go here...
      name: string;
      url: URL; // ❌ The issue is here
      geo: {
        city: string;
        country: string;
      };
    };
  }
}
```

In the example above, the problem is the `URL` field. Values like `Date`, `Map`,
`Set`, functions, classes (including `URL`), or `unknown` aren’t valid JSON.

## The rules of the RoomInfo type

The following rules apply if you want to specify a custom `RoomInfo` type:

- You can provide any keys and values here, as long as the values are valid
  JSON.
- Two small constraints:
  - _If_ you specify `name`, it _must_ be assignable to `string | undefined`.
  - _If_ you specify `url`, then it _must_ be assignable to
    `string | undefined`.

The reason for these two restrictions is that some of our higher-level
components will pick these values up and use them to provide default UIs.

## How to fix it

You’ll need to figure out what part of your provided `RoomInfo` type definition
isn’t valid. The example above can be fixed as follows:

```tsx
declare global {
  interface Liveblocks {
    RoomInfo: {
      // Your custom fields go here...
      name: string;
      url: string; // ✅ Valid
      geo: {
        city: string;
        country: string;
      };
    };
  }
}
```

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { BaseRoomInfo } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    RoomInfo: MyRoomInfo;
  }
}

// Quick debugging snippet to find root cause
const xxx: BaseRoomInfo = {} as MyRoomInfo;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid room info:

```error showLineNumbers={false}
Type 'MyRoomInfo' is not assignable to type 'BaseRoomInfo'.
  Types of property 'url' are incompatible.
    Type 'URL' is not assignable to type 'string'.
```

---
meta:
  title: "The type you provided for 'Storage' is not a valid LSON value"
  parentTitle: "Error"
  description: "Your 'Storage' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `Storage` type for your application, but the type you
provided isn’t a (completely) valid LSON object. Values like `Date`, `Map`,
`Set`, functions, classes, or `unknown` aren’t valid LSON.

<Banner type="success" title="What was LSON again?">

LSON is either a valid JSON value, or an instance of `LiveMap`, `LiveList`, or
`LiveObject`.

</Banner>

```ts highlight="6"
declare global {
  interface Liveblocks {
    Storage: {
      layers: LiveMap<string, LiveObject<Layer>>;
      layerIds: LiveList<string>;
      createdAt: Date; // ❌ The issue is here
    };
  }
}
```

In the example above, the problem is in the `Date` field, because a `Date` isn’t
a valid LSON value.

## How to fix it

You’ll need to figure out what part of your provided `Storage` type definition
isn’t valid LSON. Sometimes this is immediately obvious, like in the example
above.

Sometimes the issue may be a bit less obvious:

```ts highlight="7-8"
import type { Lson } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: {
      layers: LiveMap<string, LiveObject<Layer>>;
      layerIds: LiveList<unknown>; // ❌ Unknowns could contain non-LSON
      layerIds: LiveList<Lson>; // ✅ Prefer using Lson
    };
  }
}
```

By using `Lson`, you can still work with unknown or unspecified values, but
still ensure they will be valid LSON.

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { LsonObject } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: MyStorage;
  }
}

// Quick debugging snippet to find root cause
const xxx: LsonObject = {} as MyStorage;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid LSON:

```error showLineNumbers={false}
Type 'MyStorage' is not assignable to type 'LsonObject'.
  Property 'layerIds' is incompatible with index signature.
    Type 'LiveList<unknown>' is not assignable to type 'Lson | undefined'.
      Type 'LiveList<unknown>' is not assignable to type 'LiveList<Lson>'.
        The types returned by 'toArray()' are incompatible between these types.
          Type 'unknown[]' is not assignable to type 'Lson[]'.
            Type 'unknown' is not assignable to type 'Lson'.
```

---
meta:
  title:
    "The type you provided for 'ThreadMetadata' does not match its requirements"
  parentTitle: "Error"
  description: "Your 'ThreadMetadata' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `ThreadMetadata` type for your application, but the
type you provided isn’t a (completely) valid definition.

```ts highlight="4-8"
declare global {
  interface Liveblocks {
    ThreadMetadata: {
      // Your custom fields go here...
      pinned: boolean;
      color: string | null; // ❌ Values may not be null
      position: { x: number; y: number }; // ❌ Values must be simple
      zIndex?: number;
    };
  }
}
```

In the example above, there are two problems. Thread metadata may only contain
simple key/value pairs, where the values must always be assignable to
`string | number | boolean | undefined`.

## How to fix it

You’ll need to figure out what part of your provided `ThreadMetadata` type
definition isn’t valid. The example above could be fixed as such:

```ts highlight="6-8"
declare global {
  interface Liveblocks {
    ThreadMetadata: {
      // Your custom fields go here...
      pinned: boolean;
      color?: string; // ✅
      positionX: number; // ✅
      positionY: number; // ✅
      zIndex?: number;
    };
  }
}
```

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { BaseMetadata } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    ThreadMetadata: MyThreadMetadata;
  }
}

// Quick debugging snippet to find root cause
const xxx: BaseMetadata = {} as MyThreadMetadata;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid metadata:

```error showLineNumbers={false}
Type 'MyThreadMetadata' is not assignable to type 'BaseMetadata'.
  Property 'color' is incompatible with index signature.
    Type 'string | null' is not assignable to type 'string | number | boolean | undefined'.
      Type 'null' is not assignable to type 'string | number | boolean | undefined'.
```

---
meta:
  title: "The type you provided for 'UserMeta' does not match its requirements"
  parentTitle: "Error"
  description: "Your 'UserMeta' type is incorrect and needs to be updated"
---

## Why this error occurred

You have provided a custom `UserMeta` type for your application, but the type
you provided isn’t a (completely) valid definition.

```ts highlight="4-10"
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string;
      info: {
        name: string;
        color: string;
        picture: string;
        lastLogin: Date; // ❌ The issue is here
      };
    };
  }
}
```

In the example above, the problem is in the `Date` field. Values like `Date`,
`Map`, `Set`, functions, classes, or `unknown` aren’t valid JSON.

## The rules of the UserMeta type

The following rules apply if you want to specify a custom `UserMeta` type:

- Top-level fields `id` and `info` are special. They are optional, but only
  these two fields can exist. Extra fields you specify will not have any effect
  and will be ignored.
- _If_ you specify `id`, it _must_ still be assignable to `string | undefined`.
- _If_ you specify `info`, then it _must_ be a valid JSON object value.
  Furthermore:
  - _If_ you specify a `name` field inside `info`, it _must_ still be assignable
    to `string | undefined`.
  - _If_ you specify a `avatar` field inside `info`, it _must_ still be
    assignable to `string | undefined`.

The reason for the last two restrictions is that some of our higher-level
components will pick these values up and use them to provide default UIs.

```tsx
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string; // ✅ Valid
      id?: string; // ✅ Valid
      id?: number; // ❌ Invalid, not assignable to string | undefined

      info: {
        name: string; // ✅ Valid
        name?: string; // ✅ Valid
        name: number; // ❌ Invalid, not assignable to string | undefined

        avatar: string; // ✅ Valid
        avatar?: string; // ✅ Valid
        avatar: number; // ❌ Invalid, not assignable to string | undefined

        // Other field names are not special and are free-form
        custom: string; // ✅ Valid
        custom?: string; // ✅ Valid
        custom: number; // ✅ Valid
        custom: Json; // ✅ Valid, can take _any_ valid Json value

        // However, they still need to be valid JSON
        custom: unknown; // ❌ Invalid, not value JSON
      };
    };
  }
}
```

Also please note:

```tsx
declare global {
  interface Liveblocks {
    UserMeta: {
      id: string;
      info: { name: string };

      // Only `id` or `info` make sense inside `UserMeta`
      iWillBeIgnored: string;
    };
  }
}
```

## How to fix it

You’ll need to figure out what part of your provided `UserMeta` type definition
isn’t valid. Sometimes this is immediately obvious, but sometimes the issue may
be a bit less obvious.

## If you cannot find the root cause

Sometimes types can be complex and the root cause is still unclear. In those
cases, there is a small trick you can use. Try to assign your type to the
required base type, with this line:

```ts highlight="9-10"
import type { BaseUserMeta } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    UserMeta: MyUserMeta;
  }
}

// Quick debugging snippet to find root cause
const xxx: BaseUserMeta = {} as MyUserMeta;
//    ^?
//    The error will appear here
```

Now TypeScript will explain why it thinks your type isn’t valid JSON:

```error showLineNumbers={false}
Type 'MyUserMeta' is not assignable to type 'BaseUserMeta'.
  Types of property 'info' are incompatible.
    Type '{ name: string; color: string; picture: string; lastLogin: Date; }' is not assignable to type 'IUserInfo'.
      Property 'lastLogin' is incompatible with index signature.
        Type 'Date' is not assignable to type 'Json | undefined'.
          Type 'Date' is not assignable to type 'JsonObject'.
            Index signature for type 'string' is missing in type 'Date'.
```

---
meta:
  title: "Cross-linked Liveblocks versions are found in your project"
  parentTitle: "Error"
  description:
    "Cross-linked Liveblocks versions are found in your project. This will cause
    issues!"
---

## Why this error occurred

You’re using multiple `@liveblocks/*` packages in your application bundle, but
they’re not all on the same version.

For example: you’re using `@liveblocks/zustand` at 1.1.3, but
`@liveblocks/react` is on 1.1.4.

## How to find the culprit?

To find out if your project is affected, you can run

```bash
npm ls | grep @liveblocks
```

Please make sure that all of the versions listed there are on the same version.

## Possible ways to fix it

When you upgrade one Liveblocks package, make sure to also upgrade other
Liveblocks packages to the same version.

---
meta:
  title: "Multiple copies of Liveblocks are being loaded in your project"
  parentTitle: "Error"
  description:
    "Multiple copies of Liveblocks are being loaded in your project. This will
    cause issues!"
---

## Why this error occurred

Multiple copies of some Liveblocks package ended up being bundled in your
application bundle.

This can happen because your production bundle includes two entire copies of two
different versions of Liveblocks. Or it can be the case that it includes the
same version of Liveblocks in the bundle twice because the ESM and the CJS
version got bundled separately.

It’s important that only a single copy of Liveblocks exists in your application
bundle at runtime, otherwise bugs will happen. Plus your bundle will be
unnecessarily large.

## Possible causes

- Your project is using multiple internal packages that all rely on Liveblocks,
  but maybe some are on different versions.
- Your project is using a non-standard bundler setup. If you believe this is an
  issue with the way Liveblocks is packaged, feel free to open a support
  request.

## Possible ways to fix it

To investigate your set up, run the following command to see if all your
Liveblocks dependencies are on the same version:

```bash
npm ls | grep @liveblocks
```

If they’re not all on the same version, please fix that. You could manually
upgrade that, but we recommend declaring Liveblocks as a `"peerDependency"` in
those internal packages’ `package.json` files, and only declare it in the actual
`"dependencies"` in the outermost `package.json` for your project. That way,
your package manager will keep all the versions the same.

If all your Liveblocks dependencies are on the same version already, and you’re
still seeing this error, you’re experiencing the
[dual-package hazard](https://nodejs.org/api/packages.html#dual-package-hazard)
problem, which means that both the ESM and the CJS version of Liveblocks end up
in your production bundle as two separate "instances". Of course, this isn’t
supposed to happen. Please let us know about this by
[opening a GitHub issue](https://github.com/liveblocks/liveblocks/issues/new?template=bug_report.md),
or reaching out in our support channel on
[Discord](https://liveblocks.io/discord).

---
meta:
  title: "In order to use this channel, please set up your project first"
  parentTitle: "Error"
  description:
    "A notification channel hasn’t been set up, you need to enable it in your
    dashboard."
---

## Why this error occurred

You tried to access a notification channel, such as `settings.email`, but it’s
disabled in your Liveblocks dashboard.

## How to fix it

You first need to navigate to your project in the [dashboard](/dashboard).

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-click-notifications.png"
    alt="Notifications dashboard page"
    width={712}
    height={445}
  />
</Figure>

Then, enable a notification kind on the channel you’re trying to access. For
example, if you’re trying to access `settings.email`, navigate to the _Email_
tab and enable a notification kind.

<Banner type="warning">

If you’re working with a production app, make sure you
[read our guide on enabling notification kinds](/docs/guides/what-to-check-before-enabling-a-new-notification-kind)
before publishing your changes, as your app may be affected.

</Banner>

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-toggle-custom-notification.png"
    alt="Toggle a custom notification kind"
    width={712}
    height={445}
  />
</Figure>

Once a notification kind is enabled on the channel you’re accessing, the error
will disappear.

## Learn more

Learn more in our documentation.

- [What to check before enabling a new notification kind](/docs/guides/what-to-check-before-enabling-a-new-notification-kind).
- [How to create a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).
- [`useNotificationSettings`](/docs/api-reference/liveblocks-react#useNotificationSettings)
- [`client.getNotificationSettings`](/docs/api-reference/liveblocks-client#Client.getNotificationSettings)
- [`Liveblocks.getNotificationSettings`](/docs/api-reference/liveblocks-node#get-users-userId-notification-settings)

---
meta:
  title: "The issued access token doesn't grant enough permissions."
  parentTitle: "Error"
  description:
    "@liveblocks/client error: the issued access token doesn't grant enough
    permissions"
---

## Why this error occurred

The client may request an access token to access resources beyond a specific
room, like Notifications. In such cases, your auth endpoint should issue an
access token that grants access to multiple rooms using wildcards (`*`).

### 1.10 warning

If you saw this warning in your auth endpoint, it's because the version 1.10
allows you to create an access token with no permission, even though it's not
recommended. When doing so, Notifications will work with an access token without
permissions, and Liveblocks will return all the user's notifications (mentions
for example) even if the user doesn't have access to the room. You should move
to use wildcards or use ID tokens, and note that this will not be allowed in
later versions.

## Possible ways to fix it

In your auth endpoint, when the request's property `room` is undefined, you
should create a token that grants access to multiple rooms. Example:

```
session.allow("orga1*", session.FULL_ACCESS);
```

Learn more about
[`permissions with access tokens`](https://liveblocks.io/docs/authentication/access-token).

---
meta:
  title: "You need to polyfill atob to use the client in your environment"
  parentTitle: "Error"
  description:
    "@liveblocks/client error: atob polyfill is required in your environment."
---

## Why this error occurred

You are using `@liveblocks/client` within a JavaScript runtime which doesn't
implement [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/atob).
(environments like React Native or Node < 16)

## Possible ways to fix it

As a polyfill, we recommend installing the package
[`base-64`](https://www.npmjs.com/package/base-64).

```bash
npm install base-64
```

Then you can pass the `decode` function to our `atob` polyfill option when you
create the client.

```ts highlight="1,5-7" file="src/index.js"
import { decode } from "base-64";

const client = createClient({
  /* ... your other client's options */
  polyfills: {
    atob: decode,
  },
});
```

---
meta:
  title: "RoomProvider id property is required"
  parentTitle: "Error"
  description: "@liveblocks/react error: RoomProvider id property is required."
---

## Why this error occurred

[`RoomProvider`][] `id` property is required in order to provide a [`Room`][] in
the tree below.

## Possible ways to fix it

```jsx highlight="5"
import { RoomProvider } from "@liveblocks/react";

function Component() {
  return (
    <RoomProvider id="your-room-id">
      <YourComponent />
    </RoomProvider>
  );
}
```

Sometimes, you don’t have access to your room `id` right away. For example, if
you’re using Next.js and the `id` is coming from the query string, it’s easy to
forget that `useRouter().query.roomId` returns `undefined` on the first render.
Do not render the [`RoomProvider`][] if you don’t have access to the room `id`
right away.

## Useful links

- [`RoomProvider`][]
- [`Room`][]

[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`room`]: /docs/api-reference/liveblocks-client#Room

---
meta:
  title: "Get started with Liveblocks and JavaScript"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and JavaScript"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your JavaScript application using the APIs from the
[`@liveblocks/client`](/docs/api-reference/liveblocks-client) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      The first step in connecting to Liveblocks is creating a client which
      will be responsible for communicating with the back end.

      ```ts file="room.js"
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```js file="room.js"
      const { room, leave } = client.enterRoom("my-room");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Use the Liveblocks methods</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using Liveblocks subscriptions.
      The first we’ll add is `others`, a subscription that provides information
      about which other users are connected to the room.

      ```js file="index.js" highlight="5-7"
      import { room } from "./room.js"

      const div = document.querySelector("div");

      room.subscribe("others", (others) => {
        div.innerText = `There are ${others.length} other user(s) online`;
      });
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your JavaScript application.

- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [JavaScript guides](/docs/guides?technologies=javascript)
- [Authentication](/docs/authentication)

---

## Examples using JavaScript

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative To-do List",
      slug: "collaborative-todo-list/javascript-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors/javascript-live-cursors",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Comments using Liveblocks and Next.js"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Comments using Liveblocks and Next.js"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding a
commenting experience to your Next.js `/app` directory application using the
hooks from [`@liveblocks/react`](/docs/api-reference/liveblocks-react) and the
components from
[`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui).

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Create a Liveblocks room</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. When using Next.js’ `/app` router,
      we recommend creating your room in a `Room.tsx` file in the same directory
      as your current route.

      Set up a Liveblocks client with
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
      join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider),
      and use [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense)
      to add a loading spinner to your app.

      ```tsx file="app/Room.tsx" highlight="12-18"
      "use client";

      import { ReactNode } from "react";
      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";

      export function Room({ children }: { children: ReactNode }) {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                {children}
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Add the Liveblocks room to your page</StepTitle>
    <StepContent>

      After creating your room file, it’s time to join it. Import
      your room into your `page.tsx` file, and place
      your collaborative app components inside it.

      ```tsx file="app/page.tsx" highlight="6-8"
      import { Room } from "./Room";
      import { CollaborativeApp } from "./CollaborativeApp";

      export default function Page() {
        return (
          <Room>
            <CollaborativeApp />
          </Room>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks and components</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks hooks and components.
      We’ll add [`useThreads`](/docs/api-reference/liveblocks-react#useThreads) to get the threads in the room, then we’ll use the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component
      to render them. Finally, we’ll add a way to create threads by adding a [`Composer`](/docs/api-reference/liveblocks-react-ui#Composer).

      ```tsx file="app/CollaborativeApp.tsx" highlight="7,11-14"
      "use client";

      import { useThreads } from "@liveblocks/react/suspense";
      import { Composer, Thread } from "@liveblocks/react-ui";

      export function CollaborativeApp() {
        const { threads } = useThreads();

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

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Import default styles</StepTitle>
    <StepContent>

    The default components come with default styles, you can import them into the
    root layout of your app or directly into a CSS file with `@import`.

    ```tsx file="app/layout.tsx"
    import "@liveblocks/react-ui/styles.css";
    ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>

      Comments is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name and avatar to their comments.

      <Button asChild  className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-comments">
          Add your users to Comments
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You’ve set up the foundation to start building a commenting
experience for your Next.js application.

- [API Reference](/docs/api-reference/liveblocks-react-ui)
- [How to send email notifications when comments are created](/docs/guides/how-to-send-email-notifications-when-comments-are-created)

---

## Examples using Next.js

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments",
      slug: "comments/nextjs-comments",
      image: "/images/examples/thumbnails/comments.jpg",
    }}
    technologies={["nextjs", "react"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Video Comments",
      slug: "video-comments/nextjs-comments-video",
      image: "/images/examples/thumbnails/comments-video.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Overlay Comments",
      slug: "overlay-comments/nextjs-comments-overlay",
      image: "/images/examples/thumbnails/comments-overlay.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Text Editor Comments",
      slug: "text-editor-comments/nextjs-comments-tiptap",
      image: "/images/examples/thumbnails/comments-text-editor.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Lexical, and Next.js"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks, Lexical, and Next.js"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Next.js application using the APIs from the
[`@liveblocks/react-lexical`](/docs/api-reference/liveblocks-react-lexical)
package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks and Lexical</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-lexical lexical @lexical/react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Create a Liveblocks room</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. When using Next.js’ `/app` router,
      we recommend creating your room in a `Room.tsx` file in the same directory
      as your current route.

      Set up a Liveblocks client with
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
      join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider),
      and use [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense)
      to add a loading spinner to your app.

      ```tsx file="app/Room.tsx" highlight="12-18"
      "use client";

      import { ReactNode } from "react";
      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";

      export function Room({ children }: { children: ReactNode }) {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                {children}
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Add the Liveblocks room to your page</StepTitle>
    <StepContent>

      After creating your room file, it’s time to join it. Import
      your room into your `page.tsx` file, and place
      your collaborative app components inside it.

      ```tsx file="app/page.tsx" highlight="6-8"
      import { Room } from "./Room";
      import { Editor } from "./Editor";

      export default function Page() {
        return (
          <Room>
            <Editor/>
          </Room>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Lexical text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Lexical and Liveblocks in the `Editor.tsx` file.
      To make the editor collaborative, we can use
      [`LiveblocksPlugin`](/docs/api-reference/liveblocks-react-lexical#LiveblocksPlugin)
      from `@liveblocks/react-lexical`. [`FloatingToolbar`](/docs/api-reference/liveblocks-react-lexical#FloatingToolbar)
      adds a text selection toolbar.

      ```tsx file="app/Editor.tsx"
      "use client";

      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,
        FloatingToolbar,
      } from "@liveblocks/react-lexical";
      import { Threads } from "./Threads";

      export function Editor() {
        // Wrap your Lexical config with `liveblocksConfig`
        const initialConfig = liveblocksConfig({
          namespace: "Demo",
          onError: (error: unknown) => {
            console.error(error);
            throw error;
          },
        });

        return (
          <LexicalComposer initialConfig={initialConfig}>
            <div className="editor">
              <RichTextPlugin
                contentEditable={<ContentEditable />}
                placeholder={<div className="placeholder">Start typing here…</div>}
                ErrorBoundary={LexicalErrorBoundary}
              />
              <LiveblocksPlugin>
                <Threads />
                <FloatingToolbar />
              </LiveblocksPlugin>
            </div>
          </LexicalComposer>
        );
      }
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Render threads and composer</StepTitle>
    <StepContent>

      To add [Comments](/docs/ready-made-features/comments) to your text editor, we need to import a thread composer
      and list each thread on the page. Create a `Threads.tsx` file that uses [`FloatingComposer`](/docs/api-reference/liveblocks-react-lexical#FloatingComposer)
      for creating new threads, alongside [`AnchoredThreads`](/docs/api-reference/liveblocks-react-lexical#AnchoredThreads) and [`FloatingThreads`](/docs/api-reference/liveblocks-react-lexical#FloatingThreads) for displaying threads on desktop and mobile.

      ```tsx file="app/Threads.tsx"
      "use client";

      import { useThreads } from "@liveblocks/react/suspense";
      import {
        AnchoredThreads,
        FloatingComposer,
        FloatingThreads,
      } from "@liveblocks/react-lexical";

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

        return (
          <>
            <div className="anchored-threads">
              <AnchoredThreads threads={threads} />
            </div>
            <FloatingThreads className="floating-threads" threads={threads} />
            <FloatingComposer className="floating-composer" />
          </>
        );
      }
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Style your editor</StepTitle>
    <StepContent>

      Lexical text editor is unstyled by default, so we can create some custom styles for it in a `globals.css` file. Import `globals.css`, alongside the default Liveblocks styles. You can import them into the
      root layout of your app or directly into a CSS file with `@import`.

      ```css file="app/globals.css" isCollapsed isCollapsable
      .editor {
        position: relative;
        display: flex;
        width: 100%;
        height: 100%;
      }

      [data-lexical-editor] {
        padding: 2px 12px;
        outline: none;
      }

      [data-lexical-editor] p {
        margin: 0.8em 0;
      }

      /* For mobile */
      .floating-threads {
        display: none;
      }

      /* For desktop */
      .anchored-threads {
        display: block;
        max-width: 300px;
        width: 100%;
        position: absolute;
        right: 4px;
      }

      @media (max-width: 640px) {
        .floating-threads {
          display: block;
        }

        .anchored-threads {
          display: none;
        }
      }

      .placeholder {
        position: absolute;
        left: 12px;
        top: 16px;
        pointer-events: none;
        opacity: 0.5;
      }
      ```

      ```tsx file="app/layout.tsx"
      import "@liveblocks/react-ui/styles.css";
      import "@liveblocks/react-lexical/styles.css";
      import "./globals.css";
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>
      Text Editor is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name, color, and avatar, to their cursors and mentions.

      <Button asChild  className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-text-editor">
          Add your users to Text Editor
        </a>
      </Button>
    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Optional: add more features</StepTitle>
    <StepContent>
      Lexical is a highly extensible text editor and it's possible to create complex rich-text applications.
      A great example is in the [Lexical playground](https://playground.lexical.dev/) which enables features
      such as tables, text highlights, embedded images, and more. This is all supported using Liveblocks.

      <Button asChild  className="not-markdown">
        <a href="https://lexical.dev/docs/intro">
          Learn more about Lexical
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Lexical text editor inside your Next.js application.

- [Overview](/docs/ready-made-features/text-editor/lexical)
- [`@liveblocks/react-lexical` API Reference](/docs/api-reference/liveblocks-react-lexical)
- [`@liveblocks/node-lexical` API Reference](/docs/api-reference/liveblocks-node-lexical)
- [Lexical website](https://lexical.dev/)

---

## Examples using Lexical

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-lexical",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Notifications using Liveblocks and Next.js"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Notifications using Liveblocks and Next.js"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
notifications to your Next.js `/app` directory application using the hooks from
[`@liveblocks/react`](/docs/api-reference/liveblocks-react) and the components
from [`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui).

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Create a Liveblocks provider</StepTitle>
    <StepContent>

      Liveblocks Notifications uses the concept of projects, which relate to
      projects in [your dashboard](/dashboard). Notifications are sent between
      users in the same project. To connect and receive notifications, you must
      add [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
      to a client component in your app.

      ```tsx file="app/NotificationsProvider.tsx" highlight="8-10"
      "use client";

      import { ReactNode } from "react";
      import { LiveblocksProvider } from "@liveblocks/react";

      export function NotificationsProvider({ children }: { children: ReactNode }) {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            {children}
          </LiveblocksProvider>
        );
      }
    ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Add the provider to your layout</StepTitle>
    <StepContent>

      After creating your provider file, it’s time to join it. Import
      your room into your `layout.tsx` file, and place
      your collaborative app components inside it.

      ```tsx file="app/layout.tsx" highlight="6-1-"
      import { NotificationsProvider } from "./NotificationsProvider";
      import { MyApp } from "./MyApp";

      export default function Layout({ children }) {
        return (
          <NotificationsProvider>
            <MyApp />
          </NotificationsProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks and components</StepTitle>
    <StepContent>

      Now that we’ve set up the provider, we can start using the Liveblocks hooks and components.
      We’ll add [`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
      to get the current project’s notifications, then we’ll
      use [`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification) and [`InboxNotificationList`](/docs/api-reference/liveblocks-react-ui#InboxNotificationList) to render them.

      ```tsx file="app/MyApp.tsx" highlight="10,13-20"
      "use client";

      import { useInboxNotifications } from "@liveblocks/react/suspense";
      import {
        InboxNotification,
        InboxNotificationList,
      } from "@liveblocks/react-ui";

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

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

    </StepContent>

  </Step>
   <Step>
    <StepTitle>Import default styles</StepTitle>
    <StepContent>

    The default components come with default styles, you can import them into the
    root layout of your app or directly into a CSS file with `@import`.

    ```tsx file="app/layout.tsx"
    import "@liveblocks/react-ui/styles.css";
    ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>

      Notifications is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name and avatar to their notifications.

      <Button asChild  className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-notifications">
          Add your users to Notifications
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You’ve set up the foundation to start building a notifications
experience for your React application.

- [API reference](/docs/api-reference/liveblocks-react#Notifications)
- [Component reference](/docs/api-reference/liveblocks-react-ui#Notifications)

---

## Examples using Notifications

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments notifications",
      slug: "comments-notifications/nextjs-comments-notifications",
      image: "/images/examples/thumbnails/comments-notifications.png",
    }}
    technologies={["nextjs", "react"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Tiptap, and Next.js"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks, Tiptap, and Next.js."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Next.js application using the APIs from the
[`@liveblocks/react-tiptap`](/docs/api-reference/liveblocks-react-tiptap)
package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks and Tiptap</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-tiptap @tiptap/react @tiptap/starter-kit
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Create a Liveblocks room</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. When using Next.js’ `/app` router,
      we recommend creating your room in a `Room.tsx` file in the same directory
      as your current route.

      Set up a Liveblocks client with
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
      join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider),
      and use [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense)
      to add a loading spinner to your app.

      ```tsx file="app/Room.tsx" highlight="12-18"
      "use client";

      import { ReactNode } from "react";
      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";

      export function Room({ children }: { children: ReactNode }) {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                {children}
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

  </StepContent>

</Step>
<Step>
  <StepTitle>Add the Liveblocks room to your page</StepTitle>
  <StepContent>

    After creating your room file, it’s time to join it. Import
    your room into your `page.tsx` file, and place
    your collaborative app components inside it.

    ```tsx file="app/page.tsx" highlight="6-8"
    import { Room } from "./Room";
    import { Editor } from "./Editor";

    export default function Page() {
      return (
        <Room>
          <Editor/>
        </Room>
      );
    }
    ```

  </StepContent>

</Step>
<Step>
  <StepTitle>Set up the collaborative Tiptap text editor</StepTitle>
  <StepContent>

    Now that we set up Liveblocks, we can start integrating Tiptap and Liveblocks in the `Editor.tsx` file.
    To make the editor collaborative, we can add
    [`useLiveblocksExtension`](/docs/api-reference/liveblocks-react-tiptap#useLiveblocksExtension)
    from `@liveblocks/react-tiptap`. [`FloatingToolbar`](/docs/api-reference/liveblocks-react-tiptap#FloatingToolbar)
    adds a text selection toolbar.

    ```tsx file="app/Editor.tsx"
    "use client";

    import { useLiveblocksExtension, FloatingToolbar } from "@liveblocks/react-tiptap";
    import { useEditor, EditorContent } from "@tiptap/react";
    import StarterKit from "@tiptap/starter-kit";
    import { Threads } from "./Threads";

    export function Editor() {
      const liveblocks = useLiveblocksExtension();

      const editor = useEditor({
        extensions: [
          liveblocks,
          StarterKit.configure({
            // The Liveblocks extension comes with its own history handling
            history: false,
          }),
        ],
        immediatelyRender: false,
      });

      return (
        <div>
          <EditorContent editor={editor} className="editor" />
          <Threads editor={editor} />
          <FloatingToolbar editor={editor} />
        </div>
      );
    }
    ```

</StepContent>

</Step>
<Step>
  <StepTitle>Render threads and composer</StepTitle>
  <StepContent>

    To add [Comments](/docs/ready-made-features/comments) to your text editor, we need to import a thread composer
    and list each thread on the page. Create a `Threads.tsx` file that uses [`FloatingComposer`](/docs/api-reference/liveblocks-react-tiptap#FloatingComposer)
    for creating new threads, alongside [`AnchoredThreads`](/docs/api-reference/liveblocks-react-tiptap#AnchoredThreads) and [`FloatingThreads`](/docs/api-reference/liveblocks-react-tiptap#FloatingThreads) for displaying threads on desktop and mobile.

    ```tsx file="app/Threads.tsx"
    import { useThreads } from "@liveblocks/react/suspense";
    import {
      AnchoredThreads,
      FloatingComposer,
      FloatingThreads,
    } from "@liveblocks/react-tiptap";
    import { Editor } from "@tiptap/react";

    export function Threads({ editor }: { editor: Editor | null }) {
      const { threads } = useThreads({ query: { resolved: false } });

      return (
        <>
          <div className="anchored-threads">
            <AnchoredThreads editor={editor} threads={threads} />
          </div>
          <FloatingThreads
            editor={editor}
            threads={threads}
            className="floating-threads"
          />
          <FloatingComposer editor={editor} className="floating-composer" />
        </>
      );
    }
    ```

</StepContent>

</Step>
<Step>
  <StepTitle>Style your editor</StepTitle>
  <StepContent>

    Tiptap text editor is unstyled by default, so we can create some custom styles for it in a `globals.css` file. Import `globals.css`, alongside the default Liveblocks styles. You can import them into the
    root layout of your app or directly into a CSS file with `@import`.

    ```css file="app/globals.css" isCollapsed isCollapsable
    .editor {
      position: relative;
      display: flex;
      width: 100%;
      height: 100%;
    }

    .tiptap {
      padding: 2px 12px;
      outline: none;
      width: 100%;
    }

    /* For mobile */
    .floating-threads {
      display: none;
    }

    /* For desktop */
    .anchored-threads {
      display: block;
      max-width: 300px;
      width: 100%;
      position: absolute;
      right: 12px;
    }

    @media (max-width: 640px) {
      .floating-threads {
        display: block;
      }

      .anchored-threads {
        display: none;
      }
    }
    ```

    ```tsx file="app/layout.tsx"
    import "@liveblocks/react-ui/styles.css";
    import "@liveblocks/react-tiptap/styles.css";
    import "./globals.css";
    ```

  </StepContent>

</Step>
<Step>
  <StepTitle>Next: authenticate and add your users</StepTitle>
  <StepContent>
    Text Editor is set up and working now, but each user is anonymous—the next step is to
    authenticate each user as they connect, and attach their name, color, and avatar, to their cursors and mentions.

    <Button asChild  className="not-markdown">
      <a href="/docs/guides/how-to-add-users-to-liveblocks-text-editor">
        Add your users to Text Editor
      </a>
    </Button>

  </StepContent>

</Step>
<Step lastStep>
  <StepTitle>Optional: add more features</StepTitle>
  <StepContent>
    Tiptap is easy to extend, and a number of extensions are already available, making it possibly to quickly create complex rich-text applications. For example you can enable features
    such as tables, text highlights, embedded images, and more. This is all supported using Liveblocks.

    <Button asChild  className="not-markdown">
      <a href="https://tiptap.dev/docs/editor/extensions/overview">
        Find more extensions
      </a>
    </Button>

  </StepContent>

</Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your Next.js application.

- [@liveblocks/react-tiptap API Reference](/docs/api-reference/liveblocks-react-tiptap)
- [Tiptap guides](/docs/guides?technologies=tiptap)
- [Tiptap website](https://tiptap.dev)

---

## Examples using Tiptap

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-tiptap",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Advanced Collaborative Text Editor",
      slug: "collaborative-text-editor-advanced/nextjs-tiptap-advanced",
      image: "/images/examples/thumbnails/text-editor-advanced.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and Next.js"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and Next.js"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Next.js `/app` directory application using the hooks from
the [`@liveblocks/react`](/docs/api-reference/liveblocks-react) package.

## Quickstart

<Steps>

  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Create a Liveblocks room</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. When using Next.js’ `/app` router,
      we recommend creating your room in a `Room.tsx` file in the same directory
      as your current route.

      Set up a Liveblocks client with
      [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider),
      join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider),
      and use [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense)
      to add a loading spinner to your app.

      ```tsx file="app/Room.tsx" highlight="12-18"
      "use client";

      import { ReactNode } from "react";
      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";

      export function Room({ children }: { children: ReactNode }) {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                {children}
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Add the Liveblocks room to your page</StepTitle>
    <StepContent>

      After creating your room file, it’s time to join it. Import
      your room into your `page.tsx` file, and place
      your collaborative app components inside it.

      ```tsx file="app/page.tsx" highlight="6-8"
      import { Room } from "./Room";
      import { CollaborativeApp } from "./CollaborativeApp";

      export default function Page() {
        return (
          <Room>
            <CollaborativeApp />
          </Room>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks hooks.
      The first we’ll add is [`useOthers`](/docs/api-reference/liveblocks-react#useOthers), a hook that provides information
      about which other users are connected to the room.

      ```tsx file="app/CollaborativeApp.tsx" highlight="6"
      "use client";

      import { useOthers } from "@liveblocks/react/suspense";

      export function CollaborativeApp() {
        const others = useOthers();
        const userCount = others.length;
        return <div>There are {userCount} other user(s) online</div>;
      }
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your React application.

- [@liveblocks/react API Reference](/docs/api-reference/liveblocks-react)
- [Next.js and React guides](/docs/guides?technologies=nextjs%2Creact)
- [How to use Liveblocks Presence with React](/docs/guides/how-to-use-liveblocks-presence-with-react)
- [How to use Liveblocks Storage with React](/docs/guides/how-to-use-liveblocks-storage-with-react)

---

## Examples using Next.js

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative To-do List",
      slug: "collaborative-todo-list/nextjs-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack/nextjs-live-avatars",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Spreadsheet",
      slug: "collaborative-spreadsheet-advanced/nextjs-spreadsheet-advanced",
      image:
        "/images/examples/thumbnails/collaborative-spreadsheet-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard-advanced/nextjs-whiteboard-advanced",
      image:
        "/images/examples/thumbnails/collaborative-whiteboard-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Comments using Liveblocks and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Comments using Liveblocks and React"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding a
commenting experience to your React application using the hooks from
[`@liveblocks/react`](/docs/api-reference/liveblocks-react) and the components
from [`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui).

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Room } from "./Room";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Room } from "./Room";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Room />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks and components</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks hooks and components.
      We’ll add [`useThreads`](/docs/api-reference/liveblocks-react#useThreads) to get the threads in the room, then we’ll use the [`Thread`](/docs/api-reference/liveblocks-react-ui#Thread) component
      to render them. Finally, we’ll add a way to create threads by adding a [`Composer`](/docs/api-reference/liveblocks-react-ui#Composer).

      ```tsx file="Room.tsx" highlight="7,11-14"
      "use client";

      import { useThreads } from "@liveblocks/react/suspense";
      import { Composer, Thread } from "@liveblocks/react-ui";

      export function Room() {
        const { threads } = useThreads();

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

    </StepContent>

  </Step>
   <Step>
    <StepTitle>Import default styles</StepTitle>
    <StepContent>

    The default components come with default styles, you can import them into the
    root of your app or directly into a CSS file with `@import`.

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

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>

      Comments is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name and avatar to their comments.

      <Button asChild className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-comments">
          Add your users to Comments
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You’ve set up the foundation to start building a commenting
experience for your React application.

- [API Reference](/docs/api-reference/liveblocks-react-ui)
- [How to send email notifications when comments are created](/docs/guides/how-to-send-email-notifications-when-comments-are-created)

---

## Examples using React

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments",
      slug: "comments/react-comments",
      image: "/images/examples/thumbnails/comments.jpg",
    }}
    technologies={["nextjs", "react"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Video Comments",
      slug: "video-comments/nextjs-comments-video",
      image: "/images/examples/thumbnails/comments-video.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Overlay Comments",
      slug: "overlay-comments/nextjs-comments-overlay",
      image: "/images/examples/thumbnails/comments-overlay.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Text Editor Comments",
      slug: "text-editor-comments/nextjs-comments-tiptap",
      image: "/images/examples/thumbnails/comments-text-editor.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Lexical, and React"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks, Lexical, and React"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/react-lexical`](/docs/api-reference/liveblocks-react-lexical)
package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks and Lexical</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-lexical lexical @lexical/react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Editor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Lexical text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Lexical and Liveblocks in the `Editor.tsx` file.
      To make the editor collaborative, we can use
      [`LiveblocksPlugin`](/docs/api-reference/liveblocks-react-lexical#LiveblocksPlugin)
      from `@liveblocks/react-lexical`. [`FloatingToolbar`](/docs/api-reference/liveblocks-react-lexical#FloatingToolbar)
      adds a text selection toolbar.


      ```tsx file="Editor.tsx"
      "use client";

      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,
        FloatingToolbar,
      } from "@liveblocks/react-lexical";
      import { Threads } from "./Threads";

      export function Editor() {
        // Wrap your Lexical config with `liveblocksConfig`
        const initialConfig = liveblocksConfig({
          namespace: "Demo",
          onError: (error: unknown) => {
            console.error(error);
            throw error;
          },
        });

        return (
          <LexicalComposer initialConfig={initialConfig}>
            <div className="editor">
              <RichTextPlugin
                contentEditable={<ContentEditable />}
                placeholder={<div className="placeholder">Start typing here…</div>}
                ErrorBoundary={LexicalErrorBoundary}
              />
              <LiveblocksPlugin>
                <Threads />
                <FloatingToolbar />
              </LiveblocksPlugin>
            </div>
          </LexicalComposer>
        );
      }
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Render threads and composer</StepTitle>
    <StepContent>

      To add [Comments](/docs/ready-made-features/comments) to your text editor, we need to import a thread composer
      and list each thread on the page. Create a `Threads.tsx` file that uses [`FloatingComposer`](/docs/api-reference/liveblocks-react-lexical#FloatingComposer)
      for creating new threads, alongside [`AnchoredThreads`](/docs/api-reference/liveblocks-react-lexical#AnchoredThreads) and [`FloatingThreads`](/docs/api-reference/liveblocks-react-lexical#FloatingThreads) for displaying threads on desktop and mobile.

      ```tsx file="Threads.tsx"
      "use client";

      import { useThreads } from "@liveblocks/react/suspense";
      import {
        AnchoredThreads,
        FloatingComposer,
        FloatingThreads,
      } from "@liveblocks/react-lexical";

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

        return (
          <>
            <div className="anchored-threads">
              <AnchoredThreads threads={threads} />
            </div>
            <FloatingThreads className="floating-threads" threads={threads} />
            <FloatingComposer className="floating-composer" />
          </>
        );
      }
      ```
    </StepContent>

  </Step>
  <Step>
    <StepTitle>Style your editor</StepTitle>
    <StepContent>

      Lexical text editor is unstyled by default, so we can create some custom styles for it in a `globals.css` file. Import `globals.css`, alongside the default Liveblocks styles. You can import them into the
      root layout of your app or directly into a CSS file with `@import`.

      ```css file="globals.css" isCollapsed isCollapsable
      .editor {
        position: relative;
        display: flex;
        width: 100%;
        height: 100%;
      }

      [data-lexical-editor] {
        padding: 2px 12px;
        outline: none;
      }

      [data-lexical-editor] p {
        margin: 0.8em 0;
      }

      /* For mobile */
      .floating-threads {
        display: none;
      }

      /* For desktop */
      .anchored-threads {
        display: block;
        max-width: 300px;
        width: 100%;
        position: absolute;
        right: 4px;
      }

      @media (max-width: 640px) {
        .floating-threads {
          display: block;
        }

        .anchored-threads {
          display: none;
        }
      }

      .placeholder {
        position: absolute;
        left: 12px;
        top: 16px;
        pointer-events: none;
        opacity: 0.5;
      }
      ```

      ```tsx
      import "@liveblocks/react-ui/styles.css";
      import "@liveblocks/react-lexical/styles.css";
      import "./globals.css";
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>
      Text Editor is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name, color, and avatar, to their cursors and mentions.

      <Button asChild  className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-text-editor">
          Add your users to Text Editor
        </a>
      </Button>
    </StepContent>

  </Step>
   <Step lastStep>
    <StepTitle>Optional: add more features</StepTitle>
    <StepContent>
      Lexical is a highly extensible text editor and it's possible to create complex rich-text applications.
      A great example is in the [Lexical playground](https://playground.lexical.dev/) which enables features
      such as tables, text highlights, embedded images, and more. This is all supported using Liveblocks.

      <Button asChild  className="not-markdown">
        <a href="https://lexical.dev/docs/intro">
          Learn more about Lexical
        </a>
      </Button>
    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Lexical text editor inside your React application.

- [Overview](/docs/ready-made-features/text-editor/lexical)
- [`@liveblocks/react-lexical` API Reference](/docs/api-reference/liveblocks-react-lexical)
- [`@liveblocks/node-lexical` API Reference](/docs/api-reference/liveblocks-node-lexical)
- [Lexical website](https://lexical.dev/)

---

## Examples using Lexical

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-lexical",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Notifications using Liveblocks and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Notifications using Liveblocks and React"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
notifications to your application using the hooks from
[`@liveblocks/react`](/docs/api-reference/liveblocks-react) and the components
from [`@liveblocks/react-ui`](/docs/api-reference/liveblocks-react-ui).

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import { LiveblocksProvider } from "@liveblocks/react/suspense";
      import { Room } from "./Room";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <Room />
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks and components</StepTitle>
    <StepContent>

      Now that we’ve set up the provider, we can start using the Liveblocks hooks and components.
      We’ll add [`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
      to get the current project’s notifications, then we’ll
      use [`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification) and [`InboxNotificationList`](/docs/api-reference/liveblocks-react-ui#InboxNotificationList) to render them.

      ```tsx file="app/MyApp.tsx" highlight="1,13-20"
      "use client";

      import { useInboxNotifications } from "@liveblocks/react/suspense";
      import {
        InboxNotification,
        InboxNotificationList,
      } from "@liveblocks/react-ui";

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

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

    </StepContent>

  </Step>
   <Step>
    <StepTitle>Import default styles</StepTitle>
    <StepContent>

    The default components come with default styles, you can import them into the
    root of your app or directly into a CSS file with `@import`.

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

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>

      Notifications is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name and avatar to their notifications.

      <Button asChild className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-notifications">
          Add your users to Notifications
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You’ve set up the foundation to start building a notifications
experience for your React application.

- [API reference](/docs/api-reference/liveblocks-react#Notifications)
- [Component reference](/docs/api-reference/liveblocks-react-ui#Notifications)

---

## Examples using Notifications

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments notifications",
      slug: "comments-notifications/nextjs-comments-notifications",
      image: "/images/examples/thumbnails/comments-notifications.png",
    }}
    technologies={["nextjs", "react"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Tiptap, and React"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks, Tiptap, and React"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/react-tiptap`](/docs/api-reference/liveblocks-react-tiptap)
package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks and Tiptap</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui @liveblocks/react-tiptap @tiptap/react @tiptap/starter-kit
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Editor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Tiptap text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Tiptap and Liveblocks in the `Editor.tsx` file.
    To make the editor collaborative, we can add
    [`useLiveblocksExtension`](/docs/api-reference/liveblocks-react-tiptap#useLiveblocksExtension)
    from `@liveblocks/react-tiptap`. [`FloatingToolbar`](/docs/api-reference/liveblocks-react-tiptap#FloatingToolbar)
      adds a text selection toolbar.

    ```tsx file="Editor.tsx"
    "use client";

    import { useLiveblocksExtension, FloatingToolbar } from "@liveblocks/react-tiptap";
    import { useEditor, EditorContent } from "@tiptap/react";
    import StarterKit from "@tiptap/starter-kit";
    import { Threads } from "./Threads";

    export function Editor() {
      const liveblocks = useLiveblocksExtension();

      const editor = useEditor({
        extensions: [
          liveblocks,
          StarterKit.configure({
            // The Liveblocks extension comes with its own history handling
            history: false,
          }),
        ],
      });

      return (
        <div>
          <EditorContent editor={editor} className="editor" />
          <Threads editor={editor} />
          <FloatingToolbar editor={editor} />
        </div>
      );
    }
    ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Render threads and composer</StepTitle>
    <StepContent>

     To add [Comments](/docs/ready-made-features/comments) to your text editor, we need to import a thread composer
    and list each thread on the page. Create a `Threads.tsx` file that uses [`FloatingComposer`](/docs/api-reference/liveblocks-react-tiptap#FloatingComposer)
    for creating new threads, alongside [`AnchoredThreads`](/docs/api-reference/liveblocks-react-tiptap#AnchoredThreads) and [`FloatingThreads`](/docs/api-reference/liveblocks-react-tiptap#FloatingThreads) for displaying threads on desktop and mobile.

    ```tsx file="Threads.tsx"
    import { useThreads } from "@liveblocks/react/suspense";
    import {
      AnchoredThreads,
      FloatingComposer,
      FloatingThreads,
    } from "@liveblocks/react-tiptap";
    import { Editor } from "@tiptap/react";

    export function Threads({ editor }: { editor: Editor | null }) {
      const { threads } = useThreads({ query: { resolved: false } });

      return (
        <>
          <div className="anchored-threads">
            <AnchoredThreads editor={editor} threads={threads} />
          </div>
          <FloatingThreads
            editor={editor}
            threads={threads}
            className="floating-threads"
          />
          <FloatingComposer editor={editor} className="floating-composer" />
        </>
      );
    }
    ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Style your editor</StepTitle>
    <StepContent>

      Tiptap text editor is unstyled by default, so we can create some custom styles for it in a `globals.css` file. Import `globals.css`, alongside the default Liveblocks styles. You can import them into the
    root layout of your app or directly into a CSS file with `@import`.

    ```css file="app/globals.css" isCollapsed isCollapsable
    .editor {
      position: relative;
      display: flex;
      width: 100%;
      height: 100%;
    }

    .tiptap {
      padding: 2px 12px;
      outline: none;
      width: 100%;
    }

    /* For mobile */
    .floating-threads {
      display: none;
    }

    /* For desktop */
    .anchored-threads {
      display: block;
      max-width: 300px;
      width: 100%;
      position: absolute;
      right: 12px;
    }

    @media (max-width: 640px) {
      .floating-threads {
        display: block;
      }

      .anchored-threads {
        display: none;
      }
    }
    ```

    ```tsx file="app/layout.tsx"
    import "@liveblocks/react-ui/styles.css";
    import "@liveblocks/react-tiptap/styles.css";
    import "./globals.css";
    ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Next: authenticate and add your users</StepTitle>
    <StepContent>
      Text Editor is set up and working now, but each user is anonymous—the next step is to
      authenticate each user as they connect, and attach their name, color, and avatar, to their cursors and mentions.

      <Button asChild  className="not-markdown">
        <a href="/docs/guides/how-to-add-users-to-liveblocks-text-editor">
          Add your users to Text Editor
        </a>
      </Button>
    </StepContent>

  </Step>
   <Step lastStep>
    <StepTitle>Optional: add more features</StepTitle>
    <StepContent>
      Tiptap is easy to extend, and a number of extensions are already available, making it possibly to quickly create complex rich-text applications. For example you can enable features
    such as tables, text highlights, embedded images, and more. This is all supported using Liveblocks.

    <Button asChild  className="not-markdown">
      <a href="https://tiptap.dev/docs/editor/extensions/overview">
        Find more extensions
      </a>
    </Button>

    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your React application.

- [@liveblocks/react-tiptap API Reference](/docs/api-reference/liveblocks-react-tiptap)
- [Tiptap guides](/docs/guides?technologies=tiptap)
- [Tiptap website](https://tiptap.dev)

---

## Examples using Tiptap

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-tiptap",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Advanced Collaborative Text Editor",
      slug: "collaborative-text-editor-advanced/nextjs-tiptap-advanced",
      image: "/images/examples/thumbnails/text-editor-advanced.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and React"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and React"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the hooks from the
[`@liveblocks/react`](/docs/api-reference/liveblocks-react) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Room } from "./Room";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Room } from "./Room";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Room />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks hooks</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks hooks.
      The first we’ll add is [`useOthers`](/docs/api-reference/liveblocks-react#useOthers), a hook that provides information about
      which other users are connected to the room.

      ```tsx file="Room.tsx" highlight="6"
      "use client";

      import { useOthers } from "./liveblocks.config";

      export function Room() {
        const others = useOthers();
        const userCount = others.length;

        return <div>There are {userCount} other user(s) online</div>;
      }
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your React application.

- [@liveblocks/react API Reference](/docs/api-reference/liveblocks-react)
- [React guides](/docs/guides?technologies=react)
- [How to use Liveblocks Presence with React](/docs/guides/how-to-use-liveblocks-presence-with-react)
- [How to use Liveblocks Storage with React](/docs/guides/how-to-use-liveblocks-storage-with-react)

---

## Examples using React

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative To-do List",
      slug: "collaborative-todo-list/nextjs-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack/nextjs-live-avatars",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Spreadsheet",
      slug: "collaborative-spreadsheet-advanced/nextjs-spreadsheet-advanced",
      image:
        "/images/examples/thumbnails/collaborative-spreadsheet-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard-advanced/nextjs-whiteboard-advanced",
      image:
        "/images/examples/thumbnails/collaborative-whiteboard-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and Redux"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and Redux"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start making your Redux
state multiplayer by using the
[store enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer)
from the [`@liveblocks/redux`](/docs/api-reference/liveblocks-redux) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/redux
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Connect your Redux store to Liveblocks</StepTitle>
    <StepContent>

      Create the Liveblocks client and use the
      `liveblocksEnhancer` in your Redux store setup. This will
      add a new state called `liveblocks` to your store, enabling
      you to interact with our Presence and Storage APIs.

      ```ts file="store.ts" highlight="7-9,25-27"
      "use client";

      import { createClient } from "@liveblocks/client";
      import { liveblocksEnhancer } from "@liveblocks/redux";
      import { configureStore, createSlice } from "@reduxjs/toolkit";

      const client = createClient({
        publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
      });

      const initialState = {};

      const slice = createSlice({
        name: "state",
        initialState,
        reducers: {
          /* logic will be added here */
        },
      });

      function makeStore() {
        return configureStore({
          reducer: slice.reducer,
          enhancers: [
            liveblocksEnhancer({
              client,
            }),
          ],
        });
      }

      const store = makeStore();

      export default store;
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```tsx file="App.tsx" highlight="5,11,14"
      "use client";

      import { useEffect } from "react";
      import { useDispatch } from "react-redux";
      import { actions } from "@liveblocks/redux";

      export default function App() {
        const dispatch = useDispatch();

        useEffect(() => {
          dispatch(actions.enterRoom("room-id"));

          return () => {
            dispatch(actions.leaveRoom("room-id"));
          };
        }, [dispatch]);

        return <Room />;
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks data from the store</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks data from the Redux store.

      ```tsx file="Room.tsx" highlight="6"
      "use client";

      import { useSelector } from "react-redux";

      export function Room() {
        const others = useSelector((state) => state.liveblocks.others);
        const userCount = others.length;
        return <div>There are {userCount} other user(s) online</div>;
      }
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your Redux store.

- [@liveblocks/redux API Reference](/docs/api-reference/liveblocks-redux)
- [Redux guides](/docs/guides?technologies=redux)
- [How to create a collaborative online whiteboard with Redux](/docs/guides/how-to-create-a-collaborative-online-whiteboard-with-react-redux-and-liveblocks)
- [How to create a collaborative to-do list with Redux](/docs/guides/how-to-create-a-collaborative-to-do-list-with-react-redux-and-liveblocks)

---

## Examples using Redux

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative To-do List",
      slug: "collaborative-todo-list/redux-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard/redux-whiteboard",
      image: "/images/examples/thumbnails/collaborative-whiteboard.jpg",
      advanced: true,
    }}
    technologies={["nextjs", "redux", "zustand"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and SolidJS"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and SolidJS"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your SolidJS application using the APIs from the
[`@liveblocks/client`](/docs/api-reference/liveblocks-client) package.

<Banner title="Official package">

Liveblocks does not have a package for SolidJS. If you would like to have one,
or even better if you have ideas about what kind of API you would like to use,
please let us know about it on this
[GitHub issue](https://github.com/liveblocks/liveblocks/issues/672).

</Banner>

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      The first step in connecting to Liveblocks is creating a client which
      will be responsible for communicating with the back end.

      ```ts file="room.js"
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```js
      const { room, leave } = client.enterRoom("my-room");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Use the Liveblocks methods</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using Liveblocks subscriptions.
      The first we’ll add is `others`, a subscription that provides information
      about which other users are connected to the room.

      ```js highlight="8-10"
      import { createSignal, onCleanup, onMount } from "solid-js";
      import { room } from "./room.js";

      export function Room() {
        const [other, setOthers] = createSignal(room.getOthers());

        onMount(() => {
          const unsubscribeOthers = room.subscribe("others", (updatedOthers) => {
            setOthers(updatedOthers);
          });

          onCleanup(() => {
            unsubscribeOthers();
          });
        })

        return (
          <div>There are {others.length} other user(s) online</div>
        );
      }
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your SolidJS application.

- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)

---

## Examples using SolidJS

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack/solidjs-live-avatars",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors/solidjs-live-cursors",
      image: "/images/examples/thumbnails/live-cursors.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and Svelte"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and Svelte"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Svelte application using the APIs from the
[`@liveblocks/client`](/docs/api-reference/liveblocks-client) package.

<Banner title="Official package">

Liveblocks does not have a package for Svelte. If you would like to have one, or
even better if you have ideas about what kind of API you would like to use,
please let us know on
[GitHub](https://github.com/liveblocks/liveblocks/issues/1).

</Banner>

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      The first step in connecting to Liveblocks is creating a client which
      will be responsible for communicating with the back end.

      ```ts file="room.js"
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```js
      const { room, leave } = client.enterRoom("my-room");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Use the Liveblocks methods</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using Liveblocks subscriptions.
      The first we’ll add is `others`, a subscription that provides information
      about which other users are connected to the room.

      ```js highlight="7-9"
      <script>
        import { onDestroy } from "svelte";
        import { room } from "./room.js";

        let others = room.getOthers();

        const unsubscribeOthers = room.subscribe("others", (updatedOthers) => {
          others = updatedOthers;
        });

        onDestroy(() => {
          unsubscribeOthers();
        });
      </script>

      <div>There are {others.length} other user(s) online</div>
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your Svelte application.

- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)

---

## Examples using Svelte

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors/sveltekit-live-cursors",
      image: "/images/examples/thumbnails/live-cursors.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack/sveltekit-live-avatars",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks and Vue.js"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and Vue.js"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Vue.js application using the APIs from the
[`@liveblocks/client`](/docs/api-reference/liveblocks-client) package.

<Banner title="Official package">

Liveblocks does not have a package for Vue.js. If you would like to have one, or
even better if you have ideas about what kind of API you would like to use,
please let us know about it on this
[GitHub issue](https://github.com/liveblocks/liveblocks/issues/1).

</Banner>

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every package should use the same version.

      ```bash
      npm install @liveblocks/client
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      The first step in connecting to Liveblocks is creating a client which
      will be responsible for communicating with the back end.

      ```ts file="room.js"
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```js
      const { room, leave } = client.enterRoom("my-room");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Use the Liveblocks methods</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using Liveblocks subscriptions.
      The first we’ll add is `others`, a subscription that provides information
      about which other users are connected to the room.

      ```js highlight="7-9"
      <script setup>
        import { onUnmounted, ref } from "vue";
        import { room } from "./room.js";

        const others = ref(room.getOthers());

        const unsubscribeOthers = room.subscribe("others", (updatedOthers) => {
          others.current = updatedOthers;
        });

        onUnmounted(() => {
          unsubscribeOthers();
        });
      </script>

      <template>
        <div>There are {{ others.length }} other user(s) online</div>
      </template>
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your Vue.js application.

- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)

---

## Examples using Vue.js

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack/vuejs-live-avatars",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors/vuejs-live-cursors",
      image: "/images/examples/thumbnails/live-cursors.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Yjs, BlockNote, and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Liveblocks, Yjs, BlockNote, and React."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and BlockNote</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs @blocknote/core @blocknote/react @blocknote/mantine
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Editor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative BlockNote text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating BlockNote and Yjs in the `Editor.tsx` file.

      ```tsx file="Editor.tsx"
      import { useEffect, useState } from "react";
      import { BlockNoteEditor } from "@blocknote/core";
      import "@blocknote/core/fonts/inter.css";
      import { useCreateBlockNote } from "@blocknote/react";
      import { BlockNoteView } from "@blocknote/mantine";
      import "@blocknote/mantine/styles.css";
      import * as Y from "yjs";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import { useRoom } from "@liveblocks/react/suspense";

      type EditorProps = {
        doc: Y.Doc,
        provider: any;
      }

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

        return <BlockNote doc={yDoc} provider={yProvider} />;
      }


      function BlockNote({ doc, provider }: EditorProps) {
        const editor: BlockNoteEditor = useCreateBlockNote({
          collaboration: {
            provider,

            // Where to store BlockNote data in the Y.Doc:
            fragment: doc.getXmlFragment("document-store"),

            // Information for this user:
            user: {
              name: "My Username",
              color: "#ff0000",
            },
          },
        });

        return <BlockNoteView editor={editor} />;
      }
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
BlockNote text editor inside your React application.

- [Yjs guides](/docs/guides?technologies=yjs)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [BlockNote website](https://www.blocknotejs.org/)

---

## Examples using BlockNote

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-yjs-blocknote",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Advanced Collaborative Text Editor",
      slug: "collaborative-text-editor-advanced/nextjs-yjs-blocknote-advanced",
      image: "/images/examples/thumbnails/text-editor-advanced.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, CodeMirror, Yjs, and JavaScript"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, CodeMirror, Yjs, and JavaScript."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your JavaScript application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and CodeMirror</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs codemirror @codemirror/lang-javascript y-codemirror.next
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create an HTML element</StepTitle>
    <StepContent>

      ```html
      <div id="editor"></div>
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative CodeMirror code editor</StepTitle>
    <StepContent>

      ```js file="app.js"
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      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";

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const { room, leave } = client.enterRoom("my-room");

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc()
      const yText = yDoc.getText("codemirror");

      // Set up CodeMirror and extensions
      const state = EditorState.create({
        doc: yText.toString(),
        extensions: [
          basicSetup,
          javascript(),
          yCollab(ytext, yProvider.awareness, { undoManager }),
        ],
      });

      // Attach CodeMirror to element
      const parent = document.querySelector("#editor");
      view = new EditorView({
        state,
        parent,
      });
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
CodeMirror code editor inside your JavaScript application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [CodeMirror website](https://codemirror.net)

---
meta:
  title: "Get started with Liveblocks, CodeMirror, Yjs, and React"
  parentTitle: "Get started"
  description: "Learn how to get started with CodeMirror, Yjs, and Liveblocks."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and CodeMirror</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs codemirror @codemirror/lang-javascript y-codemirror.next
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Editor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative CodeMirror editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating CodeMirror and Yjs in the `Editor.tsx` file.
      To make the editor collaborative, we can rely on the `yCollab` from `y-codemirror.next`.

      ```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 { getYjsProviderForRoom } from "@liveblocks/yjs";
      import { useRoom } from "@/liveblocks.config";
      import styles from "./Editor.module.css";

      export default function Editor() {
        const room = useRoom();
        const yProvider = getYjsProviderForRoom(room);
        const [element, setElement] = useState<HTMLElement>();

        const ref = useCallback((node: HTMLElement | null) => {
          if (!node) return;

          setElement(node);
        }, []);

        // Set up Liveblocks Yjs provider and attach CodeMirror editor
        useEffect(() => {
          let view: EditorView;

          if (!element || !room) {
            return;
          }

          // Get document
          const yDoc = yProvider.getYDoc();
          const yText = yDoc.getText("codemirror");
          const undoManager = new Y.UndoManager(yText);

          // Set up CodeMirror and extensions
          const state = EditorState.create({
            doc: yText.toString(),
            extensions: [
              basicSetup,
              javascript(),
              yCollab(yText, yProvider.awareness, { undoManager }),
            ],
          });

          // Attach CodeMirror to element
          view = new EditorView({
            state,
            parent: element,
          });

          return () => {
            view?.destroy();
          };
        }, [element, room]);

        return <div ref={ref} className={styles.editor} />;
      }
      ```
    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>

      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
CodeMirror editor inside your React application.

- [Yjs and CodeMirror guides](/docs/guides?technologies=yjs%2Ccodemirror)
- [How to create a collaborative code editor with CodeMirror, Yjs, Next.js, and Liveblocks](/docs/guides/how-to-create-a-collaborative-code-editor-with-codemirror-yjs-nextjs-and-liveblocks)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [CodeMirror website](https://codemirror.net)

---

## Examples using CodeMirror

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Code Editor",
      slug: "collaborative-code-editor/nextjs-yjs-codemirror",
      image: "/images/examples/thumbnails/code-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, CodeMirror, Yjs, and Svelte"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, CodeMirror, Yjs, and Svelte."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Svelte application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and CodeMirror</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs codemirror @codemirror/lang-javascript y-codemirror.next
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative CodeMirror code editor</StepTitle>
    <StepContent>

      ```html file="Editor.svelte"
      <script>
      import { onMount, onDestroy } from "svelte";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      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";

      let parent;

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      onMount(() => {
        // Enter a multiplayer room
        const { room, leave } = client.enterRoom("my-room");

        // Set up Yjs document, shared text, undo manager, and Liveblocks Yjs provider
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();
        const yText = yDoc.getText("codemirror");
        const undoManager = new Y.UndoManager(yText);

        // Set up CodeMirror and extensions
        const state = EditorState.create({
          doc: yText.toString(),
          extensions: [
            basicSetup,
            javascript(),
            yCollab(yText, yProvider.awareness, { undoManager }),
          ],
        });

        // Attach CodeMirror to element
        const view = new EditorView({
          state,
          parent,
        });

        return () => {
          view.destroy();
          leave();
        };
      });
      </script>

      <div bind:this={parent}></div>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
CodeMirror code editor inside your Svelte application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [CodeMirror website](https://codemirror.net)

---
meta:
  title: "Get started with Liveblocks, CodeMirror, Yjs, and Vue.js"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, CodeMirror, Yjs, and Vue.js."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Vue.js application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and CodeMirror</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs codemirror @codemirror/lang-javascript y-codemirror.next
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative CodeMirror code editor</StepTitle>
    <StepContent>

      ```html file="Editor.vue"
      <script setup>
      import { ref, onMounted, onUnmounted } from "vue";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      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";

      const parent = ref(null);
      const leave = ref(null);
      const view = ref(null);

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const info = client.enterRoom("my-room");
      const room = info.room;
      leave.value = info.leave;

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();
      const yText = yDoc.getText("codemirror");

      onMounted(() => {
        // Set up CodeMirror and extensions
        const state = EditorState.create({
          doc: yText.toString(),
          extensions: [
            basicSetup,
            javascript(),
            yCollab(ytext, yProvider.awareness, { undoManager }),
          ],
        });

        // Attach CodeMirror to element
        view.current = new EditorView({
          state,
          parent: parent.value,
        });
      });

      onUnmounted(() => {
        view?.destroy();
        leave.value?.();
      });
      </script>

      <template>
        <div ref="parent" />
      </template>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
CodeMirror code editor inside your Vue.js application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [CodeMirror website](https://codemirror.net)

---
meta:
  title: "Get started with Liveblocks, Monaco, Yjs, and JavaScript"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, Monaco, Yjs, and JavaScript."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your JavaScript application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Monaco</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs monaco-editor y-monaco
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create an HTML element</StepTitle>
    <StepContent>

      ```html
      <div id="editor"></div>
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Monaco code editor</StepTitle>
    <StepContent>

      ```js file="app.js"
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import * as monaco from "monaco-editor";
      import { MonacoBinding } from "y-monaco";

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const { room, leave } = client.enterRoom("my-room");

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();
      const yText = yDoc.getText("monaco");

      // Set up the Monaco editor
      const parent = document.querySelector("#editor");
      const editor = monaco.editor.create(parent, {
        value: "",
        language: "javascript"
      })

      // Attach Yjs to Monaco
      const monacoBinding = new MonacoBinding(
        yText,
        editorRef.getModel(),
        new Set([editor]),
        yProvider.awareness
      );
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Monaco code editor inside your JavaScript application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Monaco website](https://microsoft.github.io/monaco-editor/)

---
meta:
  title: "Get started with Liveblocks, Yjs, Monaco, and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Liveblocks, Yjs, Monaco, and React."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Monaco</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs @monaco-editor/react y-monaco y-protocols
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          // +++
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
          // +++
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { CollaborativeEditor } from "./CollaborativeEditor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <CollaborativeEditor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Monaco code editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Monaco and Yjs in the `Editor.tsx` file.
      To make the editor collaborative, we can rely on `MonacoBinding` from `y-monaco`.

      ```tsx file="CollaborativeEditor.tsx"
      "use client";

      import * as Y from "yjs";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import { useRoom } from "@/liveblocks.config";
      import { useCallback, useEffect, useState } from "react";
      import { Editor } from "@monaco-editor/react";
      import { editor } from "monaco-editor";
      import { MonacoBinding } from "y-monaco";
      import { Awareness } from "y-protocols/awareness";

      // Collaborative text editor with simple rich text, live cursors, and live avatars
      export function CollaborativeEditor() {
        const [editorRef, setEditorRef] = useState<editor.IStandaloneCodeEditor>();
        const room = useRoom();
        const yProvider = getYjsProviderForRoom(room);

        // Set up Liveblocks Yjs provider and attach Monaco editor
        useEffect(() => {
          let binding: MonacoBinding;

          if (editorRef) {
            const yDoc = yProvider.getYDoc();
            const yText = yDoc.getText("monaco");

            // Attach Yjs to Monaco
            binding = new MonacoBinding(
              yText,
              editorRef.getModel() as editor.ITextModel,
              new Set([editorRef]),
              yProvider.awareness as Awareness
            );
          }

          return () => {
            binding?.destroy();
          };
        }, [editorRef, room]);

        const handleOnMount = useCallback((e: editor.IStandaloneCodeEditor) => {
          setEditorRef(e);
        }, []);

        return (
          <Editor
            onMount={handleOnMount}
            height="100vh"
            width="100hw"
            theme="vs-light"
            defaultLanguage="typescript"
            defaultValue=""
            options={{
              tabSize: 2,
            }}
          />
        );
      }
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Monaco code editor inside your React application.

- [Yjs and Monaco guides](/docs/guides?technologies=yjs%2Cmonaco)
- [How to create a collaborative code editor with Monaco, Yjs, Next.js, and Liveblocks](/docs/guides/how-to-create-a-collaborative-code-editor-with-monaco-yjs-nextjs-and-liveblocks)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [Monaco website](https://microsoft.github.io/monaco-editor/)

---

## Examples using Monaco

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Code Editor",
      slug: "collaborative-code-editor/nextjs-yjs-monaco",
      image: "/images/examples/thumbnails/code-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Monaco, Yjs, and Svelte"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Monaco, Yjs, and Svelte."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Svelte application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Monaco</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs monaco-editor y-monaco
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Monaco code editor</StepTitle>
    <StepContent>

      ```html file="Editor.svelte"
      <script>
      import { onMount, onDestroy } from "svelte";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import * as monaco from "monaco-editor";
      import { MonacoBinding } from "y-monaco";

      let element;
      const roomId = "my-room";

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      onMount(() => {
        // Enter a multiplayer room
        const { room, leave } = client.enterRoom(roomId);

        // Set up Yjs document, shared text, and Liveblocks Yjs provider
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();
        const yText = yDoc.getText("monaco");

        // Set up the Monaco editor
        const editor = monaco.editor.create(element, {
          value: "",
          language: "javascript"
        })

        // Attach Yjs to Monaco
        const binding = new MonacoBinding(
          yText,
          editorRef.getModel(),
          new Set([editor]),
          yProvider.awareness
        );

        return () => {
          binding.destroy();
          editor.dispose();
          leave();
        };
      });

      </script>

      <div bind:this={element}></div>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Monaco code editor inside your Svelte application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Monaco website](https://microsoft.github.io/monaco-editor/)

---
meta:
  title: "Get started with Liveblocks, Monaco, Yjs, and Vue.js"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Monaco, Yjs, and Vue.js."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Vue.js application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Monaco</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs monaco-editor y-monaco
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Monaco code editor</StepTitle>
    <StepContent>

      ```html file="Editor.vue"
      <script setup>
      import { ref, onMounted, onUnmounted } from "vue";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import * as monaco from "monaco-editor";
      import { MonacoBinding } from "y-monaco";

      const element = ref(null);
      const editor = ref(null);
      const binding = ref(null);
      const leave = ref(null);

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const info = client.enterRoom("my-room");
      const room = info.room;
      leave.value = info.leave;

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();
      const yText = yDoc.getText("monaco");

      onMounted(() => {
        // Set up the Monaco editor
        editor.value = monaco.editor.create(element.value, {
          value: "",
          language: "javascript"
        })

        // Attach Yjs to Monaco
        binding.value = new MonacoBinding(
          yText,
          editorRef.getModel(),
          new Set([editor]),
          yProvider.awareness
        );
      });

      onUnmounted(() => {
        binding?.destroy();
        editor?.dispose();
        leave?.();
      });
      </script>

      <template>
        <div ref="element" />
      </template>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Monaco code editor inside your Vue.js application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Monaco website](https://microsoft.github.io/monaco-editor/)

---
meta:
  title: "Get started with Liveblocks, Quill, Yjs, and JavaScript"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, Quill, Yjs, and JavaScript."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your JavaScript application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Quill</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs quill quill-cursors y-quill
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create an HTML element</StepTitle>
    <StepContent>

      ```html
      <div id="editor"></div>
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Quill text editor</StepTitle>
    <StepContent>

      ```js file="app.js"
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import Quill from "quill";
      import { QuillBinding } from "y-quill";
      import QuillCursors from "quill-cursors";

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const { room, leave } = client.enterRoom("my-room");

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();
      const yText = yDoc.getText("quill");

      // Attach cursors plugin
      Quill.register("modules/cursors", QuillCursors);

      // Set up Quill editor and modules
      const parent = document.querySelector("#editor");
      const quill = new Quill(parent, {
        placeholder: "Start collaborating…",
        theme: "snow",
        modules: {
          cursors: true,
          toolbar: [
            [{ header: [1, 2, false] }],
            ["bold", "italic", "underline"],
            ["code-block"],
          ],
          history: {
            // Local undo shouldn’t undo changes made by other users
            userOnly: true,
          },
        },
      });

      // Attach Yjs to Quill
      const binding = new QuillBinding(yText, quill, provider.awareness);
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative Quill
text editor inside your JavaScript application.

- [Yjs and Quill guides](/docs/guides?technologies=yjs%2Cquill)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Quill website](https://quilljs.com)

---
meta:
  title: "Get started with Liveblocks, Yjs, Quill, and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Liveblocks, Yjs, Quill, and React."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Quill</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs quill quill-cursors react-quill y-quill
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <Editor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Quill text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Quill and Yjs in the `Editor.tsx` file.
      To make the editor collaborative, we can rely on `QuillBinding` and `QuillCursors`
      from `y-quill` and `quill-cursors`.

      ```tsx file="Editor.tsx"
      "use client";

      import Quill from "quill";
      import ReactQuill from "react-quill";
      import QuillCursors from "quill-cursors";
      import { QuillBinding } from "y-quill";
      import * as Y from "yjs";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import { useRoom } from "@/liveblocks.config";
      import { useCallback, useEffect, useRef, useState } from "react";

      Quill.register("modules/cursors", QuillCursors);

      // Collaborative text editor with simple rich text, live cursors, and live avatars
      export function CollaborativeEditor() {
        const room = useRoom();
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();
        const yText = yDoc.getText("quill");

        return <QuillEditor yText={yText} 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;
          let binding: QuillBinding;

          if (!reactQuillRef.current) {
            return;
          }

          quill = reactQuillRef.current.getEditor();
          binding = new QuillBinding(yText, quill, provider.awareness);
          return () => {
            binding?.destroy?.();
          };
        }, [yText, provider]);

        return (
          <ReactQuill
            placeholder="Start typing here…"
            ref={reactQuillRef}
            theme="snow"
            modules={{
              cursors: true,
              history: {
                // Local undo shouldn't undo changes from remote users
                userOnly: true,
              },
            }}
          />
        );
      }
      ```

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative Quill
text editor inside your React application.

- [Yjs and Quill guides](/docs/guides?technologies=yjs%2Cquill)
- [How to create a collaborative text editor with Quill, Yjs, Next.js, and Liveblocks](/docs/guides/how-to-create-a-collaborative-text-editor-with-quill-yjs-nextjs-and-liveblocks)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [Quill website](https://quilljs.com)

---

## Examples using Quill

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-yjs-quill",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Quill, Yjs, and Svelte"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Quill, Yjs, and Svelte."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Svelte application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Quill</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs quill quill-cursors y-quill
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Quill text editor</StepTitle>
    <StepContent>

      ```html file="Editor.svelte"
      <script>
      import { onMount, onDestroy } from "svelte";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import Quill from "quill";
      import { QuillBinding } from "y-quill";
      import QuillCursors from "quill-cursors";

      let element;

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      onMount(() => {
        // Enter a multiplayer room
        const { room, leave } = client.enterRoom("my-room");

        // Set up Yjs document, shared text, and Liveblocks Yjs provider
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();
        const yText = yDoc.getText("quill");

        // Attach cursors plugin
        Quill.register("modules/cursors", QuillCursors);

        // Set up Quill editor and modules
        const quill = new Quill(element, {
          placeholder: "Start collaborating…",
          theme: "snow",
          modules: {
            cursors: true,
            toolbar: [
              [{ header: [1, 2, false] }],
              ["bold", "italic", "underline"],
              ["code-block"],
            ],
            history: {
              // Local undo shouldn’t undo changes made by other users
              userOnly: true,
            },
          },
        });

        // Attach Yjs to Quill
        const binding = new QuillBinding(yText, quill, yProvider.awareness);

        return () => {
          binding.destroy();
          leave();
        };
      });
      </script>

      <div bind:this={element}></div>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative Quill
text editor inside your Svelte application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Quill website](https://quilljs.com)

---
meta:
  title: "Get started with Liveblocks, Quill, Yjs, and Vue.js"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Quill, Yjs, and Vue.js."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Vue.js application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Quill</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs quill quill-cursors y-quill
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Quill text editor</StepTitle>
    <StepContent>

      ```html file="Editor.vue"
      <script setup>
      import { ref, onMounted, onUnmounted } from "vue";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import Quill from "quill";
      import { QuillBinding } from "y-quill";
      import QuillCursors from "quill-cursors";

      const element = ref(null);
      const binding = ref(null);
      const leave = ref(null);

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const info = client.enterRoom("my-room");
      const room = info.room;
      leave.value = info.leave;

      // Set up Yjs document, shared text, and Liveblocks Yjs provider
      const yText = yDoc.getText("quill");
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();

      // Attach cursors plugin
      Quill.register("modules/cursors", QuillCursors);

      onMounted(() => {
        // Set up Quill editor and modules
        const quill = new Quill(element.value, {
          placeholder: "Start collaborating…",
          theme: "snow",
          modules: {
            cursors: true,
            toolbar: [
              [{ header: [1, 2, false] }],
              ["bold", "italic", "underline"],
              ["code-block"],
            ],
            history: {
              // Local undo shouldn’t undo changes made by other users
              userOnly: true,
            },
          },
        });

        // Attach Yjs to Quill
        binding.value = new QuillBinding(yText, quill, yProvider.awareness);
      });

      onUnmounted(() => {
        binding?.destroy?.();
        leave?.();
      });
      </script>

      <template>
        <div ref="element" />
      </template>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your Vue.js application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Tiptap website](https://tiptap.dev)

---
meta:
  title: "Get started with Liveblocks, Slate, Yjs, and React"
  parentTitle: "Get started"
  description:
    "Learn how to get started with Liveblocks, Slate, Yjs, and React."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your React application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Slate</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/react @liveblocks/yjs yjs slate slate-react @slate-yjs/core
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the Liveblocks client</StepTitle>
    <StepContent>

      Liveblocks uses the concept of rooms, separate virtual spaces where people
      collaborate, and to create a realtime experience, multiple users must
      be connected to the same room. Set up a Liveblocks client with [`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider), and join a room with [`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider).

      ```tsx file="App.tsx" highlight="11-15"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
      } from "@liveblocks/react/suspense";
      import { Editor } from "./Editor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              {/* ... */}
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      After setting up the room, you can add collaborative components inside it, using
      [`ClientSideSuspense`](/docs/api-reference/liveblocks-react#ClientSideSuspense) to add loading spinners to your app.

      ```tsx file="App.tsx" highlight="14-16"
      "use client";

      import {
        LiveblocksProvider,
        RoomProvider,
        ClientSideSuspense,
      } from "@liveblocks/react/suspense";
      import { CollaborativeEditor } from "./CollaborativeEditor";

      export default function App() {
        return (
          <LiveblocksProvider publicApiKey={"{{PUBLIC_KEY}}"}>
            <RoomProvider id="my-room">
              <ClientSideSuspense fallback={<div>Loading…</div>}>
                <CollaborativeEditor />
              </ClientSideSuspense>
            </RoomProvider>
          </LiveblocksProvider>
        );
      }
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Set up the collaborative Slate text editor</StepTitle>
    <StepContent>

      Now that we set up Liveblocks, we can start integrating Slate and Yjs in the `CollaborativeEditor.tsx` file.
      To make the editor collaborative, we can rely on `withYjs` from `@slate-yjs/core`.

      ```tsx file="CollaborativeEditor.tsx"
      "use client";

      import { getYjsProviderForRoom } 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 { useRoom } from "../liveblocks.config";
      import styles from "./CollaborativeEditor.module.css";

      export function CollaborativeEditor() {
        const room = useRoom();
        const [connected, setConnected] = useState(false);

        // Set up Yjs
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();
        const sharedType = yDoc.get("slate", Y.XmlText) as Y.XmlText;

        useEffect(() => {
          yProvider.on("sync", setConnected);

          return () => {
            yProvider?.off("sync", setConnected);
          };
        }, [room]);

        if (!connected || !sharedType) {
          return <div>Loading…</div>;
        }

        return <SlateEditor sharedType={sharedType} />;
      }

      const emptyNode = {
        children: [{ text: "" }],
      };

      function SlateEditor({ sharedType }: { sharedType: Y.XmlText }) {
        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;
        }, []);

        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.

      ```css file="CollaborativeEditor.module.css" isCollapsed isCollapsable
      .container {
        display: flex;
        flex-direction: column;
        position: relative;
        border-radius: 12px;
        background: #fff;
        width: 100%;
        height: 100%;
        color: #111827;
      }

      .editor {
        border-radius: inherit;
        flex-grow: 1;
        width: 100%;
        height: 100%;
      }

      .editor:focus {
        outline: none;
      }

      .editorContainer {
        position: relative;
        padding: 1em;
        height: 100%;
      }

      .editor p {
        margin: 1em 0;
      }
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication
      endpoint. This approach is great for prototyping and marketing pages
      where defining your own security isn’t always required. If you want to
      implement your own security logic to define if certain users should
      have access to a given room, you’ll need to implement an
      authentication endpoint.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>

</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative Slate
text editor inside your React application.

- [Yjs and Slate guides](/docs/guides?technologies=yjs%2Cslate)
- [How to create a collaborative text editor with Slate, Yjs, Next.js, and Liveblocks](/docs/guides/how-to-create-a-collaborative-text-editor-with-slate-yjs-nextjs-and-liveblocks)
- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [Slate website](https://docs.slatejs.org/)

---

## Examples using Slate

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor",
      slug: "collaborative-text-editor/nextjs-yjs-slate",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Get started with Liveblocks, Tiptap, Yjs, and JavaScript"
  parentTitle: "Get started"
  description:
    "Learn how to get started Liveblocks, Tiptap, Yjs, and JavaScript."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your JavaScript application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Tiptap</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor y-prosemirror
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create an HTML element</StepTitle>
    <StepContent>

      ```html
      <div id="editor"></div>
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Tiptap text editor</StepTitle>
    <StepContent>

      ```js file="app.js"
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import { Editor } from "@tiptap/core";
      import StarterKit from "@tiptap/starter-kit";
      import Collaboration from "@tiptap/extension-collaboration";
      import CollaborationCursor from "@tiptap/extension-collaboration-cursor";

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const { room, leave } = client.enterRoom("my-room");

      // Set up Yjs document and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();

      // Set up the Tiptap editor
      const element = document.querySelector("editor");
      const editor = new Editor({
        element,
        extensions: [
          StarterKit.configure({
            // The Collaboration extension comes with its own history handling
            history: false,
          }),
          // Register the Yjs document with Tiptap
          Collaboration.configure({
            document: yDoc,
          }),
          CollaborationCursor.configure({
            provider: yProvider,
          }),
        ],
      });
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your JavaScript application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Tiptap website](https://tiptap.dev)

---
meta:
  title: "Get started with Liveblocks, Tiptap, Yjs, and Svelte"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Tiptap, Yjs, and Svelte."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Svelte application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Tiptap</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor y-prosemirror
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Tiptap text editor</StepTitle>
    <StepContent>

      ```html file="Editor.svelte"
      <script>
      import { onMount, onDestroy } from "svelte";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import { Editor } from "@tiptap/core";
      import StarterKit from "@tiptap/starter-kit";
      import Collaboration from "@tiptap/extension-collaboration";
      import CollaborationCursor from "@tiptap/extension-collaboration-cursor";

      let element;

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      onMount(() => {
        // Enter a multiplayer room
        const { room, leave } = client.enterRoom("my-room");

        // Set up Yjs document and Liveblocks Yjs provider
        const yProvider = getYjsProviderForRoom(room);
        const yDoc = yProvider.getYDoc();

        // Set up the Tiptap editor
        editor = new Editor({
          element,
          extensions: [
            StarterKit.configure({
              // The Collaboration extension comes with its own history handling
              history: false,
            }),
            // Register the Yjs document with Tiptap
            Collaboration.configure({
              document: yDoc,
            }),
            CollaborationCursor.configure({
              provider: yProvider,
            }),
          ],
          onTransaction: () => {
            // Force re-render so `editor.isActive` works as expected
            editor = editor
          },
        });

        return () => {
          editor.destroy();
          leave();
        };
      });
      </script>

      <div bind:this={element}></div>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your Svelte application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Tiptap website](https://tiptap.dev)

---
meta:
  title: "Get started with Liveblocks, Tiptap, Yjs, and Vue.js"
  parentTitle: "Get started"
  description: "Learn how to get started Liveblocks, Tiptap, Yjs, and Vue.js."
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start adding
collaboration to your Vue.js application using the APIs from the
[`@liveblocks/yjs`](/docs/api-reference/liveblocks-yjs) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks, Yjs, and Tiptap</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/yjs yjs @tiptap/vue-3 @tiptap/pm @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor y-prosemirror
      ```
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-client#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework javascript
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your collaborative Tiptap text editor</StepTitle>
    <StepContent>

      ```html file="Editor.vue"
      <script setup>
      import { onUnmounted } from "vue";
      import { createClient } from "@liveblocks/client";
      import { getYjsProviderForRoom } from "@liveblocks/yjs";
      import * as Y from "yjs";
      import { useEditor, EditorContent } from "@tiptap/vue-3";
      import StarterKit from "@tiptap/starter-kit";
      import Collaboration from "@tiptap/extension-collaboration";
      import CollaborationCursor from "@tiptap/extension-collaboration-cursor";

      const leave = ref(null);

      // Set up Liveblocks client
      const client = createClient({
        publicApiKey: "{{PUBLIC_KEY}}",
      });

      // Enter a multiplayer room
      const info = client.enterRoom("my-room");
      const room = info.room;
      leave.value = info.leave;

      // Set up Yjs document and Liveblocks Yjs provider
      const yProvider = getYjsProviderForRoom(room);
      const yDoc = yProvider.getYDoc();

      // Set up the Tiptap editor
      const editor = useEditor({
        element,
        extensions: [
          StarterKit.configure({
            // The Collaboration extension comes with its own history handling
            history: false,
          }),
          // Register the Yjs document with Tiptap
          Collaboration.configure({
            document: yDoc,
          }),
          CollaborationCursor.configure({
            provider: yProvider,
          }),
        ],
      });

      onUnmounted(() => {
        leave?.();
      });
      </script>

      <template>
        <editor-content :editor="editor" />
      </template>
      ```
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation for your collaborative
Tiptap text editor inside your Vue.js application.

- [@liveblocks/yjs API Reference](/docs/api-reference/liveblocks-yjs)
- [@liveblocks/client API Reference](/docs/api-reference/liveblocks-client)
- [Tiptap website](https://tiptap.dev)

---
meta:
  title: "Get started with Liveblocks and Zustand"
  parentTitle: "Get started"
  description: "Learn how to get started with Liveblocks and Zustand"
---

Liveblocks is a realtime collaboration infrastructure for building performant
collaborative experiences. Follow the following steps to start making your
Zustand store multiplayer by using the middleware from the
[`@liveblocks/zustand`](/docs/api-reference/liveblocks-zustand) package.

## Quickstart

<Steps>
  <Step>
    <StepTitle>Install Liveblocks</StepTitle>
    <StepContent>

      Every Liveblocks package should use the same version.

      ```bash
      npm install @liveblocks/client @liveblocks/zustand
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Initialize the `liveblocks.config.ts` file</StepTitle>
    <StepContent>

      We can use this file later to [define types for our application](/docs/api-reference/liveblocks-react#Typing-your-data).

      ```bash
      npx create-liveblocks-app@latest --init --framework react
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Connect your Zustand store to Liveblocks</StepTitle>
    <StepContent>

      Create the Liveblocks client and use the `middleware` in your
      Zustand store setup. This will add a new state called{" "}
      `liveblocks` to your store, enabling you to interact with
      our Presence and Storage APIs.

      ```ts file="store.ts" highlight="12-14,17-22"
      "use client";

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

      const useStore = create<WithLiveblocks<State>>()(
        liveblocks(
          (set) => ({
            // Your state and actions will go here
          }),
          { client }
        )
      );

      export default useStore;
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Join a Liveblocks room</StepTitle>
    <StepContent>

      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.

      ```tsx file="App.tsx" highlight="13,15"
      "use client";

      import React, { useEffect } from "react";
      import useStore from "./store";
      import "./App.css";

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

        useEffect(() => {
          enterRoom("room-id");
          return () => {
            leaveRoom("room-id");
          };
        }, [enterRoom, leaveRoom]);

        return <Room />;
      };

      export default App;
      ```

    </StepContent>

  </Step>
  <Step>
    <StepTitle>Use the Liveblocks data from the store</StepTitle>
    <StepContent>

      Now that we’re connected to a room, we can start using the Liveblocks data from the Zustand store.

      ```tsx file="Room.tsx" highlight="6"
      "use client";

      import useStore from "./store";

      export function Room() {
        const others = useStore((state) => state.liveblocks.others);
        const userCount = others.length;
        return <div>There are {userCount} other user(s) online</div>;
      }
      ```

    </StepContent>

  </Step>
  <Step lastStep>
    <StepTitle>Next: set up authentication</StepTitle>
    <StepContent>
      By default, Liveblocks is configured to work without an authentication endpoint
      where everyone automatically has access to rooms. This approach is great for
      prototyping and marketing pages where setting up your own security isn’t always
      required. If you want to limit access to a room for certain users, you’ll need
      to set up an authentication endpoint to enable permissions.

      <Button asChild className="not-markdown">
        <a href="/docs/authentication">
          Set up authentication
        </a>
      </Button>
    </StepContent>

  </Step>
</Steps>

## What to read next

Congratulations! You now have set up the foundation to start building
collaborative experiences for your Zustand store.

- [@liveblocks/zustand API Reference](/docs/api-reference/liveblocks-zustand)
- [Zustand guides](/docs/guides?technologies=zustand)
- [How to use Liveblocks Presence with Zustand](/docs/guides/how-to-create-a-collaborative-to-do-list-with-react-zustand-and-liveblocks)
- [How to use Liveblocks Storage with Zustand](/docs/guides/how-to-use-liveblocks-storage-with-zustand)

---

## Examples using Zustand

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative To-do List",
      slug: "collaborative-todo-list/zustand-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard/zustand-whiteboard",
      image: "/images/examples/thumbnails/collaborative-whiteboard.jpg",
      advanced: true,
    }}
    technologies={["nextjs", "redux", "zustand"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Flowchart",
      slug: "collaborative-flowchart/zustand-flowchart",
      image: "/images/examples/thumbnails/collaborative-flowchart.jpg",
      advanced: true,
    }}
    technologies={["zustand"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Documentation"
  description:
    "Explore the documentation to learn how to build realtime collaborative
    experiences with Liveblocks."
showTitle: false
---

<DocsHomepageHero
  title="Documentation"
  description="Liveblocks is the platform for adding collaborative editing, comments, and notifications into your application."
  actions={[
    {
      title: "Get started",
      href: "/docs/get-started",
      appearance: "primary",
    },
    {
      title: "Browse examples",
      href: "/examples",
    },
  ]}
/>

<DocsHomepageGrid />

## API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="React UI"
    href="/docs/api-reference/liveblocks-react-ui"
    description="@liveblocks/react-ui"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="React Lexical"
    href="/docs/api-reference/liveblocks-react-lexical"
    description="@liveblocks/react-lexical"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Node Lexical"
    href="/docs/api-reference/liveblocks-node-lexical"
    description="@liveblocks/node-lexical"
    visual={<DocsNodejsIcon />}
  />
  <DocsCard
    type="technology"
    title="Redux"
    href="/docs/api-reference/liveblocks-redux"
    description="@liveblocks/redux"
    visual={<DocsReduxIcon />}
  />
  <DocsCard
    type="technology"
    title="Zustand"
    href="/docs/api-reference/liveblocks-zustand"
    description="@liveblocks/zustand"
    visual={
      <img
        alt=""
        src="/assets/zustand.png"
        width={24}
        height={24}
        loading="lazy"
      />
    }
  />
  <DocsCard
    type="technology"
    title="Yjs"
    href="/docs/api-reference/liveblocks-yjs"
    description="@liveblocks/yjs"
    visual={<DocsYjsIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Node.js"
    href="/docs/api-reference/liveblocks-node"
    description="@liveblocks/node"
    visual={<DocsNodejsIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors",
      image: "/images/examples/thumbnails/live-cursors.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard-advanced",
      image:
        "/images/examples/thumbnails/collaborative-whiteboard-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

## Community

<ListGrid columns={3}>
  <DocsCard
    title="X"
    href="https://x.com/liveblocks"
    description="Follow us on X for the latest news and updates."
    visual={<DocsXIcon />}
    openInNewWindow
  />
  <DocsCard
    title="Discord"
    href="https://liveblocks.io/discord"
    description="Join hundreds of developers building with Liveblocks."
    visual={<DocsDiscordIcon />}
    openInNewWindow
  />
  <DocsCard
    title="GitHub"
    href="https://github.com/liveblocks/liveblocks"
    description="Follow progress and contribute to the codebase."
    visual={<DocsGithubIcon />}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Account management"
  parentTitle: "Platform"
  description: "Learn how to manage your Liveblocks account and team members."
---

In this section, you’ll learn everything you need to manage your Liveblocks
accounts and teams.

- [Create an account](/docs/platform/account-management/create-an-account)
- [Manage team members](/docs/platform/account-management/manage-team-members)

---
meta:
  title: "Create an account"
  parentTitle: "Platform"
  description: "Learn how to create a Liveblocks account."
---

When you create a new account with Liveblocks, you’re automatically creating a
team account on a Starter plan. This plan is free to use (subject to the
[Fair Use Policy](/docs/platform/limits/fair-use-policy)) forever. You cannot
invite others to collaborate on your Liveblocks team account until you upgrade
to a paid plan.

To create a new account, visit [liveblocks.io/signup](/api/auth/signup). You can
choose to sign up with your email address, or with a GitHub or Google provider.

<Figure>
  <Image
    src="/assets/account-management/sign-up.png"
    alt="Create a Liveblocks account"
    width={768}
    height={406}
  />
</Figure>

### Sign up with email

If you choose to sign up with your email address, you’ll be prompted to enter it
in a form. After signing up, you can then verify your new account by clicking a
link in an email Liveblocks sends you. In future, when signing in with your
email, you’ll be asked to verify your account every time you log in.

### Sign up with a provider

If you choose to sign up with Google or GitHub provider, you will be asked to
authorize Liveblocks to access your provider account. This connection will then
become the default login connection on your account.

---
meta:
  title: "Manage team members"
  parentTitle: "Platform"
  description: "Learn how to manage team members on your Liveblocks account."
---

Teams are made up of members, and each member can be assigned a role. These
roles define what you can and cannot do within a team on Liveblocks.

As your project scales, and you add more team members, you can assign each
member a role to ensure that they have the right permissions to work on your
projects.

## Inviting team members

To invite new members to your team, select the team from the scope selector,
then open the **Settings** tab and navigate to **Members**.

<Figure>
  <Image
    src="/assets/account-management/team-members.png"
    alt="Liveblocks team members"
    width={768}
    height={406}
  />
</Figure>

Enter the email address of the person you’d like to add, select their role, and
press the **Invite** button.

<Figure>
  <Image
    src="/assets/account-management/team-members-invite-dialog.png"
    alt="Invite team member to Liveblocks"
    width={768}
    height={406}
  />
</Figure>

## Access roles

Liveblocks offers two types of roles for team members, each providing different
levels of access and permissions.

### Owner role

As a team owner, you have full administrative control over your team. This
includes the ability to manage all aspects of account & project settings,
security, and billing.

Team owners can manage API keys in all projects and also change the roles of
other team members, including promoting members to owners. However, the only way
an owner can renounce their role is by either choosing to leave, or by deleting
the team altogether.

Teams can have more than one owner. For continuity, we recommend that at least
two individuals have owner permissions. Additional owners can be added without
any impact on existing ownership. Keep in mind that role changes, including
assignment and revocation of team member roles, are an exclusive capability of
those with the owner role.

### Member role

Those with the member role have the ability to create and manage projects. They
are also granted permissions to manage API keys for all projects.

However, there are certain team-level settings that are off-limits to members.
These include editing team settings, such as billing information, and the
ability to invite new users to the team. This restriction is in place to
maintain the division of responsibilities and control between members and
owners.

---
meta:
  title: "Analytics"
  parentTitle: "Platform"
  description:
    "With analytics, you’re able to gather insights into collaborative
    experiences for a given project with metrics like daily active users,
    monthly active users, connections, active rooms, and more."
---

With analytics, you’re able to gather insights into collaborative experiences
for a given project with metrics such as daily active users, monthly active
users, connections, active rooms, and more.

<Figure>
  <Image
    src="/assets/analytics/analytics.png"
    alt="Liveblocks analytics"
    width={768}
    height={406}
  />
</Figure>

You can adjust the period through the timeframe selector by picking between 1
hour, 1 day, 1 week, and 1 month.

<Figure>
  <Image
    src="/assets/analytics/analytics-timeframe.png"
    alt="Liveblocks analytics timeframe selector"
    width={768}
    height={406}
  />
</Figure>

---
meta:
  title: "Limits"
  parentTitle: "Platform"
  description:
    "A list of all the limits and limitations that apply on Liveblocks."
---

## General limits

To prevent abuse of our platform, we apply the following limits to all accounts.

|                                      | Starter                                          | Pro                                          | Enterprise |
| ------------------------------------ | ------------------------------------------------ | -------------------------------------------- | ---------- |
| Monthly active users                 | <Limits.StarterMauIncluded />                    | <Limits.ProMauIncluded />                    | Custom     |
| Projects                             | <Limits.StarterMaxProjects />                    | <Limits.ProMaxProjects />                    | Unlimited  |
| Average connections per MAU          | Up to <Limits.StarterAvgConnectionsPerMau />     | Up to <Limits.ProAvgConnectionsPerMau />     | Custom     |
| Maximum data stored size per room    | Up to <Limits.StarterMaxStorageSizePerRoom />    | Up to <Limits.ProMaxStorageSizePerRoom />    | Custom     |
| Simultaneous connections per room    | Up to <Limits.StarterMaxConnectionsPerRoom />    | Up to <Limits.ProMaxConnectionsPerRoom />    | Custom     |
| Simultaneous connections per project | Up to <Limits.StarterMaxConnectionsPerProject /> | Up to <Limits.ProMaxConnectionsPerProject /> | Custom     |
| Team members per account             | <Limits.StarterTeamMembersPerAccount />          | <Limits.ProTeamMembersPerAccount />          | Custom     |
| Monthly public key connections       | <Limits.StarterMaxAnonymousConnections />        | <Limits.ProMaxAnonymousConnections />        | Custom     |

#### Comments

{/* prettier-ignore */}
Comments is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxComments /> comments per month. You can get higher limits for an additional <Limits.ProStartingPriceComments />.

| Comments             | Included                      | Paid add-on               |
| -------------------- | ----------------------------- | ------------------------- |
| Monthly active users | <Limits.StarterMauMax />      | <Limits.ProMauIncluded /> |
| Monthly comments     | <Limits.StarterMaxComments /> | <Limits.ProMaxComments /> |

#### Notifications

{/* prettier-ignore */}
Notifications is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxNotifications /> notifications per month. You can get higher limits for an additional <Limits.ProStartingPriceNotifications />.

| Notifications         | Included                           | Paid add-on                    |
| --------------------- | ---------------------------------- | ------------------------------ |
| Monthly active users  | <Limits.StarterMauMax />           | <Limits.ProMauIncluded />      |
| Monthly notifications | <Limits.StarterMaxNotifications /> | <Limits.ProMaxNotifications /> |

#### Text editor

{/* prettier-ignore */}
Text editor is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalTextEditorStored /> data stored. You can get higher limits for an additional <Limits.ProStartingPriceTextEditor />.

| Text editor          | Included                                | Paid add-on                         |
| -------------------- | --------------------------------------- | ----------------------------------- |
| Monthly active users | <Limits.StarterMauMax />                | <Limits.ProMauIncluded />           |
| Total GB stored      | <Limits.StarterTotalTextEditorStored /> | <Limits.ProTotalTextEditorStored /> |

#### Sync Datastore

{/* prettier-ignore */}
Sync Datastore is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalCustomAppStored /> data stored. You can get higher limits for an additional <Limits.ProStartingPriceCustomApp />.

| Sync Datastore       | Included                               | Paid add-on                        |
| -------------------- | -------------------------------------- | ---------------------------------- |
| Monthly active users | <Limits.StarterMauMax />               | <Limits.ProMauIncluded />          |
| Total GB stored      | <Limits.StarterTotalCustomAppStored /> | <Limits.ProTotalCustomAppStored /> |

### Monthly active users

Learn more about how monthly active users are calculated for each plan on our
[plans page](/docs/platform/plans).

### Simultaneous connections per room

Learn more about handling simultaneous room connection limits in our guide about
[joining rooms at maximum capacity](/docs/guides/what-happens-when-a-user-joins-a-room-at-maximum-capacity).

## Other limits

### `roomId` limit

A `roomId` cannot exceed 128 characters.

### `userId` limit

A `userId` cannot exceed 128 characters.

### `userInfo` limit

`userInfo` sent from the authentication endpoint cannot exceed 1024 characters
once serialized to JSON.

### Broadcast event limit

Broadcast event messages have a limit of 1 MB.

### Liveblocks Storage limits

- A `LiveObject` cannot exceed 128 kB when totalling the size of the keys and
  values.
- A `LiveMap` can be any size, so long as each individual value does not exceed
  128kB.
- A `LiveList` can be any size, so long as each individual value does not exceed
  128kB.

Note that when one realtime data structure is nested inside another, it does not
count towards the limit. Only the JSON leaves of your data structure count
towards the limit. For example, if a `LiveList` is nested inside a `LiveObject`,
the `LiveList` and its contents do not count towards the `LiveObject`’s data
limit.

---
meta:
  title: "Fair Use Policy"
  parentTitle: "Limits"
  description: "Fair Use Policy for all Liveblocks plans."
---

All Liveblocks subscription plans are subject to this Fair Use Policy.

## Usage guidelines

We have established guidelines for our community’s usage of our plans. Most
users should fall within the specified ranges, however, if usage is excessive,
we will notify you and work to address the issue. Our aim is to be accommodating
while maintaining the stability of our infrastructure.

### Typical usage guidelines

|                                      | Starter                                          | Pro                                          | Enterprise |
| ------------------------------------ | ------------------------------------------------ | -------------------------------------------- | ---------- |
| Monthly active users                 | <Limits.StarterMauIncluded />                    | <Limits.ProMauIncluded />                    | Custom     |
| Projects                             | <Limits.StarterMaxProjects />                    | <Limits.ProMaxProjects />                    | Unlimited  |
| Average connections per MAU          | Up to <Limits.StarterAvgConnectionsPerMau />     | Up to <Limits.ProAvgConnectionsPerMau />     | Custom     |
| Maximum data stored size per room    | Up to <Limits.StarterMaxStorageSizePerRoom />    | Up to <Limits.ProMaxStorageSizePerRoom />    | Custom     |
| Simultaneous connections per room    | Up to <Limits.StarterMaxConnectionsPerRoom />    | Up to <Limits.ProMaxConnectionsPerRoom />    | Custom     |
| Simultaneous connections per project | Up to <Limits.StarterMaxConnectionsPerProject /> | Up to <Limits.ProMaxConnectionsPerProject /> | Custom     |
| Team members per account             | <Limits.StarterTeamMembersPerAccount />          | <Limits.ProTeamMembersPerAccount />          | Custom     |
| Monthly public key connections       | <Limits.StarterMaxAnonymousConnections />        | <Limits.ProMaxAnonymousConnections />        | Custom     |

To learn more about how monthly active users are calculated for each plan, take
a look at the [plans](/docs/platform/plans) docs.

### Other guidelines

The `userId` must be used to represent a single user.

### Commercial usage

**Starter accounts** are restricted to non-commercial use only. All commercial
usage of the platform requires either a Pro or Enterprise plan.

Commercial usage refers to any usage of the Liveblocks platform in projects
where financial gain is being sought by any party involved in the production,
including paid employees or consultants.

### General limits

[Take a look at our limits guide](/docs/platform/limits) to learn more about the
limits we apply to all accounts.

### Learn more

For further information regarding this policy and acceptable use of our
Services, please refer to our [Terms of Service](/terms) or your Enterprise
Service Agreement.

---
meta:
  title: "Plans"
  parentTitle: "Platform"
  description: "Learn about the different plans available on Liveblocks."
---

Liveblocks offers three plans: Starter, Pro, and Enterprise. The Starter plan is
free and includes all the features you need to get started, while the Pro and
Enterprise plans offer higher limits, enhanced features and resources.

## Starter plan

The Starter plan is **free** and designed for developers getting started with
Liveblocks. Key features include:

- Up to <Limits.StarterMauMax /> monthly active users
- Up to <Limits.StarterMaxConnectionsPerRoom /> simultaneous connections per
  room
- Pre-built components
- Realtime infrastructure
- <Limits.StarterTeamMembersPerAccount /> team members per account
- Community support

{/* This file is ignoring prettier at some points because it's splitting paragraphs in two */}

#### Comments

{/* prettier-ignore */}
Comments is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxComments /> comments per month.

| Comments             | Included                      |
| -------------------- | ----------------------------- |
| Monthly active users | <Limits.StarterMauMax />      |
| MAU overage rate     | —                             |
| Monthly comments     | <Limits.StarterMaxComments /> |

#### Notifications

{/* prettier-ignore */}
Notifications is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxNotifications /> comments per month.

| Notifications         | Included                           |
| --------------------- | ---------------------------------- |
| Monthly active users  | <Limits.StarterMauMax />           |
| MAU overage rate      | —                                  |
| Monthly notifications | <Limits.StarterMaxNotifications /> |

#### Text Editor

{/* prettier-ignore */}
Text Editor is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalTextEditorStored /> data stored.

| Text Editor          | Included                                |
| -------------------- | --------------------------------------- |
| Monthly active users | <Limits.StarterMauMax />                |
| MAU overage rate     | —                                       |
| Total GB stored      | <Limits.StarterTotalTextEditorStored /> |

#### Sync Datastore

{/* prettier-ignore */}
Sync Datastore is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalCustomAppStored /> data stored.

| Sync Datastore       | Included                               |
| -------------------- | -------------------------------------- |
| Monthly active users | <Limits.StarterMauMax />               |
| MAU overage rate     | —                                      |
| Total GB stored      | <Limits.StarterTotalCustomAppStored /> |

## Pro plan

The Pro plan starts at **<Limits.ProStartingPrice />** and is designed for
companies adding collaboration in production. Key features include:

- Up to <Limits.ProMauIncluded /> monthly active users
- Up to <Limits.ProMaxConnectionsPerRoom /> simultaneous connections per room
- <Limits.ProTeamMembersPerAccount /> team members per account
- More simultaneous connections
- Products priced separately
- Email support

#### Comments

{/* prettier-ignore */}
Comments is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxComments /> comments per month. You can get higher limits with a paid add-on.

| Comments             | Included                      | Paid add-on               |
| -------------------- | ----------------------------- | ------------------------- |
| Monthly active users | <Limits.StarterMauMax />      | <Limits.ProMauIncluded /> |
| Monthly comments     | <Limits.StarterMaxComments /> | <Limits.ProMaxComments /> |

#### Notifications

{/* prettier-ignore */}
Notifications is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterMaxNotifications /> notifications per month. You can get higher limits with a paid add-on.

| Notifications         | Included                           | Paid add-on                    |
| --------------------- | ---------------------------------- | ------------------------------ |
| Monthly active users  | <Limits.StarterMauMax />           | <Limits.ProMauIncluded />      |
| Monthly notifications | <Limits.StarterMaxNotifications /> | <Limits.ProMaxNotifications /> |

#### Text Editor

{/* prettier-ignore */}
Text Editor is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalTextEditorStored /> data stored. You can get higher limits with a paid add-on.

| Text Editor          | Included                                | Paid add-on                         |
| -------------------- | --------------------------------------- | ----------------------------------- |
| Monthly active users | <Limits.StarterMauMax />                | <Limits.ProMauIncluded />           |
| Total GB stored      | <Limits.StarterTotalTextEditorStored /> | <Limits.ProTotalTextEditorStored /> |

#### Sync Datastore

{/* prettier-ignore */}
Sync Datastore is free up to <Limits.StarterMauMax /> monthly active users and <Limits.StarterTotalCustomAppStored /> data stored. You can get higher limits with a paid add-on.

| Sync Datastore       | Included                               | Paid add-on                        |
| -------------------- | -------------------------------------- | ---------------------------------- |
| Monthly active users | <Limits.StarterMauMax />               | <Limits.ProMauIncluded />          |
| Total GB stored      | <Limits.StarterTotalCustomAppStored /> | <Limits.ProTotalCustomAppStored /> |

## Enterprise plan

The Enterprise plan is tailored for organizations with custom needs and advanced
security. Key features include:

- Up to 100M monthly active users
- Tiered usage pricing
- 99.9% Uptime SLA
- SOC 2 Type 2 report
- HIPAA compliance with BAA
- Support Slack
- Implementation support
- Dedicated Slack support

#### Comments

Comments can be included in the enterprise plan.

| Comments             |        |
| -------------------- | ------ |
| Monthly active users | Custom |
| Monthly comments     | Custom |

#### Notifications

Notifications can be included in the enterprise plan.

| Notifications         |        |
| --------------------- | ------ |
| Monthly active users  | Custom |
| Monthly notifications | Custom |

#### Text Editor

Text Editor can be included in the enterprise plan.

| Text Editor          |        |
| -------------------- | ------ |
| Monthly active users | Custom |
| Total GB stored      | Custom |

#### Sync Datastore

Sync Datastore can be included in the enterprise plan.

| Sync Datastore       |        |
| -------------------- | ------ |
| Monthly active users | Custom |
| Total GB stored      | Custom |

## General billing information

### What is a monthly active user (MAU)?

Monthly active users (MAU) represents the number of users that have used one or
more Liveblocks features within a given month.

Users are identified by the `userId` property provided in your
[authentication endpoint](/docs/authentication).

This `userId` generally comes from your database or your authentication
provider. One unique `userId` corresponds to one user, whether they connected to
a room 1 day for 5 minutes or kept coming back every day for 8 hours.

One user will be counted as one monthly active user, no matter how frequently
they connect to Liveblocks rooms in any given month as long as it falls under
our [Fair Use Policy](/docs/platform/limits/fair-use-policy).

<Banner>
  You must use the 1.0 or newer Liveblocks packages to have monthly active users
  counted appropriately. We will count each connection as one MAU if you do not
  update your packages to 1.0. See the [upgrade
  guide](/docs/platform/upgrading/1.0) for more information.
</Banner>

### How is data storage calculated?

Storage for Text Editor and Sync Datastore is a cumulative calculation that
represents all data that is currently stored. It does not reset monthly, and the
total usage will continue to accrue over time as you add more content and data.
You can monitor your usage at any time in the [dashboard](/dashboard).

### Do you count monthly active users during testing?

If you connect to rooms and call the Liveblocks API during any automated
testing, you may want to provide a static `userId` to avoid hitting limits.

For example, you could do this by setting an environment variable and checking
the process when you call `authorize` from `@liveblocks/node`.

```dotenv file=".env.test"
 TEST_USERID="machine"
```

```ts file="liveblocks.config.ts"
export default async function auth(req, res) {
  const room = req.body.room;
  const response = await authorize({
    room,
    secret,
    userId:
      process.env.NODE_ENV === "test" ? process.env.TEST_USERID : "user123",
  });
  return res.status(response.status).end(response.body);
}
```

---
meta:
  title: "Projects"
  parentTitle: "Platform"
  description:
    "To use Liveblocks, you need to create a project, a place to group your
    collaborative rooms. Learn how to set up and configure projects in this
    guide."
---

To use Liveblocks, you need to create a project, a place to group your
collaborative rooms. Learn how to set up and configure projects in this guide.

## Creating a project

You can create a new project from the [Liveblocks dashboard](/dashboard) by
clicking on the **Create project…** button.

<Figure>
  <Image
    src="/assets/projects/create-project.jpg"
    alt="Start creating a project from the Liveblocks dashboard"
    width={768}
    height={209}
  />
</Figure>

### Project environment

A project’s environment can either be set to **Development** or **Production**,
helping you map projects to your deployment model. We recommend setting up a new
project for each different environment your collaborative application uses.

<Figure>
  <Image
    src="/assets/projects/create-project-dialog.jpg"
    alt="Creating a project from the Liveblocks dashboard"
    width={768}
    height={499}
  />
</Figure>

Secret [API keys](#project-api-keys) are treated slightly differently depending
on the environment:

- **Development** environments allow you to read your secret key any time after
  generation. It’s recommended to use this setting in development, preview, and
  staging environments.
- **Production** environments encrypt your secret key, meaning it can only be
  read when it’s first generated. If you forget your secret key, you must roll a
  new one. It’s recommended to use this environment in your production
  application.

<Banner>

A project’s environment cannot be changed later.

</Banner>

## Managing a project

Each Liveblocks project has a separate dashboard to monitor usage, configure
settings, manage API keys, and more.

### Project overview

The **Overview** tab displays an overview of your project usage, providing
information on active rooms, users, and connections.

<Figure>
  <Image
    src="/assets/projects/project-overview.jpg"
    alt="Liveblocks project overview"
    width={768}
    height={499}
  />
</Figure>

### Project rooms

The **Rooms** tab displays all the rooms in your project. Use the search bar
next to the page title to find rooms. By default, rooms are sorted by the last
connection date (most recently active rooms). You can also sort them by room ID,
number of threads, document size, or creation date by clicking on the column
labels.

<Figure>
  <Image
    src="/assets/projects/project-rooms.jpg"
    alt="Liveblocks project rooms"
    width={768}
    height={499}
  />
</Figure>

You can learn more about any given by room by clicking on it. On the room detail
view, you’re able to view the stored document’s data, and common actions you can
take on that such as [attaching a schema](/docs/platform/schema-validation) or
deleting the document’s data altogether.

<Figure>
  <Image
    src="/assets/projects/project-rooms-detail.jpg"
    alt="Liveblocks project rooms detail"
    width={768}
    height={499}
  />
</Figure>

### Project API keys [#project-api-keys]

The **API keys** tab enables you to manage, view, and roll your **public** and
**secret** API keys.

<Figure>
  <Image
    src="/assets/projects/project-api-keys.jpg"
    alt="Liveblocks project API keys"
    width={768}
    height={499}
  />
</Figure>

### Project schemas

The **Schemas** tab enables you to manage your document’s schemas. Schemas can
be attached to any room’s Storage document to validate incoming changes and
ensure data integrity and facilitate future potential data migrations for your
application. See our [schema validation](/docs/platform/schema-validation) docs
to learn more.

### Project webhooks

The **Webhooks** tab enables you to configure your webhook endpoints allowing
you to respond to Liveblocks events, such as a user entering a room, or storage
being updated. See our [webhooks](/docs/platform/webhooks) docs to learn more.

### Project settings

The **Settings** tab enables you to rename and delete your project.

---
meta:
  title: "Liveblocks REST API"
  parentTitle: "Platform"
  description:
    "Liveblocks REST API allows developers to interact programmatically with
    their Liveblocks account and services using HTTP requests. With the API,
    developers can retrieve, set, and update room-related data, permissions,
    schemas, and more."
---

Liveblocks REST API allows developers to interact programmatically with their
Liveblocks account and services using HTTP requests. With the API, developers
can retrieve, set, and update room-related data, users, permissions, schemas,
and more.

The Liveblocks API is organized around REST. The API has predictable
resource-oriented URLs, accepts form-encoded request bodies, returns
JSON-encoded responses, and uses standard HTTP response codes, authentication,
and verbs. See the [API reference](api-reference/rest-api-endpoints) for more
information.

```
https://api.liveblocks.io/v2
```

---
meta:
  title: "Schema validation"
  parentTitle: "Platform"
  description:
    "Learn how to use schemas to ensure data integrity in your application"
---

## Why schema validation?

Schema validation is essential for future-proofing your application and ensuring
that implementing new features or data structures into your app will keep the
integration you have established with Liveblocks.

We currently mitigate the risk of introducing client-side errors by allowing you
to type your storage in `liveblocks.config.ts`. Still, we want to go one step
further to help you protect your application by attaching a schema to a room
that rejects invalid modifications.

By using schema validation, you will be able to:

- Trust any incoming storage modifications
- Paired with webhooks, strengthen your database synchronization
- Write migration scripts for your room storage more easily

## How schema validation works

The primary purpose of schema validation is to prevent corrupted data from being
loaded from the server. To add schema validation to your application, take the
following steps:

1. Define the shape of your storage with a schema definition (similar to how you
   would describe the storage type in TypeScript)
2. Attach your schema to a room

By default, a room storage accepts any modifications coming from the client. But
once you attach a schema to a room, Liveblocks will reject any modifications to
the storage that do not match the schema you provided. Situations like this
should only happen in development mode, and the developer is responsible for
fixing them.

## Schema actions

You can interact with the schemas you create through the dashboard or by calling
the [REST API](/docs/api-reference/rest-api-endpoints). In this guide, we will
cover the following operations:

- [Creating a schema](#creating-a-schema)
- [Deleting a schema](#deleting-a-schema)
- [Attaching a schema to a room](#attaching-a-schema-to-a-room)
- [Detaching a schema from a room](#detaching-a-schema-from-a-room)

You can also use the REST API to
[list schemas](/docs/api-reference/rest-api-endpoints#list-schemas),
[get a schema](/docs/api-reference/rest-api-endpoints#get-schema), and
[update a schema](/docs/api-reference/rest-api-endpoints#update-schema).

### Creating a schema

Creating a schema via the dashboard is straightforward. Simply navigate to the
“Schemas” page in the project you want to add the schema, and click on the
“Create schema” button. Provide a name and a definition that describes the shape
of the data you want to store in your rooms.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/schema-validation/create-schema-dashboard.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

Another way to create a schema is via the
[create schema API](/docs/api-reference/rest-api-endpoints#post-create-new-schema).
A schema body is a multi-line string using the Liveblocks
[schema syntax](/docs/platform/schema-validation/syntax). In the dashboard, a
sample schema could be represented as:

```ts
type Storage {
  todos: LiveList<LiveObject<Todo>>
}

type Todo {
  text: string
  checked?: boolean
}
```

To create a schema, provide the name and body in the JSON payload. Example:

```ts
fetch("https://api.liveblocks.io/v2/schemas", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "todo-list",
    body: `
      type Storage {
        todos: LiveList<LiveObject<Todo>>
      }

      type Todo {
        text: string
        checked?: boolean
      }
    `,
  }),
});
```

Note that in this example, the outermost `body` field is the body of the HTTP
request (required by the `fetch` API), whereas the innermost `body` field is
consumed by our API to read the schema text.

<Banner title="Schema syntax">

Learn more about our [schema syntax](/docs/platform/schema-validation/syntax)
and what kind of validations are currently supported.

</Banner>

### Deleting a schema

In the dashboard, you can delete a schema by navigating to the schema in
question and clicking on the trash icon next to the schema version you want to
delete. If you have attached a schema to a room, you will need to detach the
schema from the room before you can delete it. If this schema is frozen, the
trash icon will be greyed out.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/schema-validation/delete-schema.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

If your schema is in a detached state, you can also delete it by using the
[delete schema API](/docs/api-reference/rest-api-endpoints#delete-a-schema).

```ts
fetch("https://api.liveblocks.io/v2/schemas/{id}", {
  method: "DELETE",
});
```

### Attaching a schema to a room

You can attach a schema to a room via the dashboard by navigating to the room in
question and clicking on the “Attach schema” button.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/schema-validation/attach-schema.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

Alternatively, you can use the
[attach schema API](/docs/api-reference/rest-api-endpoints#post-attach-schema-to-room).
For example:

```ts
fetch("https://api.liveblocks.io/v2/rooms/{roomId}/schema", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    schema: "todo-list@1",
  }),
});
```

<Banner title="Prerequisites for attaching a schema">
To attach a schema to a room, you must first create a room and initialize storage.

</Banner>

### Detaching a schema from a room

You can use the dashboard to remove a schema from a room by navigating to the
room in question and clicking on the dropdown menu which displays the currently
attached schema. From there, you can click on the “Detach schema” button.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/schema-validation/detach-schema.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

To detach a schema from a room using the
[detach schema API](/docs/api-reference/rest-api-endpoints#delete-detach-schema-to-room),
use the following code:

```ts
fetch("https://api.liveblocks.io/v2/rooms/{roomId}/schema", {
  method: "DELETE",
});
```

## The validation process in practice

If you would like to work through an example, you can follow along by using the
[Collaborative To-Do List](/examples/collaborative-todo-list/nextjs-todo-list).

Let’s create a new schema called `todo-list` in your dashboard, with the
following definition:

```ts
type Storage {
  todos: LiveList<LiveObject<Todo>>
}

type Todo {
  text: string
  checked?: boolean
}
```

Schemas are automatically versioned to facilitate migrations. By saving the new
schema, we have created the first version, named `todo-list@1`.

To attach the schema we just created to a room, you can:

- Navigate to the "next-js-todo-list-v2" room and click on "Attach Schema", as
  shown in the video above
- Call the following endpoint:

```ts
POST https://api.liveblocks.io/v2/rooms/nextjs-todo-list-v2/schema
{
  "schema": "todo-list@1"
}
```

To demonstrate the importance of schema validation and how unsafe operations
will now fail, we will change the `checked` field in our schema as required,
which means that new items added to the list will have to be checked by default.

The new schema definition will look like this:

```ts
type Storage {
  todos: LiveList<LiveObject<Todo>>
}

type Todo {
  text: string
  checked: boolean
}
```

After updating the schema, and attaching the new version to our room, we can now
run our app locally by calling `npm run dev` and adding a new item to the list.
The new item will cause the following error to be thrown:

```
Error: Storage mutations rejected by server: Missing required property 'checked' on type 'LiveList<LiveObject<Todo>>'.
```

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/schema-validation/reject-schema.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

Other examples where schema validation would catch the error include:

- Attempting to update the value of the `checked` variable to a number, as it is
  defined as a boolean in the schema
- Attempting to delete the `checked` variable: it was not defined as optional in
  the schema

## How to handle validation errors

When a schema validation error occurs, the LiveBlocks server will reject the
operation

When an instance like this occurs, it’s indicative of a bug in your app. In
production, an error like this should never occur. This is because you should
address validation errors in the same way you address TypeScript errors. You
don't ship to production when your app has TypeScript errors, and neither do you
ship to prod when there are schema validation errors. Validation errors are the
responsibility of the developer to resolve.

---
meta:
  title: "Schema syntax"
  parentTitle: "Schema validation"
  description: "Liveblocks schema syntax"
---

This document describes the language rules for writing your own Liveblocks
schemas. It is an exhaustive account of all features that are implemented and
supported as part of the the public beta and is
[open source](https://github.com/liveblocks/liveblocks/tree/main/schema-lang).

We support: scalars, arrays, objects, optionals, `LiveObject`, `LiveList`,
`LiveMap`, and most unions. We’re sharing our plans for other syntaxes so you
can give us early feedback
[here](https://github.com/liveblocks/liveblocks/discussions/674).

## Storage root

Each schema must include the `Storage` type, a special type of “root” object.

```ts
type Storage {

}
```

## Scalars

Familiar scalar types are globally available when you create a schema:

- `string`
- `number`
- `boolean`
- `null`

A sample schema using only scalar types could look like this:

```ts
type Storage {
  name: string
  age: number
  hasSiblings: boolean
  favoritePet: string | null
}
```

And here are some updates that would be accepted and rejected by the schema:

```ts
// ✅ Valid storage updates
root.set("name", "Marie Curie");
root.set("age", 66);
root.set("hasSiblings", true);
root.set("favoritePet", "Cooper");
root.set("favoritePet", null);

// ❌ Invalid storage updates
root.set("name", true);
root.set("hasSiblings", null);
root.set("favoritePet", 0);
```

You can also use literal types to restrict values even further:

```ts
type Event {
  statusCode: 200 | 400
  info: string
}

type Storage {
  theme: "light" | "dark"
  history: LiveList<Event>
}
```

## Optionals

Each field inside an object type can be marked optional using the `?` operator.
An optional field means that it can be deleted.

For example, to make the `age` field optional:

```ts highlight="3"
type Storage {
  name: string
  age?: number
  height: number
  hasSiblings: boolean
}
```

Accepted and rejected updates:

```ts
// ✅
root.delete("age");

// ❌ Field 'name' is not optional
root.delete("name");
```

<Banner title="Comparison with GraphQL">
  Notice that we made the decision to make every field mandatory by default, as
  opposed to GraphQL.
</Banner>

## Objects

Our language supports two different ways to declare object types:

- Named object types

```ts
type Scientist {
  name: string
  age: number
}

type Storage {
  scientist: Scientist
}
```

- Anonymous object types (inlined)

```ts
type Storage  {
  scientist: { name: string, age: number }
}
```

These definitions are equivalent. Accepted and rejected updates:

```ts
// ✅
root.set("scientist", { name: "Marie Curie", age: 66 });

// ❌ Required field 'age' is missing
root.set("scientist", { name: "Marie Curie" });
```

## LiveObject

To use an object type definition as a “live” object, wrap it in the built-in
[`LiveObject`](/docs/api-reference/liveblocks-client#LiveObject) construct, like
so:

```ts
type Scientist {
  name: string
  age: number
}

type Storage {
  scientist: LiveObject<Scientist>
  //         ^^^^^^^^^^
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("scientist", new LiveObject({ name: "Marie Curie"; age: 66 }));

// ❌ Should be a LiveObject
root.set("scientist", { name: "Marie Curie"; age: 66 });
```

## Arrays

Arrays can be defined like this:

```ts
type Storage {
  animals: string[]
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("animals", ["🦁", "🦊", "🐵"]));

// ❌ Should contain strings
root.set("animals", [1, 2, 2]);
```

## LiveList

To use a “live” array instead of a normal array, wrap your item type in a
[`LiveList`](/docs/api-reference/liveblocks-client#LiveList) when you reference
it.

For example:

```ts
type Storage {
  animals: LiveList<string>
  //       ^^^^^^^^
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("animals", new LiveList(["🦁", "🦊", "🐵"]));

// ❌ Should be a LiveList
root.set("animals", ["🦁", "🦊", "🐵"]);
```

## LiveMap

It’s also possible to define a
[`LiveMap`](/docs/api-reference/liveblocks-client#LiveMap) in your schema.

For example:

```ts
type Shape {
  x: number
  y: number
  fill: "red" | "yellow" | "blue"
}

type Storage {
  shapes: LiveMap<string, Shape>
  //      ^^^^^^^
}
```

The first argument to a `LiveMap` construct must always be `string`.

Accepted and rejected updates:

```ts
// ✅
root.set(
  "shapes",
  new LiveMap([["shapeId", { x: 100, y: 100, fill: "blue" }]])
);

// ❌ Required field 'fill' is missing
root.set("shapes", new LiveMap([["shapeId", { x: 100, y: 100 }]]));
```

## Unions

You can model a choice between two types using a union, which will be familiar
from TypeScript. Here are some examples:

```ts
type Storage {
  ids: (string | number)[]
  selectedId: string | null
  person: LiveObject<Person> | null
  people: LiveList<LiveObject<Person>> | null
}
```

---
meta:
  title: "Sync Datastore"
  parentTitle: "Platform"
  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

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Yjs"
    href="/docs/platform/sync-datastore/liveblocks-yjs"
    description="Data store for text editors"
    visual={<DocsYjsIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Storage"
    href="/docs/platform/sync-datastore/liveblocks-storage"
    description="Data store for creative tools"
    visual={<DocsStorageIcon className="fill-product-icon-brand h-auto w-6" />}
  />
</ListGrid>

## Examples using Sync Datastore

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "nuxtjs", "vuejs", "sveltekit", "solidjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Cursors Chat",
      slug: "live-cursors-chat",
      image: "/images/examples/thumbnails/live-cursors-chat.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard-advanced",
      image:
        "/images/examples/thumbnails/collaborative-whiteboard-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Flowchart",
      slug: "collaborative-flowchart/zustand-flowchart",
      image: "/images/examples/thumbnails/collaborative-flowchart.jpg",
      advanced: true,
    }}
    technologies={["zustand"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Liveblocks Storage"
  parentTitle: "Sync Datastore"
  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.

## API Reference

### Presence

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client#Room.getPresence"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Presence"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Redux"
    href="/docs/api-reference/liveblocks-redux#enhancer-option-presence-mapping"
    description="@liveblocks/redux"
    visual={<DocsReduxIcon />}
  />
  <DocsCard
    type="technology"
    title="Zustand"
    href="/docs/api-reference/liveblocks-zustand#middleware-option-presence-mapping"
    description="@liveblocks/zustand"
    visual={
      <img
        alt=""
        src="/assets/zustand.png"
        width={24}
        height={24}
        loading="lazy"
      />
    }
  />
</ListGrid>

### Broadcast

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client#Room.broadcastEvent"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Broadcast"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API function"
    href="/docs/api-reference/liveblocks-node#post-broadcast-event"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints#post-broadcast-event"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

### Storage

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client#Storage"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Storage"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Redux"
    href="/docs/api-reference/liveblocks-redux#enhancer-option-storage-mapping"
    description="@liveblocks/redux"
    visual={<DocsReduxIcon />}
  />
  <DocsCard
    type="technology"
    title="Zustand"
    href="/docs/api-reference/liveblocks-zustand#middleware-option-storage-mapping"
    description="@liveblocks/zustand"
    visual={
      <img
        alt=""
        src="/assets/zustand.png"
        width={24}
        height={24}
        loading="lazy"
      />
    }
  />
  <DocsCard
    type="technology"
    title="REST API functions"
    href="/docs/api-reference/liveblocks-node#Storage"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints#Storage"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Liveblocks Storage

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Cursors Chat",
      slug: "live-cursors-chat",
      image: "/images/examples/thumbnails/live-cursors-chat.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Todo List",
      slug: "collaborative-todo-list",
      image: "/images/examples/thumbnails/collaborative-todo-list.jpg",
    }}
    technologies={["nextjs", "redux", "zustand", "javascript", "react-native"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Spreadsheet",
      slug: "collaborative-spreadsheet-advanced",
      image:
        "/images/examples/thumbnails/collaborative-spreadsheet-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Whiteboard",
      slug: "collaborative-whiteboard-advanced",
      image:
        "/images/examples/thumbnails/collaborative-whiteboard-advanced.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Flowchart",
      slug: "collaborative-flowchart/zustand-flowchart",
      image: "/images/examples/thumbnails/collaborative-flowchart.jpg",
      advanced: true,
    }}
    technologies={["zustand"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Liveblocks Yjs"
  parentTitle: "Sync Datastore"
  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.

## Text Editor vs Sync Datastore

If you’re using Tiptap or Lexical, we recommend using
[Text Editor](/docs/ready-made-features/text-editor) instead. This is an
alternative to Sync Datastore, with extra features specifically created for
those editors. Sync Datastore, powered by Liveblocks Yjs and Liveblocks Storage,
is intended for use in other editors, or for completely custom solutions.

## Yjs API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Yjs"
    href="/docs/api-reference/liveblocks-yjs"
    description="@liveblocks/yjs"
    visual={<DocsYjsIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="REST API functions"
    href="/docs/api-reference/liveblocks-node#Yjs"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints#Yjs"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Liveblocks Yjs

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative Text Editor (Slate)",
      slug: "collaborative-text-editor/nextjs-yjs-slate",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Text Editor (Quill)",
      slug: "collaborative-text-editor/nextjs-yjs-quill",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Collaborative Code Editor",
      slug: "collaborative-code-editor",
      image: "/images/examples/thumbnails/code-editor.jpg",
      advanced: true,
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Troubleshooting"
  parentTitle: "Platform"
  description: "Troubleshoot common errors"
---

## Common issues [#common]

<Banner title="Need help troubleshooting?">

Try the [Liveblocks DevTools extension](/devtools) to visualize your
collaborative experiences as you build them, in realtime.

</Banner>

### ReferenceError: process is not defined [#process-not-defined]

When calling `client.enterRoom()`, you stumble upon the following error:

```text
ReferenceError: process is not defined
```

The `@liveblocks/client` package expects to be consumed by a JavaScript bundler,
like Webpack, Babel, ESbuild, Rollup, etc. If you see this error, you have most
likely directly loaded the `@liveblocks/client` source code through a `<script>`
tag.

#### Solution [#process-not-defined-solution] [@hidden]

If using a bundler isn’t possible for you, there are two available solutions.

One solution is to load the source code from the
[Skypack CDN](https://www.skypack.dev/view/@liveblocks/client), which will
expose optimized production builds which have the `process` variable removed.

Another solution is to define the necessary `process.env.NODE_ENV` variable
manually, before loading the script, for example:

```ts
globalThis.process = { env: { NODE_ENV: "production" } };
```

### Why we’re asking you to pass unstable_batchedUpdates [#stale-props-zombie-child]

<Banner title="The best solution is to upgrade to React 18">

The last version of Liveblocks that supports the old React 17 version is 2.14.0.
To upgrade Liveblocks to 2.15 or higher, first upgrade React to 18.

Passing in `unstable_batchedUpdates` is no longer necessary on the latest
version of Liveblocks.

</Banner>

If you’re **on React 17 or lower**, there is a well-known problem that all state
management libraries need to deal with at some point, known as the
["Stale-props / zombie-child" problem](https://kaihao.dev/posts/Stale-props-and-zombie-children-in-Redux)—Liveblocks
is no exception.

This issue can cause catastrophic bugs, inconsistent renders, or—in the best
case—performance issues. Sooner or later, as your app grows in complexity, you
will run into some manifestation of this bug, and we want to be ahead of that.

Just do either of the following to avoid it!

1. **Just upgrade to React 18** (recommended)
1. If you cannot upgrade just yet, we ask you to pass the
   `unstable_batchedUpdates` function to the RoomProvider in the mean time, so
   Liveblocks can circumvent the issue on your behalf!

```tsx highlight="1,7"
import { unstable_batchedUpdates } from "react-dom";
//                                      ^^^^^^^^^^^ ...or "react-native"!
<RoomProvider
  id="my-room"
  initialPresence={/* ... */}
  initialStorage={/* ... */}
  unstable_batchedUpdates={unstable_batchedUpdates}
>
  <App />
</RoomProvider>;
```

Starting with 0.18.3, this will be enforced in React 17 and lower, potentially
saving hours of debugging.

#### What’s the problem, exactly? [#stale-props-zombie-child-details] [@hidden]

If you’re on React 17 or lower, state updates from “external” (non-DOM) events
will **not** get batched together automatically. If two or more of your
components subscribe to the same piece of state, and this state gets updated by
another user in the room, then both components will individually rerender,
separately.

In most cases this is just inefficient but not catastrophic. However, if you
happen to have a parent and child component that both rely on the same state,
this can lead to hard-to-debug bugs.

For example:

```tsx highlight="2,7"
function Parent() {
  const shapes = useStorage((root) => root.shapes);
  return shapes.map(({ id }) => <Child key={id} id={id} />);
}

function Child({ id }) {
  const shape = useStorage((root) => root.shapes.get(id));
  return <Shape x={shape.x} y={shape.y} />;
}
```

Both of these components need to get rerendered if, for example, some shape gets
deleted by another user in the room.

In React 17 (or lower), those rerenders will **not get batched together** and as
such they will not rerender together. Instead, they rerender individually,
separately. Which component rerenders first is undefined and often unpredictable
in larger apps. If you’re unlucky, this can lead to the Child component to get
rerendered before its Parent has had the opportunity to unmount it, which should
of course never happen.

By providing `unstable_batchedUpdates` to the RoomProvider, Liveblocks will wrap
all state updates in this helper, which will make sure that both Parent and
Child get rerendered as part of the same render cycle. This way, React will
ensure that the Parent component will always get rerendered before the Child.

## TypeScript issues [#typescript]

### Type "MyInterface" does not satisfy the constraint "Lson" [#lson-constraint-and-interfaces] [@keywords=["TS2344", "Lson", "LsonObject", "index signature missing"]]

If you found this page, chances are you stumbled upon this TypeScript error:

```text
TS2344: Type 'MyInterface' does not satisfy the constraint 'Lson'.
  Type 'MyInterface' is not assignable to type 'JsonObject'.
    Index signature for type 'string' is missing in type 'MyInterface'.
```

Liveblocks data structures (like `LiveObject`, `LiveMap`, and `LiveList`)
require that their payloads are always JSON-serializable to be able to send them
over WebSocket connections reliably and without surprises. Starting with 0.16,
we’re enforcing this with `Lson` type constraint. (LSON is a Liveblocks-specific
extension of JSON that also allows nesting more Live data structures.)

If you encounter this error above, TypeScript is trying to tell you that the
data type you are using in one of your Live structures is not (guaranteed to be)
a legal LSON (or JSON) value. But why?

```ts
interface Person {
  name: string;
  age: number;
}

const people = new LiveList<Person>();
//                          ~~~~~~
//                          TS2344: Type "Person" does not
//                          satisfy the constraint "Lson" ☹️
```

Although this `Person` type seems perfectly JSON-serializable with only those
`string` and `number` fields, TypeScript still considers this a problem because
it cannot _guarantee_ that all of its subtypes will also be that. Interface
types are "open" and extensible by design. This means it’s possible to define a
subtype that would still not be JSON-serializable.
[Example](https://www.typescriptlang.org/play?#code/JYOwLgpgTgZghgYwgAgArQM4HsTIN4BQyyIcAthAFzIZhSgDmA3EcnA1SQK5kBG0LAL4ECAelHIAanAA2XCBmRYYyAAYBRAG7AZ6KNhCrkZYAwAWYElkv9kAKQDKAeQByAWgzRgs4AC84vDIQADRiEgCeEJZwUCi0OjLImj4AJmp6BqoYBKCQsIgoWjoZOMgQAB6QICmKJbiExOLIgLwbgBB7rCDWDl4+-oGcXCAA1p0A7iBMjRIARIMjWOPTyDDAEDI1xqYWVjZxPTJ+AUEEwkA).

To fix this issue, there are roughly three available solutions.

#### Solution 1: Change your interface to a type [#lson-interface-solution1] [@hidden]

The simplest solution is to convert your `interface` to a `type`.

```ts highlight="1"
type Person = {
  name: string;
  age: number;
};

const people = new LiveList<Person>();
//                          ^^^^^^ ✅ All good now
```

Check this solution out in the TypeScript
[playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgGWANwKaoM7wL5wBmUEIcA5AAIA26GARtRAMYDW2A9M7RgHYzkA3AChhMAJ5gMcAAoYo2CLzgBeRMLhxeAQxAYAXHFxRgvAOYjN2swa0BXEPXki8I4cyW44UiGGrS1XgwAdxQ6HBgAHjkFJQA+AAoAShEODk0MzKzs7IA9fIK4QFByOABBamo4MwgIABMtCGDhIA).

#### Solution 2: Extend your interface [#lson-interface-solution2] [@hidden]

You can also explicitly pledge that your interface will be JSON serializable by
having it extend from `JsonObject`.

```ts highlight="1,3"
import { JsonObject } from "@liveblocks/client";

interface Person extends JsonObject {
  name: string;
  age: number;
}

const people = new LiveList<Person>();
//                          ^^^^^^ ✅ All good now
```

Check this solution out in the TypeScript
[playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgGWANwKaoM4wDRwBS2EAdgPIBGAVhgMbwC+cAZlBCHAOQACANugyU+EOgGtsAejoCMpGFwDcAKGXB5GKCwCGdDHAAKmkqTgYAHjDkATbERNVaDRMrhxS2kBgBccXFHUAcxU3bUCfdwBXEEpNFUYVZToyXDgwDAgwPn0AXncMAHcUQRwYAB4jKBMAPgAKAEoVSUk3Vrb2jo6APR7euEBQcjgAQT4+OECICGt3CALlIA).

#### Solution 3: Wrap the interface in a helper [#lson-interface-solution3] [@hidden]

This is the least preferred solution, but may be necessary if you don’t own the
interface definition and it’s coming from an external package.

```ts highlight="1,4"
import type { LiveList, EnsureJson } from "@liveblocks/client";
import { Person } from "some-external-package";

const people = new LiveList<EnsureJson<Person>>();
//                          ^^^^^^^^^^^^^^^^^^ ✅ All good now
```

Check this solution out in the TypeScript
[playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgGWANwKaoM4wDRwCiAdtgK5QYBS2ExcAvnAGZQQhwDkAAgDboYARrwgBjANbYA9KP4ZiMTgG4AUKEixEcACoARAKrYMURizYceMXgBMoAQwDuUq7cfKVUqXG8+4APQDAuAAlO2JrdjhgBWNmO1EMOBgATzBE1kj7cMiMAA8YY2I7XjgwePE7AHMMFRVROlw4MiMobDgAXjhiDAcUARwYAB4SckoaOkG9Q2MAPhmACgBKVSA).

---
meta:
  title: "Upgrading Liveblocks"
  parentTitle: "Platform"
  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.

<ListGrid>
  <DocsCard
    type="image"
    title="Upgrading to 2.16"
    href="/docs/platform/upgrading/2.16"
    visual={<DocsCardGradientText>2.16</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 2.15"
    href="/docs/platform/upgrading/2.15"
    visual={<DocsCardGradientText>2.15</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 2.9"
    href="/docs/platform/upgrading/2.9"
    visual={<DocsCardGradientText>2.9</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 2.8"
    href="/docs/platform/upgrading/2.8"
    visual={<DocsCardGradientText>2.8</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 2.2"
    href="/docs/platform/upgrading/2.2"
    visual={<DocsCardGradientText>2.2</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 2.0"
    href="/docs/platform/upgrading/2.0"
    visual={<DocsCardGradientText>2.0</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 1.10"
    href="/docs/platform/upgrading/1.10"
    visual={<DocsCardGradientText>1.10</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 1.9"
    href="/docs/platform/upgrading/1.9"
    visual={<DocsCardGradientText>1.9</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 1.5"
    href="/docs/platform/upgrading/1.5"
    visual={<DocsCardGradientText>1.5</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 1.2"
    href="/docs/platform/upgrading/1.2"
    visual={<DocsCardGradientText>1.2</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 1.0"
    href="/docs/platform/upgrading/1.0"
    visual={<DocsCardGradientText>1.0</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 0.19"
    href="/docs/platform/upgrading/0.19"
    visual={<DocsCardGradientText>0.19</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 0.18"
    href="/docs/platform/upgrading/0.18"
    visual={<DocsCardGradientText>0.18</DocsCardGradientText>}
  />
  <DocsCard
    type="image"
    title="Upgrading to 0.17"
    href="/docs/platform/upgrading/0.17"
    visual={<DocsCardGradientText>0.17</DocsCardGradientText>}
  />
</ListGrid>

---
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");

  /* ... */
}
```

<Banner title="Explicitly specify your live structures now">

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.

<Banner title="You may not need this">

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!

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`liveblocksprovider`]: /docs/api-reference/liveblocks-react#LiveblocksProvider
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`uselist`]: /docs/api-reference/liveblocks-react#useList
[`usemap`]: /docs/api-reference/liveblocks-react#useMap
[`usemypresence`]: /docs/api-reference/liveblocks-react#useMyPresence
[`useobject`]: /docs/api-reference/liveblocks-react#useObject

---
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.

<Banner title="Adopting Suspense">

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.

<Banner title="Tip!">

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`.

<Banner title="You may not need this">

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
```

<Banner title="Update every Liveblocks package">

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
```

<Banner title="Update every Liveblocks package">

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>

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

  <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 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
```

<Banner title="Update every Liveblocks package">

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
```

<Banner title="Update every Liveblocks package">

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.

<Banner title="Just want to upgrade?">

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 create-liveblocks-app@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]

<Banner>

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]

<Banner>

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]

<Banner>

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]

<Banner>

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]

<Banner>

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]

<Banner>

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]

<Banner title="Optional, but recommended">

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.

<Banner type="warning" title="Do you have multiple room types?">

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

<Banner type="info" title="Where to put this?">

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 create-liveblocks-app@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 create-liveblocks-app@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"
---

<Banner title="Upgrade to 2.0 required">

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 create-liveblocks-app@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.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 create-liveblocks-app@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
<!-- ❌ Before - Liveblocks 2.7 -->
<form class="lb-root lb-composer lb-composer-form">
  <!-- The editor and its controls -->
</form>

<!-- ✅ After - Liveblocks 2.8 -->
<form class="lb-root lb-composer lb-composer-form">
  <div class="lb-composer-editor-container">
    <!-- The editor and its controls -->
  </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 create-liveblocks-app@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: "Webhooks"
  parentTitle: "Platform"
  description: "Learn Liveblocks webhooks concepts and implementation."
---

Webhooks enable developers to extend the Liveblocks platform. From your system,
you can listen to events that get automatically triggered as users interact with
collaborative rooms.

## Configuring webhooks

To set up webhooks for your project, you’ll need to create an endpoint,
subscribe to events, and secure your endpoint.

- [Creating an endpoint](#creating-an-endpoint)
- [Edit endpoint events](#edit-endpoint-events)
- [Security verification](#security-verification)
- [Replaying events](#replaying-events)
- [Testing locally](#testing-locally)

### Creating an endpoint [#creating-an-endpoint]

If you would like to create an endpoint to receive webhook events, you will do
so from within the webhooks dashboard for your project.

<Steps>
  <StepCompact>

    From the <a href="/dashboard" target="_blank">dashboard</a> overview, navigate
    to the project you’d like to add webhooks to.

  </StepCompact>

  <StepCompact>

    Click on the webhooks tab from the left-hand menu.

  </StepCompact>

  <StepCompact>

    Click the **“Create endpoint…”** button.

  </StepCompact>

  <StepCompact>

    Enter the URL of the endpoint you would like to use. Configure with your own
    endpoint or generate a
    <a href="https://www.svix.com/play/" target="_blank">Svix playground</a> link
    by clicking on **"use Svix play"**.

  </StepCompact>

  <StepCompact>

    Select the events you would like to subscribe to.

  </StepCompact>

  <StepCompact lastStep>

    Click **“Create endpoint”**.

  </StepCompact>

</Steps>

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/create-endpoint.mp4" type="video/mp4" />
  </video>
</Figure>

Your endpoint must return a `2xx` (status code `200-299`) to indicate that the
event was successfully received. If your endpoint returns anything else, the
event will be retried, see [replaying events](#replaying-events) for more
details.

If all events fail to be delivered to your endpoint for 5 consecutive days, your
endpoint will automatically be disabled. You can always re-enable it from the
dashboard.

### Edit endpoint events [#edit-endpoint-events]

You can easily edit the events you want to subscribe to after creating an
endpoint.

<Steps>
  <StepCompact>

    Select the endpoint you would like to edit from the list of webhooks in the
    dashboard.

  </StepCompact>

  <StepCompact>

    Select **“Edit endpoint…”** from the top right dropdown.

  </StepCompact>

  <StepCompact lastStep>

    Update event selections and click **“Save changes”**.

  </StepCompact>

</Steps>

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/edit-events.mp4" type="video/mp4" />
  </video>
</Figure>

### Replaying events [#replaying-events]

If your service is unreachable, message retries are automatically re-attempted.
If your service incurs considerable downtime (over 8 hours), you can replay
individual messages from the Endpoints portion of the dashboard by clicking the
kebab menu on an individual message, or you can opt to bulk replay events by
clicking the top right dropdown and selecting **“Recover failed messages…”**.

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/webhooks/replay-events.mp4" type="video/mp4" />
  </video>
</Figure>

Each message is attempted based on a schedule that follows the failure of the
preceding attempt. If an endpoint is removed or disabled, delivery attempts will
also be disabled. The schedule for retries is as follows:

- Immediately
- 5 seconds
- 5 minutes
- 30 minutes
- 2 hours
- 5 hours
- 10 hours
- 10 hours (in addition to the previous)

For example, an attempt that fails three times before eventually succeeding will
be delivered roughly 35 minutes and 5 seconds following the first attempt.

## Security verification [#security-verification]

Verifying webhooks prevents security vulnerabilities by safeguarding against
man-in-the-middle, CSRF, and replay attacks. Because of this, it is essential to
prioritize verification in your integration. We recommend using the
`@liveblocks/node` package to verify and return fully typed events.

<Steps>

  <Step>
    <StepTitle>Install the package</StepTitle>
    <StepContent>

      ```bash
      npm install @liveblocks/node
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up the webhook handler</StepTitle>
    <StepContent>

      Set up your webhook handler, inserting your secret key from the webhooks dashboard you
      set up earlier into [`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler).

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

      // Insert your webhook secret key
      const webhookHandler = new WebhookHandler("whsec_...");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Verify an event request</StepTitle>
    <StepContent>

      We can verify a genuine webhook request with
      [`WebhookHandler.verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest)

      ```ts
      const event = webhookHandler.verifyRequest({
        headers: req.headers,
        rawBody: req.body,
      });
      ```

      <Banner title="rawBody takes a string" type="warning">

        Note that some frameworks parse request bodies into objects, so you may need to
        use `rawBody: JSON.stringify(req.body)` instead.

      </Banner>

      The method will return a `WebhookEvent` object that is fully typed. You can then
      use the event to perform actions based on the event type. If the request is not valid, an error will be thrown.

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>

      Full example

    </StepTitle>

    <StepContent>

      Here’s an example from start to finish.

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

      // Will fail if not properly initialized with a secret
      const webhookHandler = new WebhookHandler("whsec_...");

      export default function webhookRequestHandler(req, res) {
        try {
          const event = webhookHandler.verifyRequest({
            headers: req.headers,
            rawBody: req.body,
          });

          // Use the event, for example...
          if (event.type === "storageUpdated") {
            // { roomId: "my-room-name", projectId: "8sfhs5s...", ... }
            console.log(event.data);
          }
        } catch (error) {
          console.error(error);
          return res.status(400).end();
        }

        res.status(200).end();
      }
      ```

    </StepContent>

  </Step>

</Steps>

### Manually verify

It’s also possible to manually verify your webhooks, though it’s unlikely
this’ll be necessary.

<details>

<summary>How to manually verify webhook events</summary>

<Steps>

  <Step>
    <StepTitle>Construct the signed content</StepTitle>
    <StepContent>

      The content to sign is composed by concatenating the request’s id, timestamp,
      and payload, separated by the full-stop character (`.`). In code, it will look
      something like:

      ```ts
      const crypto = require("crypto");

      // webhookId comes from the `webhook-id` header
      // webhookTimestamp comes from the `webhook-timestamp` header
      // body is the request body
      signedContent = `${webhookId}.${webhookTimestamp}.${body}`;
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Generate the signature</StepTitle>
    <StepContent>

      Liveblocks uses an HMAC with SHA-256 to sign its webhooks.

      So to calculate the expected signature, you should HMAC the `signedContent` from
      above using the base64 portion of your webhook secret key (this is the part
      after the `whsec_` prefix) as the key. For example, given the secret
      `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` you will want to use
      `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`.

      For example, this is how you can calculate the signature in Node.js:

      ```ts
      // Your endpoint’s secret key
      const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

      // Need to base64 decode the secret
      const secretBytes = new Buffer(secret.split("_")[1], "base64");
      // This is the signature you will compare against the signature header
      const signature = crypto
      .createHmac("sha256", secretBytes)
      .update(signedContent)
      .digest("base64");
      ```

    </StepContent>

  </Step>

  <Step>
    <StepTitle>Validate the signature</StepTitle>
    <StepContent>

      The generated signature should match one of the signatures sent in the
      `webhook-signature` header.

      The `webhook-signature` header comprises a list of space-delimited signatures
      and their corresponding version identifiers. The signature list is most commonly
      of length one. Though there could be any number of signatures. For example:

      ```
      v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
      ```

      Make sure to remove the version prefix and delimiter (e.g., `v1`) before
      verifying the signature.

    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>Verify the timestamp</StepTitle>
    <StepContent>

      As mentioned above, Liveblocks also sends the timestamp of the attempt in the
      `webhook-timestamp` header. You should compare this timestamp against your
      system timestamp and make sure it’s within your tolerance to prevent timestamp
      attacks.

      <Banner title="Comparing signatures">

        We recommend implementing a constant-time string comparison method when
        comparing signatures to prevent timing attacks.

      </Banner>

    </StepContent>

  </Step>

</Steps>

</details>

## Testing locally [#testing-locally]

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
host your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

If you visit the page `localtunnel` links you to, and correctly input your IP
address, the URL it generates can be placed into the Liveblocks webhooks
dashboard for quick testing.

For a full step-by-step guide on testing with `localtunnel` and `ngrok`, read
the guide on
[how to test webhooks on localhost](/docs/guides/how-to-test-webhooks-on-localhost#Use-your-webhook-event).

## Source IP Addresses [#source-ips]

In case your webhook receiving endpoint is behind a firewall or NAT, you may
need to allow traffic from
[Svix's IP addresses](https://docs.svix.com/receiving/source-ips).

```
44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/52
```

## Liveblocks events

An event occurs when a change is made to Liveblocks data. Each endpoint you
provide in the webhooks dashboard listens to all events by default but can be
easily configured to only listen to a subset by updating the Message Filtering
section.

The Event Catalog in the webhooks dashboard provides a list of events available
for subscription, along with their schema.

Events available for use include:

- `StorageUpdated`
- `UserEntered/UserLeft`
- `RoomCreated/RoomDeleted`
- `YDocUpdated`
- `CommentCreated/CommentEdited/CommentDeleted`
- `CommentReactionAdded/CommentReactionRemoved`
- `ThreadCreated/ThreadDeleted/ThreadMetadataUpdated`
- `Notification`

More events will come later, such as:

- `MaxConnectionsReached`

#### UserEnteredEvent

When a user connects to a room, an event is triggered, indicating that the user
has entered. The `numActiveUsers` field shows the number of users in the room
after the user has joined. This event is not throttled.

```ts
// Schema
type UserEnteredEvent = {
  type: "userEntered";
  data: {
    projectId: string;
    roomId: string;
    connectionId: number;
    userId: string | null;
    userInfo: Record<string, any> | null;
    enteredAt: string;
    numActiveUsers: number;
  };
};

// Example
const userEnteredEvent = {
  type: "userEntered",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    connectionId: 4,
    userId: "a-user-id",
    userInfo: null,
    enteredAt: "2021-10-06T01:45:56.558Z",
    numActiveUsers: 8,
  },
};
```

#### UserLeftEvent

A user leaves a room when they disconnect from a room, which is when this event
is triggered. The `numActiveUsers` field represents the number of users in the
room after the user has left. This event, like `UserEntered`, is not throttled.

```ts
// Schema
type UserLeftEvent = {
  type: "userLeft";
  data: {
    projectId: string;
    roomId: string;
    connectionId: number;
    userId: string | null;
    userInfo: Record<string, any> | null;
    leftAt: string;
    numActiveUsers: number;
  };
};

// Example
const userLeftEvent = {
  type: "userLeft",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    connectionId: 4,
    userId: "a-user-id",
    userInfo: {
      name: "John Doe",
    },
    leftAt: "2021-10-06T01:45:56.558Z",
    numActiveUsers: 7,
  },
};
```

#### StorageUpdatedEvent

Storage is updated when a user writes to storage. This event is throttled at
five seconds and, as such, may not be triggered for every write.

For example, if a user writes to storage at 1:00 pm sharp, the
`StorageUpdatedEvent` event will be triggered shortly after. If the user writes
to storage again at 1:00 pm and 2 seconds, the `StorageUpdatedEvent` event will
be triggered five seconds after the first event was sent, around 1:00 pm and 5
seconds.

```ts
// Schema
type StorageUpdatedEvent = {
  type: "storageUpdated";
  data: {
    roomId: string;
    projectId: string;
    updatedAt: string;
  };
};

// Example
const storageUpdatedEvent = {
  type: "storageUpdated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    updatedAt: "2021-10-06T01:45:56.558Z", // 👈 time of the last write
  },
};
```

#### RoomCreatedEvent

An event is triggered when a room is created. This event is not throttled. There
are two ways for rooms to be created:

- By calling the
  [create room API](/docs/api-reference/rest-api-endpoints#post-rooms)
- When a user connects to a room that does not exist

```ts
// Schema
type RoomCreatedEvent = {
  type: "roomCreated";
  data: {
    projectId: string;
    roomId: string;
    createdAt: string;
  };
};

// Example
const roomCreatedEvent = {
  type: "roomCreated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

#### RoomDeletedEvent

An event is triggered when a room is deleted. This event is not throttled.

```ts
// Schema
type RoomDeletedEvent = {
  type: "roomDeleted";
  data: {
    projectId: string;
    roomId: string;
    deletedAt: string;
  };
};

// Example
const roomDeletedEvent = {
  type: "roomDeleted",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    deletedAt: "2021-10-06T01:45:56.558Z",
  },
};
```

#### YDocUpdatedEvent

Yjs document is updated when a user makes a change to a Yjs doc connected to a
room. This event is throttled at five seconds and, as such, may not be triggered
for every write.

For example, if a user updates a Yjs document at 1:00 pm sharp, the
`YDocUpdatedEvent` event will be triggered shortly after. If the user writes to
the Yjs document again at 1:00 pm and 2 seconds, the `YDocUpdatedEvent` event
will be triggered 5 seconds after the first event was sent, around 1:00 pm and 5
seconds.

```ts
// Schema
type YDocUpdatedEvent = {
  type: "ydocUpdated";
  data: {
    projectId: string;
    roomId: string;
    updatedAt: string;
  };
};

// Example
const ydocUpdatedEvent = {
  type: "ydocUpdated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    updatedAt: "2013-06-26T19:10:19Z",
  },
};
```

#### CommentCreatedEvent

An event is triggered when a comment is created. This event is not throttled.

```ts
// Schema
type CommentCreatedEvent = {
  type: "commentCreated";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    commentId: string;
    createdAt: string;
    createdBy: string;
  };
};

// Example
const commentCreatedEvent = {
  type: "commentCreated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    commentId: "my-comment-id",
    createdAt: "2021-10-06T01:45:56.558Z",
    createdBy: "my-user-id",
  },
};
```

#### CommentEditedEvent

An event is triggered when a comment is edited. This event is not throttled.

```ts
// Schema
type CommentEditedEvent = {
  type: "commentEdited";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    commentId: string;
    editedAt: string;
  };
};

// Example
const commentEditedEvent = {
  type: "commentEdited",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    commentId: "my-comment-id",
    editedAt: "2021-10-06T01:45:56.558Z",
  },
};
```

#### CommentDeletedEvent

An event is triggered when a comment is deleted. This event is not throttled.

```ts
// Schema
type CommentDeletedEvent = {
  type: "commentDeleted";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    commentId: string;
    deletedAt: string;
  };
};

// Example
const commentDeletedEvent = {
  type: "commentDeleted",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    commentId: "my-comment-id",
    deletedAt: "2021-10-06T01:45:56.558Z",
  },
};
```

#### CommentReactionAddedEvent

An event is triggered when a reaction is added to a comment. This event is not
throttled.

```ts
// Schema
type CommentReactionAddedEvent = {
  type: "commentReactionAdded";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    commentId: string;
    emoji: string;
    addedAt: string;
    addedBy: string;
  };
};

// Example
const commentReactionAddedEvent = {
  type: "commentReactionAdded",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    commentId: "my-comment-id",
    emoji: "👍",
    addedAt: "2021-10-06T01:45:56.558Z",
    addedBy: "my-user-id",
  },
};
```

#### CommentReactionRemovedEvent

An event is triggered when a reaction is removed from a comment. This event is
not throttled.

```ts
// Schema
type CommentReactionRemovedEvent = {
  type: "commentReactionRemoved";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    commentId: string;
    emoji: string;
    removedAt: string;
    removedBy: string;
  };
};

// Example
const commentReactionRemovedEvent = {
  type: "commentReactionRemoved",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    commentId: "my-comment-id",
    emoji: "👍",
    removedAt: "2021-10-06T01:45:56.558Z",
    removedBy: "my-user-id",
  },
};
```

#### ThreadCreatedEvent

An event is triggered when a thread is created. This event is not throttled.

```ts
// Schema
type ThreadCreatedEvent = {
  type: "threadCreated";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    createdAt: string;
    createdBy: string;
  };
};

// Example
const threadCreatedEvent = {
  type: "threadCreated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    createdAt: "2021-10-06T01:45:56.558Z",
    createdBy: "my-user-id",
  },
};
```

#### ThreadDeletedEvent

An event is triggered when a thread is deleted. This event is not throttled. A
thread is deleted when all comments in the thread are deleted or when the thread
is manually deleted.

```ts
// Schema
type ThreadDeletedEvent = {
  type: "threadDeleted";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    deletedAt: string;
  };
};

// Example
const threadDeletedEvent = {
  type: "threadDeleted",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    deletedAt: "2021-10-06T01:45:56.558Z",
  },
};
```

#### ThreadMetadataUpdatedEvent

An event is triggered when a thread metadata is updated. This event is not
throttled.

```ts
// Schema
type ThreadMetadataUpdatedEvent = {
  type: "threadMetadataUpdated";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    updatedAt: string;
    updatedBy: string;
  };
};

// Example
const threadMetadataUpdatedEvent = {
  type: "threadMetadataUpdated",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    updatedAt: "2021-10-06T01:45:56.558Z",
    updatedBy: "my-user-id",
  },
};
```

#### ThreadMarkedAsResolvedEvent

An event is triggered when a thread is marked as resolved. This event is not
throttled.

```ts
// Schema
type ThreadMarkedAsResolvedEvent = {
  type: "threadMarkedAsResolved";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    updatedAt: string;
    updatedBy: string;
  };
};

// Example
const ThreadMarkedAsResolvedEvent = {
  type: "threadMarkedAsResolved",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    updatedAt: "2021-10-06T01:45:56.558Z",
    updatedBy: "my-user-id",
  },
};
```

#### ThreadMarkedAsUnresolvedEvent

An event is triggered when a thread is marked as unresolved. This event is not
throttled.

```ts
// Schema
type ThreadMarkedAsUnresolvedEvent = {
  type: "threadMarkedAsUnresolved";
  data: {
    projectId: string;
    roomId: string;
    threadId: string;
    updatedAt: string;
    updatedBy: string;
  };
};

// Example
const ThreadMarkedAsUnresolvedEvent = {
  type: "threadMarkedAsUnresolved",
  data: {
    projectId: "my-project-id",
    roomId: "my-room-id",
    threadId: "my-thread-id",
    updatedAt: "2021-10-06T01:45:56.558Z",
    updatedBy: "my-user-id",
  },
};
```

#### NotificationEvent

Notification events are designed to help you create notification emails for your
users. By default, they’re triggered 30 minutes after an activity occurs, but
this number can be modified in your [dashboard](/dashboard) inside a project’s
settings.

This webhook event is triggered by both Liveblocks and custom notification
`kinds`, as detailed below.

##### Thread notification

When using [Comments](/docs/ready-made-features/comments), an event is triggered
30 minutes after a user has been mentioned or replied to in a thread, and has
not seen the thread. It will also be triggered if the user has subscribed to the
thread and has not seen the thread. The event won’t be triggered if the user has
seen the thread or unsubscribed from the room’s thread notifications. This is
the Liveblocks `thread` notification kind.

```ts
// Schema
type ThreadNotificationEvent = {
  type: "notification";
  data: {
    channel: "email";
    kind: "thread";
    projectId: string;
    roomId: string;
    userId: string;
    threadId: string;
    inboxNotificationId: string;
    createdAt: string;
  };
};

// Example
const threadNotificationEvent = {
  type: "notification",
  data: {
    channel: "email",
    kind: "thread",
    projectId: "my-project-id",
    roomId: "my-room-id",
    userId: "my-user-id",
    threadId: "my-thread-id",
    inboxNotificationId: "my-inbox-notification-id",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

If you want to easily identify this event in your code then you can use the type
guard
[`isThreadNotificationEvent`](/docs/api-reference/liveblocks-node#isThreadNotificationEvent).

##### TextMention notification

When using [Text editor](/docs/ready-made-features/text-editor), an event is
triggered 30 minutes after a user has been mentioned in a text and has not seen
the text mention. This is the Liveblocks `textMention` notification kind.

```ts
// Schema
type TextMentionNotificationEvent = {
  type: "notification";
  data: {
    channel: "email";
    kind: "textMention";
    projectId: string;
    roomId: string;
    userId: string;
    mentionId: string;
    inboxNotificationId: string;
    createdAt: string;
  };
};

// Example
const textMentionNotificationEvent = {
  type: "notification",
  data: {
    channel: "email",
    kind: "textMention",
    projectId: "my-project-id",
    roomId: "my-room-id",
    userId: "my-user-id",
    mentionId: "my-mention-id",
    inboxNotificationId: "my-inbox-notification-id",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

If you want to easily identify this event in your code then you can use the type
guard
[`isTextMentionNotificationEvent`](/docs/api-reference/liveblocks-node#isTextMentionNotificationEvent).

##### Custom notification

An event is triggered 30 minutes after the user has been notified of a custom
event and has not seen the notification. All custom notification `kinds` are
prefixed with `$` and are manually by you on the server. Learn more about
[triggering custom notifications](/docs/api-reference/rest-api-endpoints#post-inbox-notifications-trigger).

```ts
// Schema
type CustomNotificationEvent = {
  type: "notification";
  data: {
    channel: "email";
    kind: "$yourKind"; // Can be any string starting with "$" as defined by the user
    projectId: string;
    roomId: string | null;
    userId: string;
    inboxNotificationId: string;
    createdAt: string;
  };
};

// Example
const customNotificationEvent = {
  type: "notification",
  data: {
    channel: "email",
    kind: "$fileUpload",
    projectId: "my-project-id",
    roomId: "my-room-id",
    userId: "my-user-id",
    inboxNotificationId: "my-inbox-notification-id",
    createdAt: "2021-10-06T01:45:56.558Z",
  },
};
```

If you want to easily identify this event in your code then you can use the type
guard
[`isCustomNotificationEvent`](/docs/api-reference/liveblocks-node#isCustomNotificationEvent).

## Use Cases

With webhooks, you can subscribe to the events you are interested in, and be
alerted of the change when it happens. Powerful ways to leverage webhooks with
Liveblocks include:

- Storage synchronization between room(s) and an internal database
- Monitoring user activity in a room
- Notifying the client if maximum concurrency has been reached

Webhooks are an excellent way to reduce development time and the need for
polling. By following the steps outlined in this guide, you’ll be able to
configure, subscribe to, secure, and replay webhook events with Liveblocks.

If you have any questions or need help using webhooks, please let us know
[by email](mailto:support@liveblocks.io) or by joining our
[Discord community](/discord)! We’re here to help!

---
meta:
  title: "WebSocket infrastructure"
  parentTitle: "Platform"
  description: "Learn about the Liveblocks WebSocket infrastructure."
---

## WebSocket edge network

The Liveblocks WebSocket edge network enables you to automatically create
collaborative rooms in regions close to your users, reducing latency and
improving end-user performance while enabling you to scale effortlessly.

<Figure highlight>
  <Image
    src="/assets/websocket-infrastructure/edge-network.png"
    alt="Liveblocks WebSocket edge network"
    width={768}
    height={440}
  />
</Figure>

The Liveblocks WebSocket edge network primarily uses the
[Cloudflare Workers](https://workers.cloudflare.com/) global network, spanning
300 cities and 100+ countries, enabling a ~50ms connection to 95% of the world’s
internet-connected population.

## WebSocket connection engine

The Liveblocks WebSocket connection engine ensures a reliable realtime
experience for users. It handles offline, reconnections, and all sorts of
edge-cases automatically so you don’t have to. See
[API reference](/docs/api-reference/liveblocks-client#Room.getStatus) to learn
more.

<Figure highlight>
  <Image
    src="/assets/websocket-infrastructure/connection-engine.png"
    alt="Liveblocks WebSocket connection engine"
    width={820}
    height={482}
  />
</Figure>

---
meta:
  title: "AI Copilots"
  parentTitle: "Ready-made features"
  description: "Easily integrate customizable AI copilots into your product"
---

Embed customizable AI copilots into your product, enabling your users to
collaborate with AI. Features include contextual chat, floating toolbars, live
cursors, and AI comments.

## Request access

If you'd like to try AI Copilots we're currently onboarding a limited number of
customers to our private beta. You can [request access here](/ai-copilots), and
learn more about the project in [our blog post](/blog/introducing-ai-copilots-ready-made-interfaces-for-human-like-collaboration).

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

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Concepts"
    href="/docs/ready-made-features/comments/concepts"
    description="Learn about threads and comments"
    visual={<DocsIdeaIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Users and mentions"
    href="/docs/ready-made-features/comments/users-and-mentions"
    description="Add users to comments and mentions"
    visual={<DocsMentionIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Default components"
    href="/docs/ready-made-features/comments/default-components"
    description="Ready-to-use customizable components"
    visual={
      <DocsDefaultComponentsIcon className="fill-product-icon-brand h-auto w-6" />
    }
  />
  <DocsCard
    type="technology"
    title="Hooks"
    href="/docs/ready-made-features/comments/hooks"
    description="Get users, threads, & modify comments"
    visual={<DocsHooksIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Metadata"
    href="/docs/ready-made-features/comments/metadata"
    description="Add custom metadata to threads"
    visual={<DocsMetadataIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Primitives"
    href="/docs/ready-made-features/comments/primitives"
    description="Construct fully custom components"
    visual={
      <DocsPrimitivesIcon className="fill-product-icon-brand h-auto w-6" />
    }
  />
  <DocsCard
    type="technology"
    title="Styling and customization"
    href="/docs/ready-made-features/comments/styling-and-customization"
    description="CSS variables, dark mode, localization"
    visual={<DocsStylingIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Email notifications"
    href="/docs/ready-made-features/comments/email-notifications"
    description="Send notifications with webhooks"
    visual={<DocsEmailIcon className="fill-product-icon-brand h-auto w-6" />}
  />
</ListGrid>

## Comments API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Comments"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="React UI"
    href="/docs/api-reference/liveblocks-react-ui#Comments"
    description="@liveblocks/react-ui"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client#Comments"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API functions"
    href="/docs/api-reference/liveblocks-node#Comments"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints#Comments"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Comments

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments",
      slug: "comments/nextjs-comments",
      image: "/images/examples/thumbnails/comments.jpg",
    }}
    technologies={["nextjs", "react"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Video Comments",
      slug: "video-comments/nextjs-comments-video",
      image: "/images/examples/thumbnails/comments-video.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Overlay Comments",
      slug: "overlay-comments/nextjs-comments-overlay",
      image: "/images/examples/thumbnails/comments-overlay.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Text Editor Comments",
      slug: "text-editor-comments/nextjs-comments-tiptap",
      image: "/images/examples/thumbnails/comments-text-editor.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
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.

<Figure>
  <Image
    src="/assets/comments/comment-thread-room-relation.jpg"
    srcDark="/assets/comments/comment-thread-room-relation-dark.jpg"
    alt="Diagram showing a comment, inside a thread, inside a room"
    width={768}
    height={480}
    quality={100}
  />
</Figure>

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 also 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.

<Figure>
  <Image
    src="/assets/comments/first-comment-in-thread.jpg"
    srcDark="/assets/comments/first-comment-in-thread-dark.jpg"
    alt="thread.comments[0] is the first comment in a thread"
    width={768}
    height={480}
    quality={100}
  />
</Figure>

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

```ts highlight="8-20"
{
  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
        // ...
      },
    },

    // 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.

### 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.

<Figure>
  <Image
    src="/assets/comments/comment-deleted.jpg"
    srcDark="/assets/comments/comment-deleted-dark.jpg"
    alt="Image of a thread with one comment highlighting a deleted comment"
    width={768}
    height={480}
    quality={100}
  />
</Figure>

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.

<Figure>
  <Image
    src="/assets/comments/thread.png"
    alt="Thread"
    width={768}
    height={446}
  />
</Figure>

### 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.

<Figure>
  <Image
    src="/assets/comments/composer.png"
    alt="Composer"
    width={768}
    height={446}
  />
</Figure>

### 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)
- [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.

<Figure>
  <Image
    src="/assets/comments/comment.png"
    alt="Comment"
    width={768}
    height={446}
  />
</Figure>

### 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.

<Figure>
  <Image
    src="/assets/comments/email-notification.png"
    alt="An email titled 'New notifications' showing two comments and a link to the thread"
    width={1500}
    height={1000}
  />
</Figure>

<Banner title="Step-by-step tutorial">

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.

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/edit-events.mp4" type="video/mp4" />
  </video>
</Figure>

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`.

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/notification-settings.mp4" type="video/mp4" />
  </video>
</Figure>

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.reactBody}</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.reactBody}</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.reactBody}</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.reactBody}</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)
- [`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)
- [`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)
- [`getRoomNotificationSettings`](/docs/api-reference/liveblocks-node#get-rooms-roomId-users-userId-notification-settings)
- [`updateRoomNotificationSettings`](/docs/api-reference/liveblocks-node#post-rooms-roomId-users-userId-notification-settings)
- [`deleteRoomNotificationSettings`](/docs/api-reference/liveblocks-node#delete-rooms-roomId-users-userId-notification-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.

## useThreads hook [#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).

## useUser hook [#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).

## Mutation hooks [#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)
- [`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.config.ts";

// 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";
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 the `suspense`
property in your config file.

```tsx file="liveblocks.config.ts" highlight="5-7"
// ...

export const {
  suspense: {
    // Export from here to use Suspense hooks
    useThreads,
    useUser,
  },
} = createRoomContext(client, {});
```

### 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.config.ts";

// 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 the root level in your
config file.

```tsx file="liveblocks.config.ts" highlight="4-6"
// ...

export const {
  // Export from here to use regular hooks
  useThreads,
  useUser,
} = createRoomContext(client, {});
```

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

In Comments, each thread 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.

## Valid metadata

You can store any `string`, `boolean`, or `number` in thread 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, and each property can be
4000 characters long.

## Setting metadata

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

```ts file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // +++
    ThreadMetadata: {
      priority: string;
      pinned: boolean;
      timestamp: 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.

<Figure>
  <Image
    src="/assets/comments/composer.png"
    alt="Composer"
    width={768}
    height={446}
  />
</Figure>

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

### Mutation hooks

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

```tsx highlight="5,10-13"
import { useEditThreadMetadata } from "../liveblocks.config";

// 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>
  );
}
```

These hooks are exported from your config file and provide full typing.

### 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).

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

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"}'
```

---
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](http://localhost:3001/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 {
  /* Customise thread */
}

.lb-avatar[data-loading] {
  /* Customise 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 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.

<Figure>
  <Image
    src="/assets/tutorials/comments/thread.png"
    alt="Thread with resolved users"
    width={1291}
    height={892}
  />
</Figure>

<Banner title="Step-by-step tutorial">

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 Comments

In Comments, user information is retrieved from a list of user IDs, 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" }]
```

In your Liveblocks config file, you’ll find a function named
[`resolveUsers`](/docs/api-reference/liveblocks-client#resolveUsers) where you
can return this information.

```ts file="liveblocks.config.ts"
// ...

const client = createClient({
  // ...
  async resolveUsers({ 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;
  },
});
```

The `name`, and `avatar` are required for 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);

  // ...
}
```

## Resolving user mentions suggestions

Comments allows you to search for a user after typing the `"@"` character.

<Figure>
  <Image
    src="/assets/tutorials/comments/mentions.png"
    alt="Working Comments mentions"
    width={1297}
    height={781}
  />
</Figure>

When a user types `"@"` and searches for a user, Comments will pass you a `text`
property which you can use to return matching user IDs.

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

# Return matching `usersIds`
["marc@example.com", "marissa@example.com"]
```

You can resolve these search results by editing a function named
[`resolveMentionSuggestions`](/docs/api-reference/liveblocks-client#resolveMentionSuggestions)
in your Liveblocks config file. Here’s what the function might look like if the
user has typed `"@mar"` into the input.

```ts file="liveblocks.config.ts"
// ...

const client = createClient({
  // ...
  async resolveUsers({ userIds }) {
    // ...
  },
  async resolveMentionSuggestions({ 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;
  },
});
```

If a user has only typed `"@"`, `text` is an empty string, and it’s recommended
to return every user.

---
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
our other products, such as [Comments](/docs/ready-made-features/comments), can
also automatically trigger them where appropriate.

## Overview

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Concepts"
    href="/docs/ready-made-features/notifications/concepts"
    description="Learn about inbox notifications"
    visual={<DocsIdeaIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Default components"
    href="/docs/ready-made-features/notifications/default-components"
    description="Ready-to-use customizable components"
    visual={
      <DocsDefaultComponentsIcon className="fill-product-icon-brand h-auto w-6" />
    }
  />
  <DocsCard
    type="technology"
    title="Hooks"
    href="/docs/ready-made-features/notifications/hooks"
    description="Retrieve notifications & set settings"
    visual={<DocsHooksIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Styling and customization"
    href="/docs/ready-made-features/notifications/styling-and-customization"
    description="CSS variables, dark mode, localization"
    visual={<DocsStylingIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Email notifications"
    href="/docs/ready-made-features/notifications/email-notifications"
    description="Send notifications with webhooks"
    visual={<DocsEmailIcon className="fill-product-icon-brand h-auto w-6" />}
  />
</ListGrid>

## Notifications API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Notifications"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="React UI"
    href="/docs/api-reference/liveblocks-react-ui#Notifications"
    description="@liveblocks/react-ui"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client#Notifications"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API functions"
    href="/docs/api-reference/liveblocks-node#Notifications"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints#Notifications"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Notifications

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Comments notifications",
      slug: "comments-notifications",
      image: "/images/examples/thumbnails/comments-notifications.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Custom notifications",
      slug: "notifications-custom",
      image: "/images/examples/thumbnails/custom-notifications.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Comments emails",
      slug: "comments-emails",
      image: "/images/examples/thumbnails/comments-email.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Text editor emails",
      slug: "collaborative-text-editor-emails",
      image: "/images/examples/thumbnails/text-editor-email.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
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 resolves 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.

<Figure>
  <Image
    src="/assets/notifications/custom-notification.jpg"
    alt="Thread"
    width={1344}
    height={896}
  />
</Figure>

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)>,
  activityData: {
    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.

<Figure>
  <Image
    src="/assets/notifications/notification-rooms.jpg"
    alt="Notification rooms"
    width={1344}
    height={896}
  />
</Figure>

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 specific 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.

<Figure>
  <Image
    src="/assets/notifications/custom-notification-both.jpg"
    alt="Thread"
    width={1344}
    height={896}
  />
</Figure>

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`.

### Liveblocks 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.

<Figure>
  <Image
    src="/assets/notifications/notifications-inbox.jpg"
    alt="Thread"
    width={1344}
    height={896}
  />
</Figure>

This is enabled by default and the notification `kind` is `thread`. Threads
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.

<Figure>
  <Image
    src="/assets/comments/thread-unread-indicator.png"
    alt="Unread indicator in Thread component"
    width={1456}
    height={896}
  />
</Figure>

## 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.

<Figure>
  <Image
    src="/assets/notifications/notification-settings.jpg"
    alt="Notification settings"
    width={1344}
    height={896}
  />
</Figure>

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.

## 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 notifications automatically triggered by Liveblocks
  [Comments](/docs/ready-made-features/comments).
- Receive fully custom notifications.

## InboxNotification

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

<Figure>
  <Image
    src="/assets/notifications/inbox-notification.png"
    alt="InboxNotification"
    width={768}
    height={446}
  />
</Figure>

### 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}
        />
      ))}
    </>
  );
}
```

#### 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.

<Figure>
  <Image
    src="/assets/notifications/inbox-notification-list.png"
    alt="InboxNotificationList"
    width={768}
    height={446}
  />
</Figure>

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

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

[`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`.

<Figure>
  <Image
    src="/assets/comments/email-notification.png"
    alt="An email titled 'New notifications' showing two comments and a link to the thread"
    width={1500}
    height={1000}
  />
</Figure>

## 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

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. This makes more sense when
sending email notifications because it helps to avoid flooding your users with
too many emails.

## 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.

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/edit-events.mp4" type="video/mp4" />
  </video>
</Figure>

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 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`.

<Figure>
  <video width={1512} height={982} autoPlay loop muted playsInline>
    <source src="/assets/webhooks/notification-settings.mp4" type="video/mp4" />
  </video>
</Figure>

### 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;

  // 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 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 });
}
```

<Banner title="Sending Comments emails">

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

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.

## User settings

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

<Figure>
  <Image
    src="/assets/notifications/notification-settings.jpg"
    alt="Notification settings"
    width={1344}
    height={896}
  />
</Figure>

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.

## useInboxNotifications hook [#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);

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

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

## useUnreadInboxNotificationsCount hook [#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>;
}
```

## useMarkAllInboxNotificationsAsRead hook

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

## useUser hook [#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).

## 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.

<Figure>
  <Image
    src="/assets/comments/thread-unread-indicator.png"
    alt="Unread indicator in Thread component"
    width={1456}
    height={896}
  />
</Figure>

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 notification 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
[`useRoomNotificationSettings`](/docs/api-reference/liveblocks-react#useRoomNotificationSettings)
to build a settings picker in your app and allow users to change their own
notification settings for the current room, or use
[`updateRoomNotificationSettings`](/docs/api-reference/liveblocks-node#post-rooms-roomId-users-userId-notification-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.config.ts";

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

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

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";
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 the `suspense`
property in your config file.

```tsx file="liveblocks.config.ts" highlight="5-7"
// ...

export const {
  suspense: {
    // Export from here to use Suspense hooks
    useInboxNotifications,
    useUser,
  },
} = createLiveblocksContext(client, {});
```

### 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.config.ts";

// 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 the root level in your
config file.

```tsx file="liveblocks.config.ts" highlight="4-6"
// ...

export const {
  // Export from here to use regular hooks
  useInboxNotifications,
  useUser,
} = createLiveblocksContext(client, {});
```

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

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

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-notification {
  /* Customise notification */
}

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

---
meta:
  title: "Presence"
  parentTitle: "Ready-made features"
  description:
    "Easily integrate presence indicators like live cursors and avatar stacks to
    create a shared, realtime experience."
---

With Liveblocks Presence, you can integrate presence indicators like live
cursors, live avatar stacks, and more, to create a shared, realtime experience.

## Presence API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="React"
    href="/docs/api-reference/liveblocks-react#Presence"
    description="@liveblocks/react"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="JavaScript"
    href="/docs/api-reference/liveblocks-client"
    description="@liveblocks/client"
    visual={<DocsJavascriptIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API functions"
    href="/docs/api-reference/liveblocks-node"
    description="@liveblocks/node"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="REST API"
    href="/docs/api-reference/rest-api-endpoints"
    description="HTTP endpoints"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Presence

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Live Cursors",
      slug: "live-cursors",
      image: "/images/examples/thumbnails/live-cursors.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Cursors Chat",
      slug: "live-cursors-chat",
      image: "/images/examples/thumbnails/live-cursors-chat.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Avatar Stack",
      slug: "live-avatar-stack",
      image: "/images/examples/thumbnails/live-avatar-stack.jpg",
    }}
    technologies={["nextjs", "vuejs", "sveltekit", "solidjs", "javascript"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Live Form Selection",
      slug: "live-form-selection",
      image: "/images/examples/thumbnails/live-form-selection.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Text Editor"
  parentTitle: "Ready-made features"
  description:
    "Embed a customizable text editing experience into your product to enable
    people to collaborate."
---

Embed a text editing experience into your product, enabling collaboration
between your users. Liveblocks Text Editor is fully customizable, allowing you
to create a range of editing experiences that look and feel like your product.
Easily enable collaborative rich-text editing, with integrated threads,
comments, and mentions powered by
[Liveblocks Comments](/docs/ready-made-features/comments).

Text Editor is a permanent store for your Tiptap and Lexical documents, meaning
you do not need to synchronize, scale, or maintain any infrastructure.

## Overview

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Tiptap"
    href="/docs/ready-made-features/text-editor/tiptap"
    description="Add collaboration to Tiptap"
    visual={<DocsTiptapIcon className="fill-product-icon-brand h-auto w-6" />}
  />
  <DocsCard
    type="technology"
    title="Lexical"
    href="/docs/ready-made-features/text-editor/lexical"
    description="Add collaboration to Lexical"
    visual={<DocsLexicalIcon className="fill-product-icon-brand h-auto w-6" />}
  />
</ListGrid>

## Text Editor API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Tiptap React"
    href="/docs/api-reference/liveblocks-react-tiptap"
    description="@liveblocks/react-tiptap"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Tiptap/ProseMirror Node"
    href="/docs/api-reference/liveblocks-node-prosemirror"
    description="@liveblocks/node-prosemirror"
    visual={<DocsApiIcon />}
  />
  <DocsCard
    type="technology"
    title="Lexical React"
    href="/docs/api-reference/liveblocks-react-lexical"
    description="@liveblocks/react-lexical"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Lexical Node"
    href="/docs/api-reference/liveblocks-node-lexical"
    description="@liveblocks/node-lexical"
    visual={<DocsApiIcon />}
  />
</ListGrid>

## Examples using Text Editor

<ListGrid columns={2}>
  <ExampleCard
    example={{
      title: "Collaborative text editor",
      slug: "collaborative-text-editor/lexical",
      image: "/images/examples/thumbnails/text-editor.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Advanced collaborative text editor",
      slug: "collaborative-text-editor-advanced/nextjs-tiptap-advanced",
      image: "/images/examples/thumbnails/text-editor-advanced.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Linear-like issue tracker",
      slug: "linear-like-issue-tracker",
      image: "/images/examples/thumbnails/linear-like-issue-tracker.jpg",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
  <ExampleCard
    example={{
      title: "Notion-like AI editor",
      slug: "notion-like-ai-editor",
      image: "/images/examples/thumbnails/notion-like-ai-editor.png",
    }}
    technologies={["nextjs"]}
    openInNewWindow
  />
</ListGrid>

---
meta:
  title: "Lexical"
  parentTitle: "Text Editor"
  description: "Learn about using Lexical text editor"
---

A quick overview of the Text Editor 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 can be added to your document, and you can tag others inline. You can also
easily enable mention suggestions.

<Figure>
  <Image
    src="/assets/text-editor/mentions.png"
    alt="User mentions"
    width={1312}
    height={874}
  />
</Figure>

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

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

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        // Return user info from their `userIds`
        // ...
      }}
      resolveMentionSuggestions={async ({ text, roomId }) => {
        // Return suggestions from the search `text`
        // ...
      }}
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

## Real-time editing

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

<Figure>
  <Image
    src="/assets/text-editor/cursors.png"
    alt="Real-time text cursors"
    width={1312}
    height={874}
  />
</Figure>

When [authenticating your users](/docs/authentication) with
[`prepareSession`](/docs/api-reference/liveblocks-node#access-tokens) or
[`identifyUsers`](/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",
}
```

## 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.

<Figure>
  <Image
    src="/assets/text-editor/floating-toolbar.png"
    alt="FloatingToolbar"
    width={960}
    height={558}
  />
</Figure>

Add
[`Toolbar`](http://localhost:3001/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")}
    />
    // +++
  );
}
```

## 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.

<Figure>
  <Image
    src="/assets/text-editor/annotations.png"
    alt="Text editor annotations"
    width={1312}
    height={874}
  />
</Figure>

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

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.

<Figure>
  <Image
    src="/assets/text-editor/notifications.png"
    alt="Text editor notifications"
    width={1312}
    height={874}
  />
</Figure>

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

## 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.

<Figure>
  <Image
    src="/assets/text-editor/ai.png"
    alt="AI suggestions"
    width={1312}
    height={874}
  />
</Figure>

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

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

Liveblocks Lexical automatically creates versions of your document as changes
are made. 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-lexical";

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="w-full h-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.

## Lexical API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Lexical React"
    href="/docs/api-reference/liveblocks-react-lexical"
    description="@liveblocks/react-lexical"
    visual={<DocsReactIcon />}
  />
  <DocsCard
    type="technology"
    title="Lexical Node"
    href="/docs/api-reference/liveblocks-node-lexical"
    description="@liveblocks/node-lexical"
    visual={<DocsApiIcon />}
  />
</ListGrid>

---
meta:
  title: "Tiptap"
  parentTitle: "Text Editor"
  description: "Learn about using Tiptap text editor"
---

A quick overview of the Text Editor 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 can be added to your document, and you can tag others inline. You can also
easily enable mention suggestions.

<Figure>
  <Image
    src="/assets/text-editor/mentions.png"
    alt="User mentions"
    width={1312}
    height={874}
  />
</Figure>

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

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

function App() {
  return (
    <LiveblocksProvider
      resolveUsers={async ({ userIds }) => {
        // Return user info from their `userIds`
        // ...
      }}
      resolveMentionSuggestions={async ({ text, roomId }) => {
        // Return suggestions from the search `text`
        // ...
      }}
    >
      {/* children */}
    </LiveblocksProvider>
  );
}
```

## Real-time editing

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

<Figure>
  <Image
    src="/assets/text-editor/cursors.png"
    alt="Real-time text cursors"
    width={1312}
    height={874}
  />
</Figure>

When [authenticating your users](/docs/authentication) with
[`prepareSession`](/docs/api-reference/liveblocks-node#access-tokens) or
[`identifyUsers`](/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",
}
```

## 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.

<Figure>
  <Image
    src="/assets/text-editor/floating-toolbar.png"
    alt="FloatingToolbar"
    width={960}
    height={558}
  />
</Figure>

Add
[`Toolbar`](http://localhost:3001/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.

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

## 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).

<Figure>
  <Image
    src="/assets/text-editor/ai.png"
    alt="AI suggestions"
    width={1312}
    height={874}
  />
</Figure>

## 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.

<Figure>
  <Image
    src="/assets/text-editor/annotations.png"
    alt="Text editor annotations"
    width={1312}
    height={874}
  />
</Figure>

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

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.

<Figure>
  <Image
    src="/assets/text-editor/notifications.png"
    alt="Text editor notifications"
    width={1312}
    height={874}
  />
</Figure>

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

## 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).

{/* TODO: Mention Node.js package + AI agents when it's complete */}

## Version History

<Banner title="Private beta">

Version history is currently in private beta. If you would like access to the
beta, please [contact us](https://liveblocks.io/contact/sales). We’d love to
hear from you.

</Banner>

Liveblocks Tiptap automatically creates versions of your document as changes are
made. 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-tiptap";

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="w-full h-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.

## Tiptap API Reference

<ListGrid columns={2}>
  <DocsCard
    type="technology"
    title="Tiptap React"
    href="/docs/api-reference/liveblocks-react-tiptap"
    description="@liveblocks/react-tiptap"
    visual={<DocsReactIcon />}
  />

{/* TODO: <DocsCard type="technology" title="Lexical Node" href="/docs/api-reference/liveblocks-node-lexical" description="@liveblocks/node-lexical" visual={<DocsApiIcon />} /> */}

</ListGrid>

---
meta:
  title: "Metadata"
  parentTitle: "Rooms"
  description: "Learn more Liveblocks room metadata"
---

You can assign custom `metadata` to your room. For example, if you have
different types of room experiences, you can store that type as `metadata`. This
would then come handy when building an overview page listing all the rooms where
the type `metadata` could be used as a filter, making it easy for people to find
what they’re looking for.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/managing-rooms/rooms-type-metadata.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

One way to edit `metadata` is to use the
[create room API](/docs/api-reference/rest-api-endpoints#post-rooms). In this
example we’re creating a new room with a custom `roomType` property, and setting
it to "whiteboard":

```ts highlight="7"
fetch("https://api.liveblocks.io/v2/rooms", {
  method: "POST",
  body: JSON.stringify({
    id: "my-room-name",
    defaultAccesses: [],
    metadata: {
      roomType: "whiteboard",
    },
  }),
});
```

We can then use the
[get rooms API](/docs/api-reference/rest-api-endpoints#get-rooms) to retrieve a
list of rooms containing the "whiteboard" `roomType`:

```ts
const metadata = "metadata.roomType=whiteboard";
const url = `https://api.liveblocks.io/v2/rooms?${metadata}`;
const response = await fetch(url);
const rooms = await response.json();
```

Metadata can be also be used within a number of our
[other APIs](/docs/api-reference/rest-api-endpoints).

---
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/).

<Banner title="Live demo video">

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/devtools/liveblocks-starter-dev.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

### 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`.

<Figure highlight={false}>
  <Image
    src="/assets/devtools/spreadsheet-example.png"
    alt="Liveblocks DevTools panel"
    width={768}
    height={576}
  />
</Figure>

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/devtools/highlight-changes.mp4" type="video/mp4" />
  </video>
</Figure>

### Search

Storage values are searchable by key and regex.

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/devtools/search-regex.mp4" type="video/mp4" />
  </video>
</Figure>

### Hover

Hovering over a value in storage or presence makes an eye icon appear. If
clicked, it displays the value of that key.

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/devtools/expand-tooltip.mp4" type="video/mp4" />
  </video>
</Figure>

### 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

<Banner title="Initialization">

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: "Next.js Starter Kit"
  parentTitle: "Tools"
  description:
    "Kickstart your collaborative SaaS product with the Liveblocks Next.js
    Starter Kit."
---

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/nextjs-starter-kit/starter-kit.mp4" type="video/mp4" />
  </video>
</Figure>

<Banner title="Live demo">

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, drafts, groups, auto-revalidation
- Collaborative whiteboard app with a fully-featured share menu
- Authentication compatible with GitHub, Google, Auth0, and more
- Document permissions can be scoped to users, groups, and the public

## 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:

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/nextjs-starter-kit/create-liveblocks-app.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/nextjs-starter-kit/deploy-on-vercel.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/nextjs-starter-kit/create-liveblocks-project.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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".

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/nextjs-starter-kit/github-auth.mp4" type="video/mp4" />
  </video>
</Figure>

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:

```dotenv 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".

<Figure>
  <video autoPlay loop muted playsInline>
    <source src="/assets/nextjs-starter-kit/auth0-auth.mp4" type="video/mp4" />
  </video>
</Figure>

`.env.local` should now contain these three lines, along with anything
previously there:

```dotenv 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: "yourname@example.com",
  name: "Your Name",
  avatar: "https://liveblocks.io/avatars/avatar-0.png",
  groupIds: ["product", "engineering", "design"],
},
```

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
auth.ts
auth.config.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>`/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/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: "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: "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

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 },
  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 },
  // +++
  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.

<Figure>
  <Image
    src="/assets/tutorials/comments/thread.png"
    alt="Thread with resolved users"
    width={1291}
    height={892}
  />
</Figure>

## 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 access token authentication, with an email address as a
user’s ID.

```ts title="Metadata in access tokens"
const session = liveblocks.prepareSession("marc@example.com", {
  userInfo: {
    name: "Marc",
    avatar: "https://example.com/marc.png",

    // Your custom metadata
    // ...
  },
});
```

If you’re using ID token authentication, it’ll look a little different.

```ts title="Metadata in ID tokens" isCollapsed isCollapsable
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",
    groupIds: [], // Optional
  },
  {
    userInfo: {
      name: "Marc",
      avatar: "https://example.com/marc.png",

      // Your custom metadata
      // ...
    },
  }
);
```

Don’t forget to 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).

<Figure>
  <Image
    src="/assets/tutorials/comments/thread.png"
    alt="Thread with resolved users"
    width={1291}
    height={892}
  />
</Figure>

<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!

      <Figure>
        <Image
          src="/assets/tutorials/comments/thread.png"
          alt="Thread with resolved users"
          width={1291}
          height={892}
        />
      </Figure>

    </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).

<Figure>
  <Image
    src="/assets/tutorials/comments/mentions.png"
    alt="Working Comments mentions"
    width={1297}
    height={781}
  />
</Figure>

<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!

      <Figure>
        <Image
          src="/assets/tutorials/comments/mentions.png"
          alt="Working Comments mentions"
          width={1297}
          height={781}
        />
      </Figure>

    </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.

<Figure>
  <Image
    src="/assets/notifications/notifications-inbox.jpg"
    alt="Thread"
    width={1344}
    height={896}
  />
</Figure>

## 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 access token authentication, with an email address as a
user’s ID.

```ts title="Metadata in access tokens"
const session = liveblocks.prepareSession("marc@example.com", {
  userInfo: {
    name: "Marc",
    avatar: "https://example.com/marc.png",

    // Your custom metadata
    // ...
  },
});
```

If you’re using ID token authentication, it’ll look a little different.

```ts title="Metadata in ID tokens" isCollapsed isCollapsable
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",
    groupIds: [], // Optional
  },
  {
    userInfo: {
      name: "Marc",
      avatar: "https://example.com/marc.png",

      // Your custom metadata
      // ...
    },
  }
);
```

Don’t forget to 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).

<Figure>
  <Image
    src="/assets/notifications/notifications-inbox.jpg"
    alt="Thread"
    width={1344}
    height={896}
  />
</Figure>

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

  </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 notifications!

      <Figure>
        <Image
          src="/assets/notifications/notifications-inbox.jpg"
          alt="Thread"
          width={1344}
          height={896}
        />
      </Figure>

    </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-ui#Notifications)
- [Examples](/examples/browse/notifications)

---
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.

<Figure>
  <Image
    src="/assets/text-editor/mentions.png"
    alt="User mentions"
    width={1312}
    height={874}
  />
</Figure>

## 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 access token authentication, with an email address as a user’s
ID.

```ts title="Metadata in access tokens"
const session = liveblocks.prepareSession("marc@example.com", {
  userInfo: {
    name: "Marc",
    color: "#00ff00",
    avatar: "https://example.com/marc.png",

    // Your custom metadata
    // ...
  },
});
```

If you’re using ID token authentication, it’ll look a little different.

```ts title="Metadata in ID tokens" isCollapsed isCollapsable
const { status, body } = await liveblocks.identifyUser(
  {
    userId: "marc@example.com",
    groupIds: [], // Optional
  },
  {
    userInfo: {
      name: "Marc",
      color: "#00ff00",
      avatar: "https://example.com/marc.png",

      // Your custom metadata
      // ...
    },
  }
);
```

Don’t forget to 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;
        color: 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).

<Figure>
  <Image
    src="/assets/text-editor/cursors.png"
    alt="Real-time text cursors"
    width={1312}
    height={874}
  />
</Figure>

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

  </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 user names in cursors!

      <Figure>
        <Image
          src="/assets/text-editor/cursors.png"
          alt="Real-time text cursors"
          width={1312}
          height={874}
        />
      </Figure>

    </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).

<Figure>
  <Image
    src="/assets/text-editor/mentions.png"
    alt="User mentions"
    width={1312}
    height={874}
  />
</Figure>

<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, Text Editor can display
      a list of mention suggestions!

      <Figure>
        <Image
          src="/assets/text-editor/mentions.png"
          alt="User mentions"
          width={1312}
          height={874}
        />
      </Figure>

    </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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/code-editors/code-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

<Banner title="Download the example">

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

  // 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 } = 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

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. After adding the following, you should see live
cursors:

```tsx file="Cursors.tsx" highlight="1,10-11,35-40"
import { useRoom, useSelf } from "@/liveblocks.config";
// ...

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

  // 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;
    }

    // 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);

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

    // 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>
  );
}
```

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

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/code-editors/code-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/code-editors/code-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org/),
[TypeScript](https://www.typescriptlang.org/), and
[Monaco](https://microsoft.github.io/monaco-editor/).

## Install Monaco, Yjs, and Liveblocks into your Next.js application

<Banner title="Download the example">

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

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

  // 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 } = 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 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="100hw"
          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.

```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;
}
```

## 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="100hw"
          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 {
  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;
}

.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="100hw"
          theme="vs-light"
          defaultLanguage="typescript"
          defaultValue=""
          options={{
            tabSize: 2,
            padding: { top: 20 },
          }}
        />
      </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,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="100hw"
          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

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-monaco).

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/code-editors/code-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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](/api/auth/signup), then navigate to
[the dashboard](/dashboard/apikeys) to find your public key. It should start
with `pk_`.

<Banner title="Public vs secret key">

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: [
      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,27"
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: [
      liveblocksEnhancer({
        client,
        storageMapping: { shapes: 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    insertRectangle: (state) => {
      const shapeId = Date.now().toString();
      const shape = {
        x: getRandomInt(300),
        y: getRandomInt(300),
        fill: getRandomColor(),
      };
      state.shapes[shapeId] = shape;
    },
  },
});

export const { insertRectangle } = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      liveblocksEnhancer({
        client,
        storageMapping: { shapes: true },
      }),
    ],
  });
}

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-2.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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,30"
/* ... */

const initialState = {
  shapes: {},
  selectedShape: null,
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    insertRectangle: (state) => {
      /* ... */
    },
    onShapePointerDown: (state, action) => {
      state.selectedShape = action.payload;
    },
  },
});

export const { insertRectangle, onShapePointerDown } = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      liveblocksEnhancer({
        client,
        storageMapping: { shapes: true },
        presenceMapping: { selectedShape: true },
      }),
    ],
  });
}

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    insertRectangle: (state) => {
      const shapeId = Date.now().toString();
      const shape = {
        x: getRandomInt(300),
        y: getRandomInt(300),
        fill: getRandomColor(),
      };
      state.shapes[shapeId] = shape;
      state.selectedShape = shapeId;
    },
    onShapePointerDown: (state, action) => {
      /* ... */
    },
    deleteShape: (state) => {
      if (state.selectedShape) {
        delete state.shapes[state.selectedShape];
        state.selectedShape = null;
      }
    },
  },
});

export const { insertRectangle, onShapePointerDown, deleteShape } =
  slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      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!

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-4.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    insertRectangle: (state) => {
      /* ... */
    },
    onShapePointerDown: (state, action) => {
      state.selectedShape = action.payload;
      state.isDragging = true;
    },
    deleteShape: (state) => {
      /* ... */
    },
    onCanvasPointerUp: (state) => {
      state.isDragging = false;
    },
    onCanvasPointerMove: (state, action) => {
      if (state.isDragging && state.selectedShape) {
        state.shapes[state.selectedShape].x = action.payload.x - 50;
        state.shapes[state.selectedShape].y = action.payload.y - 50;
      }
    },
  },
});

export const {
  insertRectangle,
  onShapePointerDown,
  deleteShape,
  onCanvasPointerUp,
  onCanvasPointerMove,
} = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-5.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-6.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

<Figure>
  <Image
    src="/assets/tutorials/whiteboard/tutorial-whiteboard-dashboard.png"
    alt="Liveblocks dashboard"
    width={1336}
    height={822}
    quality={80}
  />
</Figure>

## 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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]

In order to use Liveblocks, we’ll need to sign up and get an API key.
[Create an account](/api/auth/signup), then navigate to
[the dashboard](/dashboard/apikeys) to find your public key. It should start
with `pk_`.

<Banner title="Public vs secret key">

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.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 {
  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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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]

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-2.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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 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";

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

  /* ... */

  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={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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set, get) => ({
      shapes: {},
      selectedShape: null,
      insertRectangle: () => {
        /* ... */
      },
      onShapePointerDown: (shapeId) => {
        /* ... */
      },
      deleteShape: () => {
        const { shapes, selectedShape } = get();
        if (!selectedShape) {
          /* Nothing todo */
          return;
        }
        const { [selectedShape]: shapeToDelete, ...newShapes } = shapes;
        set({
          shapes: newShapes,
          selectedShape: null,
        });
      },
    }),
    {
      client,
      storageMapping: { shapes: true },
      presenceMapping: { selectedShape: true },
    }
  )
);

export default useStore;
```

```tsx file="src/App.ts" highlight="11,20-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);

  /* ... */

  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!

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-4.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-5.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

```tsx file="src/App.tsx" highlight="14,15,33,34"
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);
  const undo = useStore((state) => state.liveblocks.room?.history.undo);
  const redo = useStore((state) => state.liveblocks.room?.history.redo);

  /* ... */

  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.

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/whiteboard/tutorial-whiteboard-6.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

```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).

<Figure>
  <Image
    src="/assets/tutorials/whiteboard/tutorial-whiteboard-dashboard.png"
    alt="Liveblocks dashboard"
    width={1336}
    height={822}
    quality={80}
  />
</Figure>

## 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

<Banner title="No longer recommended" type="warning">

We now have an official Lexical package, and we recommend you use this instead
of following this guide. Read more in our
[Lexical getting stared 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

<Banner title="Download the example">

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

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

  // 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 } = 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

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 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.

```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;
}

.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 {
  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;
}

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

  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,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).

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

<Banner title="Download the example">

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

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

  // 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 } = 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

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 Quill 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 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.

```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;
}

.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);

// ...

function QuillEditor({ yText, provider }: EditorProps) {
  // Add user info to cursors from Liveblocks authentication endpoint
  const userInfo = useSelf((me) => me.info);
  useEffect(() => {
    const { name, color } = userInfo;
    provider.awareness.setLocalStateField("user", {
      name,
      color,
    });
  }, [userInfo]);

  // ...

  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 {
  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;
}

.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

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

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

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-quill).

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

This guide assumes that you’re already familiar with
[React](https://react.dev/), [Next.js](https://nextjs.org/),
[TypeScript](https://www.typescriptlang.org/), and
[Slate](https://docs.slatejs.org/).

## Install Slate, Yjs, and Liveblocks into your Next.js application

<Banner title="Download the example">

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

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

  // 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 } = 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

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 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.

```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;
}

.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 {
  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;
}

.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

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

  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 {
  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

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-slate).

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

<Banner title="No longer recommended" type="warning">

We now have an official Tiptap package, and we recommend you use this instead of
following this guide. Read more in our
[Lexical getting stared 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

<Banner title="Download the example">

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

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

  // 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 } = 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

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 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
        history: 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.

```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;
}

.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

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

.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

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

  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="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

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-tiptap).

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/text-editors/text-editor-demo.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

---
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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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](/api/auth/signup) to get
[your API key](/dashboard/apikeys). It should start with `pk_`.

<Banner title="Public vs secret key">

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>

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]

<Banner title="Need help troubleshooting presence?">

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-2.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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]

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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("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();
```

## Sync and persist to-dos [#add-liveblocks-storage]

<Banner title="Need help troubleshooting 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`.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

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

<Figure>
  <Image
    src="/assets/tutorials/todo-list/tutorial-todo-list-dashboard.png"
    alt="Liveblocks dashboard"
    width={1380}
    height={778}
  />
</Figure>

## 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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
```

<Banner title="Next.js setup options">

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

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="/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]

<Banner title="Need help troubleshooting presence?">

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.

<figure className="relative my-10 overflow-hidden rounded-lg">
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-2.mp4"
      type="video/mp4"
    />
  </video>
  <div className="shadow-thin-border-300 pointer-events-none absolute inset-0 rounded-lg" />
</figure>

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 {
  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]

Next, we’ll add some code to show a message when another user is typing.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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.

```tsx file="pages/index.tsx"
import {
  LiveblocksProvider,
  RoomProvider,
  ClientSideSuspense,
  useOthers,
  useUpdateMyPresence,
} from "@liveblocks/react/suspense";
import { useState } from "react";

/* 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]

<Banner title="Need help troubleshooting 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

<Figure>
  <Image
    src="/assets/tutorials/todo-list/tutorial-todo-list-dashboard.png"
    alt="Liveblocks dashboard"
    width={1380}
    height={778}
  />
</Figure>

## 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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 to-do list tutorials:

- [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]

In order to use Liveblocks, we’ll need to sign up and get an API key.
[Create an account](/api/auth/signup), then navigate to
[the dashboard](/dashboard/apikeys) to find your public key (it starts with
`pk_`).

<Banner title="Public vs secret key">

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";

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: [
      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]

<Banner title="Need help troubleshooting presence?">

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-2.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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 {
  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]

Next, we'll add some code to show a message when another user is typing.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    setDraft: (state, action) => {
      state.isTyping = action.payload === "" ? false : true;
      state.draft = action.payload;
    },
  },
});

export const { setDraft } = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      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]);

  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))}
      ></input>
      <SomeoneIsTyping />
    </div>
  );
}
```

## Sync and persist to-dos [#add-liveblocks-storage]

<Banner title="Need help troubleshooting 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    setDraft: (state, action) => {
      state.isTyping = action.payload === "" ? false : true;
      state.draft = action.payload;
    },
    addTodo: (state) => {
      state.isTyping = false;
      state.todos.push({ text: state.draft });
      state.draft = "";
    },
    deleteTodo: (state, action) => {
      state.todos.splice(action.payload, 1);
    },
  },
});

export const { setDraft, addTodo, deleteTodo } = slice.actions;

export function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      liveblocksEnhancer({
        client,
        storageMapping: { todos: true },
        presenceMapping: { isTyping: true },
      }),
    ],
  });
}

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

<Figure>
  <Image
    src="/assets/tutorials/todo-list/tutorial-todo-list-dashboard.png"
    alt="Liveblocks dashboard"
    width={1380}
    height={778}
  />
</Figure>

## 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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 to-do
list tutorials:

- [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]

In order to use Liveblocks, we’ll need to sign up and get an API key.
[Create an account](/api/auth/signup), then navigate to
[the dashboard](/dashboard/apikeys) to find your public key (it starts with
`pk_`).

<Banner title="Public vs secret key">

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.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.

```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 collaborative 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 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]

<Banner title="Need help troubleshooting presence?">

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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-2.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

```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);

  return (
    <div className="who_is_here">
      There are {othersUsersCount} other users online
    </div>
  );
}

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">
      <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 {
  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]

Next, we'll add some code to show a message when another user is typing.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-3.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

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 Zustand store, `draft` will contain the value of
the input. `isTyping` will be set when the user is writing a draft.

The middleware option
[`presenceMapping: { isTyping: true }`](/docs/api-reference/liveblocks-zustand#middleware-option-presence-mapping)
means that we want to automatically sync the part of the state named `isTyping`
to Liveblocks Presence.

```ts highlight="7-9,19-21,25" 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 = {
  draft: string;
  isTyping: boolean;
  setDraft: (draft: string) => void;
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      draft: "",
      isTyping: false,
      setDraft: (draft) => set({ draft, isTyping: draft !== "" }),
    }),
    {
      client,
      presenceMapping: { isTyping: true },
    }
  )
);

export default useStore;
```

Now that we set the `isTyping` state when necessary, create a new component
called `SomeoneIsTyping` to display a message when at least one other user has
`isTyping` equals to `true`.

```tsx highlight="8-16,20-21,35-42" file="src/App.tsx"
import React, { useEffect } from "react";
import useStore from "./store";

import "./App.css";

/* WhoIsHere */

function SomeoneIsTyping() {
  const others = useStore((state) => state.liveblocks.others);

  const someoneIsTyping = others.some((user) => user.presence.isTyping);

  return someoneIsTyping ? (
    <div className="someone_is_typing">Someone is typing</div>
  ) : null;
}

export default function App() {
  const {
    draft,
    setDraft,
    liveblocks: { enterRoom, leaveRoom },
  } = useStore();

  useEffect(() => {
    enterRoom("zustand-todo-app");
    return () => {
      leaveRoom("zustand-todo-app");
    };
  }, [enterRoom, leaveRoom]);

  return (
    <div className="container">
      <WhoIsHere />
      <input
        className="input"
        type="text"
        placeholder="What needs to be done?"
        value={draft}
        onChange={(e) => setDraft(e.target.value)}
      ></input>
      <SomeoneIsTyping />
    </div>
  );
}
```

## Sync and persist to-dos [#add-liveblocks-storage]

<Banner title="Need help troubleshooting 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.

<Figure>
  <video autoPlay loop muted playsInline>
    <source
      src="/assets/tutorials/todo-list/tutorial-todo-list-1.mp4"
      type="video/mp4"
    />
  </video>
</Figure>

Add an array of todos to your Zustand store, and tell the middleware to sync and
persist them with Liveblocks.

To achieve that, we are going to use the middleware option
[`storageMapping: { todos: true }`](/docs/api-reference/liveblocks-zustand#middleware-option-storage-mapping).
It means that the part of the state named `todos` should be automatically synced
with Liveblocks Storage.

```ts highlight="6,8-9,19,21-29,34" file="src/store.ts"
/* ... */

type State = {
  draft: string;
  isTyping: boolean;
  todos: { text: string }[];
  setDraft: (draft: string) => void;
  addTodo: () => void;
  deleteTodo: (index: number) => void;
};

/* ... */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      draft: "",
      isTyping: false,
      todos: [],
      setDraft: (draft) => set({ draft, isTyping: draft !== "" }),
      addTodo: () =>
        set((state) => ({
          todos: state.todos.concat({ text: state.draft }),
          draft: "",
        })),
      deleteTodo: (index) =>
        set((state) => ({
          todos: state.todos.filter((_, i) => index !== i),
        })),
    }),
    {
      client,
      presenceMapping: { isTyping: true },
      storageMapping: { todos: true },
    }
  )
);

export default useStore;
```

We can display the list of todos and use the functions `addTodo` and
`deleteTodo` to update our list:

```tsx highlight="13-15,39-43,46-60" file="src/App.tsx"
import React, { useEffect } from "react";
import useStore from "./store";

import "./App.css";

/* WhoIsHere */
/* SomeoneIsTyping */

export default function App() {
  const {
    draft,
    setDraft,
    todos,
    addTodo,
    deleteTodo,
    liveblocks: { enterRoom, leaveRoom, isStorageLoading },
  } = useStore();

  useEffect(() => {
    enterRoom("zustand-todo-app");
    return () => {
      leaveRoom("zustand-todo-app");
    };
  }, [enterRoom, leaveRoom]);

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

  return (
    <div className="container">
      <WhoIsHere />
      <input
        className="input"
        type="text"
        placeholder="What needs to be done?"
        value={draft}
        onChange={(e) => setDraft(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            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={() => {
                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).

<Figure>
  <Image
    src="/assets/tutorials/todo-list/tutorial-todo-list-dashboard.png"
    alt="Liveblocks dashboard"
    width={1380}
    height={778}
  />
</Figure>

## Next steps

- [API reference](/docs/api-reference/liveblocks-zustand)
- [Authentication](/docs/authentication)

---
meta:
  title: "How to create a notification settings panel"
  description:
    "Learn how to create a notifications preference interface, allowing users to
    choose which notifications they should receive."
---

[Notifications](/docs/ready-made-features/notifications) allows you to add
in-app notifications to your product. However, it also allows you to send unread
notifications via other channels, such as email, Slack, Microsoft Teams—an
effective way to link back to your app and keep users engaged.

Additionally, Liveblocks allows your end users to individually choose which
notifications they should receive, and on which channel. This guide shows you
how to create a notification preferences panel, which enables this.

<Figure>
  <Image
    src="/assets/notifications/notification-settings.jpg"
    alt="Notification settings"
    width={1344}
    height={896}
  />
</Figure>

## Set up webhooks first

Before starting, it’s important that you’ve already set up a notification
channel in our dashboard, and set up a webhook endpoint. Here are two guides
that take you through how to do this:

- [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).

## Enabling a notification channel

If you’ve followed one of the previous guides, you should already have enabled a
notification kind for a certain channel in the Notifications dashboard (this is
different to setting up a webhook), however if you already have a production
project, make sure of
[what to check before enabling a notification kind](/docs/guides/what-to-check-before-enabling-a-new-notification-kind)
before continuing, as you may change the behavior of your app.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-click-notifications.png"
    alt="Notifications dashboard page"
    width={712}
    height={445}
  />
</Figure>

Each notification channel has a unique identifier, such as `email` or `slack`,
but they all function in the same way. These distinct names allow developers to
customize notifications for different platforms.

## Building the interface

Now that the back end’s set up, you can use Liveblocks hooks to build the
interface. Each user in your app can set their own preferences for
notifications, and after enabling a notification kind, each user’s will be set
to the default value in the Notifications dashboard.

With
[`useNotificationSettings`](/docs/api-reference/liveblocks-react#useNotificationSettings)
you can see the default value in your app. For example, the value if thread
notifications on the email channel are enabled:

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

function NotificationSettings() {
  // +++
  const [{ isLoading, error, settings }, updateSettings] =
    useNotificationSettings();
  // +++

  if (isLoading || error) {
    return null;
  }

  // +++
  // { email: { thread: true } }
  console.log(settings);
  // +++
}
```

You can also use this function to toggle values—**this will disable
corresponding webhook events for the current user, meaning they no longer
receive notifications of that type, on that channel**. All other webhook events
are sent as normal, only the current user is affected. Here’s how to create a
checkbox that toggles the current user’s email/thread setting, disabling the
corresponding webhook.

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

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

  if (isLoading || error) {
    return null;
  }

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

Also make sure to check if the notification kind is enabled before creating the
UI. This way, if it’s toggled in the dashboard, it will gracefully
disappear/reappear. We’re doing this above by checking if `settings.email`
exists before displaying the `input`.

### Custom notification kinds

You can also use
[custom notification kinds](/docs/ready-made-features/notifications/concepts#Custom-notifications)
as highlighted below, where we’re using a custom `$documentInvite` kind.

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

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

  if (isLoading || error) {
    return null;
  }

  return (
    <>
      {settings.email ? (
        <>
          // +++
          <label>
            Receive document invites notifications by email
            <input
              type="checkbox"
              checked={settings.email.$documentInvite}
              onChange={(e) =>
                updateSettings({ email: { $documentInvite: e.target.checked } })
              }
            />
          </label>
          // +++
          <label>
            Receive thread notifications by email
            <input
              type="checkbox"
              checked={settings.email.thread}
              onChange={(e) =>
                updateSettings({ email: { thread: e.target.checked } })
              }
            />
          </label>
        </>
      ) : null}
    </>
  );
}
```

Note that you can
[type your app](/docs/api-reference/liveblocks-react#Typing-your-data) to
receive hints for custom notifications.

```tsx file="liveblocks.config.ts"
declare global {
  interface Liveblocks {
    // Custom activities data for custom notification kinds
    ActivitiesData: {
      // +++
      $documentInvite: {
        documentId: string; // Example
      };
      // +++
    };

    // ...
  }
}
```

### Extend it further

If you extend this further, you can create a whole notifications settings panel,
with settings for each notification kind on channel. Below we’ve created an
interface with three kinds of two channels, email and Slack. Like with
`settings.email`, we’re also checking if `settings.slack` exists before using
it.

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

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

  if (isLoading || error) {
    return null;
  }

  return (
    <>
      {settings.email ? (
        <>
          <label>
            Receive document invites notifications by email
            <input
              type="checkbox"
              checked={settings.email.$documentInvite}
              onChange={(e) =>
                updateSettings({ email: { $documentInvite: e.target.checked } })
              }
            />
          </label>
          <label>
            Receive thread notifications by email
            <input
              type="checkbox"
              checked={settings.email.thread}
              onChange={(e) =>
                updateSettings({ email: { thread: e.target.checked } })
              }
            />
          </label>
          <label>
            Receive text mentions notifications by email
            <input
              type="checkbox"
              checked={settings.email.textMention}
              onChange={(e) =>
                updateSettings({ email: { textMention: e.target.checked } })
              }
            />
          </label>
        </>
      ) : null}

      {settings.thread ? (
        <>
          <label>
            Receive document invites notifications on Slack
            <input
              type="checkbox"
              checked={settings.slack.$documentInvite}
              onChange={(e) =>
                updateSettings({ slack: { $documentInvite: e.target.checked } })
              }
            />
          </label>
          <label>
            Receive thread notifications on Slack
            <input
              type="checkbox"
              checked={settings.slack.thread}
              onChange={(e) =>
                updateSettings({ slack: { thread: e.target.checked } })
              }
            />
          </label>
          <label>
            Receive text mentions notifications on Slack
            <input
              type="checkbox"
              checked={settings.slack.textMention}
              onChange={(e) =>
                updateSettings({ slack: { textMention: e.target.checked } })
              }
            />
          </label>
        </>
      ) : null}
    </>
  );
}
```

You now have a notification settings interface that allows each user to choose
their own settings! This works by toggling webhooks on specific channels and
kinds.

## Other methods

Should you need to access and modify user notification settings outside of
React, we also provide
[JavaScript functions](/docs/api-reference/liveblocks-client#Client.getNotificationSettings),
[Node.js methods](/docs/api-reference/liveblocks-node#get-users-userId-notification-settings),
and
[REST API endpoints](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-users-userId-notification-settings).

---
meta:
  title: "How to filter rooms using query language"
  description:
    "Learn how to filter for certain rooms using their names and metadata with
    our query language"
---

When retrieving rooms with our REST API, it’s possible to filter for specific
threads using [custom metadata](/docs/ready-made-features/comments/metadata) and
room ID prefixes using our custom query language. This enables the
[Get Rooms REST API](/docs/api-reference/rest-api-endpoints#get-rooms) to have
filtering that works the same as with
[`liveblocks.getRooms`](/docs/api-reference/liveblocks-node#get-rooms).

## Query language

You can filter rooms by their metadata and room ID prefixes, which is helpful
when you’re using a
[naming pattern](/docs/authentication/access-token#Naming-pattern) for your
rooms. Filters can be combined using `AND` logic.

```js
// Rooms with IDs that begin with "liveblocks:"
roomId^'liveblocks:'

// Rooms with { roomType: 'whiteboard' } string metadata
metadata['roomType']:'whiteboard'

// Combine queries with AND
roomId^'liveblocks:' AND metadata['roomType']:'whiteboard'

// Use multiple metadata filters at once
metadata['roomType']:'whiteboard' AND metadata['creator']:'florent'
```

<Banner>

The `AND` is optional and can actually be omitted, but we’re using it here for
clarity.

</Banner>

Note that room metadata can contain `strings` or `arrays`, but only `strings`
can be filtered. If you wish to return a single specific room, instead use the
[Get Room API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId) or
[`liveblocks.getRoom`](/docs/api-reference/liveblocks-node#get-rooms-roomId).

### How to use

To use the query language with the
[REST API](/docs/api-reference/rest-api-endpoints#get-rooms) pass your query
string to the `query` parameter. For example, given this query:

```js
roomId^'liveblocks:' AND metadata['roomType']:'whiteboard'
```

Encode it, and add it to the `query` parameter:

```
https://api.liveblocks.io/v2/rooms?query=roomId%5E'liveblocks%3A'%20AND%20metadata%5B'roomType'%5D%3A'whiteboard'
```

To learn more on _setting_ custom metadata on rooms, make sure to
[read our guide](/docs/rooms/metadata).

---
meta:
  title: "How to filter threads with query language"
  description:
    "Learn how to filter for certain threads using their metadata with our query
    language"
---

When using Comments and retrieving threads with our REST API, it’s possible to
filter for specific threads using
[custom metadata](/docs/ready-made-features/comments/metadata) and our custom
query language. This enables the
[Get Threads REST API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads)
to have filtering that works the same as with
[`useThreads`](/docs/api-reference/liveblocks-react#useThreads) and
[`liveblocks.getThreads`](/docs/api-reference/liveblocks-node#get-rooms-roomId-threads).

## Query language

You can filter threads by their metadata, allowing you to select for certain
properties, values, or even for string prefixes. Filters can be combined using
`AND` logic.

```js
// Resolved threads
resolved:true

// Threads with { status: 'open' } string metadata
metadata['status']:'open'

// Threads with `{ org }` string metadata that starts with "liveblocks:"
metadata['org']^'liveblocks:'

// Threads with { priority: 3 } number metadata
metadata['priority']:3

// Threads with { pinned: false } boolean metadata
metadata['pinned']:false

// Threads without a `color` property
metadata['color']:null

// Combine queries with AND
resolved:true AND metadata['priority']:3

// A more complex combination
metadata['status']:'closed' AND metadata['org']^'liveblocks:'
```

<Banner>

The `AND` is optional and can actually be omitted, but we’re using it here for
clarity.

</Banner>

### How to use

To use the query language with the
[REST API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads) pass
your query string to the `query` parameter. For example, given this query:

```js
metadata['status']:'open' AND metadata['priority']:3
```

Encode it, and add it to the `query` parameter:

```
https://api.liveblocks.io/v2/rooms/{roomId}/threads?query=metadata%5B'status'%5D%3A'open'%20AND%20metadata%5B'priority'%5D%3A3
```

To learn more on _setting_ custom metadata on threads, make sure to
[read our guide](/docs/ready-made-features/comments/metadata).

---
meta:
  title: "Grant access to individual rooms with access tokens"
  description:
    "Learn how to grant access to individual rooms with access tokens"
---

<Banner title="Looking for more complex permissions?" type="warning">

If you’re looking to build an application with permissions at organization,
group, and user levels, we recommend using
[ID tokens](/docs/authentication/id-token) instead. Access tokens have
[limitations when granting nested permissions](#limitations).

</Banner>

With [access tokens](/docs/authentication/access-token) we always recommend
using a [naming pattern](/docs/authentication/access-token#Naming-pattern) to
grant access to multiple rooms at once, for example every room in a user’s
organization.

```ts
// ✅ Grants access to every `acme` organization room
session.allow(`session.allow(`acme:*`, session.FULL_ACCESS);
```

However, it may not always be possible to grant access to every room with a
wildcard and naming pattern. One example would be if a user is invited to _only
one room_ in a _different_ organization. There’s a way to work around this
limitation.

## Grant access to individual rooms

When using
[`authEndpoint`](/docs/api-reference/liveblocks-client#createClientAuthEndpoint),
Liveblocks provides the current room ID in the `request`. Below is a Next.js
example, where the current room ID is taken from the body, and the user is
allowed access to the room. Note that `room` is `undefined` when
[Notifications](/docs/ready-made-features/comments/email-notifications) is
authenticating, which is why we’re checking if it exists. Notifications works
across rooms, and it doesn’t require any permissions.

```tsx highlight="17,19-21"
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});

export async function POST(request: Request) {
  // 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
  );

  const { room } = request.body;

  if (room && __shouldUserHaveAccess__(user, room)) {
    session.allow(room, session.FULL_ACCESS);
  }

  // Authorize the user and return the result
  const { status, body } = await session.authorize();
  return new Response(body, { status });
}
```

This approach relies on you creating the `__shouldUserHaveAccess__` function,
and determining whether the user is allowed inside the room.

---
meta:
  title: "How to migrate to Liveblocks Comments"
  description:
    "Learn how to import your threads, comments, and reaction to Liveblocks
    Comments in this migration guide."
---

To migrate your threads, comments, and reactions to Liveblocks Comments, you can
create a migration script using our
[Node.js methods](https://liveblocks.io/docs/api-reference/liveblocks-node) or
[REST API](https://liveblocks.io/docs/api-reference/rest-api-endpoints). This
guide will take you through all the Liveblocks features required to create a
migration script in Node.js. Note that each Node.js method also has an
equivalent REST API which could be used instead.

<Banner title="Before starting" type="warning">

Before starting to migrate, make sure to
[set up authentication](https://liveblocks.io/docs/authentication) in your app,
deciding on either _ID tokens_ or _access tokens_.

</Banner>

## Creating rooms

The first step is to create the multiplayer room where the comments are stored.
This is equivalent to a document in your project. Make sure to read the sections
on permissions under
[access tokens](/docs/authentication/access-token#permissions) or
[ID tokens](/docs/authentication/id-token#permissions) to fully understand
setting up your room.

Create a room using
[`liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms) or the
[Create Room API](/docs/api-reference/rest-api-endpoints#post-rooms), and set
permissions if you’re using ID tokens.

```ts
// The unique ID for the room
const roomId = "my-room-id";

// Create a room
const room = await liveblocks.createRoom(roomId, {
  // If you're using ID tokens, set your permissions/accesses, examples below
  defaultAccesses: [
    // "room:write"`
  ],
  // groupsAccesses: {
  //   my-group: ["room:write"]
  // }
  // usersAccesses: {
  //   my-user: ["room:write"]
  // }
});
```

## Creating threads

Next up is creating threads in the room. Before starting, make sure you
understand the
[concepts behind Comments](/docs/ready-made-features/comments/concepts). When a
thread is created, the first comment is also created, and you can do this with
[`liveblocks.createThread`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads)
or the
[Create Thread API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads).

```ts
// The unique ID for the room
const roomId = "my-room-id";

// Create a room
const room = await liveblocks.createRoom(roomId, {
  defaultAccesses: [],
});

//+++
// Create a thread
const thread = await liveblocks.createThread({
  roomId,

  data: {
    comment: {
      // ID of the user that created the thread
      userId: "florent@example.com",

      body: {
        version: 1,
        content: [
          // The initial comment's body text goes here
          // {
          //   type: "paragraph",
          //   children: [{ text: "Hello " }, { text: "world", bold: true }],
          // },
        ],
      },
    },
  },
});
// +++
```

Read under
[`liveblocks.createThread`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads)
to learn how to create a Comment body, and check in
[GitHub](https://github.com/liveblocks/liveblocks/blob/64a2f5707785b95b1f56d7ff3b53a234dfc9ccd7/packages/liveblocks-core/src/protocol/Comments.ts#L55)
for information about each comment body element.

## Adding further comments

To add more comments to the new thread, use
[`liveblocks.createComment`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments)
or the
[Create Comment API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments).
We’re just sharing a simple code snippet below, but of course, we recommend you
use a loop.

```ts
// The unique ID for the room
const roomId = "my-room-id";

// Create a room
const room = await liveblocks.createRoom(roomId, {
  defaultAccesses: [],
});

// Create a thread
const thread = await liveblocks.createThread({
  /* ... */
});

// +++
// Adding a comment to the existing thread
const comment = await liveblocks.createComment({
  roomId,
  threadId: thread.id,

  data: {
    // ID of the user that created the comment
    userId: "pierre@example.com",

    // Optional, when the comment was created
    createdAt: new Date(),

    body: {
      version: 1,
      content: [
        // The comment's body text goes here
        // {
        //   type: "paragraph",
        //   children: [{ text: "Hello " }, { text: "world", bold: true }],
        // },
      ],
    },
  },
});
// +++
```

## Adding reactions

To add reactions to each comment, use
[`liveblocks.addCommentReaction`](/docs/api-reference/liveblocks-node#post-rooms-roomId-threads-threadId-comments-commentId-add-reaction)
or the
[Add Comment Reaction API](/docs/api-reference/rest-api-endpoints#post-rooms-roomId-threads-threadId-comments-commentId-add-reaction).

```ts
// The unique ID for the room
const roomId = "my-room-id";

// Create a room
const room = await liveblocks.createRoom(roomId, {
  defaultAccesses: [],
});

// Create a thread
const thread = await liveblocks.createThread({
  /* ... */
});

// Adding a comment to the existing thread
const comment = await liveblocks.createComment({
  /* ... */
});

// +++
// Add a reaction to a comment
const reaction = await liveblocks.addCommentReaction({
  roomId,
  threadId: thread.id,
  commentId: comment.id,

  data: {
    // The reaction emoji
    emoji: "✅",

    // ID of the user that reacted
    userId: "guillaume@example.com",

    // Optional, the time the reaction was added
    createdAt: new Date(),
  },
});
// +++
```

## Migrating users

There’s no need to migrate users to Comments, as the only user information
Liveblocks stores
[is each user’s ID](/docs/ready-made-features/comments/users-and-mentions).
Other user info is retrieved in-app by Comments with
[`resolveUserInfo`](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers).

## Putting it together

To create a migration script, put everything together and loop through all the
functions we’ve listed above. Below is an example of a migration script, though
you’ll need to make changes based on the format of the comment system you’re
migrating from. `oldDocumentId` and `oldDocumentThreads` represent your current
data.

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

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

async function migrateDocument({ oldDocumentId, oldDocumentThreads }) {
  console.log(`Migrating document: ${oldDocumentId}`);

  // The unique ID for the room
  const roomId = oldDocumentId;

  // Create a Liveblocks room
  const room = await liveblocks.createRoom(roomId, {
    // If you're using ID tokens, set your permissions/accesses, examples below
    defaultAccesses: [
      // "room:write"`
    ],
    // groupsAccesses: {
    //   my-group: ["room:write"]
    // }
    // usersAccesses: {
    //   my-user: ["room:write"]
    // }
  });

  // Loop through your existing threads for the current room
  for (const oldThread of oldDocumentThreads) {
    const [firstComment, ...otherComments] = oldThread.comments;

    // Create a Liveblocks thread
    const thread = await liveblocks.createThread({
      roomId: room.id,

      data: {
        comment: {
          // ID of the user that created the thread
          userId: firstComment.userId,

          body: {
            version: 1,
            content: __convertCommentToLiveblocksFormat__(firstComment.body),
          },
        },
      },
    });

    // Loop through this existing thread's comments
    for (const oldComment of otherComments) {
      // Create a Liveblocks comment
      const comment = await liveblocks.createComment({
        roomId: room.id,
        threadId: thread.id,

        data: {
          // ID of the user that created the comment
          userId: oldComment.userId,

          // Optional, when the comment was created
          createdAt: new Date(oldComment.timestamp),

          body: {
            version: 1,
            content: __convertCommentToLiveblocksFormat__(oldComment.body),
          },
        },
      });

      // Loop through this existing comment's reactions
      for (const oldReaction of oldComment.reactions) {
        // Add a reaction to a Liveblocks comment
        await liveblocks.addCommentReaction({
          roomId: room.id,
          threadId: thread.id,
          commentId: comment.id,

          data: {
            // The reaction emoji
            emoji: oldReaction.emoji,

            // ID of the user that reacted
            userId: oldReaction.userId,

            // Optional, the time the reaction was added
            createdAt: new Date(oldReaction.timestamp),
          },
        });
      }
    }
  }

  console.log(`Document migrated: ${oldDocumentId}`);
}
```

---
meta:
  title: "How to modify Liveblocks Storage from the server"
  description:
    "Learn about the different methods you can use to modify Liveblocks Storage
    within Node.js"
---

In realtime applications, Liveblocks Storage is generally modified from the
browser with [`useMutation`](/docs/api-reference/liveblocks-react#useMutation)
or through
[conflict-free data methods](/docs/api-reference/liveblocks-client#Storage).
However, sometimes it can be useful to modify your realtime storage from
server-side Node.js too.

## What we’re building

In this guide, we’ll be building a function that allows you to easily modify
storage from the server. We’ll do this by running `@liveblocks/client`
server-side using Node.js polyfills, and by signing in with a service account
`userId`.

<Banner title="This solution has caveats" type="warning">

When using this solution, the service account user will appear in presence, and
you must account for this in your front end (e.g. filtering out the service
account when displaying live avatars). We are investigating other solutions, and
hope to provide a superior API in future.

</Banner>

```ts
await modifyStorage("my-room-name", (root) => {
  root.get("list").push("item3");
});
```

## Set up Liveblocks server config

<Banner title="Liveblocks already set up">

This tutorials assumes you’ve already set up Liveblocks on the client-side, and
you’ve created a `liveblocks.config.ts` file containing your types.

</Banner>

The first thing we need to do is to install the required Node.js polyfills.

```bash
npm i node-fetch ws
```

After this we can create a server config file, which we’ll name
`liveblocks.server.config.ts`. In this file we’re implementing the following.

<Steps>
  <StepCompact>Creating a node client with `new Liveblocks`.</StepCompact>
  <StepCompact>
    Creating a regular client to be used on the server, `serverClient`.
  </StepCompact>
  <StepCompact>Authenticating inside the regular client.</StepCompact>
  <StepCompact>
    Using the same `userId` for server changes, so that MAUs do not increase.
  </StepCompact>
  <StepCompact>Adding Node.js polyfills to the regular client.</StepCompact>
  <StepCompact lastStep>Creating a typed enter room function.</StepCompact>
</Steps>

Here’s the full file:

```ts file="liveblocks.server.config.ts"
import { createClient } from "@liveblocks/client";
import { Liveblocks } from "@liveblocks/node";
import fetch from "node-fetch";
import WebSocket from "ws";

// 1. Creating a node client
const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

// 2. Creating a regular client
export const serverClient = createClient({
  // 3. Authenticating inside the client
  authEndpoint: async (room) => {
    const session = liveblocks.prepareSession(
      // 4. Using a specific userId for all server changes
      "_SERVICE_ACCOUNT"
    );
    session.allow(room, session.FULL_ACCESS);
    const { body } = await session.authorize();
    return JSON.parse(body);
  },

  // 5. Adding polyfills
  polyfills: {
    fetch: fetch as any,
    WebSocket,
  },
});

// 6. Creating a typed enter room function
export const enterRoom = (roomId: string) => {
  return serverClient.enter(roomId, {
    // Match the options in your browser code
  });
};
```

## Create the modify storage function

Using `serverClient` and `enterRoom` from the previous file, we can create a
typed `modifyStorage` function that allows us to join a room, modify storage
(batching all changes into one request), before leaving the room.

```ts
import type { LiveObject } from "@liveblocks/client";
import { enterRoom } from "./liveblocks.server.config";

export async function modifyStorage(
  roomId: string,
  storageChanges: (root: LiveObject<Liveblocks["Storage"]>) => void
) {
  const roomContext = enterRoom(roomId);
  const { room } = roomContext;
  const { root } = await room.getStorage();

  // Make storage adjustments in a batch, so they all happen at once
  room.batch(() => {
    storageChanges(root);
  });

  // If storage changes are not synchronized, wait for them to finish
  if (room.getStorageStatus() !== "synchronized") {
    await room.events.storageStatus.waitUntil(
      (status) => status === "synchronized"
    );
  }

  // Leave when storage has been synchronized
  roomContext.leave();
}
```

Note that the `Liveblocks["Storage"]` type originates from your 
[config file](/docs/api-reference/liveblocks-react#Typing-your-data) and needs
no import.

## Start modifying storage

We can now start modify storage from the server! Import `modifyStorage`, pass a
room name, and use the callback to modify as you like.

```ts file="route.ts" highlight="6-8"
import { modifyStorage } from "./modifyStorage";

export async function POST() {
  console.log("Updating storage");

  await modifyStorage("my-liveblocks-room", (root) => {
    root.get("list").push("item3");
  });

  console.log("Storage update complete!");
}
```

## Account for the service user in your app

Remember to account for the service user appearing in your presence. In our
`liveblocks.server.config.ts` we authenticated with `"_SERVICE_ACCOUNT"` as the
`userId`, so we’ll filter it out when using others in our application.

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

function LiveAvatars() {
  // Others, with the service account filtered out
  const others = useOthers(
    (others) => others.filter((other) => other.id !== "_SERVICE_ACCOUNT"),
    shallow
  );

  // ...
}
```

A `shallow` equality check is necessary here, because `filter` creates a new
array every time.

---
meta:
  title:
    "How to migrate your existing rooms IDs to use access token naming patterns"
  description:
    "Learn how to migrate your current rooms IDs to match access token naming
    patterns."
---

When using [access token authentication](/docs/authentication/access-token) we
recommend using a naming pattern for your room IDs. If you’ve already created
rooms, it’s possible to rename them with `@liveblocks/node` or our REST API.

## Update your room IDs

To rename a room ID, you can use the
[liveblocks.updateRoomId](/docs/api-reference/liveblocks-node#post-rooms-update-roomId)
endpoint to update a room ID.

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

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

const room = await liveblocks.updateRoomId({
  roomId: "my-room-id",
  newRoomId: "new-room-id",
});

// { type: "room", id: "new-room-id", ... }
console.log(room);
```

When you change a room ID, currently connected users will disconnect, but there
is a way around this.

## Handle active users connected to a room

To avoid users disconnecting after the change, you can listen for a room ID
changed error, `4006`, with
[`useErrorListener`](/docs/api-reference/liveblocks-react#useErrorListener) or
[`room.subscribe("error")`](/docs/api-reference/liveblocks-client#Room.subscribe.error).
This error is sent immediately after the ID is changed, and it returns the new
room ID inside `error.message`. You can use this the new ID to redirect users to
the new location of the room in your application.

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

function App() {
  useErrorListener((error) => {
    if (error.code === 4006) {
      // Room ID has been changed, get the new ID and redirect
      const newRoomId = error.message;
      __redirect__(`https://example.com/document/${newRoomId}}`);
    }
  });
}
```

After implementing this, you can safely update the room ID, and users will be
immediately redirected to the new location.

---
meta:
  title: "How to send email notifications for unread text editor mentions"
  description:
    "Learn how to automatically send email notifications when a text mention or
    is created with Liveblocks Text Editor."
---

Liveblocks allows you to embed a text editing experience with
[Text Editor](/docs/ready-made-features/text-editor) using Tiptap or Lexical.
Using our webhooks and REST API, it’s possible get unread text mentions and use
them to email users when they’re mentioned in a document. Notifications can also
be displayed in your app using
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
and the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component.

<Figure>
  <Image
    src="/assets/emails/new-text-mention-email.png"
    alt="An email showing a text mention in a text editor document"
    width={1126}
    height={470}
  />
</Figure>

<Banner title="Ready-made email templates">

We have two examples containing ready-made email templates, built with React
Email. These are great starting points for your Text Editor notification emails:
[Tiptap emails example](/examples/collaborative-text-editor-emails/nextjs-tiptap-emails-resend),
[Lexical emails example](/examples/collaborative-text-editor-emails/nextjs-lexical-emails-resend).

</Banner>

## What we’re building

In this guide we’ll be learning how to send text mentions notifications, and
more specifically, we’ll be looking at how to:

- Trigger events based on unread comments using the
  [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent) webhook
  event.
- Fetch unread text mention and add styles to the surrounding text using the
  [`@liveblocks/emails`](/docs/api-reference/liveblocks-emails) package.
- Send an email notification containing the mention and its surrounding text
  with [Resend](https://resend.com/).

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Text Editor project set up. If
you don’t have one yet, you can get started with
[Lexical](/docs/get-started/text-editor/lexical) or
[Tiptap](/docs/get-started/text-editor/tiptap), and come back after you’re set
up. You could also use our
[ready-made email examples](/examples/collaborative-text-editor-emails) which
have this set up already, along with some email templates.

</Banner>

## What are 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. This makes more sense when
sending email notifications because it helps to avoid flooding your users with
too many emails.

Learn more about Notifications for Lexical Text Editor in the
[overview page](/docs/ready-made-features/text-editor/lexical#Notifications).

## Using webhooks

Liveblocks provides a number of [webhooks](/docs/platform/webhooks) that can
send requests to your API endpoint when certain events occurs. One webhook we
provide is the [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent)
webhook, which is triggered for each mentioned users in a document, 30 minutes
after activity has occurred, and this can be used to send emails to your users.

The information it returns allows you to retrieve a text mention that have not
yet been read by the user. Let’s take a look at how to set this up.

### Notification channels

You can send notifications via different channels, such as email, Slack,
Microsoft Teams, and Web Push. In our dashboard, you can enable notifications on
certain channels, and in this case, we’ll be using the email channel. You must
always enable the correct channel to ensure your
[`NotificationEvent`](/docs/platform/webhooks#NotificationEvent) webhook events
are triggered, and this guide will take you through setting it up.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project. In this guide, we’ll be using a Next.js route handler (API
endpoint) as an example, but other frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and notifications
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-notifications
```

Make a note of this endpoint URL, as you’ll be using it later.

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-notifications

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-notifications
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when a comment
has been created.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the notifications dashboard</StepTitle>
  <StepContent>
    Click on the **“Notifications”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-notifications.png"
        alt="Click notifications"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Enable the textMention notification type</StepTitle>
  <StepContent>
    Click on **“Edit”** at the top right, enable `textMention` notifications on
    the email channel, and publish your changes.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-enable-textMention-notification.png"
        alt="Enable textMention notifications"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your webhook secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={710}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `notification` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Webhook secret key” from the Liveblocks dashboard—in a
real project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Send notifications
  // ...

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

## Check the event and notification permissions

After verifying the request, we can then check we’re receiving the correct type
of event on the correct channel. There are different `notification` events, and
in this case we’d like to check for
[text mention notification](/docs/platform/webhooks#TextMention-notification),
as we’re specifically listening for new text mentions. We can do this using
[`isTextMentionNotificationEvent`](/docs/api-reference/liveblocks-node#isTextMentionNotificationEvent),
making sure to check for the `email` channel.

```ts
import {
  WebhookHandler,
  isTextMentionNotificationEvent,
} from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 on the email channel
  if (isTextMentionNotificationEvent(event) && event.data.channel === "email") {
    // 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);

    // Send notifications
    // ...
  }
  // +++

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

Note that we’re also checking if the user should receive a notification, and
getting their email address—Liveblocks doesn’t have knowledge of your
permissions system on the back end, so it’s your responsibility to check if this
user should have access to the room.

## Fetching data for emails

[`@liveblocks/emails`](/docs/api-reference/liveblocks-emails) provides functions
for fetching unread text mentions and styling emails, returning them as either
React components or an HTML string. In this guide we’ll use the React function,
but the HTML function works almost identically, so you can still follow along if
you’d prefer HTML emails.

First set up your
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client and wrap
[`prepareTextMentionNotificationEmailAsReact`](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react)
in `try/catch`, getting the data for the email.

<Banner>

If you’d prefer your email content as an HTML string, use
[`prepareTextMentionNotificationEmailAsHtml`](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-html).

</Banner>

```ts
import {
  // +++
  Liveblocks,
  // +++
  WebhookHandler,
  isTextMentionNotificationEvent,
} from "@liveblocks/node";
// +++
import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails";
// +++

// 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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isTextMentionNotificationEvent(event) && event.data.channel === "email") {
    // 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 prepareTextMentionNotificationEmailAsReact(
        liveblocks,
        event
      );
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch text mention notification data", {
        status: 500,
      });
    }

    // The text mention has already been read
    if (!emailData) {
      return new Response(null, { status: 200 });
    }

    // Create email
    // ...
    // +++
  }

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

## Create the emails

Next, we need to create the emails with React, using `emailData` to build the
content.

```tsx
import {
  Liveblocks,
  WebhookHandler,
  isTextMentionNotificationEvent,
} from "@liveblocks/node";
import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails";

// 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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isTextMentionNotificationEvent(event) && event.data.channel === "email") {
    // 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 prepareTextMentionNotificationEmailAsReact(
        liveblocks,
        event
      );
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch text mention notification data", {
        status: 500,
      });
    }

    // The text mention has already been read
    if (!emailData) {
      return new Response(null, { status: 200 });
    }

    // +++
    const email = (
      <div>
        <div>
          @{emailData.mention.author.id} at {emailData.mention.createdAt}
        </div>
        <div>{emailData.mention.reactContent}</div>
      </div>
    );
    // +++

    // Send emails
    // ...
  }

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

## Resolving data

We’ve now fully created a basic React email, and it’s ready to send. However,
we’re displaying each user’s ID, and not their names. We can go back to
[`prepareTextMentionNotificationEmailAsReact`](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react)
and use resolver functions to transform an ID into a name, for example
`chris@example.com` -> `Chris`. These functions work similarly to
[resolvers on the client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers).

```tsx
// ...

emailData = await prepareTextMentionNotificationEmailAsReact(
  liveblocks,
  event,
  {
    // +++
    resolveUsers: async ({ userIds }) => {
      const usersData = await __getUsersFromDB__(userIds);

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

      return {
        name: roomData.name, // "Untitled document"
        url: roomData.url, //`https://example.com/my-room-id`
      };
    },
    // +++
  }
);

// ...
```

## Customizing text mention and surrounding text components

We can also edit `prepareTextMentionNotificationEmailAsReact` to allow for
[custom components](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react-customizing-components)
for the text mention and its surrounding text, for example we can customize the
container, color mentions, and modify fonts.

```tsx
// ...

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

      return usersData.map((userData) => ({
        name: userData.name, // "Chris"
        avatar: userData.avatar.src, // "https://example.com/chris.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: {
      Container: ({ children }) => (
        <main style={{ margin: "12px 0" }}>{children}</main>
      ),

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

      Text: ({ children }) => (
        <p style={{ fontSize: "16px", fontStyle: "italic" }}>{children}</p>
      ),
    },
    // +++
  }
);

// ...
```

Any component can be passed here, including those used in
[`react-email`](https://react.email/),
[learn more](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-react-customizing-components).

<Banner>

If you’re using HTML instead of React, you can
[apply custom CSS properties](/docs/api-reference/liveblocks-emails#prepare-text-mention-notification-email-as-html-styling-elements).

</Banner>

## Send notification emails

Now that the React code has been generated, we can send the notification emails.
[Resend](https://resend.com) is a great tool for easily sending emails, and in
this code example, we’re using it to send notifications to each user. Make sure
to add your API key from the [Resend dashboard](https://resend.com/overview)
before running the code.

```tsx
import {
  Liveblocks,
  WebhookHandler,
  isTextMentionNotificationEvent,
} from "@liveblocks/node";
import { prepareTextMentionNotificationEmailAsReact } 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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isTextMentionNotificationEvent(event) && event.data.channel === "email") {
    // 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 prepareTextMentionNotificationEmailAsReact(
        liveblocks,
        event,
        {
          resolveUsers: async ({ userIds }) => {
            const usersData = await __getUsersFromDB__(userIds);

            return usersData.map((userData) => ({
              name: userData.name, // "Chris"
              avatar: userData.avatar.src, // "https://example.com/chris.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: {
            Container: ({ children }) => (
              <main style={{ margin: "12px 0" }}>{children}</main>
            ),

            // `user` is the optional data returned from `resolveUsers`
            Mention: ({ element, user }) => (
              <span style={{ color: "red" }}>@{user?.name ?? element.id}</span>
            ),
          },
        }
      );
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch text mention notification data", {
        status: 500,
      });
    }

    // The text mention has already been read
    if (!emailData) {
      return new Response(null, { status: 200 });
    }

    const email = (
      <div>
        <div>
          @{emailData.mention.author.id} at {emailData.mention.createdAt}
        </div>
        <div>{emailData.mention.reactContent}</div>
      </div>
    );

    // +++
    // 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 text mention",
        react: email,
      });
    } catch (err) {
      console.error(err);
    }
    // +++
  }

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

## Allow users to toggle notifications

Using Liveblocks hooks and methods, it’s possible to create a notifications
settings interface, allowing end users to choose which notifications they’d like
to receive, and on which channels, saving their preferences.

<Figure>
  <Image
    src="/assets/notifications/notification-settings.jpg"
    alt="Notification settings"
    width={1344}
    height={896}
  />
</Figure>

Learn more in our guide on
[creating a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).

## Recap

Great, we’re successfully sending email notifications after new text mentions
are created! In this guide we’ve learned:

- How to use [webhooks](/docs/platform/webhooks) and the
  [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent).
- How to use the [`@liveblocks/emails`](/docs/api-reference/liveblocks-emails)
  package to fetch and render unread text mention data.
- How to send email notifications with [Resend](https://resend.com).

---
meta:
  title: "How to send email notifications of unread comments"
  description:
    "Learn how to automatically send email notifications of unread comments."
---

Liveblocks [Comments](/docs/ready-made-features/comments) allows you to build a
commenting experience. With our webhooks and REST API, it’s possible to
aggregate a list of unread comments from the last 30 minutes into a single
email, and send it to your users. Notifications can also be displayed in your
app using
[`useInboxNotifications`](/docs/api-reference/liveblocks-react#useInboxNotifications)
and the
[`InboxNotification`](/docs/api-reference/liveblocks-react-ui#InboxNotification)
component.

<Figure>
  <Image
    src="/assets/emails/new-comments-email.png"
    alt="An email showing 7 new comments, with comment bodies and links to each comment"
    width={1567}
    height={830}
  />
</Figure>

<Banner title="Ready-made email templates">

We have an example containing ready-made email templates, built with React
Email. This a great starting point for your Comments notification emails:
[Comments emails example](/examples/comments-emails/nextjs-comments-emails-resend).
We also have a second example that shows you how to
[send simple HTML emails](/examples/comments-emails/nextjs-comments-emails-sendgrid).

</Banner>

## What we’re building

In this guide we’ll be learning how to send emails notifying users about unread
comments, and more specifically, we’ll be looking at how to:

- Trigger events based on unread comments using the
  [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent) webhook
  event.
- Fetch unread comments and add styles to comment text using the
  [`@liveblocks/emails`](/docs/api-reference/liveblocks-emails) package.
- Send an email notification containing a list of unread comments in thread
  format with [Resend](https://resend.com/).

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Comments project set up. If you
don’t have one yet, you can
[get started with Comments](/docs/get-started/comments), and come back after
you’re set up. You could also use our
[Comments emails example](/examples/comments-emails/nextjs-comments-emails-resend)
which has this set up already, alongside ready-made email templates.

</Banner>

## What are 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).

## Using webhooks

Liveblocks provides a number of [webhooks](/docs/platform/webhooks) that can
send requests to your API endpoint when certain events occurs. One webhook we
provide is the [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent)
webhook, which is triggered for each participating user in a thread, 30 minutes
after activity has occurred, and this can be used to send emails to your users.

The information it returns allows you to retrieve comments that have not yet
been read by the user, making it possible to aggregate multiple unread comments
into a single notification email. Let’s take a look at how to set this up.

### Notification channels

You can send notifications via different channels, such as email, Slack,
Microsoft Teams, and Web Push. In our dashboard, you can enable notifications on
certain channels, and in this case, we’ll be using the email channel. You must
always enable the correct channel to ensure your
[`NotificationEvent`](/docs/platform/webhooks#NotificationEvent) webhook events
are triggered, and this guide will take you through setting it up.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project. In this guide, we’ll be using a Next.js route handler (API
endpoint) as an example, but other frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and notifications
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-notifications
```

Make a note of this endpoint URL, as you’ll be using it later.

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-notifications

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-notifications
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when a comment
has been created.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the notifications dashboard</StepTitle>
  <StepContent>
    Click on the **“Notifications”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-notifications.png"
        alt="Click notifications"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Enable the thread notification type</StepTitle>
  <StepContent>
    Click on **“Edit”** at the top right, enable `thread` notifications on the
    email channel, and publish your changes.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-enable-thread-notification.png"
        alt="Enable thread notifications"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your webhook secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={710}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `notification` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Webhook secret key” from the Liveblocks dashboard—in a
real project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Send notifications
  // ...

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

## Check the event and notification permissions

After verifying the request, we can then check we’re receiving the correct type
of event, on the correct channel. There are different `notification` events, and
in this case we’d like to check for
[thread notification](/docs/platform/webhooks#Thread-notification), as we’re
specifically listening for new comments. We can do this using
[`ThreadNotificationEvent`](/docs/api-reference/liveblocks-node#isThreadNotificationEvent),
making sure to check for the `email` channel.

```ts
import { WebhookHandler, isThreadNotificationEvent } from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 on the email channel
  if (isThreadNotificationEvent(event) && event.data.channel === "email") {
    // 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);

    // Send notifications
    // ...
  }
  // +++

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

Note that we’re also checking if the user should receive a notification, and
getting their email address—Liveblocks doesn’t have knowledge of your
permissions system on the back end, so it’s your responsibility to check if this
user should have access to the room.

## Fetching data for emails

[`@liveblocks/emails`](/docs/api-reference/liveblocks-emails) provides functions
for fetching unread comments and styling emails, returning them as either React
components or an HTML string. In this guide we’ll use the React function, but
the HTML function works almost identically, so you can still follow along if
you’d prefer HTML emails.

<Figure>
  <Image
    src="/assets/emails/new-comments-email.png"
    alt="An email showing 7 new comments, with comment bodies and links to each comment"
    width={1567}
    height={830}
  />
</Figure>

First set up your
[`Liveblocks`](/docs/api-reference/liveblocks-node#Liveblocks-client) Node.js
client and wrap
[`prepareThreadNotificationEmailAsReact`](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react)
in `try/catch`, getting the data for the email.

<Banner>

If you’d prefer your email content as an HTML string, use
[`prepareThreadNotificationEmailAsHtml`](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-html).

</Banner>

```ts
import {
  // +++
  Liveblocks,
  // +++
  WebhookHandler,
  isThreadNotificationEvent,
} from "@liveblocks/node";
// +++
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";
// +++

// 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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isThreadNotificationEvent(event) && event.data.channel === "email") {
    // 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
      );
    } 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 });
    }

    // Create emails
    // ...
    // +++
  }

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

## Create the emails

Next, we need to create the emails with React.
[`prepareThreadNotificationEmailAsReact`](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react)
helps you identify two different thread notification types, _unread replies_ in
a thread, or an _unread mention_ in a comment. We can choose to create different
emails for these cases.

```tsx
import {
  Liveblocks,
  WebhookHandler,
  isThreadNotificationEvent,
} from "@liveblocks/node";
import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails";

// 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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isThreadNotificationEvent(event) && event.data.channel === "email") {
    // 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
      );
    } 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.reactBody}</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.reactBody}</div>
              </div>
            ))}
          </div>
        );
        break;
      }
    }
    // +++

    // Send emails
    // ...
  }

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

## Resolving data

We’ve now fully created a basic React email, and it’s ready to send. However,
we’re displaying each user’s ID, and not their names. We can go back to
[`prepareThreadNotificationEmailAsReact`](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react)
and use resolver functions to transform an ID into a name, for example
`steven@example.com` -> `Steven`. These functions work similarly to
[resolvers on the client](/docs/api-reference/liveblocks-react#LiveblocksProviderResolveUsers).

```tsx
// ...

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

// ...
```

## Customizing comment components

We can also edit `prepareThreadNotificationEmailAsReact` to allow for
[custom components in comment bodies](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react-customizing-components),
for example we can add margin around a paragraph, color mentions, and underline
links.

```tsx
// ...

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

// ...
```

Any component can be passed here, including those used in
[`react-email`](https://react.email/),
[learn more](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-react-customizing-components).

<Banner>

If you’re using HTML instead of React, you can
[apply custom CSS properties](/docs/api-reference/liveblocks-emails#prepare-thread-notification-email-as-html-styling-elements).

</Banner>

## Send notification emails

Now that the React code has been generated, we can send the notification emails.
[Resend](https://resend.com) is a great tool for easily sending emails, and in
this code example, we’re using it to send notifications to each user. Make sure
to add your API key from the [Resend dashboard](https://resend.com/overview)
before running the code.

```tsx
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 = "{{SECRET_KEY}}";
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 on the email channel
  if (isThreadNotificationEvent(event) && event.data.channel === "email") {
    // 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.reactBody}</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.reactBody}</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 });
}
```

## Allow users to toggle notifications

Using Liveblocks hooks and methods, it’s possible to create a notifications
settings interface, allowing end users to choose which notifications they’d like
to receive, and on which channels, saving their preferences.

<Figure>
  <Image
    src="/assets/notifications/notification-settings.jpg"
    alt="Notification settings"
    width={1344}
    height={896}
  />
</Figure>

Learn more in our guide on
[creating a notification settings panel](/docs/guides/how-to-create-a-notification-settings-panel).

## Recap

Great, we’re successfully sending email notifications after new comments are
created! In this guide we’ve learned:

- How to use [webhooks](/docs/platform/webhooks) and the
  [`NotificationEvent`](/docs/platform/webhooks#NotificationEvent).
- How to use the [`@liveblocks/emails`](/docs/api-reference/liveblocks-emails)
  package to fetch and render unread thread data.
- How to send email notifications with [Resend](https://resend.com).

---
meta:
  title: "How to send email notifications when comments are created"
  description:
    "Learn how to automatically send email notifications when a comment or
    thread is created with Liveblocks Comments."
---

Liveblocks allows you to build a commenting experience with
[Comments](/docs/ready-made-features/comments). Using our webhooks and REST API,
it’s possible to send email notifications to users when they’re mentioned in
comments.

<Banner title="You’re probably looking for a different guide" type="warning">

This guide is about sending an email immediately after every comment is posted.
If you’d prefer aggregate multiple notifications into one email, and only notify
users about unread comments, you should read this guide on
[how to send email notifications of unread comments](/docs/guides/how-to-send-email-notifications-of-unread-comments).

</Banner>

## What we’re building

In this guide we’ll be learning how to send comments notifications, and more
specifically, we’ll be looking at how to:

- Trigger events when comments are created using the
  [CommentCreated](/docs/platform/webhooks#CommentCreatedEvent) webhook event.
- Fetch a comment’s data using the
  [@liveblocks/node](/docs/api-reference/liveblocks-node) package.
- Create notifications containing the comment’s
  [formatted text](/docs/guides/how-to-send-email-notifications-when-comments-are-created#Formatting-a-comment's-body).
- Send an email notification with [Resend](https://resend.com/).

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Comments project set up. If you
haven’t already got one, you can
[get started with Comments](/docs/get-started/comments), and come back after
you’re set up. You could also use our
[basic Comments example](/examples/comments/nextjs-comments).

</Banner>

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can send the email. In this guide, we’ll
be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and notifications
  // ...

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

Create this endpoint in your project, and make it available on `localhost`, for
example at the following URL:

```
/api/liveblocks-notifications
```

Make a note of this endpoint URL, as you’ll be using it later.

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-notifications

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-notifications
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when a comment
has been created.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your webhook secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={710}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `commentCreated` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Webhook secret key” from the Liveblocks dashboard—in a
real project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Send notifications
  // ...

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

We can then check we’re receiving the correct type of event, get the data from
the webhook, and handle sending the notification inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 a comment has been created
  if (event.type === "commentCreated") {
    const { roomId, threadId, commentId } = event.data;

    // Send notifications
    // ...
  }

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

We now have the `roomId`, `threadId`, and `commentId` of the created comment,
along with some
[other information](/docs/platform/webhooks#CommentCreatedEvent).

## Get comment and thread data

<Banner title="Threads vs comments">
  Note that a thread is different to a comment—a thread is “top-level”, and each
  thread contains a list of comments. When you create a thread with
  [`useCreateThread`](/docs/api-reference/liveblocks-react#useCreateThread), you
  also create the first comment in the thread.
</Banner>

The next step is to use the
[Liveblocks client](/docs/api-reference/liveblocks-node#Liveblocks-client) from
`@liveblocks/node` to retrieve the entire comment’s data, along with the thread
participants. In Liveblocks Comments, a participant refers to a user that has
commented or been mentioned in a thread—we’ll be sending a notification to each
of these users.

To do this we’ll need to add our project’s secret key to the Liveblocks client,
before awaiting the following functions:
[`getComment`](/docs/api-reference/liveblocks-node#get-comment) and
[`getThreadParticipants`](/docs/api-reference/liveblocks-node#get-thread-participants).

```ts highlight="1,7-9,31-43"
import { Liveblocks, WebhookHandler } from "@liveblocks/node";

// 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 = "{{SECRET_KEY}}";
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 a comment has been created
  if (event.type === "commentCreated") {
    const { roomId, threadId, commentId } = event.data;

    try {
      // Get comment data and participants
      const [comment, { participantIds }] = await Promise.all([
        liveblocks.getComment({ roomId, threadId, commentId }),
        liveblocks.getThreadParticipants({ roomId, threadId }),
      ]);

      // Send notifications
      // ...
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch comment data", { status: 500 });
    }
  }

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

## Formatting a comment’s body

Now that we have the comment data and a list of participants, we have one more
step before sending the notifications—formatting the comment’s text, found
inside `comment.body`. Let’s take a look at how it works for an example comment,
using
[`stringifyCommentBody`](/docs/api-reference/liveblocks-node#stringify-comment-body)
to transform `comment.body`.

<Figure>
  <Image
    src="/assets/comments/comment-body.png"
    alt="Comment with example body: 'Thank you so much @Emil Joyce!', with 'so much' in bold"
    width={1289}
    height={390}
  />
</Figure>

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

// Format comment text into a string
const stringComment = await stringifyCommentBody(comment.body);

// "Thank you so much emil.joyce@example.com!"
console.log(stringComment);
```

As you can see on line 6, we’re converting the body into a plain string, which
means we lose the formatting. We’re also seeing the user’s ID, instead of the
name—this is because we need to provide the user’s information, as the comment
only stores the user’s ID.

By providing two options, we can transform the comment into HTML, keeping the
formatting, and add the user information.

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

// Format comment text into an HTML string
const htmlComment = await stringifyCommentBody(comment.body, {
  // Transform into HTML
  format: "html",

  // Provider user information
  async resolveUsers({ userIds }) {
    // ["emil.joyce@example.com", ...]
    console.log(userIds);

    // Return each user's name
    [{ name: "Emil Joyce" } /*, ... */];
  },
});

// "<p>Thank you <b>so much</b> <span data-mention>@Emil Joyce</span>!</p>"
console.log(stringComment);
```

On line 18, you can now see that we’re creating an HTML string, and using the
mentioned user’s name. Note that you can also easily transform your comment into
Markdown, or a completely custom format, learn more under
[`stringifyCommentBody`](/docs/api-reference/liveblocks-node#stringify-comment-body).

Let’s use this HTML formatting function in our endpoint, getting user
information from your database.

```ts highlight="1,38-50"
import { Liveblocks, WebhookHandler, stringifyCommentBody } from "@liveblocks/node";

// 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 = "{{SECRET_KEY}}";
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 a comment has been created
  if (event.type === "commentCreated") {
    const { roomId, threadId, commentId } = event.data;

    try {
      // Get comment data and participants
      const [comment, { participantIds }] = await Promise.all([
        liveblocks.getComment({ roomId, threadId, commentId }),
        liveblocks.getThreadParticipants({ roomId, threadId }),
      ]);

      // HTML comment body
      const htmlComment = await stringifyCommentBody(comment.body, {
        format: "html",

        async resolveUsers({ userIds }) {
          // Get the correct users from your database
          const users = await __getUsers__(userIds);

          return users.map((user) => ({
            name: user.name,
          });
        },
      });

      // Send notifications
      // ...
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch comment data", { status: 500 });
    }
  }

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

## Send notifications

Now that the comment’s body is in our preferred format, we can send the
notifications. Earlier we retrieved `participants`, a list of `userIds` that
have been mentioned in the thread. You most likely have user information in your
database, which you can retrieve from these `userIds`.

<Banner title="userIds">
  These are the same `userIds` that are passed to
  [`resolveUsers`](/docs/api-reference/liveblocks-client#resolveUsers) in your
  `liveblocks.config.ts` file.
</Banner>

After getting each user’s email, simply loop through and send the formatted
comment.

```ts highlight="52-64"
import { Liveblocks, WebhookHandler, stringifyCommentBody } from "@liveblocks/node";

// 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 = "{{SECRET_KEY}}";
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 a comment has been created
  if (event.type === "commentCreated") {
    const { roomId, threadId, commentId } = event.data;

    try {
      // Get comment data and participants
      const [comment, { participantIds }] = await Promise.all([
        liveblocks.getComment({ roomId, threadId, commentId }),
        liveblocks.getThreadParticipants({ roomId, threadId }),
      ]);

      // HTML comment body
      const htmlComment = await stringifyCommentBody(comment.body, {
        format: "html",

        async resolveUsers({ userIds }) {
          // Get the correct users from your database
          const users = await __getUsers__(userIds);

          return users.map((user) => ({
            name: user.name,
          });
        },
      });

      // Get participating users from your database
      const users = await __getUsers__(participantIds);

      // Send notifications
      for (const user of users) {
        // Send email to the user's email address
        // send({
        //   from: "hello@my-company.com",
        //   to: user.email,
        //   title: "New comment",
        //   html: htmlComment
        // });
      }
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch comment data", { status: 500 });
    }
  }

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

## Sending emails with Resend

[Resend](https://resend.com) is a great tool for easily sending emails, and in
this code example, we’re using it to send the notifications to each user. Make
sure to add your API key from the
[Resend dashboard](https://resend.com/overview) before running the code.

```ts highlight="2,4-5,59-69" file="route.ts"
import { Liveblocks, WebhookHandler, stringifyCommentBody } from "@liveblocks/node";
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 = "{{SECRET_KEY}}";
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 a comment has been created
  if (event.type === "commentCreated") {
    const { roomId, threadId, commentId } = event.data;

    try {
      // Get comment data and participants
      const [comment, { participantIds }] = await Promise.all([
        liveblocks.getComment({ roomId, threadId, commentId }),
        liveblocks.getThreadParticipants({ roomId, threadId }),
      ]);

      // HTML comment body
      const htmlComment = stringifyCommentBody(comment.body, {
        format: "html",

        async resolveUsers({ userIds }) {
          // Get the correct users from your database
          const users = await __getUsers__(userIds);

          return users.map((user) => ({
            name: user.name,
          });
        },
      });

      // Get participating users from your database
      const users = await __getUsers__(participantIds);

      // Send email to the users' email addresses
      try {
        const data = await resend.emails.send({
          from: "My company <hello@my-company.com>",
          to: [users.map((user) => user.email)],
          subject: "New comment",
          html: htmlComment,
        });
      } catch (err) {
        console.error(err);
      }
    } catch (err) {
      console.log(err);
      return new Response("Could not fetch comment data", { status: 500 });
    }
  }

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

## Recap

Great, we’re successfully sending email notifications after new comments are
created! In this guide we’ve learned:

- How to use [webhooks](/docs/platform/webhooks) and the
  [`CommentCreatedEvent`](/docs/platform/webhooks#CommentCreatedEvent).
- How to use the `@liveblocks/node` package to get
  [comment data](/docs/api-reference/liveblocks-node#get-comment) and
  [thread participants](/docs/api-reference/liveblocks-node#get-thread-participants).
- How to shape a comment’s body into HTML with
  [`stringifyCommentBody`](/docs/api-reference/liveblocks-node#stringify-comment-body).
- How to send email notifications with [Resend](https://resend.com).

---
meta:
  title:
    "How to synchronize your Liveblocks Storage document data to a PlanetScale
    MySQL database"
  description:
    "Learn how to automatically update your PlanetScale MySQL database with
    changes from your Storage-based application."
---

Liveblocks allows you to build collaborative applications with
[Storage](/storage), a persisted conflict-free data store. Using our webhooks
and REST API, you can then retrieve the Storage document data as it changes, and
store it in your database.

## What we’re building

In this guide we’ll be linking a Storage application up to a
[PlanetScale](https://planetscale.com/) MySQL database so that Storage document
data is automatically synchronized. This is enabled through the following:

- [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent) webhook event
- [Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Storage project set up. If you
haven’t already got one, you can select _Custom_ on our
[getting started page](https://liveblocks.io/docs/get-started/custom), choose a
framework, and come back after you’re set up. You could also use an example such
as our [collaborative
spreadsheet)(/examples/collaborative-spreadsheet-advanced/nextjs-spreadsheet-advanced).

</Banner>

### This specific webhook is throttled

Note that the [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent)
webhook event is throttled at a rate of _once every 5 seconds_. This is because
Storage can update up to _60 times per second_, and it would be impractical to
run the webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Storage
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `storageUpdated` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Storage document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    // ...
  }

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

## Create a PlanetScale MySQL database

We’re ready to set up our PlanetScale database! We’ll be creating a simple
`documents` table that contains the following fields:

| Field         | Description                        | Type           | Key       |
| ------------- | ---------------------------------- | -------------- | --------- |
| `roomId`      | The `roomId`.                      | `VARCHAR(255)` | `PRIMARY` |
| `storageData` | The stringified JSON Storage data. | `TEXT`         |           |

<Steps>
  <Step>
    <StepTitle>Create a database</StepTitle>
    <StepContent>
      Navigate to PlanetScale’s [new database page](https://app.planetscale.com/new),
      give your database a name, and click “Create” at the bottom.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-db.png"
          alt="Create a PlanetScale database"
          width={1486}
          height={792}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create a new branch</StepTitle>
    <StepContent>
      After the database has been created, click “New branch” at the top right to create
      a branch—this works like Git.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-new-branch.png"
          alt="Create a new branch"
          width={866}
          height={681}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your schema</StepTitle>
    <StepContent>
      Click “Console” at the top, select your branch, and enter the following to set up your table.

      ```sql
      CREATE TABLE documents (
         roomId VARCHAR(255) PRIMARY KEY,
         storageData TEXT NOT NULL
      );
      ```

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-schema.png"
          alt="Create your table"
          width={1531}
          height={745}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Click “Connect”</StepTitle>
    <StepContent>
      After the database has been created, click “Connect” at the top right to create
      new credentials.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-connect.png"
          alt="Click connect"
          width={864}
          height={534}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create credentials</StepTitle>
    <StepContent>
      Give your new credentials a name, then click “Create Password”.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-credentials.png"
          alt="Create a PlanetScale password"
          width={936}
          height={655}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Add the credentials to your project</StepTitle>
    <StepContent>
    Select “Node.js” in the dropdown and copy the database URL (or add it as an environment variable).

    <Figure>
      <Image
        src="/assets/tutorials/webhooks/planetscale-get-credentials.png"
        alt="Get the database URL"
        width={1473}
        height={593}
      />
    </Figure>
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>
      Database ready!
    </StepTitle>

    <StepContent>
      Let’s take a look at the code.
    </StepContent>

  </Step>
</Steps>

## Add the Storage data to your database

And finally, we can add the Storage JSON data to our database! First, we need to
install `mysql2`:

```bash
npm i mysql2
```

Then implement the following to synchronize your data to PlanetScale:

```ts highlight="2,11-12,49-67"
import { WebhookHandler } from "@liveblocks/node";
import mysql from "mysql2";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

// Your PlanetScale database URL
const DATABASE_URL = "YOUR_DATABASE_URL";

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    const connection = await mysql.createConnection(DATABASE_URL);

    const sql = `
      INSERT INTO documents (roomId, storageData)
      VALUES (?, ?)
      ON DUPLICATE KEY UPDATE
          storageData = VALUES(storageData);
    `;

    try {
      await connection.query(sql, [roomId, storageData]);
    } catch (err) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }

    await connection.end();
  }

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

## Check if it worked

To check if your database synchronization is working, you can replay a
`storageUpdated` event from the Liveblocks dashboard.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={768}
    height={426}
  />
</Figure>

Then go back to the Console page on PlanetScale and enter the following to see
all entries:

```sql
SELECT * FROM documents;
```

You should now see your Storage document—we’ve successfully set up data
synchronization! When a user edits Storage data in your app, this function will
be called, and your database will be updated. You can rely on this to stay up to
date, within the 5 second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Storage Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage).

---
meta:
  title:
    "How to synchronize your Liveblocks Storage document data to a Supabase
    Postgres database"
  description:
    "Learn how to automatically update your Supabase Postgres database with
    changes from your Storage-based application."
---

Liveblocks allows you to build collaborative applications with
[Storage](/storage), a persisted conflict-free data store. Using our webhooks
and REST API, you can then retrieve the Storage document data as it changes, and
store it in your database.

## What we’re building

In this guide we’ll be linking a Storage application up to a
[Supabase Postgres](https://supabase.com/database) database so that Storage
document data is automatically synchronized. This is enabled through the
following:

- [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent) webhook event
- [Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Storage project set up. If you
haven’t already got one, you can select _Custom_ on our
[getting started page](https://liveblocks.io/docs/get-started/custom), choose a
framework, and come back after you’re set up. You could also use an example such
as our [collaborative
spreadsheet)(/examples/collaborative-spreadsheet-advanced/nextjs-spreadsheet-advanced).

</Banner>

### This specific webhook is throttled

Note that the [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent)
webhook event is throttled at a rate of _once every 5 seconds_. This is because
Storage can update up to _60 times per second_, and it would be impractical to
run the webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Storage
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `storageUpdated` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Storage document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    // ...
  }

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

## Create a Supabase Postgres database

We’re ready to set up our Supabase database! We’ll be creating a simple
`documents` table that contains the following fields:

| Field         | Description                        | Type           | Key       |
| ------------- | ---------------------------------- | -------------- | --------- |
| `roomId`      | The `roomId`.                      | `VARCHAR(255)` | `PRIMARY` |
| `storageData` | The stringified JSON Storage data. | `TEXT`         |           |

<Steps>
  <Step>
    <StepTitle>New project</StepTitle>
    <StepContent>
      Navigate to Supabase’s [dashboard
      page](https://supabase.com/dashboard/projects), and click “New project” at
      the top.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/supabase-new-project.png"
          alt="Click new project"
          width={942}
          height={443}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Create a database</StepTitle>
  <StepContent>
    Give your database a name and password, then click “Create new project” at
    the bottom. Make sure to save your password, because you won’t be able to
    view it again.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-new-project-details.png"
        alt="Create a new project"
        width={1517}
        height={1203}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create your table</StepTitle>
  <StepContent>
    Click the SQL Editor icon in the left bar, enter the following code into the
    console, and click “Run” at the bottom right to create the table. ```sql
    CREATE TABLE documents ( roomId VARCHAR(255) PRIMARY KEY, storageData TEXT
    NOT NULL ); ```
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-create-schema.png"
        alt="Create your table schema"
        width={1635}
        height={984}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your credentials</StepTitle>
  <StepContent>
    Click the Settings icon in the left bar, click “API” at the left and find
    two items: 1. Your “URL”, under “Project URL”. 2. Your `anon``public` key,
    under “Project API key”. Make a note of these, or add them as environment
    variables in your project.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-get-credentials.png"
        alt="Create your table schema"
        width={2053}
        height={972}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Database ready!</StepTitle>
    <StepContent>Let’s take a look at the code.</StepContent>
  </Step>
</Steps>

## Add the Storage data to your database

And finally, we can add the Storage JSON data to our database! First, we need to
install the Supabase library:

```bash
npm i @supabase/supabase-js
```

Then implement the following to synchronize your data, making sure to add your
Project URL:

```ts highlight="2,11-15,52-62"
import { WebhookHandler } from "@liveblocks/node";
import { createClient } from "@supabase/supabase-js";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

// Create a Supabase client
const supabase = createClient(
  "YOUR_SUPABASE_PROJECT_URL",
  "YOUR_SUPABASE_PUBLIC_ANON_KEY"
);

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    const { data, error } = await supabase
      .from("documents")
      .insert({ roomid: roomId, storagedata: storageData })
      .select();

    if (error) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }
  }

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

## Check if it worked

To check if it worked, you can replay an event from the Liveblocks dashboard, or
just edit your document.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={768}
    height={426}
  />
</Figure>

Next, go to Supabase, and click the Table Editor icon on the left bar. Find your
`documents` table on the left, and check the entries. You should now see your
Storage document—we’ve successfully set up data synchronization!

When a user edits Storage data in your app, this function will be called, and
your database will be updated. You can rely on this to stay up to date, within
the 5 second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Storage Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage).

---
meta:
  title:
    "How to synchronize your Liveblocks Storage document data to a Vercel
    Postgres database"
  description:
    "Learn how to automatically update your Vercel Postgres database with
    changes from your Storage-based application."
---

Liveblocks allows you to build collaborative applications with
[Storage](/storage), a persisted conflict-free data store. Using our webhooks
and REST API, you can then retrieve the Storage document data as it changes, and
store it in your database.

## What we’re building

In this guide we’ll be linking a Storage application up to a
[Vercel Postgres](https://vercel.com/docs/storage/vercel-postgres) database so
that Storage document data is automatically synchronized. This is enabled
through the following:

- [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent) webhook event
- [Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Storage project set up. If you
haven’t already got one, you can select _Custom_ on our
[getting started page](https://liveblocks.io/docs/get-started/custom), choose a
framework, and come back after you’re set up. You could also use an example such
as our [collaborative
spreadsheet)(/examples/collaborative-spreadsheet-advanced/nextjs-spreadsheet-advanced).

</Banner>

### This specific webhook is throttled

Note that the [StorageUpdated](/docs/platform/webhooks#StorageUpdatedEvent)
webhook event is throttled at a rate of _once every 5 seconds_. This is because
Storage can update up to _60 times per second_, and it would be impractical to
run the webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Storage
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>

  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>
      Webhooks dashboard is set up!
    </StepTitle>

    <StepContent>
      Note that you can filter specifically for `storageUpdated`
      events, but we’re ignoring this for now so we can test more easily. Let’s go
      back to the code.
    </StepContent>

  </Step>

</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Storage document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Storage Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    // ...
  }

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

## Create a Vercel Postgres database

We’re ready to set up our database! This is how to get started with Vercel
Postgres:

<Steps>
  <StepCompact>
    Navigate to the [Vercel Storage](https://vercel.com/dashboard/stores)
    dashboard.
  </StepCompact>

<StepCompact>Click "Create Database", then select “Postgres”.</StepCompact>

<StepCompact>Give the database a name and click “Create”.</StepCompact>

  <StepCompact lastStep>
    Follow the getting started guide to connect the database to
    your Vercel project, link your environment variables, and install the packages.
  </StepCompact>
</Steps>

## Add the Storage data to your database

And finally, we can add the Storage JSON data to our database. Here we’re
creating a simple `documents` table that contains the following fields:

| Field         | Description                        | Type           | Key       |
| ------------- | ---------------------------------- | -------------- | --------- |
| `roomId`      | The `roomId`.                      | `VARCHAR(255)` | `PRIMARY` |
| `storageData` | The stringified JSON Storage data. | `TEXT`         |           |

This is how to implement it in your endpoint:

```ts highlight="2,46-65"
import { WebhookHandler } from "@liveblocks/node";
import { sql } from "@vercel/postgres";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Storage document data has been updated
  if (event.type === "storageUpdated") {
    const { roomId } = event.data;

    // Get Storage data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/storage`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Storage document data as a string
    const storageData = await response.text();

    // Update database
    try {
      await sql`
        CREATE TABLE IF NOT EXISTS documents (
          roomId VARCHAR(255) PRIMARY KEY,
          storageData TEXT NOT NULL
        );
      `;
      await sql`
        INSERT INTO documents (roomId, storageData)
        VALUES (${roomId}, ${storageData})
        ON CONFLICT (roomId)
        DO UPDATE SET
          storageData = EXCLUDED.storageData
      `;
    } catch (err) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }
  }

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

## Check if it worked

To check if your database synchronization is working, you can replay a
`storageUpdated` event from the Liveblocks dashboard.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={768}
    height={426}
  />
</Figure>

Then go to the Data page on your Vercel Postgres dashboard, find your table in
the dropdown, and check the entries. You should now see your Storage
document—we’ve successfully set up data synchronization!

When a user edits Storage data in your app, this function will be called, and
your database will be updated. You can rely on this to stay up to date, within
the 5 second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Storage Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-storage).

---
meta:
  title:
    "How to synchronize your Liveblocks Yjs document data to a PlanetScale MySQL
    database"
  description:
    "Learn how to automatically update your PlanetScale MySQL database with
    changes from your Yjs application."
---

Liveblocks allows you to build collaborative applications with
[Yjs](https://yjs.dev/), which is tightly integrated into our infrastructure.
Using our webhooks and REST API, you can then retrieve the Yjs document data as
it changes, and store it in your database.

## What we’re building

In this guide we’ll be linking a Yjs application up to a
[PlanetScale](https://planetscale.com/) MySQL database so that Yjs document data
is automatically synchronized. This is enabled through the following:

- [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook event
- [Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Yjs project set up. If you
haven’t already got one, you can open our getting started page, select a
[text editor](/docs/get-started/text-editor) or
[code editor](/docs/get-started/code-editor), both of which use Yjs, and come
back after you’re set up.

</Banner>

### This specific webhook is throttled

Note that the [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook
event is throttled at a rate of _once every 5 seconds_. This is because Yjs can
update up to _60 times per second_, and it would be impractical to run the
webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Yjs
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `ydocUpdated` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Yjs document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    // ...
  }

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

## Create a PlanetScale MySQL database

We’re ready to set up our PlanetScale database! We’ll be creating a simple
`documents` table that contains the following fields:

| Field      | Description                    | Type           | Key       |
| ---------- | ------------------------------ | -------------- | --------- |
| `roomId`   | The `roomId`.                  | `VARCHAR(255)` | `PRIMARY` |
| `yDocData` | The stringified JSON Yjs data. | `TEXT`         |           |

<Steps>
  <Step>
    <StepTitle>Create a database</StepTitle>
    <StepContent>
      Navigate to PlanetScale’s [new database page](https://app.planetscale.com/new),
      give your database a name, and click “Create” at the bottom.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-db.png"
          alt="Create a PlanetScale database"
          width={1486}
          height={792}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create a new branch</StepTitle>
    <StepContent>
      After the database has been created, click “New branch” at the top right to create
      a branch—this works like Git.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-new-branch.png"
          alt="Create a new branch"
          width={866}
          height={681}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Set up your schema</StepTitle>
    <StepContent>
      Click “Console” at the top, select your branch, and enter the following to set up your table.

      ```sql
      CREATE TABLE documents (
         roomId VARCHAR(255) PRIMARY KEY,
         yDocData TEXT NOT NULL
      );
      ```

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-schema.png"
          alt="Create your table"
          width={1531}
          height={745}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Click “Connect”</StepTitle>
    <StepContent>
      After the database has been created, click “Connect” at the top right to create
      new credentials.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-connect.png"
          alt="Click connect"
          width={864}
          height={534}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Create credentials</StepTitle>
    <StepContent>
      Give your new credentials a name, then click “Create Password”.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/planetscale-create-credentials.png"
          alt="Create a PlanetScale password"
          width={936}
          height={655}
        />
      </Figure>
    </StepContent>

  </Step>

  <Step>
    <StepTitle>Add the credentials to your project</StepTitle>
    <StepContent>
    Select “Node.js” in the dropdown and copy the database URL (or add it as an environment variable).

    <Figure>
      <Image
        src="/assets/tutorials/webhooks/planetscale-get-credentials.png"
        alt="Get the database URL"
        width={1473}
        height={593}
      />
    </Figure>
    </StepContent>

  </Step>

  <Step lastStep>
    <StepTitle>
      Database ready!
    </StepTitle>

    <StepContent>
      Let’s take a look at the code.
    </StepContent>

  </Step>
</Steps>

## Add the Yjs data to your database

And finally, we can add the Yjs JSON data to our database! First, we need to
install `mysql2`:

```bash
npm i mysql2
```

Then implement the following to synchronize your data to PlanetScale:

```ts highlight="2,11-12,49-67"
import { WebhookHandler } from "@liveblocks/node";
import mysql from "mysql2";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

// Your PlanetScale database URL
const DATABASE_URL = "YOUR_DATABASE_URL";

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    const connection = await mysql.createConnection(DATABASE_URL);

    const sql = `
      INSERT INTO documents (roomId, yDocData)
      VALUES (?, ?)
      ON DUPLICATE KEY UPDATE
          yDocData = VALUES(yDocData);
    `;

    try {
      await connection.query(sql, [roomId, yDocData]);
    } catch (err) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }

    await connection.end();
  }

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

## Check if it worked

To check if your database synchronization is working, you can replay a
`yDocUpdated` event from the Liveblocks dashboard.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={768}
    height={426}
  />
</Figure>

Then go back to the Console page on PlanetScale and enter the following to see
all entries:

```sql
SELECT * FROM documents;
```

You should now see your Yjs document—we’ve successfully set up data
synchronization! When a user edits Yjs data in your app, this function will be
called, and your database will be updated. You can rely on this to stay up to
date, within the 5 second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Yjs Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc).

---
meta:
  title:
    "How to synchronize your Liveblocks Yjs document data to a Supabase Postgres
    database"
  description:
    "Learn how to automatically update your Supabase Postgres database with
    changes from your Yjs application."
---

Liveblocks allows you to build collaborative applications with
[Yjs](https://yjs.dev/), which is tightly integrated into our infrastructure.
Using our webhooks and REST API, you can then retrieve the Yjs document data as
it changes, and store it in your database.

## What we’re building

In this guide we’ll be linking a Yjs application up to a
[Supabase Postgres](https://supabase.com/database) database so that Yjs document
data is automatically synchronized. This is enabled through the following:

- [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook event
- [Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Yjs project set up. If you
haven’t already got one, you can open our getting started page, select a
[text editor](/docs/get-started/text-editor) or
[code editor](/docs/get-started/code-editor), both of which use Yjs, and come
back after you’re set up.

</Banner>

### This specific webhook is throttled

Note that the [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook
event is throttled at a rate of _once every 5 seconds_. This is because Yjs can
update up to _60 times per second_, and it would be impractical to run the
webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Yjs
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your webhook secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Note that you can filter specifically for `ydocUpdated` events, but we’re
      ignoring this for now so we can test more easily. Let’s go back to the
      code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Yjs document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    // ...
  }

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

## Create a Supabase Postgres database

We’re ready to set up our Supabase database! We’ll be creating a simple
`documents` table that contains the following fields:

| Field      | Description                    | Type           | Key       |
| ---------- | ------------------------------ | -------------- | --------- |
| `roomId`   | The `roomId`.                  | `VARCHAR(255)` | `PRIMARY` |
| `yDocData` | The stringified JSON Yjs data. | `TEXT`         |           |

<Steps>
  <Step>
    <StepTitle>New project</StepTitle>
    <StepContent>
      Navigate to Supabase’s [dashboard
      page](https://supabase.com/dashboard/projects), and click “New project” at
      the top.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/supabase-new-project.png"
          alt="Click new project"
          width={942}
          height={443}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Create a database</StepTitle>
  <StepContent>
    Give your database a name and password, then click “Create new project” at
    the bottom. Make sure to save your password, because you won’t be able to
    view it again.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-new-project-details.png"
        alt="Create a new project"
        width={1517}
        height={1203}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create your table</StepTitle>
  <StepContent>
    Click the SQL Editor icon in the left bar, enter the following code into the
    console, and click “Run” at the bottom right to create the table. ```sql
    CREATE TABLE documents ( roomId VARCHAR(255) PRIMARY KEY, yDocData TEXT NOT
    NULL ); ```
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-create-schema.png"
        alt="Create your table schema"
        width={1635}
        height={984}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your credentials</StepTitle>
  <StepContent>
    Click the Settings icon in the left bar, click “API” at the left and find
    two items: 1. Your “URL”, under “Project URL”. 2. Your `anon``public` key,
    under “Project API key”. Make a note of these, or add them as environment
    variables in your project.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/supabase-get-credentials.png"
        alt="Create your table schema"
        width={2053}
        height={972}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Database ready!</StepTitle>
    <StepContent>Let’s take a look at the code.</StepContent>
  </Step>
</Steps>

## Add the Yjs data to your database

And finally, we can add the Yjs JSON data to our database! First, we need to
install the Supabase library:

```bash
npm i @supabase/supabase-js
```

Then implement the following to synchronize your data, making sure to add your
Project URL:

```ts highlight="2,11-15,52-62"
import { WebhookHandler } from "@liveblocks/node";
import { createClient } from "@supabase/supabase-js";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

// Create a Supabase client
const supabase = createClient(
  "YOUR_SUPABASE_PROJECT_URL",
  "YOUR_SUPABASE_PUBLIC_ANON_KEY"
);

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    const { data, error } = await supabase
      .from("documents")
      .insert({ roomid: roomId, ydocdata: yDocData })
      .select();

    if (error) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }
  }

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

## Check if it worked

To check if it worked, you can replay an event from the Liveblocks dashboard, or
just edit your document.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={1563}
    height={657}
  />
</Figure>

Next, go to Supabase, and click the Table Editor icon on the left bar. Find your
`documents` table on the left, and check the entries. You should now see your
Yjs document—we’ve successfully set up data synchronization!

When a user edits Yjs data in your app, this function will be called, and your
database will be updated. You can rely on this to stay up to date, within the 5
second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Yjs Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc).

---
meta:
  title:
    "How to synchronize your Liveblocks Yjs document data to a Vercel Postgres
    database"
  description:
    "Learn how to automatically update your Vercel Postgres database with
    changes from your Yjs application."
---

Liveblocks allows you to build collaborative applications with
[Yjs](https://yjs.dev/), which is tightly integrated into our infrastructure.
Using our webhooks and REST API, you can then retrieve the Yjs document data as
it changes, and store it in your database.

## What we’re building

In this guide we’ll be linking a Yjs application up to a
[Vercel Postgres](https://vercel.com/docs/storage/vercel-postgres) database so
that Yjs document data is automatically synchronized. This is enabled through
the following:

- [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook event
- [Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
  REST API

<Banner title="Have a project ready">

This guide assumes you already have a Liveblocks Yjs project set up. If you
haven’t already got one, you can open our getting started page, select a
[text editor](/docs/get-started/text-editor) or
[code editor](/docs/get-started/code-editor), both of which use Yjs, and come
back after you’re set up.

</Banner>

### This specific webhook is throttled

Note that the [YDocUpdated](/docs/platform/webhooks#YDocUpdatedEvent) webhook
event is throttled at a rate of _once every 5 seconds_. This is because Yjs can
update up to _60 times per second_, and it would be impractical to run the
webhook this frequently.

## Create an endpoint in your project

When a webhook event is triggered, it can send a POST request to the back end in
your project, and from within there we can update the database. In this guide,
we’ll be using a Next.js route handler (API endpoint) as an example, but other
frameworks work similarly.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks and database
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-database-sync
```

### Testing webhooks locally

Running webhooks locally can be difficult, but one way to do this is to use a
tool such as [`localtunnel`](https://www.npmjs.com/package/localtunnel) or
[`ngrok`](https://www.npmjs.com/package/ngrok) which allow you to temporarily
put your localhost server online.

If your project is running on `localhost:3000`, you can run the following
command to generate a temporary URL that’s available while your localhost server
is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-database-sync

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-database-sync
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger when Yjs
document data has changed.

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.

      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>

  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` URL from earlier.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Get your webhook secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>
      Webhooks dashboard is set up!
    </StepTitle>

    <StepContent>
      Note that you can filter specifically for `ydocUpdated`
      events, but we’re ignoring this for now so we can test more easily. Let’s go
      back to the code.
    </StepContent>

  </Step>

</Steps>

## Verify the webhook request

The [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package provides
you with a function that verifies whether the current request is a real webhook
request from Liveblocks. You can set this up by setting up a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real
project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  // Update database
  // ...

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

We can then check we’re receiving the correct type of event, get the updated
`roomId`, and handle updating the database inside there.

```ts highlight="23-29"
import { WebhookHandler } from "@liveblocks/node";

// Add your signing key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_SIGNING_SECRET";
const webhookHandler = new WebhookHandler(WEBHOOK_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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Update database
    // ...
  }

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

## Get the current room’s Yjs document data

Before updating our database, we need to get the current room’s data. We can do
this through the
[Get Yjs Document](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc)
REST API. You use the REST API, you need to add your secret key from your
project page.

```ts highlight="7-8,30-43"
import { WebhookHandler } from "@liveblocks/node";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    // ...
  }

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

## Create a Vercel Postgres database

We’re ready to set up our database! This is how to get started with Vercel
Postgres:

<Steps>
  <StepCompact>
    Navigate to the [Vercel Storage](https://vercel.com/dashboard/stores)
    dashboard.
  </StepCompact>

<StepCompact>Click "Create Database", then select “Postgres”.</StepCompact>

<StepCompact>Give the database a name and click “Create”.</StepCompact>

  <StepCompact lastStep>
    Follow the getting started guide to connect the database to
    your Vercel project, link your environment variables, and install the packages.
  </StepCompact>
</Steps>

## Add the Yjs data to your database

And finally, we can add the Yjs JSON data to our database. Here we’re creating a
simple `documents` table that contains the following fields:

| Field      | Description                    | Type           | Key       |
| ---------- | ------------------------------ | -------------- | --------- |
| `roomId`   | The `roomId`.                  | `VARCHAR(255)` | `PRIMARY` |
| `yDocData` | The stringified JSON Yjs data. | `TEXT`         |           |

This is how to implement it in your endpoint:

```ts highlight="2,46-65"
import { WebhookHandler } from "@liveblocks/node";
import { sql } from "@vercel/postgres";

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

// Add your secret key from a project's API keys dashboard
const API_SECRET = "{{SECRET_KEY}}";

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 Yjs document data has been updated
  if (event.type === "ydocUpdated") {
    const { roomId } = event.data;

    // Get Yjs data from Liveblocks REST API
    const url = `https://api.liveblocks.io/v2/rooms/${roomId}/ydoc`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_SECRET}` },
    });

    if (!response.ok) {
      return new Response("Problem accessing Liveblocks REST APIs", {
        status: 500,
      });
    }

    // Your JSON Yjs document data as a string
    const yDocData = await response.text();

    // Update database
    try {
      await sql`
        CREATE TABLE IF NOT EXISTS documents (
          roomId VARCHAR(255) PRIMARY KEY,
          yDocData TEXT NOT NULL
        );
      `;
      await sql`
        INSERT INTO documents (roomId, yDocData)
        VALUES (${roomId}, ${yDocData})
        ON CONFLICT (roomId)
        DO UPDATE SET
          yDocData = EXCLUDED.yDocData
      `;
    } catch (err) {
      return new Response("Problem inserting data into database", {
        status: 500,
      });
    }
  }

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

## Check if it worked

To check if your database synchronization is working, you can replay a
`yDocUpdated` event from the Liveblocks dashboard.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-replay-event.png"
    alt="Create your table schema"
    width={1563}
    height={657}
  />
</Figure>

Then go to the Data page on your Vercel Postgres dashboard, find your table in
the dropdown, and check the entries. You should now see your Yjs document—we’ve
successfully set up data synchronization!

When a user edits Yjs data in your app, this function will be called, and your
database will be updated. You can rely on this to stay up to date, within the 5
second throttle limit.

## Learn more

You can learn more about Liveblocks webhooks in our full
[webhooks guide](/docs/platform/webhooks). We also have an API reference for the
[Get Yjs Document API](/docs/api-reference/rest-api-endpoints#get-rooms-roomId-ydoc).

---
meta:
  title: "How to test webhooks on localhost"
  description:
    "Learn how to test Liveblocks webhooks on your local system using
    localtunnel or ngrok."
---

Testing webhooks on your local system can be difficult, but there are ways to
make it possible using tools such as
[`localtunnel`](https://www.npmjs.com/package/localtunnel) and
[`ngrok`](https://www.npmjs.com/package/ngrok).

## Create an endpoint in your project

The first step in testing webhooks is making sure you have an API endpoint set
up in your project. This is the endpoint that’ll receive the webhook event from
Liveblocks.

In order to use webhooks, we’ll need to retrieve the `headers` and `body` from
the request. Here’s the basic endpoint we’ll be starting from:

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

  // Handle webhooks
  // ...

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

Create this endpoint in your project, and make it available on `localhost` at
the following URL:

```
/api/liveblocks-webhook
```

## Testing webhooks locally

Tools such as `localtunnel` and `ngrok` allow you to temporarily place your
localhost server online, by providing you with a temporary URL. Let’s take a
look at these two options.

### localtunnel

[`localtunnel`](https://www.npmjs.com/package/localtunnel) allows you to get
started without signing up. If your project is running on `localhost:3000`, you
can run the following `localtunnel` command to generate your URL, which will
stay online while your localhost server is running:

```bash
npx localtunnel --port 3000
```

`localtunnel` generates a base URL that can be placed into the Liveblocks
webhooks dashboard for quick testing. To use this, take the full address of your
webhook endpoint, and replace the domain in your `localhost` address with the
generated URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-webhook

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-webhook
```

You now have a URL that can be used in the webhooks dashboard.

### ngrok

[`ngrok`](https://www.npmjs.com/package/ngrok) requires you to sign up and
install, but it has more features and is simpler to use after you’ve created an
account. If your project is running on `localhost:3000`, you can run the
following `ngrok` command to generate your URL, which will stay online while
your localhost server is running:

```bash
ngrok http 3000
```

`ngrok` generates a base URL that can be placed into the Liveblocks webhooks
dashboard for quick testing. To use this, take the full address of your webhook
endpoint, and replace the domain in your `localhost` address with the generated
URL.

```shell
# Take your local URL
http://localhost:3000/api/liveblocks-webhook

# Replace localhost with the generated domain, then copy it
https://my-localtunnel-url.loca.lt/api/liveblocks-webhook
```

You now have a URL that can be used in the webhooks dashboard.

## Set up webhooks on the Liveblocks dashboard

To use webhooks, you need to pass your endpoint URL to the webhooks dashboard
inside your Liveblocks project, and tell the webhook to trigger on any specific
[webhook events](/docs/platform/webhooks#Liveblocks-events).

<Steps>
  <Step>
    <StepTitle>Select your project</StepTitle>
    <StepContent>
      From the [Liveblocks dashboard](/dashboard), navigate to the project you’d
      like to use with webhooks, or create a new project.
      <Figure>
        <Image
          src="/assets/tutorials/webhooks/liveblocks-create-project.png"
          alt="Create a Liveblocks project"
          width={712}
          height={445}
        />
      </Figure>
    </StepContent>
  </Step>

<Step>
  <StepTitle>Go to the webhooks dashboard</StepTitle>
  <StepContent>
    Click on the **“Webhooks”** tab on the menu at the left.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-click-webhooks.png"
        alt="Click webhooks"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Create an endpoint</StepTitle>
  <StepContent>
    Click the **“Create endpoint…”** button on the webhooks dashboard to start
    setting up your webhook.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint.png"
        alt="Click add endpoint"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

<Step>
  <StepTitle>Add your endpoint URL</StepTitle>
  <StepContent>
    Enter the URL of the endpoint. In a production app this will be the real
    endpoint, but for now enter your `localtunnel` or `ngrok` URL from earlier.

    You can filter for any specific [webhook events](/docs/platform/webhooks#Liveblocks-events) here, in case you’d only like to listen to certain types.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-add-endpoint-url.png"
        alt="Add endpoint URL"
        width={712}
        height={445}
      />
    </Figure>

  </StepContent>
</Step>

<Step>
  <StepTitle>Get your secret key</StepTitle>
  <StepContent>
    Click **“Create endpoint”** at the bottom, then find your **“Webhook secret
    key”** on the next page, and copy it.
    <Figure>
      <Image
        src="/assets/tutorials/webhooks/liveblocks-get-secret-key.png"
        alt="Copy your webhook secret key"
        width={712}
        height={445}
      />
    </Figure>
  </StepContent>
</Step>

  <Step lastStep>
    <StepTitle>Webhooks dashboard is set up!</StepTitle>

    <StepContent>
      Done! Let’s go back to the code.
    </StepContent>

  </Step>
</Steps>

## Verify the webhook request

It’s recommended to verify that your webhook requests have come from Liveblocks,
and the [`@liveblocks/node`](/docs/api-reference/liveblocks-node) package
provides you with a function that will verify this for you. You can set this up
by creating a
[`WebhookHandler`](/docs/api-reference/liveblocks-node#WebhookHandler) and
running [`verifyRequest`](/docs/api-reference/liveblocks-node#verifyRequest).

Make sure to add your "Webhook secret key" from the Liveblocks dashboard—in a
real project we’d recommend using an environment variable for this.

```ts highlight="1,3-5,11-21"
import { WebhookHandler } 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);

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

  // Use webhook event
  // ...

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

The webhook has now been verified!

## Use your webhook event

From this point on, you can use the webhook event as you like. Here’s a
[Comments](/docs/ready-made-features/comments) example, showing you how to fetch
a new thread after it’s just been created.

```ts highlight="2,8-10,28-37"
import { WebhookHandler } from "@liveblocks/node";
import { Liveblocks } 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;

  // 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 a new thread has been created
  if (event.type === "threadCreated") {
    const { roomId, threadId } = event.data;

    // Fetch new thread
    const thread = await liveblocks.getThread({ roomId, threadId });

    // Use thread
    // ...
  }

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

Visit the [webhook events](/docs/platform/webhooks#Liveblocks-events) section of
our webhooks guide to learn more.

---
meta:
  title: "How to use Liveblocks multiplayer undo/redo with React"
  description: "Learn how to use Liveblocks multiplayer undo/redo with React"
---

In this guide, we’ll be learning how to use Liveblocks multiplayer undo/redo
with React using the hooks from the [`@liveblocks/react`][] package.

This guide uses [TypeScript](https://www.typescriptlang.org/). Liveblocks can
definitely be used without TypeScript. We believe typings are helpful to make
collaborative apps more robust, but if you’d prefer to skip the TypeScript
syntax, feel free to write your code in JavaScript.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your React
application. If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/react) first.

</Banner>

## Multiplayer undo/redo [#undo-redo]

Implementing undo/redo in a multiplayer environment is
[notoriously complex](/blog/how-to-build-undo-redo-in-a-multiplayer-environment),
but Liveblocks provides functions to handle it for you. `useUndo` and `useRedo`
return functions that allow you to undo and redo the last changes made to your
app.

```tsx highlight="4,5,9,10"
import { useUndo, useRedo } from "@liveblocks/react/suspense";

function App() {
  const undo = useUndo();
  const redo = useRedo();

  return (
    <>
      <button onClick={() => undo()}>Undo</button>
      <button onClick={() => redo()}>Redo</button>
    </>
  );
}
```

An example of this in use would be a button that updates the current `firstName`
of a scientist. Every time a Liveblocks storage change is detected, in this case
`.set` being called, it’s stored. Pressing the undo button will change the name
back to its previous value.

```tsx highlight="6,9,15,16"
import { useState } from "react";
import { useMutation, useUndo } from "@liveblocks/react/suspense";

function YourComponent() {
  const [text, setText] = useState("");
  const undo = useUndo();

  const updateName = useMutation(({ storage }, newName) => {
    storage.get("scientist").set("firstName", newName);
  });

  return (
    <>
      <input
        type="text"
        value={text}
        onChange={(e) => setText(e.target.value)}
      />
      <button onClick={() => updateName(text)}>Update Name</button>
      <button onClick={() => undo()}></button>
    </>
  );
}
```

Multiplayer undo/redo is much more complex that it sounds—if you’re interested
in the technical details, you can find more information in our interactive
article:
[How to build undo/redo in a multiplayer environment](/blog/how-to-build-undo-redo-in-a-multiplayer-environment).

### Pause and resume history [#pause-resume]

Sometimes it can be helpful to pause undo/redo history, so that multiple updates
are reverted with a single call.

For example, let’s consider a design tool; when a user drags a rectangle, the
intermediate rectangle positions should not be part of the undo/redo history,
otherwise pressing `undo` may only move the rectangle one pixel backwards.
However, these small pixel updates should still be transmitted to others, so
that the transition is smooth.

`useHistory` is a hook that allows us to pause and resume history states as we
please.

```tsx highlight="4,8,9"
import { useHistory } from "@liveblocks/react/suspense";

function App() {
  const { resume, pause } = useHistory();

  return <Rectangle onDragStart={() => pause()} onDragEnd={() => resume()} />;
}
```

### Presence history

By default, undo/redo only impacts the room storage—there’s generally no need to
use it with presence, for example there’s no reason to undo the position of a
user’s cursor. However, occasionally it can be useful.

If we explore the design tool scenario, the currently selected rectangle may be
stored in a user’s presence. If `undo` is pressed, and the rectangle is moved
back, it would make sense to remove the user’s selection on that rectangle.

To enable this, we can use the `addToHistory` option when updating the user’s
presence.

```tsx highlight="4,9"
import { useUpdateMyPresence } from "@liveblocks/react/suspense";

function App() {
  const updateMyPresence = useUpdateMyPresence();

  return (
    <Rectangle
      onClick={(rectangleId) =>
        updateMyPresence({ selected: rectangleId }, { addToHistory: true })
      }
    />
  );
}
```

This also works in mutations with `setMyPresence`.

```tsx highlight="4"
import { useMutation } from "@liveblocks/react/suspense";

const updateSelected = useMutation(({ setMyPresence }, rectangleId) => {
  setMyPresence({ selected: rectangleId }, { addToHistory: true });
});
```

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livelist.push`]: /docs/api-reference/liveblocks-client#LiveList.push
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`liveobject.get`]: /docs/api-reference/liveblocks-client#LiveObject.get
[`liveobject.set`]: /docs/api-reference/liveblocks-client#LiveObject.set
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`room.subscribe`]:
  /docs/api-reference/liveblocks-client#Room.subscribe(storageItem)
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`usehistory`]: /docs/api-reference/liveblocks-react#useHistory
[`useothers`]: /docs/api-reference/liveblocks-react#useOthers
[`useredo`]: /docs/api-reference/liveblocks-react#useRedo
[`useundo`]: /docs/api-reference/liveblocks-react#useUndo
[`useupdatemypresence`]:
  /docs/api-reference/liveblocks-react#useUpdateMyPresence
[`useconnectionids`]: /docs/api-reference/liveblocks-react#useConnectionIds
[`usestorage`]: /docs/api-reference/liveblocks-react#useStorage
[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation

---
meta:
  title: "How to use Liveblocks multiplayer undo/redo with Redux"
  description: "Learn how to use Liveblocks multiplayer undo/redo with Redux"
---

In this guide, we’ll be learning how to use Liveblocks multiplayer undo/redo
with Redux using the APIs from the [`@liveblocks/redux`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Redux store. If
you don’t make sure to follow
[these quick steps to get started](/docs/get-started/redux) first.

</Banner>

## Multiplayer undo/redo [#undo-redo]

Implementing undo/redo when multiple users can edit the app state simultaneously
is quite complex!

**When only one user can edit the app state, undo/redo acts like a "time
machine"**; undo/redo replaces the current app state with an app state that was
already be seen by the user.

When multiple users are involved, undo or redo can lead to an app state that no
one has seen before. For example, let's imagine a design tool with two users
editing the same circle.

- Initial state => `{ radius: "10px", color: "yellow" }`
- User A sets the `color` to `blue` => `{ radius: "10px", color: "blue" }`
- User B sets the `radius` to `20px` => `{ radius: "20px", color: "blue" }`
- User A realizes that it preferred the circle in yellow and undoes **its last
  modification** => `{ radius: "20px", color: "yellow" }`

A yellow circle with a radius of 20px in a completely new state. **Undo/redo in
a multiplayer app does not act like a "time machine"; it only undoes local
operation**.

The good news is that [`room.history.undo`][] and [`room.history.redo`][] takes
that complexity out of your hands so you can focus on the core features of your
app.

Access these two functions from the client like below so you can easily bind
them to keyboard events (⌘+Z/⌘+⇧+Z on Mac and Ctrl+Z/Ctrl+Y on Windows) or undo
and redo buttons in your application..

```js
const { undo, redo } = client.getRoom("room-id").history;
```

### Pause and resume history [#pause-resume]

Some applications require skipping intermediate states from the undo/redo
history. Let's consider a design tool; when a user drags a rectangle, the
intermediate rectangle positions should not be part of the undo/redo history.
But they should be shared with the rest of the room to create a great
experience.

[`room.history.pause`][] and [`room.history.resume`][] lets you skip these
intermediate states. To go back to our design tool example, the sequence of
calls would look like that:

- User presses the rectangle
- Call `room.history.pause` to skip future operations from the history
- User drags the rectangle
- User release the rectangle
- Call `room.history.resume`

At this point, if the user calls `room.history.undo`, the rectangle will go back
to its initial position.

```js
const { pause, resume } = client.getRoom("room-id").history;
```

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-redux
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks multiplayer undo/redo with Zustand"
  description: "Learn how to use Liveblocks multiplayer undo/redo with Zustand"
---

In this guide, we’ll be learning how to use Liveblocks multiplayer undo/redo
with Zustand using the APIs from the [`@liveblocks/zustand`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Zustand store.
If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/zustand) first.

</Banner>

## Multiplayer undo/redo [#undo-redo]

Implementing undo/redo when multiple users can edit the app state simultaneously
is quite complex!

**When only one user can edit the app state, undo/redo acts like a "time
machine"**; undo/redo replaces the current app state with an app state that was
already be seen by the user.

When multiple users are involved, undo or redo can lead to an app state that no
one has seen before. For example, let's imagine a design tool with two users
editing the same circle.

- Initial state => `{ radius: "10px", color: "yellow" }`
- User A sets the `color` to `blue` => `{ radius: "10px", color: "blue" }`
- User B sets the `radius` to `20px` => `{ radius: "20px", color: "blue" }`
- User A realizes that it preferred the circle in yellow and undoes **its last
  modification** => `{ radius: "20px", color: "yellow" }`

A yellow circle with a radius of 20px in a completely new state. **Undo/redo in
a multiplayer app does not act like a "time machine"; it only undoes local
operation**.

The good news is that [`room.history.undo`][] and [`room.history.redo`][] takes
that complexity out of your hands so you can focus on the core features of your
app.

Access these two functions from your store like below so you can easily bind
them to keyboard events (⌘+Z/⌘+⇧+Z on Mac and Ctrl+Z/Ctrl+Y on Windows) or undo
and redo buttons in your application..

```tsx
import useStore from "../store";

function YourComponent() {
  const undo = useStore((state) => state.liveblocks.room?.history.undo);
  const redo = useStore((state) => state.liveblocks.room?.history.redo);

  return (
    <>
      <button onClick={undo}>Undo</button>
      <button onClick={redo}>Redo</button>
    </>
  );
}
```

### Pause and resume history [#pause-resume]

Some applications require skipping intermediate states from the undo/redo
history. Let's consider a design tool; when a user drags a rectangle, the
intermediate rectangle positions should not be part of the undo/redo history.
But they should be shared with the rest of the room to create a great
experience.

[`room.history.pause`][] and [`room.history.resume`][] lets you skip these
intermediate states. To go back to our design tool example, the sequence of
calls would look like that:

- User presses the rectangle
- Call `room.history.pause` to skip future operations from the history
- User drags the rectangle
- User release the rectangle
- Call `room.history.resume`

At this point, if the user calls `room.history.undo`, the rectangle will go back
to its initial position.

```tsx
import useStore from "../store";

const pause = useStore((state) => state.liveblocks.room?.history.pause);
const resume = useStore((state) => state.liveblocks.room?.history.resume);
```

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-zustand
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks Presence with React"
  description: "Learn how to use Liveblocks Presence with React"
---

In this guide, we’ll be learning how to use Liveblocks Presence with React using
the hooks from the [`@liveblocks/react`][] package.

This guide uses [TypeScript](https://www.typescriptlang.org/). Liveblocks can
definitely be used without TypeScript. We believe typings are helpful to make
collaborative apps more robust, but if you’d prefer to skip the TypeScript
syntax, feel free to write your code in JavaScript.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your React
application. If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/react) first.

</Banner>

## Get other users in the room [#get-others]

Now that the provider is set up, we can start using the Liveblocks hooks. The
first we’ll add is [`useOthers`][], a hook that provides us information about
which _other_ users are connected to the room.

To show how many other users are in the room, import `useOthers` into a
component and use it as below.

```tsx highlight="1,4"
import { RoomProvider, useOthers } from "@liveblocks/react/suspense";

function App() {
  const others = useOthers();

  return <div>There are {others.length} other users with you in the room.</div>;
}

function Index() {
  return (
    <RoomProvider id="my-room-id">
      <App />
    </RoomProvider>
  );
}
```

Great! We’re connected, and we already have information about the other users
currently online.

## Define initial presence [#define-presence]

Most collaborative features rely on each user having their own temporary state,
which is then shared with others. For example, in an app using multiplayer
cursors, the location of each user’s cursor will be their state. In Liveblocks,
we call this _presence_.

We can use _presence_ to hold any object that we wish to share with others. An
example would be the pixel coordinates of a user’s cursor:

```js
cursor: { x: 256, y: 367 }
```

To start using presence, let’s define a type named `Presence` in
`liveblocks.config.ts`.

```tsx file="liveblocks.config.ts" highlight="8-10,12"
declare global {
  interface Liveblocks {
    Presence: {
      cursor: { x: number; y: number } | null;
    };
  }
}
```

Then, define an `initialPresence` value on our `RoomProvider`. We’ll set the
initial cursor to `null` to represent a user whose cursor is currently
off-screen.

```tsx file="index.ts" highlight="7"
import { RoomProvider, useOthers } from "@liveblocks/react/suspense";

// App

function Index() {
  return (
    <RoomProvider id="my-room-id" initialPresence={{ cursor: null }}>
      <App />
    </RoomProvider>
  );
}
```

## Update user presence [#update-presence]

We can add the [`useUpdateMyPresence`][] hook to share this information in
realtime, and in this case, update the current user cursor position when
`onPointerMove` is called. Next, import `updateMyPresence` and call it with the
updated cursor coordinates whenever a pointer move event is detected.

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

function App() {
  const updateMyPresence = useUpdateMyPresence();

  return (
    <div
      style={{ width: "100vw", height: "100vh" }}
      onPointerMove={(e) =>
        updateMyPresence({ cursor: { x: e.clientX, y: e.clientY } })
      }
      onPointerLeave={() => updateMyPresence({ cursor: null })}
    />
  );
}
```

We’re setting `cursor` to `null` when the user’s pointer leaves the element.

## Get other users’ presence [#get-others-presence]

To retrieve each user’s presence, and cursor locations, we can once again add
[`useOthers`][]. This time we’ll use a selector function to map through each
user’s presence, and grab their cursor property. If a cursor is set to `null`, a
user is off-screen, so we’ll skip rendering it.

```tsx highlight="20-26"
import {
  useOthers,
  useUpdateMyPresence,
  RoomProvider,
} from "@liveblocks/react/suspense";

function App() {
  const others = useOthers();
  const updateMyPresence = useUpdateMyPresence();

  return (
    <div
      style={{ width: "100vw", height: "100vh" }}
      onPointerMove={(e) =>
        updateMyPresence({ cursor: { x: e.clientX, y: e.clientY } })
      }
      onPointerLeave={() => updateMyPresence({ cursor: null })}
    >
      {others.map(({ connectionId, presence }) =>
        presence.cursor ? (
          <Cursor
            key={connectionId}
            x={presence.cursor.x}
            y={presence.cursor.y}
          />
        ) : null
      )}
    </div>
  );
}

// Basic cursor component
function Cursor({ x, y }) {
  return (
    <img
      style={{
        position: "absolute",
        transform: `translate(${x}px, ${y}px)`,
      }}
      src="/assets/cursor.svg"
    />
  );
}
```

Presence isn’t only for [multiplayer cursors](/examples/browse/cursors), and can
be helpful for a number of other use cases such as
[live avatar stacks](/examples/browse/avatar-stack) and
[realtime form presence](/examples/browse/forms).

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livelist.push`]: /docs/api-reference/liveblocks-client#LiveList.push
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`liveobject.get`]: /docs/api-reference/liveblocks-client#LiveObject.get
[`liveobject.set`]: /docs/api-reference/liveblocks-client#LiveObject.set
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`room.subscribe`]:
  /docs/api-reference/liveblocks-client#Room.subscribe(storageItem)
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`usehistory`]: /docs/api-reference/liveblocks-react#useHistory
[`useothers`]: /docs/api-reference/liveblocks-react#useOthers
[`useredo`]: /docs/api-reference/liveblocks-react#useRedo
[`useundo`]: /docs/api-reference/liveblocks-react#useUndo
[`useupdatemypresence`]:
  /docs/api-reference/liveblocks-react#useUpdateMyPresence
[`useconnectionids`]: /docs/api-reference/liveblocks-react#useConnectionIds
[`usestorage`]: /docs/api-reference/liveblocks-react#useStorage
[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation

---
meta:
  title: "How to use Liveblocks Presence with Redux"
  description: "Learn how to use Liveblocks Presence with Redux"
---

In this guide, we’ll be learning how to use Liveblocks Presence with Redux using
the APIs from the [`@liveblocks/redux`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Redux store. If
you don’t make sure to follow
[these quick steps to get started](/docs/get-started/redux) first.

</Banner>

## Get other users in the room [#get-others]

<Banner title="Need help troubleshooting presence?">

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

If you want to list all the people connected to the room, you can use
`state.liveblocks.others` to get an array of the other users in the room.

```jsx
import { useSelector } from "react-redux";

function App() {
  const others = useSelector((state) => state.liveblocks.others);
}
```

## Update user presence [#update-presence]

To create immersive multiplayer experiences, it’s helpful for each person in the
room to share their real‑time state with other connected users. That real‑time
state often corresponds to a cursor position or even the item a user has
currently selected. We call this concept "Presence".

For instance, to share the cursor’s position in real‑time with others, we’re
going to add a new `presenceMapping` option to our `enhancer` to specify which
part of the state maps to the current user’s `presence`.

```jsx file="src/store.js"
/* ... imports and client setup ... */

const initialState = {
  cursor: { x: 0, y: 0 },
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    setCursor: (state, action) => {
      state.cursor = action.payload;
    },
  },
});

export const { setCursor } = slice.actions;

function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      enhancer({
        client,
        presenceMapping: { cursor: true },
      }),
    ],
  });
}

const store = makeStore();

export default store;
```

Then you can dispatch an action like in any redux app and we will broadcast this
cursor to everyone in the room.

```jsx
import { useDispatch } from "react-redux";
import { setCursor } from "./store.js";

function YourComponent() {
  const dispatch = useDispatch();

  return (
    <div
      style={{ width: "100vw", height: "100vh" }}
      onPointerMove={(e) => dispatch(setCursor({ x: e.clientX, y: e.clientY }))}
    />
  );
}
```

## Get other users’ presence [#get-others-presence]

Get people’s cursor positions with
`liveblocks.others.map(user => user.presence?.cursor)`. It’s worth noting that a
user presence can be `undefined`.

```jsx
import { useSelector } from "react-redux";

function OthersCursors() {
  const others = useSelector((state) => state.liveblocks.others);

  const othersCursors = others.map((user) => user.presence?.cursor);

  // Render cursors with custom SVGs based on x and y
}
```

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-redux
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks Presence with Zustand"
  description: "Learn how to use Liveblocks Presence with Zustand"
---

In this guide, we’ll be learning how to use Liveblocks Presence with Zustand
using the APIs from the [`@liveblocks/zustand`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Zustand store.
If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/zustand) first.

</Banner>

## Get other users in the room [#get-others]

<Banner title="Need help troubleshooting presence?">

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

If you want to list all the people connected to the room, you can use
`liveblocks.others` to get an array of the other users in the room.

```tsx
import useStore from "./store";

function YourComponent() {
  useStore((state) => state.liveblocks.others);
}
```

## Update user presence [#update-presence]

To create immersive multiplayer experiences, it’s helpful for each person in the
room to share their real‑time state with other connected users. That real‑time
state often corresponds to a cursor position or even the item a user has
currently selected. We call this concept “Presence”.

For instance, to share the cursor’s position in real‑time with others, we’re
going to add a new `presenceMapping` option to our `liveblocks` middleware
configuration to specify which part of the state maps to the current user’s
presence. In this case, we’re updating the `cursor` position in our store in the
`onPointerMove` event listener in our React component.

```ts file="src/store.ts" highlight="6,9-10,20-21,25-27"
import create from "zustand";
import { createClient } from "@liveblocks/client";
import { liveblocks } from "@liveblocks/zustand";
import type { WithLiveblocks } from "@liveblocks/zustand";

type Cursor = { x: number; y: number };

type State = {
  cursor: Cursor;
  setCursor: (cursor: Cursor) => void;
};

const client = createClient({
  publicApiKey: "{{PUBLIC_KEY}}",
});

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

export default useStore;
```

```tsx file="src/App.tsx" highlight="18-24"
import React, { useEffect } from "react";
import useStore from "./store";

import "./App.css";

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

  useEffect(() => {
    enterRoom("room-id");
    return () => {
      leaveRoom("room-id");
    };
  }, [enterRoom, leaveRoom]);

  const setCursor = useStore((state) => state.setCursor);
  return (
    <div
      style={{ width: "100vw", height: "100vh" }}
      onPointerMove={(e) => setCursor({ x: e.clientX, y: e.clientY })}
    />
  );
};

export default App;
```

## Get other users’ presence [#get-others-presence]

Get people’s cursor positions with
`liveblocks.others.map(user => user.presence.cursor)`.

```tsx file="src/App.tsx"
function App() {
  /* ... */

  const others = useStore((state) => state.liveblocks.others);
  const othersCursors = others.map((user) => user.presence.cursor);

  // Render cursors with custom SVGs based on x and y
}
```

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-zustand
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks Storage with React"
  description: "Learn how to use Liveblocks Storage with React"
---

In this guide, we’ll be learning how to use Liveblocks Storage with React using
the hooks from the [`@liveblocks/react`][] package.

This guide uses [TypeScript](https://www.typescriptlang.org/). Liveblocks can
definitely be used without TypeScript. We believe typings are helpful to make
collaborative apps more robust, but if you’d prefer to skip the TypeScript
syntax, feel free to write your code in JavaScript

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your React
application. If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/react) first.

</Banner>

## Sync and persist the state across client [#storage-intro]

<Banner title="Need help troubleshooting storage?">

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

Some collaborative features require a single shared state between all users—an
example of this would be a
[collaborative design tool](/examples/browse/whiteboard), with each shape having
its own state, or a form with shared inputs. In Liveblocks, this is where
`storage` comes in. Room storage automatically updates for every user on
changes, and unlike presence, persists after users disconnect.

### Storage types

Our storage uses special data structures (inspired by
[CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)) to
resolve all conflicts, meaning that state is always accurate. There are
[multiple storage types](https://liveblocks.io/docs/api-reference/liveblocks-client#Storage)
available:

- [`LiveObject`][] - Similar to a JavaScript object.
- [`LiveList`][] - An array-like ordered collection of items.
- [`LiveMap`][] - Similar to a JavaScript Map.

### Defining initial storage [#initial-storage]

To use storage, first define a type named `Storage` in `liveblocks.config.ts`.
In this example we’ll define a [`LiveObject`][] called `scientist`, containing
first and last name properties.

```tsx file="liveblocks.config.ts" highlight="1,4-6,11"
import { LiveObject } from "@liveblocks/client";

declare global {
  interface Liveblocks {
    Storage: { scientist: LiveObject<{ firstName: string; lastName: string }> };
  }
}
```

Then, define the initial structure within [`RoomProvider`][].

```tsx file="index.ts"
import { LiveObject } from "@liveblocks/client";
import { RoomProvider } from "@liveblocks/react/suspense";

/* App */

function Index() {
  return (
    <RoomProvider
      id="my-room-id"
      initialPresence={/* ... */}
      // +++
      initialStorage={{
        scientist: new LiveObject({
          firstName: "Marie",
          lastName: "Curie",
        }),
        // +++
      }}
    >
      <App />
    </RoomProvider>
  );
}
```

### Using storage

Once the default structure is defined, we can then make use of our storage. The
[`useStorage`][] hook allows us to access an immutable version of our storage
using a selector function.

```tsx highlight="4,12,13"
import { useStorage } from "@liveblocks/react";

function App() {
  const scientist = useStorage((root) => root.scientist);

  if (scientist == null) {
    return <div>Loading...</div>;
  }

  return (
    <>
      <input value={scientist.firstName} />
      <input value={scientist.lastName} />
    </>
  );
}
```

The two input values will now automatically update in a realtime as `firstName`
and `lastName` are modified by other users.

`useStorage` returns `null` during the initial loading because the storage is
loaded from the server. It can quickly become cumbersome to handle `null`
whenever we use `useStorage`, but we have some good new for you;
`@liveblocks/react` contains a
[`Suspense`](https://beta.reactjs.org/reference/react/Suspense) version of all
of our hooks.

### Updating storage

The best way to update storage is through mutations. The [`useMutation`][] hook
allows you to create reusable callback functions that modify Liveblocks state.
For example, let’s create a mutation that can modify the scientist’s name.

Inside this mutation we’re accessing the storage root, a [`LiveObject`][] like
`scientist`, and retrieving a mutable copy of `scientist` with
[`LiveObject.get`]. From there, we can set the updated name using
[`LiveObject.set`].

```tsx
// Define mutation
const updateName = useMutation(({ storage }, nameType, newName) => {
  const mutableScientist = storage.get("scientist");
  mutableScientist.set(nameType, newName);
}, []);
```

We can then call this mutation, and pass `nameType` and `newName` arguments.

```tsx
updateName("firstName", "Albert");
```

If we take a look at this in the context of a component, we can see how to
combine [`useStorage`][] to display the names, and [`useMutation`][] to modify
them. Note that `useMutation` takes a dependency array, and works similarly to
`useCallback`.

```tsx file="index.ts"
import { useStorage, useMutation } from "@liveblocks/react";

function YourComponent() {
  const scientist = useStorage((root) => root.scientist);

  if (scientist == null) {
    return <div>Loading...</div>;
  }

  const updateName = useMutation(({ storage }, nameType, newName) => {
    const mutableScientist = storage.get("scientist");
    mutableScientist.set(nameType, newName);
  }, []);

  return (
    <>
      <input
        value={scientist.firstName}
        onChange={(e) => updateName("firstName", e.target.value)}
      />
      <input
        value={scientist.lastName}
        onChange={(e) => updateName("lastName", e.target.value)}
      />
    </>
  );
}
```

All changes made within `useMutation` are automatically batched and sent to the
Liveblocks together. `useMutation` can also be used to retrieve and modify
presence too, giving you access to multiple parameters, not just `storage`.

```tsx
useMutation({ storage, self, others, setMyPresence });
```

Find more information in the
[Mutations](/docs/api-reference/liveblocks-react#useMutation) section of our
documentation.

### Nested data structures

With Liveblocks storage, it’s possible to nest data structures inside each
other, for example `scientist` could hold a [`LiveList`][] containing a list of
pets.

```tsx highlight="3"
initialStorage={{
  scientist: new LiveObject({
    pets: new LiveList(["🐶", "🐱", "🐷"]),
    firstName: "Marie",
    lastName: "Curie",
  })
}}
```

Because the `useStorage` selector converts your data structure into a normal
immutable JavaScript structure (made from objects, arrays, maps), `pets` can be
accessed directly with `useStorage`.

```tsx
// ["🐶", "🐱", "🐷"]
const pets = useStorage((root) => root.scientist.pets);
```

You can even reach into a `LiveObject` or `LiveList` and extract a property.

```tsx
// "Marie"
const firstName = useStorage((root) => root.scientist.firstName);

// "🐶"
const firstPet = useStorage((root) => root.scientist.pets[0]);
```

### Improving storage performance

`useStorage` is highly efficient and only triggers a rerender when the value
returned from the selector changes. For example, the following selectors will
only trigger rerenders when their respective values change, and are unaffected
by any other storage updates.

```tsx
// ✅ Rerenders only when root.scientist.firstName changes
const firstName = useStorage((root) => root.scientist.firstName);

// ✅ Rerenders only when root.scientist changes
const scientist = useStorage((root) => root.scientist);
```

However, selector functions must return a stable result to be efficient—if a new
object is created within the selector function, it will rerender on every
storage change.

```tsx
// ❌ Rerenders on every change because `map` returns a new array every time
const pets = useStorage((root) => root.scientist.pets.map((pet) => pet + pet));
```

To account for this, we can pass a `shallow` equality check function, provided
by `@liveblocks/react`:

```tsx highlight="1,6"
import { shallow } from "@liveblocks/react";

// ✅ Rerenders only when root.scientist.pets shallowly changes
const pets = useStorage(
  (root) => root.scientist.pets.map((pet) => pet + pet),
  shallow
);
```

Find more information in the
[How selectors work](/docs/api-reference/liveblocks-react#selectors) section of
our documentation.

### Using Suspense

If you’d like to use `Suspense` in your application, make sure to re-export our
hooks from `"@liveblocks/react/suspense"`.

And then put a `Suspense` component right below the `RoomProvider`. This version
of `useStorage` never returns `null`, the loading fallback will be handled by
`Suspense` `fallback`.

```tsx file="index.ts" highlight="2,28-30"
import { LiveObject } from "@liveblocks/client";
import { Suspense } from "react";
import { RoomProvider, useStorage } from "@liveblocks/react/suspense";

function App() {
  const scientist = useStorage((root) => root.scientist);

  return (
    <>
      <input value={scientist.firstName} />
      <input value={scientist.lastName} />
    </>
  );
}

function Index() {
  return (
    <RoomProvider
      id="my-room-id"
      initialPresence={/* ... */}
      initialStorage={{
        scientist: new LiveObject({
          firstName: "Marie",
          lastName: "Curie",
        }),
      }}
    >
      <Suspense fallback={<div>Loading</div>}>
        <App />
      </Suspense>
    </RoomProvider>
  );
}
```

If you’re using a framework that supports Server Side Rendering like
[Next.js](https://nextjs.org/), you cannot use `Suspense` directly like this.
Liveblocks does not load the storage on the server by default, so the components
using `useStorage` will never be able to render. To keep the benefits from
`Suspense`, you should use `ClientSideSuspense` from ` @liveblocks/react`
instead of the normal `Suspense` from React like this:

```tsx file="index.ts" highlight="1,12-14"
import { ClientSideSuspense } from "@liveblocks/react/suspense";

// ...

function Index() {
  return (
    <RoomProvider
      id="my-room-id"
      initialPresence={/* ... */}
      initialStorage={/* ... */}
    >
      <ClientSideSuspense fallback={<div>Loading...</div>}>
        {() => <App />}
      </ClientSideSuspense>
    </RoomProvider>
  );
}
```

[`@liveblocks/client`]: /docs/api-reference/liveblocks-client
[`@liveblocks/react`]: /docs/api-reference/liveblocks-react
[`createroomcontext`]: /docs/api-reference/liveblocks-react#createRoomContext
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`livelist.push`]: /docs/api-reference/liveblocks-client#LiveList.push
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`liveobject.get`]: /docs/api-reference/liveblocks-client#LiveObject.get
[`liveobject.set`]: /docs/api-reference/liveblocks-client#LiveObject.set
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`room.subscribe`]:
  /docs/api-reference/liveblocks-client#Room.subscribe(storageItem)
[`roomprovider`]: /docs/api-reference/liveblocks-react#RoomProvider
[`usehistory`]: /docs/api-reference/liveblocks-react#useHistory
[`useothers`]: /docs/api-reference/liveblocks-react#useOthers
[`useredo`]: /docs/api-reference/liveblocks-react#useRedo
[`useundo`]: /docs/api-reference/liveblocks-react#useUndo
[`useupdatemypresence`]:
  /docs/api-reference/liveblocks-react#useUpdateMyPresence
[`useconnectionids`]: /docs/api-reference/liveblocks-react#useConnectionIds
[`usestorage`]: /docs/api-reference/liveblocks-react#useStorage
[`usemutation`]: /docs/api-reference/liveblocks-react#useMutation

---
meta:
  title: "How to use Liveblocks Storage with Redux"
  description: "Learn how to use Liveblocks Storage with Redux"
---

In this guide, we’ll be learning how to use Liveblocks Storage with Redux using
the APIs from the [`@liveblocks/redux`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Redux store. If
you don’t make sure to follow
[these quick steps to get started](/docs/get-started/redux) first.

</Banner>

## Sync and persist the state across client [#storage-intro]

As opposed to `presence`, some collaborative features require that every user
interacts with the same piece of state. For example, in Google Docs, 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`.

<Banner title="Need help troubleshooting storage?">

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

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.

When using our Redux integration you cannot interact directly with these data
structures. Our enhancer synchronizes your store with our data structures based
on the `storageMapping` configuration.

Here is an example to explain how it works under the hood. Imagine you have the
following store:

```js
/* ...client setup... */

const initialState = {
  firstName: "Marie",
  lastName: "Curie",
  discoveries: ["Polonium", "Radium"],
};

const slice = createSlice({
  name: "state",
  initialState,
  reducers: {
    setFirstName: (state, action) => {
      state.firstName = action.payload;
    },
    setLastName: (state, action) => {
      state.lastName = action.payload;
    },
    addDiscovery: (state, action) => {
      state.discoveries.push(action.payload);
    },
  },
});

export const { setScientist } = slice.actions;

function makeStore() {
  return configureStore({
    reducer: slice.reducer,
    enhancers: [
      enhancer({
        client,
        storageMapping: { firstName: true, lastName: true, discoveries: true },
      }),
    ],
  });
}

const store = makeStore();
```

With this setup, the room's `storage` root is :

```js
const root = new LiveObject({
  firstName: "Marie",
  lastName: "Curie",
  discoveries: new LiveList(["Polonium", "Radium"]),
});
```

If you update your store by dispatching `setFirstName("Pierre")`, the enhancer
will do `root.set("firstName", "Pierre")` for you and update the store of all
the users currently connected to the room. The enhancer compares the previous
state and the new state to detect changes and patch our data structures
accordingly.

The reverse process happens when receiving updates from other clients; the
enhancer patches your immutable state.

When entering a room with `enterRoom`, the enhancer fetches the room's storage
from our server and patches your store. If this is the first time you're
entering a room, the storage will be empty. `enterRoom` takes an additional
argument to initialize the room's storage.

```js
enterRoom("room-id", {
  firstName: "Lise",
  lastName: "Meitner",
  discoveries: ["Nuclear fission", "Protactinium"],
});
```

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-redux
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks Storage with Zustand"
  description: "Learn how to use Liveblocks Storage with Zustand"
---

In this guide, we’ll be learning how to use Liveblocks Storage with Zustand
using the APIs from the [`@liveblocks/zustand`][] package.

<Banner title="Install Liveblocks">

This guide assumes you already have Liveblocks set up into your Zustand store.
If you don’t make sure to follow
[these quick steps to get started](/docs/get-started/zustand) first.

</Banner>

## Sync and persist the state across client [#storage-intro]

As opposed to `presence`, some collaborative features require that every user
interacts with the same piece of state. For example, in Google Docs, 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”.

<Banner title="Need help troubleshooting storage?">

Try the [Liveblocks DevTools extension](/devtools) to inspect and debug your
collaborative experiences as you build them, in realtime.

</Banner>

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.

When using our Zustand integration you cannot interact directly with these data
structures. Our middleware synchronizes your store with our data structures
based on the `storageMapping` configuration.

Here is an example to explain how it works under the hood. Imagine you have the
following store:

```ts file="src/store.ts" highlight="6-8,20-22"
/* ...client setup */

const useStore = create<WithLiveblocks<State>>()(
  liveblocks(
    (set) => ({
      firstName: "Marie",
      lastName: "Curie",
      discoveries: ["Polonium", "Radium"],

      setFirstName: (firstName) => set({ firstName }),
      setLastName: (lastName) => set({ lastName }),
      addDiscovery: (discovery) =>
        set((state) => ({
          discoveries: state.discoveries.concat([discovery]),
        })),
    }),
    {
      client,
      storageMapping: {
        firstName: true,
        lastName: true,
        discoveries: true,
      },
    }
  )
);
```

With this setup, the room's `storage` root is:

```ts
const root = new LiveObject({
  firstName: "Marie",
  lastName: "Curie",
  discoveries: new LiveList(["Polonium", "Radium"]),
});
```

If you update your store by calling `setFirstName("Pierre")`, the middleware
will do `root.set("firstName", "Pierre")` for you and update the store of all
the users currently connected to the room. The middleware compares the previous
state and the new state to detect changes and patch our data structures
accordingly.

The reverse process happens when receiving updates from other clients; the
middleware patches your immutable state.

When entering a room with `liveblocks.enterRoom`, the middleware fetches the
room's storage from our server and patches your store. If this is the first time
you're entering a room, the storage will be initialized with the current value
in your Zustand state, typically your initial state.

[`room.history.undo`]: /docs/api-reference/liveblocks-client#Room.history.undo
[`room.history.redo`]: /docs/api-reference/liveblocks-client#Room.history.redo
[`room.history.pause`]: /docs/api-reference/liveblocks-client#Room.history.pause
[`room.history.resume`]:
  /docs/api-reference/liveblocks-client#Room.history.resume
[`liveobject`]: /docs/api-reference/liveblocks-client#LiveObject
[`livemap`]: /docs/api-reference/liveblocks-client#LiveMap
[`livelist`]: /docs/api-reference/liveblocks-client#LiveList
[`createclient`]: /docs/api-reference/liveblocks-client#createClient
[api reference]: /docs/api-reference/liveblocks-zustand
[authentication]: /docs/authentication

---
meta:
  title: "How to use Liveblocks with Astro"
  description: "Learn how to add Liveblocks to your Astro app"
---

When adding Liveblocks to [Astro](https://astro.build) apps, it's recommended to
use
[`client:only`](https://docs.astro.build/en/reference/directives-reference/#clientonly)
with your components. This is recommended because Liveblocks only needs on the
client, and in Astro, you may run into bundling issues if the app is rendered on
both the server and client.

## Example

Here's an example of `client:only` used with various frameworks:

```astro
---
import SvelteInput from "../components/SvelteInput.svelte";
import ReactInput from "../components/ReactInput.tsx";
import VueInput from "../components/VueInput.vue";
---

<main>
  <ReactInput client:only="react" />
  <SvelteInput client:only="svelte" />
  <VueInput client:only="vue" />
</main>
```

## Not required with .astro components

Note that when using `.astro` components and the `<script>` tag, `client:only`
is not necessary, because it always runs on the client:

```astro
---
import VanillaInput from "../components/VanillaInput.astro";
---

<main>
  <VanillaInput />
</main>
```

```html
<script>
  import { room, myLiveObject } from "../liveblocksSetup.js";

  const input = document.querySelector("#vanilla");

  room.subscribe(myLiveObject, (updatedLiveObject) => {
    input.value = updatedLiveObject.get("text");
  });

  room.addEventListener("input", (e) => {
    myLiveObject.set("text", e.target.value);
  });
</script>

<input id="vanilla" type="text" onClick="this.select()" />
```

## Using @liveblocks/react with Astro

Note that when using our React package with Astro, `RoomProvider` does not work
in nested `.astro` files, as each component is a separate "island", and cannot
see the context in another island. Each React root in `.astro` files is like a
new React app, and will need its own `RoomProvider`.

---
meta:
  title: "How to use Liveblocks with Next.js /app directory"
  description: "Learn how to add Liveblocks to your Next.js app directory"
---

A pattern we’d recommend when using [Next.js](https://nextjs.org) /app directory
is creating a providers client component for
[`LiveblocksProvider`](/docs/api-reference/liveblocks-react#LiveblocksProvider)
and importing it into `layout.tsx`.

```tsx file="app/Providers.tsx"
import { ReactNode } from "react";
import { LiveblocksProvider } from "@liveblocks/react/suspense";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">
      {children}
    </LiveblocksProvider>
  );
}
```

```tsx file="app/layout.tsx"
import { ReactNode } from "react";
import { Providers } from "./Providers";

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

To join rooms, create a `Room.tsx` client component in the current route, using
`RoomProvider` within here.

```tsx file="app/Room.tsx"
"use client";

import { ReactNode } from "react";
import { RoomProvider } from "../liveblocks.config";
import { LiveObject } from "@liveblocks/client";

export default function Room({ children }: { children: ReactNode }) {
  return (
    <RoomProvider
      id="my-room-name"
      initialStorage={{
        // ✅ This is a client component, so everything works!
        session: new LiveObject(),
      }}
    >
      {children}
    </RoomProvider>
  );
}
```

Doing this avoids an issue when importing `LiveObject/LiveMap/ListList` into
server components. You can then use `Room.tsx` in your page component, and
everything will work as expected.

```tsx file="app/page.tsx"
import { Room } from "./Room";

export default function Page() {
  return <Room>{/* Your Liveblocks app */}</Room>;
}
```

## Structuring your app

To take this one step further, you can then server-render your layout within
`Room`’s `children`, whilst using other client components for realtime parts of
your app:

```tsx file="room.tsx"
import { ReactNode } from "react";
import { Room } from "./Room";
import { LiveCanvas } from "./LiveCanvas";

export default function Page({ children }: { children: ReactNode }) {
  return (
    // Room.tsx is a client component that contains RoomProvider
    <Room>
      {/* This layout is server rendered */}
      <header style={{ height: "150px" }}>My drawing app</header>
      <main style={{ width: "100%" }}>
        {/* LiveCanvas is a client component using Liveblocks features */}
        <LiveCanvas />
      </main>
    </Room>
  );
}
```

---
meta:
  title: "How to use Yjs subdocuments"
  description: "Learn how to Yjs subdocuments on client and server"
---

Liveblocks Yjs supports [subdocuments](https://docs.yjs.dev/api/subdocuments),
which allow you to nest Yjs documents inside each other. This guide takes you
through how to use them on client and server.

## When to use subdocuments

Subdocuments are helpful when you have multiple _large_ Yjs documents in the
same room, and you wish to lazy-load them individually. Each subdocument works
similarly to a normal Yjs document, allowing you to use
[shared types](https://docs.yjs.dev/getting-started/working-with-shared-types),
[awareness](https://docs.yjs.dev/getting-started/adding-awareness), and more.

### Not necessary for multiple text editors

Please note that **subdocuments are not necessary for displaying multiple text
editors** on one page. For this use case, it’s often best to create a
[`Y.Map`](https://docs.yjs.dev/api/shared-types/y.map) in your Yjs document, and
place the contents of each editor inside. For example, if your text editor uses
[`Y.XmlFragment`](https://docs.yjs.dev/api/shared-types/y.xmlfragment), here’s
how to create this.

```tsx
// Create Yjs document with an `editors` map
const yDoc = new Y.Doc();
const yMap = yDoc.getMap("editors");

// Create shared types and add to map
const editorOne = new Y.XMLFragment();
const editorTwo = new Y.XMLFragment();
yMap.set("editor-1", editorOne);
yMap.set("editor-2", editorTwo);

// Pass `editorOne` and `editorTwo` to your text editors
// ...
```

This is much simpler than using subdocuments. However, if the content of these
editors is very large, or if your text editor only accepts a `Y.Doc`,
subdocuments may be for you.

## On the client

Subdocuments can be stored in your Yjs tree like any other shared type. In this
example we’ll create a [`Y.Map`](https://docs.yjs.dev/api/shared-types/y.map) to
store them in, making sure to lazy load any subdocuments.

```ts
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import * as Y from "yjs";

// Create main document and connect, disabling auto-loading of subdocuments
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, doc, {
  autoloadSubdocs: false,
});

// Create a Y.Map to hold subdocuments
const subdocMap = yDoc.getMap("subdocs");
```

### Create a subdocument [#create-a-subdocument]

To create a new subdocument, create a `new Y.Doc()`, and use this it any other.

```ts highlight="8-9,11-14,16-17"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import * as Y from "yjs";

// Create main document and connect, disabling auto-loading of subdocuments
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, doc, {
  autoloadSubdocs: false,
});

// Create a Y.Map to hold subdocuments
const subdocMap = yDoc.getMap("subdocs");

// Create subdocument
const subdoc = new Y.Doc();
yDoc.getMap().set("my-document", subdoc);
subdoc.getText("default").insert(0, "This is a subdocument");

// Make note of its `guid`, which is used for retrieving it later
const guid = subdoc.guid; // e.g. "c4a755..."
```

Make sure to keep track of its `guid`.

### Load the subdocument

To load the subdocument on _another client_, use its `guid`.

```ts highlight="8-9"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import * as Y from "yjs";

// Create main document and connect, disabling auto-loading of subdocuments
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, doc, {
  autoloadSubdocs: false,
});

// From another client, load the subdoc using the GUID from `subdoc.guid` or `doc.getSubdocGuids`
yProvider.loadSubdoc("c4a755...");

// Alternatively, get a reference to a subdocument from `doc.getSubdocs()` and then load
// subdoc.load();
```

### Listening for changes

To keep track of subdocument changes, you can use `Y.Doc.on("subdocs")`.

```ts highlight="10-13"
import { LiveblocksYjsProvider } from "@liveblocks/yjs";
import * as Y from "yjs";

// Create main document and connect, disabling auto-loading of subdocuments
const yDoc = new Y.Doc();
const yProvider = new LiveblocksYjsProvider(room, yDoc, {
  autoloadSubdocs: false,
});

yDoc.on("subdocs", ({ added, removed, loaded }) => {
  // Subdocument change
  // ...
});
```

## On the server

It’s possible to use your subdocument on the server, without connecting with a
provider.

### Fetching a subdocument

When fetching a Yjs subdocument on the server, it’s recommended to use
[`liveblocks.getYjsDocumentAsBinaryUpdate`](/docs/api-reference/liveblocks-node#get-rooms-roomId-ydoc-binary)
with the `guid` of your subdocument. We stored the `guid` when we
[created the subdocument](#create-a-subdocument).

```ts highlight="9-13,15-17"
import { Liveblocks } from "@liveblocks/node";
import * as Y from "yjs";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export function POST() {
  // Get your Yjs subdocument as a binary update
  const update = liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id", {
    // The `guid` of your subdocument, as noted earlier
    guid: "c4a755...",
  });

  // Create a Yjs document for your subdoc and apply the update
  const subdoc = new Y.Doc();
  Y.applyUpdate(subdoc, new Uint8Array(update));

  // `subdoc` can now be read
  // ...
}
```

We’ve now retrieved the subdocument, and it can be read, but any changes you
make won’t be applied to other clients, and are only temporary.

### Updating a subdocument

To permanently apply changes to your subdocument, sending them to Liveblocks and
other clients, you can use
[`liveblocks.sendYjsBinaryUpdate`](/docs/api-reference/liveblocks-node#put-rooms-roomId-ydoc).

```ts highlight="19-20,22-23,25-29"
import { Liveblocks } from "@liveblocks/node";
import * as Y from "yjs";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});

export function POST() {
  // Get your Yjs subdocument as a binary update
  const update = liveblocks.getYjsDocumentAsBinaryUpdate("my-room-id", {
    // The `guid` of your subdocument, as noted earlier
    guid: "c4a755...",
  });

  // Create a Yjs document for your subdoc and apply the update
  const subdoc = new Y.Doc();
  Y.applyUpdate(subdoc, new Uint8Array(update));

  // Make changes to your `subdoc`, for example
  subdoc.getText("my-text").insert(0, "Hello world");

  // Convert `subdoc` into a binary update
  const subdocChanges = Y.encodeStateAsUpdate(subdoc);

  // Send the changes to Liveblocks, and other clients
  liveblocks.sendYjsBinaryUpdate("my-room-id", subdocChanges, {
    // The `guid` of your subdocument, as noted earlier
    guid: "c4a755...",
  });
}
```

After running this code, all connected users will see the update.

---
meta:
  title: "How to use your Y.Doc on the server"
  description: "Learn how to retrieve your Yjs document’s Y.Doc on the server"
---

Using [`@liveblocks/node`](/docs/api-reference/liveblocks-node), it’s possible
to retrieve your Yjs document and use it as a
[`Y.Doc`](https://docs.yjs.dev/api/y.doc) on the server. This is often helpful
for retrieving text editor state, and we have some specific guides for this:

- [Getting Tiptap state on the server](/docs/guides/getting-tiptap-state-on-the-server).
- [Getting ProseMirror state on the server](/docs/guides/getting-prosemirror-state-on-the-server).

## Getting your Y.Doc

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`.

```ts
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";

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

  // `yDoc` can now be used as you like
  // ...
}
```

Note that any changes you make will not be applied to other users, as the
`Y.Doc` is not connected to any providers.

## Applying changes

Should you wish to send any changes to your document to other users, you can
encode `yDoc` as a binary update, and use
[`Liveblocks.sendYjsBinaryUpdate`](/docs/api-reference/liveblocks-node#put-rooms-roomId-ydoc)
to apply the change.

```ts highlight="18-20,22-23,25-26"
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";

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

  // An example of a `yDoc` modification
  const yText = yDoc.getText("text");
  yText.insert(0, "Hello world");

  // Encode the document state as an update
  const yUpdate = Y.encodeStateAsUpdate(yDoc);

  // Send the update to Liveblocks
  await liveblocks.sendYjsBinaryUpdate(roomId, yUpdate);
}
```

These changes will be immediately applied to all connected users.

---
meta:
  title: "Modifying Yjs document data with the REST API"
  description:
    "Learn how to update your Yjs document using the Liveblocks REST API"
---

Liveblocks allows you to update your Yjs document data, or `yDoc`, from the REST
API, helpful for sending updates from the server. This is made possible through
[`Liveblocks.sendYjsBinaryUpdate`](/docs/api-reference/liveblocks-node#put-rooms-roomId-ydoc)
in [`@liveblocks/node`](/docs/api-reference/liveblocks-node).

## Updating a Yjs document

Updating a Yjs document requires you to create a
[binary update](https://docs.yjs.dev/api/document-updates), before sending it to
Liveblocks using
[`Liveblocks.sendYjsBinaryUpdate`](/docs/api-reference/liveblocks-node#put-rooms-roomId-ydoc).
Here’s an example in a serverless endpoint.

```ts
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});
const roomId = "my-room-name";

export async function POST() {
  // Create a Yjs document
  const yDoc = new Y.Doc();

  // Create your data structures and make your update
  // Each editor is different, you probably need to change these two lines
  const yText = yDoc.getText("text");
  yText.insert(0, "Hello world");

  // Encode the document state as an update
  const yUpdate = Y.encodeStateAsUpdate(yDoc);

  // Insert the update
  await liveblocks.sendYjsBinaryUpdate(roomId, yUpdate);
}
```

Note that if you’re using a text editor,
[each one works differently](#each-editor-works-differently), so you’ll most
likely need to modify these two lines to use a format your editor defines.

```ts
const yText = yDoc.getText("text");
yText.insert(0, "Hello world");
```

## Initializing a Yjs document

It’s also possible to create a new room with an initial Yjs document. To do
this, call
[`Liveblocks.createRoom`](/docs/api-reference/liveblocks-node#post-rooms), then
send the update as before.

```ts highlight="21-24"
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});
const roomId = "my-room-name";

export async function POST() {
  // Create a Yjs document
  const yDoc = new Y.Doc();

  // Create your data structures and make your update
  // Each editor is different, you probably need to change these two lines
  const yText = yDoc.getText("text");
  yText.insert(0, "Hello world");

  // Encode the document state as an update
  const yUpdate = Y.encodeStateAsUpdate(yDoc);

  // Create the new room
  const room = await liveblocks.createRoom(roomId, {
    defaultAccesses: ["room:write"],
  });

  // Initialize the Yjs document with the update
  await liveblocks.sendYjsBinaryUpdate(roomId, yUpdate);
}
```

## Each editor works differently [#each-editor-works-differently]

Note that each text and code editor may work differently, and may include
specific functions for creating binary updates, or use different shared types.
Slate and Tiptap use
[`Y.XmlFragment`](https://docs.yjs.dev/api/shared-types/y.xmlfragment) instead
of [`Y.Text`](https://docs.yjs.dev/api/shared-types/y.text).

### Slate

This is how to initialize a [Slate](/docs/get-started/yjs-slate-react) document.

```ts highlight="3,14-18,20-22"
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";
import { slateNodesToInsertDelta } from "@slate-yjs/core";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});
const roomId = "my-room-name";

export async function POST() {
  // Create a Yjs document
  const yDoc = new Y.Doc();

  // The Slate document we're creating
  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 yUpdate = Y.encodeStateAsUpdate(yDoc);

  // Create the new room
  const room = await liveblocks.createRoom(roomId, {
    defaultAccesses: ["room:write"],
  });

  // Initialize the Yjs document with the update
  await liveblocks.sendYjsBinaryUpdate(roomId, yUpdate);
}
```

### Tiptap

This is how to initialize a
[Tiptap](https://tiptap.dev/docs/editor/api/extensions/collaboration) document.

```ts highlight="13-15,17-19"
import * as Y from "yjs";
import { Liveblocks } from "@liveblocks/node";

const liveblocks = new Liveblocks({
  secret: "{{SECRET_KEY}}",
});
const roomId = "my-room-name";

export async function POST() {
  // Create a Yjs document
  const yDoc = new Y.Doc();

  // The Tiptap Yjs state we're creating
  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);

  // Create the new room
  const room = await liveblocks.createRoom(roomId, {
    defaultAccesses: ["room:write"],
  });

  // Initialize the Yjs document with the update
  await liveblocks.sendYjsBinaryUpdate(roomId, yUpdate);
}
```

---
meta:
  title: "Reauthenticate without reloading the page or losing state"
  description:
    "Learn how to reauthenticate the current room without refreshing the page"
---

Sometimes it’s helpful to [reauthenticate](/docs/authentication) users, for
example after a logged out user has signed into your application, and you wish
to display their details.

## How to reauthenticate

By calling
[`room.reconnect`](/docs/api-reference/liveblocks-client#Room.reconnect) you can
reconnect and reauthenticate your collaborative application without refreshing
the page or unmounting the
[`RoomProvider`](/docs/api-reference/liveblocks-react#RoomProvider) component.
Using this method will preserve the current client’s state, such as the
undo/redo history.

```ts highlight="5"
const { room, leave } = client.enterRoom("my-room", {
  // ...
});

room.reconnect();
```

### In React

In our React package, you can retrieve the current room with the
[`useRoom`](/docs/api-reference/liveblocks-react#useRoom) hook, before calling
`room.reconnect` from there.

```tsx highlight="4,6"
import { useRoom } from "../liveblocks.config";

export function App() {
  const room = useRoom();

  return <button onClick={room.reconnect}>Reauthenticate</button>;
}
```

---
meta:
  title: "Revalidate API data in realtime with SWR"
  description:
    "Learn how use Liveblocks and SWR to revalidate API data in realtime"
---

[SWR](https://swr.vercel.app) is a library that provides
[React](https://react.dev) hooks for data fetching. It’s possible to revalidate
your data in realtime by broadcasting events using Liveblocks.

An example usage of this may be a share dialog containing a list of users—when a
new user is added to the dialog, we can broadcast an event telling other online
users to refresh their user list.

## Broadcasting events

A simple SWR hook that fetches a list of users may look similar to this:

```tsx
function Component() {
  const { data: users, mutate } = useSWR("/api/users", fetcher);

  return (
     <div>
       {users.map((user) => /* ... */)}:
     </div>
  );
}
```

To create a function that allows us to update this data in realtime, we can
broadcast an event telling other clients to revalidate their data with
[useBroadcastEvent](https://liveblocks.io/docs/api-reference/liveblocks-react#useBroadcastEvent):

```tsx
const broadcast = useBroadcastEvent();

// Sending a custom REVALIDATE event
broadcast({ type: "REVALIDATE" });
```

We can then listen for the event with
[useEventListener](https://liveblocks.io/docs/api-reference/liveblocks-react#useEventListener),
and call the mutate function from SWR to update the data:

```tsx
const { data: users, mutate } = useSWR("/api/users", fetcher);

useEventListener(({ event }) => {
  if (event.type === "REVALIDATE") {
    mutate();
  }
});
```

## Putting it together

If we put everything together, we can display a list of users, broadcasting a
revalidate event when a new user is added to the list.

```tsx
import { useBroadcastevent, useEventListener } from "../liveblocks.config";

function Component() {
  // Data updates on every button click
  const { data, mutate } = useSWR("/api/user", fetcher);

  // Listen for custom event
  useEventListener(({ event }) => {
    if (event.type === "REVALIDATE") {
      mutate();
    }
  });

  // Create broadcast hook
  const broadcast = useBroadcastEvent();

  function addUser() {
    // Code to add a new user to your list
    // ...

    // Broadcast the custom event
    broadcast({ type: "REVALIDATE" });
  }

  return (
    <div>
      {users.map((user) => /* ... */)}:
      <button onClick={addUser}>Add new user</button>
    </div>
  );
}
```

Great, data that revalidates in realtime at the click of a button! You can find
an example of this technique being used in the
[Next.js Starter Kit](https://github.com/liveblocks/liveblocks/blob/main/starter-kits/nextjs-starter-kit/components/ShareDialog/ShareDialog.tsx#L123-L131).

---
meta:
  title: "Setting an initial or default value in BlockNote"
  description:
    "Learn how to set an initial value to display when the document is empty"
---

Yjs doesn’t allow you to set an initial value for a document, as documents are
stored as a list of changes, rather than as the current state. If you were to
try add a default value, this would instead be sent as an append command,
meaning that it would be added to any existing data in the document, instead of
working as a default value.

## Setting content in BlockNote

BlockNote allows you to set a default value by setting `initialContent` in
`useCreateBlockNote`, however when connected to Yjs this will trigger the
duplication problem.

```tsx
function Editor({ doc, provider }: EditorProps) {
  const editor: BlockNoteEditor = useCreateBlockNote({
    // +++
    initialContent: [{ type: "paragraph", content: "Hello world" }],
    // +++

    // Other options
    // ...
  });

  return <BlockNoteView editor={editor} />;
}
```

### Default value with Yjs

To avoid this problem, you can instead wait for Liveblocks Yjs to connect, check
if the editor’s content is empty, and _then_ set a default value.

```tsx
function Editor({ doc, provider }: EditorProps) {
  const editor = useEditor({
    // Options
    // ...
  });

  // +++
  // Set default state
  useEffect(() => {
    function setDefault() {
      if (!editor) {
        return;
      }

      if (editor.document.length === 1) {
        editor.insertBlocks(
          [{ type: "paragraph", content: "Hello world" }],
          editor.document[0]
        );
      }
    }

    if (provider.isReady) {
      setDefault();
    }

    provider.on("sync", setDefault);
    return () => provider.off("sync", setDefault);
  }, [provider, editor]);
  // +++

  return <BlockNoteView editor={editor} />;
}
```

Note that we’re assuming your BlockNote application is set up as recommended in
our [getting started guide](/docs/get-started/yjs-blocknote-react).

---
meta:
  title: "Setting an initial or default value in Tiptap"
  description:
    "Learn how to set an initial value to display when the document is empty"
---

Yjs doesn’t allow you to set an initial value for a document, as documents are
stored as a list of changes, rather than as the current state. If you were to
try add a default value, this would instead be sent as an append command,
meaning that it would be added to any existing data in the document, instead of
working as a default value.

<Banner title="This guide is for Yjs, not Text Editor" type="warning">

If you’re using our [Text Editor](/docs/ready-made-features/text-editor) Tiptap
product, there’s an
[option to set the initial value](/docs/api-reference/liveblocks-react-tiptap#Setting-initial-content),
and you should use this method. This guide is only
[Sync Datastore and Yjs](/docs/platform/sync-datastore).

</Banner>

## Setting content in Tiptap

Tiptap allows you to set a default value by setting `content` in `useEditor`,
however when connected to Yjs this will trigger the duplication problem.

```tsx highlight="3"
function Editor({ doc, provider }: EditorProps) {
  const editor = useEditor({
    content: "<p>This will duplicate on load</p>",

    // Options
    // ...
  });

  return <EditorContent editor={editor} />;
}
```

### Default value with Yjs

To avoid this problem, you can instead wait for Liveblocks Yjs to connect, check
if the editor’s content is empty, and _then_ set a default value.

```tsx highlight="7-27"
function Editor({ doc, provider }: EditorProps) {
  const editor = useEditor({
    // Options
    // ...
  });

  // Set default state
  useEffect(() => {
    function setDefault() {
      if (!editor) {
        return;
      }

      if (editor.getText() === "") {
        editor.commands.setContent(`
          <h1>Default content</h1>
          <p>
            My <strong>paragraph</strong>
          </p>
        `);
      }
    }

    setDefault();
    provider.on("sync", setDefault);
    return () => provider.off("sync", setDefault);
  }, [provider, editor]);

  return <EditorContent editor={editor} />;
}
```

Note that we’re assuming your Tiptap application is set up as recommended in our
[getting started guide](/docs/get-started/yjs-tiptap-react).

---
meta:
  title: "What happens when a user joins a room at maximum capacity?"
  description:
    "Learn what happens when a room reaches the maximum simultaneous connections
    per room"
---

Liveblocks allows you to gracefully handle maximum user limits in rooms. But
first, when is a room at maximum capacity?

- A room is full when it’s hit your maximum simultaneous connections per room
  limit.
- Your maximum simultaneous connections limit is defined by your current
  [plan](/pricing).
- Any users above that count will not be able to join the room.
- Any users already in the room will not be affected by another user trying to
  join.
- If a user can’t join a room, they will not be counted towards your MAUs.

## Example

For example, let’s say your plan allows for 50 simultaneous connections. If
there’s a room that currently has 50 users inside, Marie (the 51st user) will
not be able to join the room. If Marie tries to join, the first 50 users in the
room will be unaffected, and the room will function as normal. However, Marie’s
client will receive an error, which can be handled.

## Handling users that are over the count

No JavaScript `Error` is thrown when a user tries to join a room that’s full,
instead you can listen for error events, which are helpful for displaying a
warning or redirecting the user elsewhere.

### In React

With our
[`@liveblocks/react`](https://liveblocks.io/docs/api-reference/liveblocks-react)
package, you can listen for error events with
[`useErrorListener`](/docs/api-reference/liveblocks-react#useErrorListener).
When `error.code === 4005`, that means the room was full when the user tried to
join.

```tsx highlight="15-17"
import { useErrorListener } from "../liveblocks.config";

function App() {
  // Listen for errors
  useErrorListener((error) => {
    switch (error.code) {
      case -1:
        // Authentication error
        break;

      case 4001:
        // Could not connect because you don't have access to this room
        break;

      case 4005:
        // Could not connect because room was full
        break;

      default:
        // Unexpected error
        break;
    }
  });

  // ...
}
```

### In JavaScript

With our [`@liveblocks/client`](/docs/api-reference/liveblocks-client) package,
you can listen for error events with
[`room.subscribe("error")`](/docs/api-reference/liveblocks-client#Room.subscribe.error).
When `error.code === 4005`, that means the room was full when the user tried to
join.

```ts highlight="17-19"
// No error is thrown when the room is full
const { room, leave } = client.enterRoom("my-room", {
  /* ... */
});

// Listen for errors
const unsubscribe = room.subscribe("error", (error) => {
  switch (error.code) {
    case -1:
      // Authentication error
      break;

    case 4001:
      // Could not connect because you don't have access to this room
      break;

    case 4005:
      // Could not connect because room was full
      break;

    default:
      // Unexpected error
      break;
  }
});
```

---
meta:
  title: "What to check before enabling a new notification kind"
  description: "Checklist for changing notification kinds in the dashboard"
---

When publishing changes to your notification settings in the dashboard, you
should make sure your app is ready to handle any webhooks changes. This is not a
problem when _disabling_ a notification kind, but when you _enable_ a new
notification kind you should check that your app is ready to receive these new
notifications.

## Enabling in the dashboard

When in the notifications settings dashboard, you can enable and disable various
webhook events for different kinds. For example, below we’ve toggled a custom
notification `kind`.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-toggle-custom-notification.png"
    alt="Toggle a custom notification kind"
    width={712}
    height={445}
  />
</Figure>

Before publishing this change, it’s important to understand what will occur, and
to modify your app.

## What happens when you enable a notification kind

After enabling and publishing a notification kind, a new webhook event will be
sent for that `kind` on the channel you selected. Below is an example of an API
endpoint set up for a Liveblocks webhook—you can see the new event that will be
received if you were to enable a custom notification sent on the email channel.

<Banner title="Step-by-step guides">

If you don’t recognise this code, you should read one of our guides on setting
up notification kinds with webhooks, where everything is explained:
[thread guide](/docs/guides/how-to-send-email-notifications-of-unread-comments)
and
[textMention guide](/docs/guides/how-to-send-email-notifications-for-unread-text-editor-mentions).

</Banner>

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

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  if (event.type !== "notification") {
    return new Response("This is not a notification webhook", { status: 400 });
  }

  // {
  //   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",
  //   },
  // }
  console.log(event);

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

As you can see above, the two highlighted lines are the fields for the new
event, and you’ll need to handle them.

## Before publishing the change

Before publishing your notification settings change, you’ll most likely wish to
check for `channel` and `kind` in your webhook endpoint, and handle it
accordingly.

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

// Add your webhook secret key from a project's webhooks dashboard
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_KEY";
const webhookHandler = new WebhookHandler(WEBHOOK_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 });
  }

  if (event.type !== "notification") {
    return new Response("This is not a notification webhook", { status: 400 });
  }

  // +++
  if (
    event.data.channel === "email" &&
    event.data.kind === "$myCustomNotification"
  ) {
    // Send an email to your user for this custom notification
    // ...

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

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

If you don’t handle this, you may find yourself running into problems, depending
on the way you’ve written the logic in your app.

## Safe to publish

After changing your webhook endpoint, it’s safe for you to go back to the
notification settings page, and publish your changes.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-enable-custom-notification.png"
    alt="Enable a notification kind"
    width={712}
    height={445}
  />
</Figure>

Events for the new notification kind will now be called in your app.

## Users can change their preferences

Each user in your app can set their own preferences for notifications, and after
enabling a notification kind, each user’s will be set to the default value.

<Figure>
  <Image
    src="/assets/tutorials/webhooks/liveblocks-default-enabled.png"
    alt="Default notification settings"
    width={768}
    height={480}
  />
</Figure>

You can use
[`useUpdateNotificationSettings`](/docs/api-reference/liveblocks-react#useUpdateNotificationSettings)
to view and set each user’s individual values, making it easy to create
notification setting panels. Below, we’re allowing users to toggle `thread`
notifications on the `email` channel.

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

function NotificationSettings() {
  // +++
  const [{ isLoading, error, settings }, updateSettings] =
    useNotificationSettings();
  // +++

  if (isLoading || error) {
    return null;
  }

  return (
    <form>
      <input
        type="checkbox"
        // +++
        checked={settings.email.thread}
        onChange={(e) =>
          updateSettings({ email: { thread: e.target.checked } })
        }
        // +++
        id="setting-email-thread"
      />
      <label htmlFor="setting-email-thread">
        Receive thread notifications by email
      </label>
    </form>
  );
}
```

You can use this hook to create a full notification panel for each user. If
you’re not on React, you can use
[JavaScript](/docs/api-reference/liveblocks-client#Client.getNotificationSettings)
or
[Node.js](/docs/api-reference/liveblocks-node#get-users-userId-notification-settings)
functions instead.