@liveblocks/react-comments
provides you with React
components to build a commenting experience. Read our
getting started guide to learn more.
Displays a thread of comments. Each thread has a composer for creating replies.
Map through threads
to render a list of the room’s threads and comments.
Threads can be retrieved with
useThreads
.
A thread allows you to attach custom metadata to it when using the
mutation hooks, and when
creating a thread with the composer. The Thread
component automatically adds the resolved
property to metadata
, and this
property is used to display a checkbox which denotes whether the thread has been
resolved or not.
If you’d like to use this, make sure to add the resolved
property to
ThreadMetadata
in your config file for valid type-checking.
Displays a composer for creating threads or comments.
By default, submitting the composer will create a new thread.
If you’d like to attach custom metadata to the newly created thread, you can add
a metadata
prop.
Optionally, you can type metadata
by importing your custom ThreadMetadata
type from your config file.
If you provide a threadId
, then submitting the composer will add a new reply
to the thread.
If you provide both a threadId
and a commentId
, then submitting the composer
will edit the comment.
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.
Learn more about mutation hooks under
@liveblocks/react
.
Displays a single comment.
Map through thread.comments
to render each comment in a thread. Threads can be
retrieved with useThreads
.
Comment
can be used in combination with Composer
to
create a custom thread component. The composer in this example is used to
reply to the existing thread.
Displays a single inbox notification.
Override specific kinds of inbox notifications.
Displays a thread inbox notification.
Displays a custom notification kind.
Displays inbox notifications as a list. Each
InboxNotification
component will be wrapped in a li
element.
Set configuration options for all Comments components, such as overrides.
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
.
You can also import default dark mode styling. There are two versions to choose from, the first uses the system theme.
The second uses the dark
class name, and two commonly used data attributes.
The default components are built around a set of customizable CSS variables. Set
these variables within .lb-root
to globally style your components.
Each default component has a set of predefined class names, which can be helpful for custom styling, for example.
Additionally, some elements also have data attributes to provide contextual information, for example:
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.
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 CommentsConfig
:
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:
Primitives are unstyled, headless components that can be used to create fully custom commenting experiences.
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.
Used to render a composer for creating, or editing, threads and comments.
Combine with
useCreateThread
to
render a composer that creates threads.
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,
creating comments,
editing comments, etc.
Displays the composer’s editor.
Attribute | Value |
---|---|
data-focused | Present when the component is focused. |
data-disabled | Present when the component is disabled. |
The components displayed within the editor.
The component used to display mentions.
The component used to display mention suggestions.
The component used to display links.
Displays mentions within Composer.Editor
.
Attribute | Value |
---|---|
data-selected | Present when the mention is selected. |
Contains suggestions within Composer.Editor
.
Displays a list of suggestions within Composer.Editor
.
Displays a suggestion within Composer.SuggestionsList
.
Attribute | Value |
---|---|
data-selected | Present when the item is selected. |
Displays links within Composer.Editor
.
A button to submit the composer.
Used to render a single comment.
Map through thread.comments
to render each comment in a thread. Threads can be
retrieved with useThreads
.
Displays a comment body.
The components displayed within the comment body.
The component used to display mentions.
The component used to display links.
Displays mentions within Comment.Body
.
Displays links within Comment.Body
.
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”).
Use with comment.createdAt
, comment.editedAt
, or comment.deletedAt
to
display a human-readable time.
Returns states and methods related to the composer. Can only be used within the
Composer.Form
primitive.
This hook has a number of uses, for example constructing a custom button that submits threads, and disabling it when the composer input is empty.
Other Comments hooks are part of
@liveblocks/react
, you can find them
on the
React API reference page.