Skip to main content

​
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 Ace extension

npm i @veltdev/ace-velt-comments

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

import { useEffect, useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments, renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';

function AceEditorComponent() {
  const editorRef = useRef(null);
  const cleanupRef = useRef(null);
  const annotations = useCommentAnnotations();

  const handleLoad = useCallback((editor) => {
    editorRef.current = editor;
    // Initialize Velt comments - returns a cleanup function
    cleanupRef.current = AceVeltComments(editor);
  }, []);

  useEffect(() => {
    return () => {
      if (cleanupRef.current) {
        cleanupRef.current();
      }
    };
  }, []);

  useEffect(() => {
    if (editorRef.current) {
      renderComments({
        editor: editorRef.current,
        commentAnnotations: annotations ?? [],
      });
    }
  }, [annotations]);

  return (
    <AceEditor
      mode="markdown"
      theme="github"
      name="ace-editor"
      defaultValue="Your initial content here"
      onLoad={handleLoad}
      width="100%"
      height="100%"
    />
  );
}

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

  • Add a button that users can click to add comments after selecting text.
import { addComment } from '@veltdev/ace-velt-comments';

// Add this button before <AceEditor> in your JSX
<button
  onMouseDown={(e) => e.preventDefault()}
  onClick={() => {
    if (editorRef.current) {
      addComment({ editor: editorRef.current });
    }
  }}
>
  Add Comment
</button>

​
Step 5: Call addComment to add a comment

  • Call this method to add a comment to selected text in the Ace 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 Ace Editor.
    • editorId: Id of the Ace editor. Use this if you have multiple Ace 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/ace-velt-comments';

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

addComment(addCommentRequest);

​
Step 6: Render comments in Ace editor

  • Get the comment data from Velt SDK and render it in the Ace Editor.
  • Params: RenderCommentsRequest. It has the following properties:
    • editor: Instance of the Ace Editor.
    • editorId: Id of the Ace editor. Use this if you have multiple Ace editors on the same page in your app. (optional)
    • commentAnnotations: Array of Comment Annotation objects.
import { renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';

const annotations = useCommentAnnotations();

useEffect(() => {
  if (editorRef.current && annotations?.length) {
    const renderCommentsRequest = {
      editor: editorRef.current,
      editorId: 'EDITOR_ID',
      commentAnnotations: annotations,
    };
    renderComments(renderCommentsRequest);
  }
}, [annotations]);

​
Step 7: Persist Velt Comment Marks (optional)

  • By default, Velt comment marks (<velt-comment-text>) are persisted in the Ace editor by 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 Ace editor on your end with the comment marks already included, you can disable this feature.
  • Default: true
const cleanup = AceVeltComments(editor, {
  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

​
AceVeltComments()

Initializes the Velt Comments extension for an Ace Editor instance.
  • Params: editor: Ace.Editor, config?: AceVeltCommentsConfig
    • editorId?: string - Unique identifier for this editor instance (for multi-editor scenarios)
    • persistVeltMarks?: boolean - Whether to persist Velt marks. Default: true
  • Returns: () => void - Cleanup function to remove event listeners
import { useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import { AceVeltComments } from '@veltdev/ace-velt-comments';

function AceEditorComponent() {
  const editorRef = useRef(null);
  const cleanupRef = useRef(null);

  const handleLoad = useCallback((editor) => {
    editorRef.current = editor;
    cleanupRef.current = AceVeltComments(editor, {
      editorId: 'my-editor',
      persistVeltMarks: true,
    });
  }, []);

  return (
    <AceEditor
      onLoad={handleLoad}
      mode="markdown"
      theme="github"
      name="ace-editor"
    />
  );
}

​
addComment()

Creates a comment annotation for the currently selected text in the editor.
  • Params:
  • Returns: Promise<void>
import { addComment } from '@veltdev/ace-velt-comments';

<button
  onMouseDown={(e) => {
    e.preventDefault();
    addComment({
      editor: editorRef.current,
      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/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';

const annotations = useCommentAnnotations();

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