API Reference - @liveblocks/react-blocknote
@liveblocks/react-blocknote
provides you with a React
plugin that adds collaboration to any
BlockNote rich-text editor. It also adds
realtime cursors, document persistence on the cloud, comments, and mentions. Use
@liveblocks/node-prosemirror
for server-side editing.
Setup
To set up your collaborative BlockNote editor, create an editor with
useCreateBlockNoteWithLiveblocks
and pass
it into the
BlockNoteView
component provided by @blocknote/mantine
.
Liveblocks BlockNote components should be passed editor
to enable them.
Learn more in our get started guides.
Default components
FloatingComposer
Displays a Composer
near the current BlockNote selection, allowing you to
create threads.

Submitting a comment will attach an annotation thread at the current selection.
Should be passed your BlockNote editor
, and it’s recommended you set a width
value. Display created threads with AnchoredThreads
or
FloatingThreads
.
Opening the composer
To open the FloatingComposer
, you need to click the comment button in the
BlockNote toolbar, or call the addPendingComment
command added by Liveblocks. You
can use liveblocksCommentMark
to check if the current selection is a comment.
Props
- metadataThreadMetadata
The metadata of the thread to create.
- onComposerSubmitfunction
The event handler called when the composer is submitted.
- defaultValueCommentBody
The composer’s initial value.
- collapsedboolean
Whether the composer is collapsed. Setting a value will make the composer controlled.
- onCollapsedChangefunction
The event handler called when the collapsed state of the composer changes.
- defaultCollapsedboolean
Whether the composer is initially collapsed. Setting a value will make the composer uncontrolled.
- disabledboolean
Whether the composer is disabled.
- autoFocusboolean
Whether to focus the composer on mount.
- overridesPartial<GlobalOverrides & ComposerOverrides>
Override the component’s strings.
FloatingThreads
Displays floating Thread
components below text highlights in the editor.

Takes a list of threads retrieved from useThreads
and renders them to the
page. Each thread is opened by clicking on its corresponding text highlight.
Should be passed your BlockNote editor
, and it’s recommended you set a width
value.
Recommended usage
FloatingThreads
and AnchoredThreads
have been designed to work
together to provide the optimal experience on mobile and desktop. We generally
recommend using both components, hiding one on smaller screens, as we are below
with Tailwind classes. Most apps also don’t need to display resolved threads, so
we can filter those out with a useThreads
option.
We can place this component inside ClientSideSuspense
to prevent it
rendering until threads have loaded.
Customization
The FloatingThreads
component acts as a wrapper around each individual
Thread
. You can treat the component like you would a div
, using classes,
listeners, and more.
To apply styling to each Thread
, you can pass a custom Thread
property
to components
and modify this in any way. This is the best way to modify a
thread’s width.
You can return any custom ReactNode
here, including anything from a simple
wrapper around Thread
, up to a full custom Thread
component built using our
Comment primitives.
Props
- threadsThreadData[]Required
The threads to display.
- componentsPartial<AnchoredThreadsComponents>
Override the component’s components.
- components.Thread(props: ThreadProps) => ReactNode
Override the
Thread
component.
AnchoredThreads
Displays a list of Thread
components vertically alongside the editor.

