Documentation Index
Fetch the complete documentation index at: https://docs.velt.dev/llms.txt
Use this file to discover all available pages before exploring further.
Setup
- 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
Other Frameworks
<VeltProvider apiKey="API_KEY">
<VeltComments textMode={false} />
</VeltProvider>
<body>
<velt-comments text-mode="false"></velt-comments>
</body>
Step 2: Install the Velt Ace extension
npm i @veltdev/ace-velt-comments
React / Next.js
Other Frameworks
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 } from '@veltdev/ace-velt-comments';
function AceEditorComponent() {
const editorRef = useRef(null);
const cleanupRef = useRef(null);
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();
}
};
}, []);
return (
<AceEditor
mode="markdown"
theme="github"
name="ace-editor"
defaultValue="Your initial content here"
onLoad={handleLoad}
width="100%"
height="100%"
/>
);
}
import * as ace from 'ace-builds';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
const editor = ace.edit(document.querySelector('#editor'));
editor.setTheme('ace/theme/github');
editor.session.setMode('ace/mode/markdown');
editor.setValue('Your initial content here', -1);
// Initialize Velt comments - returns a cleanup function
const cleanup = AceVeltComments(editor);
// Call cleanup() when done to remove event listeners
// cleanup();
- Add a button that users can click to add comments after selecting text.
React / Next.js
Other Frameworks
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>
<button id="add-comment-btn">Add Comment</button>
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentBtn = document.getElementById('add-comment-btn');
addCommentBtn.addEventListener('mousedown', (e) => e.preventDefault());
addCommentBtn.addEventListener('click', () => {
addComment({ editor });
});
- 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)
React / Next.js
Other Frameworks
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentRequest = {
editor: editorRef.current,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
- 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.
React / Next.js
Other Frameworks
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]);
import { renderComments } from '@veltdev/ace-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations?.length) {
const renderCommentsRequest = {
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
- 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,
});
- 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
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
React / Next.js
Other Frameworks
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"
/>
);
}
import * as ace from 'ace-builds';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
const editor = ace.edit(document.querySelector('#editor'));
const cleanup = AceVeltComments(editor, {
editorId: 'my-editor',
persistVeltMarks: true,
});
// Later, when done:
cleanup();
- Params:
- Returns:
Promise<void>
React / Next.js
Other Frameworks
import { addComment } from '@veltdev/ace-velt-comments';
<button
onMouseDown={(e) => {
e.preventDefault();
addComment({
editor: editorRef.current,
editorId: 'my-editor',
context: { customData: 'value' }
});
}}
>
Comment
</button>
import { addComment } from '@veltdev/ace-velt-comments';
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' },
});
React / Next.js
Other Frameworks
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]);
import { renderComments } from '@veltdev/ace-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
