> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plate Setup

![](https://mintcdn.com/velt/gAz_vLsG-ukKamYM/gifs/Add-Text-Comments.gif?s=1da499b73486c2acd4667b517baab389)

> [!NOTE]
>
> 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.

> [tab] React / Next.js
>
> ```js theme={null}
> <VeltProvider apiKey="API_KEY">
>   <VeltComments textMode={false} />
> </VeltProvider>
> ```

#### Step 2: Install the Velt Plate extension

```bash theme={null}
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.

> [tab] React / Next.js
>
> ```js theme={null}
> 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.

> [tab] React / Next.js
>
> ```js theme={null}
> 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`](https://velt.dev/docs/api-reference/sdk/models/data-models#addcommentrequest-4). 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](https://velt.dev/docs/async-collaboration/comments/customize-behavior.md#metadata). (optional)

> [tab] React / Next.js
>
> ```js theme={null}
> 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`](https://velt.dev/docs/api-reference/sdk/models/data-models#rendercommentsrequest-4). 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.

> [tab] React / Next.js
>
> ```js theme={null}
> 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`

```js theme={null}
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.

```css theme={null}
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()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#veltcommentsplugin-configure)

A Plate.js plugin for Velt Comments integration.

* Params: `options?:` [VeltCommentsPluginConfig](https://velt.dev/docs/api-reference/sdk/models/data-models.md#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

> [tab] React / Next.js
>
> ```tsx theme={null}
> 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()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#addcomment-4)

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

* Params:
  * `request:` [AddCommentRequest](https://velt.dev/docs/api-reference/sdk/models/data-models.md#addcommentrequest-4)
    * `editor: PlateEditor`
    * `editorId?: string`
    * `context?: object`
* Returns: `Promise<void>`

> [tab] React / Next.js
>
> ```tsx theme={null}
> import { addComment } from '@veltdev/plate-comments-react';
>
> <button
>   onMouseDown={(e) => {
>     e.preventDefault();
>     addComment({
>       editor,
>       editorId: 'my-editor',
>       context: { customData: 'value' },
>     });
>   }}
> >
>   Comment
> </button>
> ```

#### [renderComments()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#rendercomments-4)

Renders and highlights comment annotations in the editor.

* Params:
  * `request:` [RenderCommentsRequest](https://velt.dev/docs/api-reference/sdk/models/data-models.md#rendercommentsrequest-4)
    * `editor: PlateEditor`
    * `editorId?: string`
    * `commentAnnotations?:` [CommentAnnotation\[\]](https://velt.dev/docs/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`

> [tab] React / Next.js
>
> ```tsx theme={null}
> 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()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#exportjsonwithoutcomments-2)

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.

> [tab] React / Next.js
>
> ```tsx theme={null}
> 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.

> [tab] React / Next.js
>
> ```tsx theme={null}
> 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
> };
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.