Collaboration extension

This small guide quickly shows how to integrate basic collaboration functionality into your editor. For a proper collaboration integration, review the documentation of Tiptap Collaboration, which is a cloud and on-premises collaboration server solution.

Install

npm install @tiptap/extension-collaboration @tiptap/y-tiptap yjs y-websocket

Settings

document

An initialized Y.js document.

Default: null

Collaboration.configure({
  document: new Y.Doc(),
})

field

Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document.

Default: 'default'

Collaboration.configure({
  document: new Y.Doc(),
  field: 'title',
})

fragment

A raw Y.js fragment, can be used instead of document and field.

Default: null

Collaboration.configure({
  fragment: new Y.Doc().getXmlFragment('body'),
})

Commands

The Collaboration extension comes with its own history extension. Make sure to disable the UndoRedo extension, if you’re working with the StarterKit.

undo()

Undo the last change.

editor.commands.undo()

redo()

Redo the last change.

editor.commands.redo()

Keyboard shortcuts

Content that doesn't fit the schema

A shared document can contain content that your editor's schema can't display, for example a node from an extension you didn't register. The extension handles it in one of two ways:

• By default, the editor removes that content and fills in missing required nodes. These changes are synced, so other users lose that content too.
• With the editor option enableContentCheck: true, the editor keeps that content in the shared document. It shows what it can, pauses editing and sends no changes. It emits the contentError event and resumes when the content fits the schema again. Handle that event with onContentError, because the default handler throws the error. This needs @tiptap/extension-collaboration 3.33.0 and @tiptap/y-tiptap 3.2.0 or later.

Read more in Invalid schema handling.

Usage with UniqueID

If you are using the UniqueID extension together with Collaboration, make sure to mount the editor only after the collaboration provider has synced. Incorrect initialization order can cause persistent empty paragraphs in the document. See UniqueID: Usage with Collaboration for details.

Source code

packages/extension-collaboration/

You Did It!

Your editor is now collaborative! Invite your friends and start typing together 🙌🏻 If you want to continue building out your collaborative editing features, make sure to check out the Tiptap Collaboration Docs for a fully hosted on on-premises collaboration server solution.