Collaboration

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({
      render: {
        afterEditable: RemoteCursorOverlay,
      },
      options: {
        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.

    See WithCursorsOptions API.

    Configuration for the Hocuspocus provider.

    See HocuspocusProviderConfiguration API.

    Optional configuration for the Yjs integration.

    See WithYjsOptions API.

    Whether to disable the cursor feature in the editor.

API

useYjsStore

State

Collapse all

    Whether the editor is connected to the Hocuspocus server.

    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.

Types

PlateYjsEditorProps

Attributes

Collapse all

    Base editor props types.

    Yjs-specific properties.

Optionsobject

Collapse all

    The Hocuspocus provider instance.

YHistoryEditorProps

Attributes

Collapse all

YjsEditorProps

See YjsEditor API.