Plate Setup

Plate.js is a React-only framework. This guide covers the React integration only.

Setup

Step 1: Add Comment components

Add the Velt Comments component to the root of your app.
This component is required to render comments in your app.
Set the text mode prop to false to hide the default text comment tool.

React / Next.js

<VeltProvider apiKey="API_KEY">
  <VeltComments textMode={false} />
</VeltProvider>

Step 2: Install the Velt Plate extension

npm i @veltdev/plate-comments-react

Step 3: Configure the Plate editor with the Velt Comments extension

Import VeltCommentsPlugin and add it to your Plate editor’s plugins array.

React / Next.js

import { Plate, PlateContent, usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin } from '@veltdev/plate-comments-react';

function PlateEditor() {
  const editor = usePlateEditor({
    plugins: [VeltCommentsPlugin],
    value: initialValue, // Your initial editor content
  });

  return (
    <Plate editor={editor}>
      <PlateContent placeholder="Start typing..." />
    </Plate>
  );
}

Step 4: Add a comment button to your Plate editor

Add a button that users can click to add comments after selecting text.
Use onMouseDown with preventDefault to preserve the editor selection when clicking the button.

React / Next.js

import { Plate, PlateContent, usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin, addComment } from '@veltdev/plate-comments-react';

function PlateEditor() {
  const editor = usePlateEditor({
    plugins: [VeltCommentsPlugin],
    value: initialValue,
  });

  const handleAddComment = () => {
    if (editor) {
      addComment({ editor });
    }
  };

  return (
    <div>
      <button
        onMouseDown={(e) => {
          e.preventDefault();
          handleAddComment();
        }}
      >
        Add Comment
      </button>
      <Plate editor={editor}>
        <PlateContent placeholder="Start typing..." />
      </Plate>
    </div>
  );
}

Step 5: Call `addComment` to add a comment

Call this method to add a comment to selected text in the Plate editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
Params: AddCommentRequest. It has the following properties:
- editor: Instance of the Plate editor.
- editorId: Id of the Plate editor. Use this if you have multiple Plate editors on the same page in your app. (optional)
- context: Add any custom metadata to the Comment Annotation. Learn more. (optional)

React / Next.js

import { addComment } from '@veltdev/plate-comments-react';

const addCommentRequest = {
  editor,
  editorId: 'EDITOR_ID',
  context: {
    storyId: 'story-id',
    storyName: 'story-name',
  },
};

addComment(addCommentRequest);

Step 6: Render comments in Plate editor

Get the comment data from Velt SDK using the useCommentAnnotations hook and render it in the Plate editor.
Params: RenderCommentsRequest. It has the following properties:
- editor: Instance of the Plate editor.
- editorId: Id of the Plate editor. Use this if you have multiple Plate editors on the same page in your app. (optional)
- commentAnnotations: Array of Comment Annotation objects.

React / Next.js

import { useEffect } from 'react';
import { renderComments } from '@veltdev/plate-comments-react';
import { useCommentAnnotations } from '@veltdev/react';

function PlateEditor() {
  const annotations = useCommentAnnotations();

  useEffect(() => {
    if (editor && annotations) {
      renderComments({
        editor,
        editorId: 'EDITOR_ID',
        commentAnnotations: annotations,
      });
    }
  }, [editor, annotations]);

  // ... rest of component
}

Step 7: Persist Velt Comment Marks (optional)

By default, Velt comment marks are persisted by the Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
If you plan to store the contents of the Plate editor on your end with the comment marks already included, you can disable this feature.
Default: true

const editor = usePlateEditor({
  plugins: [
    VeltCommentsPlugin.configure({
      options: {
        persistVeltMarks: false,
      },
    }),
  ],
});

Step 8: Style the commented text

You can style the commented text by adding CSS for the velt-comment-text element.

velt-comment-text {
  background-color: rgba(255, 255, 0, 0.3);
  border-bottom: 2px solid #ffcc00;
  cursor: pointer;
}