Takes a list of threads retrieved from useThreads
and renders them to the
page. Each thread is displayed at the same vertical coordinates as its
corresponding text highlight. If multiple highlights are in the same location,
each thread is placed in order below the previous thread.
Recommended usage
FloatingThreads
and AnchoredThreads
have been designed to work
together to provide the optimal experience on mobile and desktop. We generally
recommend using both components, hiding one on smaller screens, as we are below
with Tailwind classes. Most apps also don’t need to display resolved threads, so
we can filter those out with a useThreads
option.
We can place this component inside ClientSideSuspense
to prevent it
rendering until threads have loaded.
Customization
The AnchoredThreads
component acts as a wrapper around each Thread
. It
has no width, so setting this is required, and each thread will take on the
width of the wrapper. You can treat the component like you would a div
, using
classes, listeners, and more.
To apply styling to each Thread
, you can pass a custom Thread
property
to components
and modify this in any way.
You can return any custom ReactNode
here, including anything from a simple
wrapper around Thread
, up to a full custom Thread
component built using our
Comment primitives.
Modifying thread floating positions
Using CSS variables you can modify the gap between threads, and the horizontal offset that’s added when a thread is selected.
Props
- threadsThreadData[]Required
The threads to display.
- componentsPartial<AnchoredThreadsComponents>
Override the component’s components.
- components.Thread(props: ThreadProps) => ReactNode
Override the
Thread
component.
HistoryVersionPreviewbeta
The HistoryVersionPreview
component allows you to display a preview of a
specific version of your BlockNote editor’s content. It also contains a button
and logic for restoring. It must be used inside the <LiveblocksPlugin>
context. To render a list of versions, see
VersionHistory
.
Usage
Props
- versionHistoryVersionRequired
The version of the editor content to preview.
- onVersionRestore(version: HistoryVersion) => void
Callback function called when the user chooses to restore this version.
The HistoryVersionPreview
component renders a read-only view of the specified
version of the editor content. It also provides a button for users to restore
the displayed version.
Hooks
useCreateBlockNoteWithLiveblocks
Creates a Liveblocks collaborative BlockNote editor. Use this hook instead of
useCreateBlockNote
.
editor
should be passed to
BlockNoteView
.
A number of options can be applied to BlockNote and Liveblocks.
- liveblocksExtension
Returns a BlockNote editor with collaborative Liveblocks features.
- blockNoteOptionsBlockNoteEditorOptions
Options to apply to BlockNote. Learn more.
- liveblocksOptionsobject
Options to apply to Liveblocks.
- liveblocksOptions.initialContentContent
The initial content for the editor, if it’s never been set. Learn more.
- liveblocksOptions.fieldstring
The name of this text editor’s field. Allows you to use multiple editors on one page, if each has a separate field value. Learn more.
- liveblocksOptions.offlineSupport_experimentalbooleanDefault is false
Experimental. Enable offline support using IndexedDB. This means the after the first load, documents will be stored locally and load instantly. Learn more.
- liveblocksOptions.commentsbooleanDefault is true
Enable comments in the editor.
- liveblocksOptions.mentionsbooleanDefault is true
Enable mentions in the editor.
Setting initial content
Initial content for the editor can be set with initialContent
. This content
will only be used if the current editor has never been edited by any users, and
is ignored otherwise.
Multiple editors
It’s possible to use multiple editors on one page by passing values to the
field
property. Think of it like an ID for the current editor.
Here’s an example of how multiple editors may be set up.
Offline supportexperimental
It’s possible to enable offline support in your editor with an experimental
option. This means that once a document has been opened, it’s saved locally on
the browser, and can be shown instantly without a loading screen. As soon as
Liveblocks connects, any remote changes will be synchronized, without any load
spinner. Enable this by passing a offlineSupport_experimental
value.
To make sure that your editor loads instantly, you must structure your app
carefully to avoid any Liveblocks hooks and ClientSideSuspense
components
from triggering a loading screen. For example, if you’re displaying threads in
your editor with useThreads
, you must place this inside a separate
component and wrap it in ClientSideSuspense
.
useIsEditorReady
Used to check if the editor content has been loaded or not, helpful for displaying a loading skeleton.
Here's how it can be used in the context of your editor.
Stylesheets
React BlockNote comes with default styles, and these can be imported into the
root of your app or directly into a CSS file with @import
. Note that you must
also install and import a stylesheet from
@liveblocks/react-ui
to use these
styles.
Customizing your styles
Adding dark mode and customizing your styles is part of @liveblocks/react-ui
,
learn how to do this under
styling and customization.