Text editor - BlockNote

A quick overview of the packages for BlockNote.

Concepts

Liveblocks BlockNote allows you add collaboration to any BlockNote text editor, along with a number of related features. Each collaborative room in your application can store one document each, and these documents are persisted on the cloud, visible on your dashboard, and are integrated into other Liveblocks products such as Comments and Notifications.

Permanent storage

All documents created with BlockNote are permanently stored. You don’t need to sync, scale, or maintain any infrastructure.

Users and mentions

Users and groups can be added to your document, and you can tag others inline. You can also easily enable mention suggestions for both users and groups.

Users, groups, and mention suggestions can be added with resolveUsers, resolveGroupsInfo, and resolveMentionSuggestions.

import { LiveblocksProvider } from "@liveblocks/react/suspense";
function App() { return ( <LiveblocksProvider resolveUsers={async ({ userIds }) => { // Return user info from their `userIds` // ... }} resolveGroupsInfo={async ({ groupIds }) => { // Return group info from their `groupIds` // ... }} resolveMentionSuggestions={async ({ text, roomId }) => { // Return suggestions from the search `text` // Can return user IDs or mention objects for both users and groups // ... }} > {/* children */} </LiveblocksProvider> );}

Realtime editing

Your document can be edited in real-time by multiple users at once. Each user renders a cursors on screen that updates live as they move, select, and edit.

When authenticating your users with prepareSession or identifyUsers, pass name and color properties to their userInfo to add their cursor information.

userInfo: { name: "Marie", color: "#00ff00",}

Annotations and comments

Add Comments to your text editor, allowing others to select words in the editor, and leave annotations. Each annotation creates a thread, and inside each you can reply, use emoji reactions, mention others, and more.

Add a floating Comments composer to your text editor using FloatingComposer.

<FloatingComposer editor={editor} />

Add useThreads alongside FloatingThreads and Anchoredthreads to render your comments to the page.

export function Threads({ editor }) { const { threads } = useThreads();
 return ( <> <AnchoredThreads editor={editor} threads={threads} /> <FloatingThreads editor={editor} threads={threads} /> </> );}

FloatingThreads displays floating threads below text highlights in the editor, ideal for mobile, whereas AnchoredThreads displays threads vertically alongside the editor which is great on desktop. To create a new thread use the button in the BlockNote toolbar, or build a button yourself.

Notifications

Add a Notifications UI to your application, and automatically notify users when they’ve been mentioned. Notifications also allows you to trigger sending emails, Slack, or any other kind of notification, using our webhooks.

Notifications is enabled by default, which means you just need to add our UI components to keep your users notified. Follow our get started guides to learn how to set up InboxNotification.

export function CollaborativeApp() { const { inboxNotifications } = useInboxNotifications();
 return ( <InboxNotificationList> {inboxNotifications.map((inboxNotification) => ( <InboxNotification key={inboxNotification.id} inboxNotification={inboxNotification} /> ))} </InboxNotificationList> );}

Inline mentions also trigger TextMention notification webhook events. Learn more about sending email notifications.

Multiple editors

It’s possible to use multiple BlockNote editors on a single page, and each editor having its own collaboration and extensions. You can enable this by giving each editor a unique field value.

import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote";
function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { field: "editor-one", } );
 // ...}

Learn more about using multiple editors.

Offline support

Liveblocks BlockNote has an experimental option that enables offline support. Offline support means that once a document has been opened, it’s saved locally on the browser, and can be shown instantly without a loading screen. Enable this by passing a offlineSupport_experimental value.

import { useCreateBlockNoteWithLiveblocks } from "@liveblocks/react-blocknote";
function TextEditor() { const editor = useCreateBlockNoteWithLiveblocks( {}, { offlineSupport_experimental: true, } );
 // ...}

Learn more about offline support.

Version History

Liveblocks BlockNote enables version history for your document. Versions can be automatically created when enabled in your project settings, or manually created using the REST API. These versions can be easily displayed to users using a few simple components. This allows for a comprehensive version history feature in your collaborative text editor.

To implement version history in your application, you can use the useHistoryVersions hook along with the HistoryVersionsList and HistoryVersionPreview components. Here's an example of how to set this up:

import { useHistoryVersions, HistoryVersionSummaryList,} from "@liveblocks/react";import { HistoryVersionPreview } from "@liveblocks/react-blocknote";
function DocumentHistory() { const [selectedVersionId, setSelectedVersionId] = useState<string>(); const { versions, isLoading } = useHistoryVersions(); const selectedVersion = useMemo( () => versions?.find((version) => version.id === selectedVersionId), [selectedVersionId, versions] );
 if (isLoading) { return <div>Loading version history...</div>; }
 return ( <> <div> {selectedVersion ? ( <HistoryVersionPreview version={selectedVersion} className="h-full w-full" onVersionRestore={onVersionRestore} /> ) : ( <div>No version selected</div> )} </div>
 <div> <HistoryVersionSummaryList> {versions?.map((version) => ( <HistoryVersionSummary onClick={() => { setSelectedVersionId(version.id); }} key={version.id} version={version} selected={version.id === selectedVersionId} /> ))} </HistoryVersionSummaryList> </div> </> );}

In this example, useHistoryVersions fetches the version history, HistoryVersionSummaryList displays a list of available versions, and HistoryVersionPreview shows a preview of the selected version. This setup provides users with an interface to browse through the document's history and restore different versions.