SlateJS Setup

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 SlateJS extension

npm i @veltdev/slate-velt-comments

Step 3: Import and add the extension to your SlateJS editor

React / Next.js

import { withVeltComments } from '@veltdev/slate-velt-comments';
import { withReact, withHistory } from 'slate-react';

const editor = withVeltComments(
  withReact(withHistory(createEditor())),
  { HistoryEditor: SlateHistoryEditor }
);

Step 4: Register Velt Component Type in SlateJS

• Register the Velt Comments Element type with your SlateJS editor’s custom types.
• This ensures proper type checking for the comments functionality.

React / Next.js

import type { VeltCommentsElement } from '@veltdev/slate-velt-comments';

type CustomElement = VeltCommentsElement;

declare module 'slate' {
  interface CustomTypes {
    Element: CustomElement;
  }
}

Step 5: Add a comment button to your SlateJS editor

• Add a button that appears in the context menu of your SlateJS editor when the user selects text.
• This button will be used to add a comment to the selected text.

React / Next.js

import { addComment } from '@veltdev/slate-velt-comments';
import { useSlate } from 'slate-react';

const CommentButton = (props) => {
  const editor = useSlate();
  
  return (
    <Button
      onMouseDown={(e) => {
        e.preventDefault();
        addComment({ editor });
      }}
    >
      Comment
    </Button>
  );
};

Step 6: Call addComment to add a comment

• Call this method to add a comment to selected text in the SlateJS editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
• Params: AddCommentRequest
  • editorId: string, the id of the editor. Use this if you have multiple editors in your app.
  • editor: instance of the SlateJS editor.
  • context: optional object to set the Comment Annotation’s custom metadata.

React / Next.js

import { addComment } from '@veltdev/slate-velt-comments';
import { useSlate } from 'slate-react';

const CommentButton = (props) => {
  const editor = useSlate();
  
  return (
    <Button
      onMouseDown={(e) => {
        e.preventDefault();
        addComment({ editor });
      }}
    >
      Comment
    </Button>
  );
};

Step 7: Render Comments in SlateJS Editor

• Get the comment data.
• Render the comments in the SlateJS editor.
• Params: RenderCommentsRequest
  • editorId: string, the id of the editor. Use this if you have multiple editors in your app.
  • editor: instance of the SlateJS editor.
  • commentAnnotations: CommentAnnotation[]

React / Next.js

import { renderComments } from '@veltdev/slate-velt-comments';

const commentAnnotations = useCommentAnnotations();

useEffect(() => {
  if (editor && commentAnnotations) {
    renderComments({ editor, commentAnnotations });
  }
}, [commentAnnotations, editor]);

Step 8: Style the commented text

• You can style the commented text by adding a CSS class to the velt-comment-text element.
• By using the comment-available attribute, you can apply styles only when the comment data has loaded.

velt-comment-text[comment-available="true"] {
  background-color: #ffff00;
}

Complete Example

APIs

withVeltComments()

Augment a Slate editor with Velt Comments support (adds schema/commands/normalizers).

• Params:
  • editor: Editor
  • options?: VeltCommentsEditorOptions
• Returns: VeltCommentsEditor

React / Next.js

import { withVeltComments } from '@veltdev/slate-velt-comments';
import { withReact, withHistory } from 'slate-react';

const editor = withVeltComments(
  withReact(withHistory(createEditor())),
  { HistoryEditor: SlateHistoryEditor }
);

addComment()

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

• Signature: async (request: AddCommentRequest) => Promise<void>
• Params: request: AddCommentRequest
• Returns: Promise<void>

React / Next.js

import { addComment } from '@veltdev/slate-velt-comments';

<button onMouseDown={(e) => { e.preventDefault(); addComment({ editor }); }}>
  Comment
</button>

renderComments()

Renders and highlights comment annotations in the editor.

• Signature: (request: RenderCommentsRequest) => void
• Params: request: RenderCommentsRequest
• Returns: void

React / Next.js

import { renderComments } from '@veltdev/slate-velt-comments';
import type { CommentAnnotation } from '@veltdev/types';

useEffect(() => {
  if (editor && commentAnnotations) {
    renderComments({ editor, commentAnnotations });
  }
}, [editor, commentAnnotations]);

SlateVeltComment

React component that renders a Velt comment text element with annotation ID.

• Params:
  • props: RenderElementProps
  • element: VeltCommentsElement
• Returns: N/A

import { SlateVeltComment } from '@veltdev/slate-velt-comments';
import type { RenderElementProps } from 'slate-react';
import type { VeltCommentsElement } from '@veltdev/slate-velt-comments';

const RenderElement = (props: RenderElementProps) => {
  if (props.element.type === 'veltComment') {
    return <SlateVeltComment {...props} element={props.element as VeltCommentsElement} />;
  }
  return <p {...props.attributes}>{props.children}</p>;
};