Collaboration

Charts and diagrams are nodes like any other, so Tiptap Collaboration shares them without extra setup. One rule applies: every client that opens the shared document registers Diagrams.

AlphaPilot program

Where to register Diagrams

in every editor
in a read-only viewer
in an agent
on the collaboration server

A client you missed deletes every chart and diagram from the shared document, unless it sets enableContentCheck: true. See A client without Diagrams.

Two people changing one chart

A chart stores its data, its Chart Spec and its Renderer as separate attributes. The shared document merges each attribute on its own:

Changes to different attributes at the same time are both kept. For example, one person changes the title and another person changes a cell.
Changes to the data at the same time keep only one of the two. For example, two people change different cells of one chart. The data is one attribute, so the change that arrives last replaces the other.
Undo takes back only your own change, also after somebody else changed the chart.

The same applies to a diagram. Its source is one attribute.

A client without Diagrams

A client whose schema has no chart or flowDiagram node, or that sets chart: false or flowDiagram: false, cannot build those nodes. What happens then depends on the editor option enableContentCheck:

`enableContentCheck`	The shared document	That client
`false` (default)	Loses the charts or diagrams that client cannot build. The deletion reaches every other client	Deletes them while it loads the document
`true`	Stays as it is. Everybody else keeps their charts and diagrams	Shows the rest of the document, cannot be edited, sends nothing, and emits `contentError`

enableContentCheck: true needs @tiptap/extension-collaboration 3.33.0 and @tiptap/y-tiptap 3.2.0 or later. With older versions, the client deletes those charts or diagrams in both cases. Only @tiptap/y-tiptap 3.0.10 and 3.0.11 behave differently: they make the editor read-only and may show an empty or outdated document.

Set enableContentCheck: true on every client that might not register Diagrams, for example an older version of your app. That client stays paused while the document contains charts or diagrams it cannot build. Also set onContentError, because the default handler throws the error. See Invalid schema handling.

A client that shows nothing

A client that does not draw anything registers Diagrams without any Renderer or Diagram Renderer. It needs no DOM and no chart library, and it keeps every chart and diagram as it is.

import { getSchema } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Diagrams } from '@tiptap-pro/extension-diagrams'

const extensions = [StarterKit, Diagrams.configure({ renderers: [] })]
const schema = getSchema(extensions)

An editor without a Renderer shows each chart or diagram as not drawable here, or as what unavailable returns. Its data stays untouched.

Turning away a client without Diagrams

If clients you do not control can connect, let the server refuse those that do not declare Diagrams. With Hocuspocus, for example, the client adds a parameter to its connection. The server checks it before the document is loaded:

// client
const provider = new HocuspocusProvider({
  url: 'wss://collaboration.example.com?schema=diagram-1',
  name: 'document-id',
})

// server
const server = new Hocuspocus({
  async onConnect({ requestParameters }) {
    if (requestParameters.get('schema') !== 'diagram-1') {
      throw new Error('This document needs the Diagrams extension.')
    }
  },
})

Mixed versions

A newer version of @tiptap-pro/extension-diagrams may store a chart attribute that an older client does not know. The older client keeps that attribute only until it changes the chart. Then the attribute is lost. Update every client to the same version before you use a feature that a newer version added.

PreviouslyGoogle Sheets, Excel and Airtable

Next upVersions