Skip to main content
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.
<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.
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.
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)
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.
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
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:
  • Returns: Promise<void>
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. 
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.
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. 
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
};