Collaboration

Collaborate with others in a single document.

Features

  • The yjs plugin enables support for collaboration using slate-yjs and Hocuspocus.
  • By default remote cursors are not rendered unless you install the remote cursor overlay and include it in the config.
  • Cursors are rendered slightly faded and become solid on hover. Use the data field in cursorOptions to customise the display name and color.

Frontend

Installation

npm install @udecode/plate-yjs

Usage

import { YjsPlugin } from '@udecode/plate-yjs/react';
import { RemoteCursorOverlay } from '@/components/plate-ui/remote-cursor-overlay';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    YjsPlugin.configure({
      options: {
        render: {
          afterEditable: RemoteCursorOverlay,
        },
        cursorOptions: {
          autoSend: true,
          data: { name: 'A plate user', color: '#5AC990' },
        },
        disableCursors: false,
        hocuspocusProviderOptions: {
          url: 'https://hocuspocus.test/hocuspocus',
          name: 'test',
        },
      },
    }),
  ],
});

Editor Container

The editor requires a container component above PlateContent to ensure correct cursor overlay positioning:

export const EditorContainer = (
  props: React.HTMLAttributes<HTMLDivElement>
) => {
  const editor = useEditorRef();
  const containerRef = useEditorContainerRef();
 
  return <div id={editor.uid} ref={containerRef} {...props} />;
};

This component is available in Editor.

Backend

Follow the backend instructions in Hocuspocus docs.

Plugins

YjsPlugin

Options

Collapse all

    Configuration for handling cursors in the editor. These options are passed to the withCursors function.

    Configuration for the Hocuspocus provider.

    Optional configuration for the Yjs integration. These options are passed to the withYjs function.

    A flag indicating whether to disable the cursor feature in the editor.

API

useYjsStore

State

Collapse all

    A flag indicating whether the editor is connected to the Hocuspocus server.

    A flag indicating whether the editor is synced with the Hocuspocus server.

withTYjs

Higher-order function that wraps a Plate editor with Yjs support, allowing for real-time collaborative editing.

PlateYjsEditorProps

Attributes

Collapse all

    Extends YjsEditorProps and CursorEditor.

YHistoryEditorProps

Extends YjsEditorProps, YHistoryEditor.

YjsEditorProps

YjsEditor API.

CaptionColumn