@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.
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 attachments.
Whether to show the composer’s formatting controls.
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 the composer is submitted.
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.
The event handler called when clicking on a comment’s attachment.
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.
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
.
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.
The composer’s initial attachments.
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 to show and allow adding attachments.
Whether to show formatting controls (e.g. a floating toolbar with formatting toggles when selecting text)
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 show attachments.
Whether to show the composer’s formatting controls when editing the comment.
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.
The event handler called when clicking on a comment’s attachment.
Override the component’s strings.
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 composer’s initial attachments.
Whether to create attachments when pasting files into the editor.
When preventUnsavedChanges
is set on your Liveblocks
client
on
LiveblocksProvider
,
then closing a browser tab will be prevented when there are unsaved changes.
By default, that will include draft text or attachments that are being
uploaded via this composer, but not submitted yet. If you want to prevent
unsaved changes with Liveblocks, but not for this composer, you can opt-out
this composer instance by setting this prop to false
.
The event handler called when the form is submitted.
Whether the composer is disabled.
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 a floating toolbar attached to the selection.
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 a floating toolbar attached to the selection within Composer.Editor
.
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.
Displays a floating toolbar attached to the selection within Composer.Editor
.
Replace the rendered element by the one passed as a child.
A toggle button which toggles a specific text mark.
The text mark to toggle.
The event handler called when the mark is toggled.
Replace the rendered element by the one passed as a child.
A button which opens a file picker to create attachments.
Replace the rendered element by the one passed as a child.
A drop area which accepts files to create attachments.
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.
Displays a formatted file size.
Use with attachment.size
to display a human-readable file size.
The file size to display.
A function to format the displayed file size. Defaults to a human-readable file size formatting function.
The locale used when formatting the file size. 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.
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.
Whether the composer is currently disabled.
Whether the editor is currently focused.
Whether the editor is currently empty.
Whether the composer can currently be submitted.
Submit the editor programmatically.
Clear the editor programmatically.
Select the editor programmatically.
Focus the editor programmatically.
Blur the editor programmatically.
Which text marks are currently active and which aren’t.
Remove an attachment by its ID.
Start creating a mention at the current selection.
Insert text at the current selection.
Open a file picker programmatically to create attachments.
The composer’s current attachments.
Remove an attachment by its ID.
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">
.
The inbox notification to display.
The URL which the inbox notification links to.
How to show or hide the actions.
Override specific kinds of inbox notifications.
Override the component’s strings.
Override the component’s components.
Override specific kinds of inbox notifications.
The component used to display thread notifications. Defaults to
InboxNotification.Thread
.
The component used to display a custom notification kind. Custom
notification kinds must start with a $
.
Displays a thread inbox notification.
The inbox notification to display.
How to show or hide the actions.
Whether to show the room name in the title.
Whether to show reactions.
Whether to show attachments.
Displays a custom notification kind.
The inbox notification to display.
The inbox notification’s title.
The inbox notification’s content.
How to show or hide the actions.
The inbox notification’s aside content. Can be combined with
InboxNotification.Icon
or InboxNotification.Avatar
to easily follow default styles.
Replace the rendered element by the one passed as a child.
Displays inbox notifications as a list. Each
InboxNotification
component will be wrapped in a li
element.
The inbox notifications to display.
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.
The function to call when the version summary is clicked.
The version object containing information about the specific version.
Whether this version is currently selected.
Displays a list of version summaries for a document’s history including authors and dates.
The version summaries to display, typically an array of HistoryVersionSummary components.
Most icons used in the default components can be exported via <Icon.* />
.
They’re stroke-based and designed for use at 20×20 pixels.
Find a full list of available icons in our GitHub repo.
Set configuration options for all @liveblocks/react-ui
components, such as
overrides.
Override the components’ strings.
Override the components’ components.
The container to render the portal into.
When preventUnsavedChanges
is set on your Liveblocks client (or set on
LiveblocksProvider
), then closing a browser tab will be prevented when
there are unsaved changes. By default, that will include draft texts or
attachments that are (being) uploaded via comments/threads composers, but
not submitted yet. If you want to prevent unsaved changes with Liveblocks,
but not for composers, you can opt-out by setting this option to false
.
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.
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 destructive color.
The foreground color used over the destructive color.
The main background color.
The main foreground color.
The line height of main elements (e.g. comment bodies).
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.
Affects the lightness of accent colors. %
value required.
Affects the lightness of destructive colors. %
value required.
Affects the lightness of foreground colors. %
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 LiveblocksUIConfig
:
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:
We use cookies to collect data to improve your experience on our site. Read our Privacy Policy to learn more.