Hooks

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

List a room’s threads

The most important Comments hook is 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, or primitives. Here’s an example of it used with the default Thread component.

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 hook, the Suspense version, which we recommend by default, and the regular version.

Fetch a user’s information

The only information Liveblocks stores about users is their user ID, which is set when authenticating with Liveblocks. With the 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.

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 function in your liveblocks.config.ts file.

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 hook, Suspense, which we recommend by default, and regular.

Fetch a group’s information

Similar to users, Liveblocks only stores group IDs for groups. With the useGroupInfo hook, you can fetch a group’s information from their ID. This is particularly helpful when building primitive components, as this allows you to fetch their name, avatar, and any other custom data you’ve set.

import { useGroupInfo } from "../liveblocks.config";
function Component() {  const { group } = useGroupInfo("engineering");
  // { name: "Engineering", avatar: "https://...", color: "blue" }  console.log(group);
  return <img src={group.avatar} alt={group.name} />;}

The group data retrieved is set within the resolveGroupsInfo function in your liveblocks.config.ts file.

async function resolveGroupsInfo({ groupIds }) {  // ["engineering"]  console.log(groupIds);
  return [    {      name: "Engineering",      avatar: "https://example.com/engineering.png",      color: "blue",    },  ];}

There are two versions of the useGroupInfo hook, Suspense, which we recommend by default, and regular.

Create and modify threads and comments

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 which adds a reaction to a specified comment.

import { CommentData } from "@liveblocks/client";import { useAddReaction } from "../liveblocks.config.ts";
// A button that adds a "⭐" reaction to a commentfunction 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, have more complex behaviour and are designed to work alongside primitives.

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 submitfunction 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:

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

There are two different ways to use the threads and user hooks; with React Suspense, and without it. We recommend using the Suspense versions, as they often result in simpler code.

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.

import { useThreads } from "@liveblocks/react/suspense";
// Suspense: `threads` is always definedfunction MyThreads() {  const { threads } = useThreads();
  // [{ type: "thread", id: "th_sf8s6sh...", ... }, ...]  console.log(threads);}

To catch errors and display a loading screen, you can use ErrorBoundary and ClientSideSuspense.

import { ClientSideSuspense } from "@liveblocks/react/suspense";import { ErrorBoundary } from "react-error-boundary";
// Handle errors and loading state in the component abovefunction Component() {  return (    <ErrorBoundary fallback={<div>Error</div>}>      <ClientSideSuspense fallback={<div>Loading...</div>}>        <MyThreads />      </ClientSideSuspense>    </ErrorBoundary>  );}

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

// Suspense version of hooksimport { useThreads, useUser, useGroupInfo } from "@liveblocks/react/suspense";//                                                                   ^^^^^^^^

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.

import { useThreads } from "@liveblocks/react";
// Handle errors and loading state in the same componentfunction MyThreads() {  const { threads, error, isLoading } = useThreads();
  if (error) {    return <div>Error</div>;  }
  if (isLoading) {    return <div>Loading...</div>;  }
  // Non-Suspense: `threads` is only defined AFTER the `if` checks  // [{ type: "thread", id: "th_sf8s6sh...", ... }, ...]  console.log(threads);}

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

// Regular version of hooksimport { useThreads, useUser, useGroupInfo } from "@liveblocks/react";//                                                 ^^^^^^^^^^^^^^^^^