API Reference - Comments

@liveblocks/react-comments provides you with React components to build a commenting experience. Read our getting started guide to learn more.

Components

Customization

Styling

The default components come with default styles, import them either at the root of your app or directly in CSS depending on your setup.

import "@liveblocks/react-comments/styles.css";

@import "@liveblocks/react-comments/styles.css";

They are built around a few customizable CSS variables:

/* Basic */--lb-radius: 0.5em;--lb-spacing: 1em;--lb-accent: #17f;--lb-accent-foreground: #fff;--lb-background: #fff;--lb-foreground: #111;
/* Advanced */--lb-icon-size: 20px;--lb-icon-weight: 1.5px;--lb-avatar-radius: 50%;--lb-button-radius: calc(0.75 * var(--lb-radius));--lb-transition-duration: 0.1s;--lb-transition-easing: cubic-bezier(0.4, 0, 0.2, 1);--lb-elevation-shadow: 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%);--lb-tooltip-shadow: 0 2px 4px rgb(0 0 0 / 8%), 0 4px 12px rgb(0 0 0 / 12%);--lb-elevation-background: var(--lb-background);--lb-elevation-foreground: var(--lb-foreground);--lb-tooltip-background: #222;--lb-tooltip-foreground: #fff;--lb-accent-contrast: 8%;--lb-foreground-contrast: 6%;--lb-elevation-foreground-contrast: 6%;--lb-tooltip-foreground-contrast: 10%;

If these CSS variables aren’t enough, every elements within the components have clearly defined classes. Additionaly, some elements also have data attributes to provide contextual information (e.g. data-variant="primary" on .lb-button, data-self on .lb-comment-mention, data-loading on .lb-avatar and .lb-user, etc.).

Dark mode

Dark mode can be implemented by customizing some of the default CSS variables, and we provide styles that do so out-of-the-box. They exist in two versions:

• media-query uses the prefers-color-scheme media query.
• attributes targets either the dark class, the data-theme attribute if it’s set to "dark", or the data-dark attribute.

import "@liveblocks/react-comments/styles.css";
// Choose one depending on your setupimport "@liveblocks/react-comments/styles/dark/media-query.css";import "@liveblocks/react-comments/styles/dark/attributes.css";

@import "@liveblocks/react-comments/styles.css";
/* Choose one depending on your setup */@import "@liveblocks/react-comments/styles/dark/media-query.css";@import "@liveblocks/react-comments/styles/dark/attributes.css";

Browser support

The default styles use modern CSS features like container queries, :has() and color-mix(). While container queries and :has() are used as progressive enhancements and aren’t required, color-mix() is used extensively to generate the various color scales. If you need to support browser versions that don’t support color-mix(), you can specify the color scales manually:

--lb-accent-subtle: ;--lb-accent-moderate: ;--lb-accent-tertiary: ;--lb-accent-secondary: ;--lb-foreground-subtle: ;--lb-foreground-moderate: ;--lb-foreground-tertiary: ;--lb-foreground-secondary: ;--lb-elevation-foreground-subtle: ;--lb-elevation-foreground-moderate: ;--lb-elevation-foreground-tertiary: ;--lb-elevation-foreground-secondary: ;--lb-tooltip-foreground-subtle: ;--lb-tooltip-foreground-moderate: ;--lb-tooltip-foreground-tertiary: ;--lb-tooltip-foreground-secondary: ;

Overrides

Overrides can be used to customize the components’ strings and localization-related properties like the locale and reading direction.

They can be set globally once for all components using CommentsConfig:

import { CommentsConfig } from "@liveblocks/react-comments";
export function App() {  return (    <CommentsConfig      overrides={{ locale: "fr", UNKNOWN_USER: "Anonyme" /* ... */ }}    >      {/* ... */}    </CommentsConfig>  );}

Or they can be set per-component (which will take precedence over the global ones) for contextual cases like a <Composer /> used specifically to reply for example:

<Composer  overrides={{    COMPOSER_PLACEHOLDER: "Reply to thread…",    COMPOSER_SEND: "Reply",  }}/>

Thread

Displays a thread of comments, with a composer to reply to it.

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

Comment

Displays a single comment.

<>  {thread.comments.map((comment) => (    <Comment key={comment.id} comment={comment} />  ))}</>

Composer

Displays a composer to create comments.

<Composer />

By default, submitting the composer will create a new thread. If you provide a threadId prop, it will reply to that thread, and if you also provide a commentId prop, it will edit that comment. If you want to customize this, you can use event.preventDefault() in onComposerSubmit to disable the default behavior and call the mutation methods (e.g. createThread) manually.

