Comments - Primitives

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 and Headless UI.
  • Can be used alongside the default components.

Concepts

Each primitive is made up of one or more components, for example Comment only needs Comment.Body. This component takes a comment’s body, and turns it into readable text, with links and mentions.

import { CommentData } from "@liveblocks/client";import { Comment } from "@liveblocks/react-comments/primitives";
// Render a custom comment bodyfunction 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.

import { CommentData } from "@liveblocks/client";import { Comment } from "@liveblocks/react-comments/primitives";
// Render a custom comment bodyfunction 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.

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.

import { CommentData } from "@liveblocks/client";import {  Comment,  CommentBodyLinkProps,} from "@liveblocks/react-comments/primitives";
// Render a custom comment bodyfunction 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.

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.

<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.

<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.

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 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.

import { Composer } from "@liveblocks/react-comments/primitives";import { useCreateThread } from "../liveblocks.config.ts";
// Render a custom composer that creates a thread on submitfunction 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, links, and a suggestions selection popover.

useComposer

The 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.

import { Composer, useComposer } from "@liveblocks/react-comments/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 emptyfunction MyComposerButton() {  const { isEmpty, submit } = useComposer();
  return (    <button onClick={submit} disabled={isEmpty}>      Create thread    </button>  );}

Comment

The Comment primitive is used to render a comment.body object as text, mentions, and links.

import { Comment } from "@liveblocks/react-comments/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.

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 and links.

Timestamp

The 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.

import { Timestamp } from "@liveblocks/react-comments";import { useThreads } from "../liveblocks.config";
// Render threads with friendly datetime messages abovefunction Component() {  const { threads } = useThreads();
  return (    <>      {threads.map((thread) => (        <div key={thread.id}>          Thread posted at: <Timestamp date={thread.createdAt} />          {/* Render `thread` ... */}        </div>      ))}    </>  );}