Text Editor – Tiptap

A quick overview of the Text Editor packages for Tiptap.

Concepts

Liveblocks Tiptap allows you add collaboration to any Tiptap 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.

Users and mentions

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

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

import { LiveblocksProvider } from "@liveblocks/react/suspense";
function App() {  return (    <LiveblocksProvider      resolveUsers={async ({ userIds }) => {        // Return user info from their `userIds`        // ...      }}      resolveMentionSuggestions={async ({ text, roomId }) => {        // Return suggestions from the search `text`        // ...      }}    >      {/* children */}    </LiveblocksProvider>  );}

Real-time 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} />

You can then create a button that opens the new annotation composer for the current selection with addPendingComment.

<button onClick={() => editor.chain().focus().addPendingComment().run()}>  💬 New comment</button>

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.

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 Tiptap 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 { useLiveblocksExtension } from "@liveblocks/react-tiptap";
function TextEditor() {  const liveblocks = useLiveblocksExtension({    field: "editor-one",  });
  // ...}

Learn more about using multiple editors.

Offline support

Liveblocks Tiptap 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 { useLiveblocksExtension } from "@liveblocks/react-tiptap";
function TextEditor() {  const liveblocks = useLiveblocksExtension({    offlineSupport_experimental: true,  });
  // ...}

Learn more about offline support.

Version History

Liveblocks Tiptap automatically creates versions of your document as changes are made. 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-tiptap";
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="w-full h-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.

Tiptap API Reference

• Tiptap React

  @liveblocks/react-tiptap