@liveblocks/react-ui
provides you with React components
to build collaborative experiences. Read our
Comments and
Notifications get started guides 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 can be marked as resolved or unresolved via its resolved
property.
The Thread
component automatically handles this through its resolved
toggle
button displayed by default.
You can additionally use thread.resolved
to filter the displayed threads for
example. Or if you want to create your own Thread
component using
the primitives, you can use
useMarkThreadAsResolved
and
useMarkThreadAsUnresolved
to update the property.
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.
You can use TypeScript to type your custom metadata by editing your config file.
Metadata properties can be string
, number
, or boolean
.
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.
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 a floating toolbar attached to the selection within Composer.Editor
.
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.
Displays a floating toolbar attached to the selection within Composer.Editor
.
A toggle button which toggles a specific text mark.
A button which opens a file picker to create attachments.
A drop area which accepts files to create attachments.
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.
Displays a formatted file size.
Use with attachment.size
to display a human-readable file size.
Returns states and methods related to the composer. Can only be used within the
Composer.Form
primitive.
All values listed below.
useComposer
can be used in combination with
Composer
primitives to create a custom composer, and
control its behavior. For example, createMention
allows you to create a button
which focuses the editor, adds @
, and opens the mention suggestions dropdown.
When using primitives,
Composer.AttachFiles
and
Composer.AttachmentsDropArea
add
attachments to the composer, but they’re not rendered without useComposer
. The
attachments
array can be used to render the current attachments, and
removeAttachment
allows you to remove them.
Other Comments hooks are part of
@liveblocks/react
, you can find them
on the
React API reference page.
useThreads
useThreadSubscription
useCreateThread
useDeleteThread
useEditThreadMetadata
useMarkThreadAsResolved
useMarkThreadAsUnresolved
useMarkThreadAsRead
useCreateComment
useEditComment
useDeleteComment
useAddReaction
useRemoveReaction
useAttachmentUrl
Displays a single inbox notification.
Map through inboxNotifications
with
useInboxNotifications
to render a list of the room’s notifications.
Different kinds
of notifications are available, for example thread
which is
triggered when using Comments, or $myCustomNotification
which would be a
custom notification you’ve triggered manually. You can choose to render each
notification differently.
Adding these two properties to kinds
will overwrite the default component
that’s displayed for those two notification types. Using
InboxNotification.Thread
and
InboxNotification.Custom
in this way allow you to easily create components that fit into the existing
design system, whilst still adding lots of customization. However, it’s also
valid to render any custom JSX.
To type custom notifications, edit the ActivitiesData
type in your config
file.
Your activities data is now correctly typed in inline functions.
If you’d like to create a typed function elsewhere, you can use
InboxNotificationCustomProps
with a generic. In the example below we’re using
the $alert
notification kind as a generic,
InboxNotificationCustomKindProps<"$alert">
.
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.
All hooks for Notifications are in
@liveblocks/react
.
When enabled, version history will automatically create versions of your Lexical or Yjs document and allow you to restore to specific versions. These components aid in displaying a list of those versions.
Displays a version summary which includes the author and date.
Displays a list of version summaries for a document’s history including authors and dates.
Set configuration options for all @liveblocks/react-ui
components, such as
overrides.
All hooks for Version History are in
@liveblocks/react
.
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.