<Composer  onComposerSubmit={({ body }, event) => {    event.preventDefault();
    createThread({      body,      metadata: {        x: 80,        y: 120,      },    });  }}/>

Primitives

Primitives are headless/unstyled components that can be used to create custom experiences with full control.

Composition

All primitives are composable: they forward their props and refs, merge their classes and styles, and chain their event handlers.

Inspired by Radix (and powered by its 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. Learn more about this concept on Radix’s composition guide.

import { Button } from "@/my-design-system";
// A default <button> element<Composer.Submit disabled>Send</Composer.Submit>;
// An existing custom <Button> component<Composer.Submit disabled asChild>  <Button variant="primary">Send</Button></Composer.Submit>;

Comment

import { Comment } from "@liveblocks/react-comments/primitives";
() => (  <Comment.Body    renderMention={() => <Comment.Mention />}    renderLink={() => <Comment.Link />}  />);

Comment.Body

Displays a comment body.

<Comment.Body body={comment.body} />

renderMention

A render prop that accepts a component used to render mentions.

<Comment.Body  renderMention={({ userId }) => <Comment.Mention>@{userId}</Comment.Mention>}/>

renderLink

A render prop that accepts a component used to render links.

<Comment.Body  renderLink={({ href, children }) => (    <Comment.Link href={href}>{children}</Comment.Link>  )}/>

Comment.Mention

Displays mentions within Comment.Body’s renderMention prop.

<Comment.Mention>@{userId}</Comment.Mention>

Comment.Link

Displays links within Comment.Body’s renderLink prop.

<Comment.Link href={href}>{children}</Comment.Link>

Composer

import { Composer } from "@liveblocks/react-comments/primitives";
() => (  <Composer.Form>    <Composer.Editor      renderMention={() => <Composer.Mention />}      renderMentionSuggestions={() => (        <Composer.Suggestions>          <Composer.SuggestionsList>            <Composer.SuggestionsListItem />          </Composer.SuggestionsList>        </Composer.Suggestions>      )}      renderLink={() => <Composer.Link />}    />    <Composer.Submit />  </Composer.Form>);

Composer.Form

Surrounds the composer’s content and handles submissions.

<Composer.Form onComposerSubmit={({ body }) => {}}>{/* ... */}</Composer.Form>

Composer.Editor

Displays the composer’s editor.

<Composer.Editor placeholder="Write a comment…" />

renderMention

A render prop that accepts a component used to render mentions.

<Composer.Editor  renderMention={({ userId, isSelected }) => (    <Composer.Mention>@{userId}</Composer.Mention>  )}/>

renderMentionSuggestions

A render prop that accepts a component used to render mention suggestions.

<Composer.Editor  renderMentionSuggestions={() => (    <Composer.Suggestions>      <Composer.SuggestionsList>        <Composer.SuggestionsListItem />      </Composer.SuggestionsList>    </Composer.Suggestions>  )}/>

renderLink

A render prop that accepts a component used to render links.

<Composer.Editor  renderLink={({ href, children }) => <Composer.Link>{children}</Composer.Link>}/>

Composer.Mention

Displays mentions within Composer.Editor’s renderMention prop.

<Composer.Mention>@{userId}</Composer.Mention>

Composer.Suggestions

Surrounds a list of suggestions within Composer.Editor.

<Composer.Suggestions>{/* … */}<Composer.Suggestions>

Composer.SuggestionsList

Displays a list of suggestions within Composer.Editor.

<Composer.SuggestionsList>{/* … */}</Composer.SuggestionsList>

Composer.SuggestionsListItem

Displays a suggestion within Composer.SuggestionsList.

<Composer.SuggestionsList>  {userIds.map((userId) => (    <Composer.SuggestionsListItem key={userId} value={userId}>      @{userId}    </Composer.SuggestionsListItem>  ))}</Composer.SuggestionsList>

Composer.Link

Displays links within Composer.Editor’s renderLink prop.

<Composer.Link href={href}>{children}</Composer.Link>

Composer.Submit

A button to submit the composer.

<Composer.Submit>Send</Composer.Submit>

Timestamp

Displays a formatted date, and automatically re-renders to support relative formatting. Defaults to relative formatting for recent dates and a short absolute formatting for older ones.

<Timestamp date={new Date()} />

Hooks

useComposer

Returns states and methods related to the composer. Can only be used within Composer.Form.

import { useComposer } from "@liveblocks/react-comments/primitives";
const { isEmpty, submit } = useComposer();