@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.
The thread to display.
How to show or hide the composer to reply to the thread.
How to show or hide the actions.
Whether to show reactions.
Whether to show the action to resolve the thread.
Whether to indent the comments’ content.
Whether to show deleted comments.
The event handler called when changing the resolved status.
The event handler called when the thread is deleted. A thread is deleted when all its comments are deleted.
The event handler called when a comment is edited.
The event handler called when a comment is deleted.
The event handler called when clicking on a comment’s author.
The event handler called when clicking on a mention.
Override the component’s strings.
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
.
The ID of the thread to reply to or to edit a comment in.
The ID of the comment to edit.
The metadata of the thread to create.
The event handler called when the composer is submitted.
The composer’s initial value.
Whether the composer is collapsed. Setting a value will make the composer controlled.
The event handler called when the collapsed state of the composer changes.
Whether the composer is initially collapsed. Setting a value will make the composer uncontrolled.
Whether the composer is disabled.
Whether to focus the composer on mount.
Override the component’s strings.
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.
The comment to display.
How to show or hide the actions.
Whether to show reactions.
Whether to indent the comment’s content.
Whether to show the comment if it was deleted. If set to false
, it will
render deleted comments as null
.
The event handler called when the comment is edited.
The event handler called when the comment is deleted.
The event handler called when clicking on the author.
The event handler called when clicking on a mention.
Override the component’s strings.
Set configuration options for all Comments components, such as overrides.
Override the components’ strings.
The container to render the portal into.
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.
The border radius scale. em
values recommended.
The spacing scale. em
values recommended.
The accent color.
The foreground color used over the accent color.
The main background color.
The main foreground color.
The size of icons.
The stroke weight of icons.
The border radius used for avatars.
The border radius used for buttons.
The duration used for transitioned elements.
The easing function used for transitioned elements.
The box shadow added to elevated elements.
The box shadow added to tooltips.
The background color used for elevated elements.
The foreground color used for elevated elements.
The background color used for tooltips.
The foreground color used for tooltips.
Affects the lightness of accent colors. %
value required.
Affects the lightness of foreground colors. %
value required.
Affects the lightness of foreground colors in elevated elements. %
value
required.
Affects the lightness of foreground colors in tooltips. %
value required.
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.
The event handler called when the form is submitted.
Replace the rendered element by the one passed as a child.
Displays the composer’s editor.
The editor’s initial value.
The text to display when the editor is empty.
Whether the editor is disabled.
Whether to focus the editor on mount.
The reading direction of the editor and related elements.
The components displayed within the 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. Defaults to the mention’s userId
prefixed by an @.
The component used to display mention suggestions. Defaults to a list of the
suggestions’ userId
.
The component used to display links. Defaults to the link’s children
property.
The component used to display mentions.
The mention’s user ID.
Whether the mention is selected.
The component used to display mention suggestions.
The list of suggested user IDs.
he currently selected user ID.
The component used to display links.
The link’s absolute URL.
The link’s content.
Displays mentions within Composer.Editor
.
Replace the rendered element by the one passed as a child.
Attribute | Value |
---|---|
data-selected | Present when the mention is selected. |
Contains suggestions within Composer.Editor
.
Replace the rendered element by the one passed as a child.
Displays a list of suggestions within Composer.Editor
.
Replace the rendered element by the one passed as a child.
Displays a suggestion within Composer.SuggestionsList
.
The suggestion’s value.
Replace the rendered element by the one passed as a child.
Attribute | Value |
---|---|
data-selected | Present when the item is selected. |
Displays links within Composer.Editor
.
Replace the rendered element by the one passed as a child.
A button to submit the composer.
Replace the rendered element by the one passed as a child.
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 comment body to display. If not defined, the component will render
null
.
The components displayed within the comment body.
Replace the rendered element by the one passed as a child.
The components displayed within the comment body.
The component used to display mentions. Defaults to the mention’s userId
prefixed by an @.
The component used to display links. Defaults to the link’s children
property.
The component used to display mentions.
The mention’s user ID.
The component used to display links.
The link’s absolute URL.
The link’s content.
Displays mentions within Comment.Body
.
Replace the rendered element by the one passed as a child.
Displays links within Comment.Body
.
Replace the rendered element by the one passed as a child.
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.
The date to display.
A function to format the displayed date. Defaults to a relative date formatting function.
The title
attribute’s value or a function to format it. Defaults to an
absolute date formatting function.
The interval in milliseconds at which the component will re-render. Can be
set to false
to disable re-rendering.
The locale used when formatting the date. Defaults to the browser’s locale.
Replace the rendered element by the one passed as a child.
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.