Tiptap Editor

Documentation Index

Fetch the complete documentation index at: https://docs.velt.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Prerequisites

• Node.js (v14 or higher)
• React (v16.8 or higher for hooks)
• A Velt account with an API key (sign up)
• Optional: TypeScript for type safety

​

Setup

​

Step 1: Install Dependencies

npm install @veltdev/tiptap-crdt-react @tiptap/react @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor

npm install @veltdev/tiptap-crdt @veltdev/client @tiptap/core @tiptap/starter-kit @tiptap/extension-collaboration-caret

​

Step 2: Setup Velt

​

Step 3: Initialize Velt CRDT Extension

• Initialize the Velt CRDT extension and use it to initialize the Tiptap editor.
• Pass an editorId to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.

const { VeltCrdt } = useVeltTiptapCrdtExtension({
  editorId: 'YOUR_EDITOR_ID'
});

const editor = useEditor({
  extensions: [
    StarterKit.configure({
      history: false,
    }),
    ...(VeltCrdt ? [VeltCrdt] : []),
  ],
  content: ''
}, [VeltCrdt]);

return <EditorContent editor={editor} />;

// Create the CRDT store
const store = await createVeltTipTapStore({
  editorId: editorId,
  veltClient: veltClient,
});

// Create TipTap editor with collaboration extensions
const editor = new Editor({
  element: editorContainer,
  extensions: [
    StarterKit.configure({
      history: false, // Disable history as CRDT handles undo/redo
    }),
    store.getCollabExtension(),
    CollaborationCaret.configure({
      provider: store.getStore().getProvider(),
      user: { name: user.name, color: user.color },
    }),
  ],
  content: '',
});

​

Step 4: Add CSS for Collaboration Cursor

• Add the following CSS to your app to style the collaboration cursor.

/* Collaboration cursor styling */
.collaboration-cursor__caret,
.collaboration-carets__caret {
  border-left: 1px solid #0d0d0d;
  border-right: 1px solid #0d0d0d;
  margin-left: -1px;
  margin-right: -1px;
  pointer-events: none;
  position: relative;
  word-break: normal;
}

/* Render the username above the caret */
.collaboration-cursor__label,
.collaboration-carets__label {
  border-radius: 3px 3px 3px 0;
  color: #0d0d0d;
  font-size: 12px;
  font-style: normal;
  font-weight: 600;
  left: -1px;
  line-height: normal;
  padding: 0.1rem 0.3rem;
  position: absolute;
  top: -1.4em;
  user-select: none;
  white-space: nowrap;
}

​

Notes

• Unique editorId: Use a unique editorId per editor instance.
• Disable history: Turn off Tiptap history when using collaboration.
• Auth required: Ensure the Velt client is initialized and user is available before starting.

​

Testing and Debugging

1. Login two unique users on two browser profiles and open the same page in both.
2. Edit in one window and verify changes and cursors appear in the other.

• Cursors not appearing: Ensure each editor has a unique editorId and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles.
• Editor not loading: Confirm the Velt client is initialized and the API key is valid.
• Desynced content: Make sure Tiptap history is disabled when using collaboration.

​

Complete Example

import { EditorContent, useEditor } from '@tiptap/react';
import StarterKit from '@tiptap/starter-kit';
import { useVeltTiptapCrdtExtension } from '@veltdev/tiptap-crdt-react';
import React from 'react';

const CollaborativeEditor: React.FC = () => {

  const { VeltCrdt } = useVeltTiptapCrdtExtension({
    editorId: 'velt-tiptap-crdt-demo'
  });
  // Initialize the editor with our collaboration extension
  const editor = useEditor({
    extensions: [
      StarterKit.configure({
        history: false,
      }),
      ...(VeltCrdt ? [VeltCrdt] : []),
    ],
    content: ''
  }, [VeltCrdt]);

  return (
    <div className="editor-container">
      <div className="editor-content">
        <EditorContent editor={editor} />
      </div>
      <div className="status">
        {VeltCrdt ? 'Connected to collaborative session' : 'Connecting to collaborative session...'}
      </div>
    </div>
  );
};
export default CollaborativeEditor;

// Import required modules
import { initVelt } from '@veltdev/client';
import { createVeltTipTapStore } from '@veltdev/tiptap-crdt';
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import CollaborationCaret from '@tiptap/extension-collaboration-caret';

// Step 1: Initialize Velt client
const veltClient = await initVelt('YOUR_API_KEY');

// Step 2: Authenticate user
const user = { userId: 'user-1', name: 'John Doe', color: '#3b82f6' };
await veltClient.identify(user);

// Step 3: Set document
await veltClient.setDocument('my-document-id');

// Step 4: Create CRDT store
const store = await createVeltTipTapStore({
  editorId: 'velt-tiptap-crdt-demo',
  veltClient: veltClient,
});

// Step 5: Create TipTap editor
const editor = new Editor({
  element: document.getElementById('editor'),
  extensions: [
    StarterKit.configure({ history: false }),
    store.getCollabExtension(),
    CollaborationCaret.configure({
      provider: store.getStore().getProvider(),
      user: { name: user.name, color: user.color },
    }),
  ],
  content: '',
});

// Cleanup on unmount
editor.destroy();
store.destroy();

​

APIs

​

Custom Encryption

async function encryptData(config: EncryptConfig<number[]>): Promise<string> {
  const encryptedData = await yourEncryptDataMethod(config.data);
  return encryptedData;
}

async function decryptData(config: DecryptConfig<string>): Promise<number[]> {
  const decryptedData = await yourDecryptDataMethod(config.data);
  return decryptedData;
}

const encryptionProvider: VeltEncryptionProvider<number[], string> = {
  encrypt: encryptData,
  decrypt: decryptData,
};

<VeltProvider
  apiKey="YOUR_API_KEY"
  encryptionProvider={encryptionProvider}
/>

async function encryptData(config: EncryptConfig<number[]>): Promise<string> {
  const encryptedData = await yourEncryptDataMethod(config.data);
  return encryptedData;
}

async function decryptData(config: DecryptConfig<string>): Promise<number[]> {
  const decryptedData = await yourDecryptDataMethod(config.data);
  return decryptedData;
}

const encryptionProvider: VeltEncryptionProvider<number[], string> = {
  encrypt: encryptData,
  decrypt: decryptData,
};

client.setEncryptionProvider(encryptionProvider);

​

Initialization

const { VeltCrdt, store, isLoading } = useVeltTiptapCrdtExtension({ 
  editorId: 'velt-tiptap-crdt-demo' 
});

import { createVeltTipTapStore } from '@veltdev/tiptap-crdt';

const store = await createVeltTipTapStore({
  editorId: 'velt-tiptap-crdt-demo',
  veltClient: client,
  initialContent: '<p>Start collaborating...</p>',
});

const collabExtension = store.getCollabExtension();

​

Store Methods

​

store.getStore()

• Returns: Store

const crdtStore = store.getStore();

​

store.destroy()

• Returns: void

store.destroy();

​

store.getYDoc()

• Returns: Y.Doc

const ydoc = store.getYDoc();

​

store.getYXml()

• Returns: Y.XmlFragment | null

const yxml = store.getYXml();

​

store.setStateFromVersion()

• Signature: setStateFromVersion(version: Version): Promise<void>
• Params:
  • version: The version object to restore the document to.
• Returns: Promise<void>

// Restore document to a previous version
await store.setStateFromVersion(previousVersion);