velt-comment-text:hover {
  background-color: rgba(255, 255, 0, 0.5);
}

velt-comment-text.velt-comment-selected {
  background-color: rgba(255, 255, 0, 0.5);
}

APIs

VeltCommentsPlugin.configure()

A Plate.js plugin for Velt Comments integration.

Params: options?: VeltCommentsPluginConfig
- editorId?: string - Unique identifier for this editor instance (for multi-editor scenarios).
- persistVeltMarks?: boolean - Whether to persist Velt marks. Default: true.
Returns: Plate Plugin

React / Next.js

import { usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin } from '@veltdev/plate-comments-react';

// Basic usage
const editor = usePlateEditor({
  plugins: [VeltCommentsPlugin],
});

// With configuration
const editor = usePlateEditor({
  plugins: [
    VeltCommentsPlugin.configure({
      options: {
        editorId: 'my-editor',
        persistVeltMarks: true,
      },
    }),
  ],
});

addComment()

Creates a comment annotation for the currently selected text in the editor.

Params:
- request: AddCommentRequest
  - editor: PlateEditor
  - editorId?: string
  - context?: object
Returns: Promise<void>

React / Next.js

import { addComment } from '@veltdev/plate-comments-react';

<button
  onMouseDown={(e) => {
    e.preventDefault();
    addComment({
      editor,
      editorId: 'my-editor',
      context: { customData: 'value' },
    });
  }}
>
  Comment
</button>

renderComments()

Renders and highlights comment annotations in the editor.

Params:
- request: RenderCommentsRequest
  - editor: PlateEditor
  - editorId?: string
  - commentAnnotations?: CommentAnnotation[]
Returns: void

React / Next.js

import { useEffect } from 'react';
import { renderComments } from '@veltdev/plate-comments-react';
import { useCommentAnnotations } from '@veltdev/react';

const annotations = useCommentAnnotations();

useEffect(() => {
  if (editor && annotations) {
    renderComments({
      editor,
      editorId: 'my-editor',
      commentAnnotations: annotations,
    });
  }
}, [editor, annotations]);

exportJSONWithoutComments()

Exports the editor content as JSON with Velt comment elements removed. Useful when saving content to your backend without comment markup.

Params: content: Descendant[] - The editor content (Slate nodes).
Returns: Descendant[] - Content with comment elements removed.

React / Next.js

import { exportJSONWithoutComments } from '@veltdev/plate-comments-react';

const saveContent = () => {
  const cleanContent = exportJSONWithoutComments(editor.children);
  // Save cleanContent to your backend
};

PlateVeltComment

React component for rendering Velt comment elements in the editor. This is automatically used by the plugin, but can be referenced for custom render element implementations.

React / Next.js

import { PlateVeltComment, VeltCommentsElement } from '@veltdev/plate-comments-react';

const renderElement = (props) => {
  if (props.element.type === 'veltComment') {
    return <PlateVeltComment {...props} element={props.element as VeltCommentsElement} />;
  }
  // ... other elements
};

​Setup

​Step 1: Add Comment components

​Step 2: Install the Velt Plate extension

​Step 3: Configure the Plate editor with the Velt Comments extension

​Step 4: Add a comment button to your Plate editor

​Step 5: Call addComment to add a comment

​Step 6: Render comments in Plate editor

​Step 7: Persist Velt Comment Marks (optional)

​Step 8: Style the commented text

​APIs

​VeltCommentsPlugin.configure()

​addComment()

​renderComments()

​exportJSONWithoutComments()

​PlateVeltComment

Setup

Step 1: Add Comment components

Step 2: Install the Velt Plate extension

Step 3: Configure the Plate editor with the Velt Comments extension

Step 4: Add a comment button to your Plate editor

Step 5: Call `addComment` to add a comment

Step 6: Render comments in Plate editor

Step 7: Persist Velt Comment Marks (optional)

Step 8: Style the commented text

APIs

VeltCommentsPlugin.configure()

addComment()

renderComments()

exportJSONWithoutComments()

PlateVeltComment