Skip to main content

​
Threads

​
addCommentAnnotation

const commentAnnotation = {
  comments: [
    {
      commentText: 'This is a comment',
      commentHtml: '<p>This is a comment</p>',
    }
  ]
};
const addCommentAnnotationRequest = {
  annotation: commentAnnotation
};

// Hook
const { addCommentAnnotation } = useAddCommentAnnotation();
const addCommentAnnotationEventData = await addCommentAnnotation(addCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const addCommentAnnotationEventData = await commentElement.addCommentAnnotation(addCommentAnnotationRequest);

​
addCommentOnSelectedText

By default, when you highlight over any text in textMode a Comment Tool button will appear. Clicking the button will add a comment on the highlighted text. If you want to trigger the comment using an API method call instead of clicking the button, you can do the following: 
const commentElement = client.getCommentElement();
// to add comment on selected text
commentElement.addCommentOnSelectedText();

​
addCommentOnElement

Adds a Comment on a specific element by ID. To add a comment on a specific element through an API method, use the addCommentOnElement() method and pass in an object with the schema shows in the example: Example 1: Add comment with targetElementId only: 
const element = {
  "targetElement": {
    "elementId": "element_id",  // optional (pass elementId if you want to add comment on a specific element)
    "targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
    "occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
  	"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
  },
  "commentData": [
    {
      "commentText": "This is awesome! Well done.", // To set plain text content
      "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.", // To set HTML formatted content
      "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
      "replaceContentHtml": "<span>This is <b>new</b> comment.</span>", // If replacement text contains html formatted text, then provide it here
    }
  ],
  "status": "open", // optional (default: open)
}

const commentElement = client.getCommentElement();
commentElement.addCommentOnElement(element);

​
addManualComment

  • This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins.
  • Using this you can manually set the position of Comment Annotations.
  • Handle click events on your canvas/document and use the this method to create a comment with custom metadata.
const context = {
  position: {x: 200, y: 100},
};
const commentElement = client.getCommentElement();
const config: ManualCommentAnnotationConfig = {
	context: context, // your context here
};
commentElement.addManualComment(config);

​
Comment and Reply Placeholders

Customize the placeholder text shown in the Comments dialog inputs to match your product voice and guide first-time users. 
// Using props on VeltComments
<VeltComments commentPlaceholder="Text Comment" replyPlaceholder="Text Reply" />

​
deleteCommentAnnotation

const deleteCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { deleteCommentAnnotation } = useDeleteCommentAnnotation();
const deleteCommentAnnotationEvent = await deleteCommentAnnotation(deleteCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const deleteCommentAnnotationEvent = await commentElement.deleteCommentAnnotation(deleteCommentAnnotationRequest);

​
deleteSelectedComment

To delete a comment using an API method, use the deleteSelectedComment() method. 
if (client) {
  const commentElement = client.getCommentElement();
  commentElement.deleteSelectedComment();
}

​
getCommentAnnotationsCount

  • Get the total and unread comment annotations count of all the comment annotations across specified Organization, Folder, Document and Multiple Documents levels.
  • If you don’t specify any query, it will return data from the folder/documents specified in the setDocuments method.
  • You can specify 30 documents at a time.
  • Set aggregateDocuments to true to aggregate comment counts across all documents set in the setDocuments method, returning a single combined count instead of per-document counts.
  • Params: (optional) CommentRequestQuery
  • Returns: GetCommentAnnotationsCountResponse
Avaiable on SDK version 4.0.0 and above.
const { data } = useCommentAnnotationsCount({ organizationId: 'org1' });

useEffect(() => {
  if (data) {
    console.log('Comment annotations count for org1:', data);
  }
}, [data]);
Using API:
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((response) => {
  console.log('getCommentAnnotationsCount with organizationId', response.data);
});

​
getUnreadCommentAnnotationCountByLocationId

  • Get the number of CommentAnnotations with at least 1 unread Comment by Location Id.
Using Hooks:
const count = useUnreadCommentAnnotationCountByLocationId(locationId);
useEffect(() => {
  console.log(count, 'countObj')
}, [count])
Using API:
if (client) {
  const commentElement = client.getCommentElement();
  let subscription = commentElement.getUnreadCommentAnnotationCountByLocationId(locationId).subscribe((countObj) => {
    console.log(countObj);
  });
}
To unsubscribe from the subscription:
subscription?.unsubscribe()

​
getCommentAnnotations

  • Subscribe to the comment annotations for all the specified documents.
  • If you don’t specify any query, it will return data from the currently set documents and locations.
  • You can specify 30 documents at a time.
  • Params: (optional) CommentRequestQuery
  • Returns: GetCommentAnnotationsResponse
Avaiable on SDK version 4.0.0 and above.
Using Hooks:
const { data } = useGetCommentAnnotations(query);

useEffect(() => {
  if (data) {
    // initial data value will be null while the request is in progress
    console.log("Comment Annotations:", data);
  }
}, [data]);
Using API:
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotations(query).subscribe((response) => {
  // initial data value will be null while the request is in progress
  console.log("Comment Annotations:", response.data);
});

​
fetchCommentAnnotations

  • Fetches comment annotations based on various criteria such as organizationId, folderId, or specific documentIds.
  • It supports pagination and filtering options.
  • This is different from the existing subscription API which susbcribes to realtime changes to the comments data.
  • Params: FetchCommentAnnotationsRequest
  • Returns: FetchCommentAnnotationsResponse
// Get all annotations for a specific folder
const commentElement = client.getCommentElement();
const response = await commentElement.fetchCommentAnnotations({
  organizationId: 'org1', 
  folderId: 'folder1',
  allDocuments: true
});

// Get annotations for specific documents
const response = await commentElement.fetchCommentAnnotations({
  organizationId: 'org1',
  documentIds: ['doc1', 'doc2']
});

// Get annotations with filters
const response = await commentElement.fetchCommentAnnotations({
  organizationId: 'org1',
  documentIds: ['doc1', 'doc2'],
  createdAfter: 1234567890,
  statusIds: ['open'],
  pageSize: 20
});

​
getSelectedComments

const commentElement = client.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
  console.log('Selected comments:', selectedComments);
});
Unsubscribe from the subscription when you’re done:
subscription?.unsubscribe()

​
getCommentAnnotationById

  • Retrieve a specific comment annotation by its ID.
  • By default, it will return the comment annotation for the current documentId.
  • If you pass in a documentId, it will return the comment annotation for the given documentId.
  • Returns: CommentAnnotation
Using Hooks:
const annotation = useCommentAnnotationById({
  annotationId: '-O6W3jD0Lz3rxuDuqQFx',  // AnnotationID
  documentId: 'document-id'              // DocumentId (Optional)
});

useEffect(() => {
  console.log('annotation', annotation);
}, [annotation]);
Using API:
const commentElement = client.getCommentElement();

let subscription = commentElement.getCommentAnnotationById({
  annotationId: '-O6W3jD0Lz3rxuDuqQFx',  // AnnotationID
  documentId: 'document-id'              // DocumentId (Optional)
}).subscribe((annotation) => {
  console.log('annotation', annotation);
});
To unsubscribe from the subscription:
subscription?.unsubscribe()

​
getElementRefByAnnotationId

This will return the Xpath of the DOM element on which the comment was added. 
const commentElement = client.getCommentElement();
let elementRef = commentElement.getElementRefByAnnotationId('annotationId')

​
markAsRead

  • Mark a comment annotation as read for the current user. This updates the viewedBy field of the comment annotation to include the current user.
  • Params: annotationId: string
  • Returns: Promise<void>
const markAsReadRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { markAsRead } = useCommentUtils();
await markAsRead(markAsReadRequest);

// API Method
const commentElement = client.getCommentElement();
await commentElement.markAsRead(markAsReadRequest);

​
markAsUnread

  • Mark a comment annotation as unread for the current user. This removes the current user from the viewedBy field of the comment annotation.
  • Params: annotationId: string
  • Returns: Promise<void>
const markAsUnreadRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { markAsUnread } = useCommentUtils();
await markAsUnread(markAsUnreadRequest);

// API Method
const commentElement = client.getCommentElement();
await commentElement.markAsUnread(markAsUnreadRequest);

​
Messages

​
addComment

const comment = {
    commentText: 'This is a comment',
    commentHtml: '<p>This is a comment</p>',
};

const addCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  comment: comment
};

// Hook
const { addComment } = useAddComment();
const addCommentEventData = await addComment(addCommentRequest);

// API Method
const commentElement = client.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);

​
updateComment

const comment = {
		commentId: 'COMMENT_ID',
    commentText: 'This is a comment',
    commentHtml: '<p>This is a comment</p>',
};

const updateCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  comment: comment
};

// Hook
const { updateComment } = useUpdateComment();
const updateCommentEvent = await updateComment(updateCommentRequest);

// API Method
const commentElement = client.getCommentElement();
const updateCommentEvent = await commentElement.updateComment(updateCommentRequest);

​
deleteComment

const deleteCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  commentId: COMMENT_ID
};

// Hook
const { deleteComment } = useDeleteComment();
const deleteCommentEvent = await deleteComment(deleteCommentRequest);

// API Method
const commentElement = client.getCommentElement();
const deleteCommentEvent = await commentElement.deleteComment(deleteCommentRequest);

​
getComment

const getCommentRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { getComment } = useGetComment();
const comments = await getComment(getCommentRequest);

// API Method
const commentElement = client.getCommentElement();
const comments = await commentElement.getComment(getCommentRequest);

​
getUnreadCommentCountOnCurrentDocument

You can get the number of unread Comments on the current Document by using the useUnreadCommentCountOnCurrentDocument() hook:
const count = useUnreadCommentCountOnCurrentDocument();
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

​
getUnreadCommentCountByLocationId

You can get the number of unread Comments by Location Id by using the useUnreadCommentCountByLocationId() hook:
const count = useUnreadCommentCountByLocationId(locationId);
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

​
getUnreadCommentCountByAnnotationId

You can get the number of unread Comments by annotation id by using the useUnreadCommentCountByAnnotationId() hook:
const count = useUnreadCommentCountByAnnotationId(annotationId);
useEffect(() => {
   console.log(count, 'countObj')
}, [count])

​
@Mentions

​
assignUser

const assignUserRequest = {
  annotationId: 'ANNOTATION_ID',
  assignedTo: {
    userId: 'USER_ID',
    name: 'USER_NAME',
    email: 'USER_EMAIL'
  }
};

// Hook
const { assignUser } = useAssignUser();
const assignUserEventData = await assignUser(assignUserRequest);

// API Method
const commentElement = client.getCommentElement();
const assignUserEventData = await commentElement.assignUser(assignUserRequest);

​
customAutocompleteSearch

  • Handle autocomplete search for @mentions. You should use this if you have a large contact list that you want to plug into the autocomplete dropdown, and search directly your own data source.
  • Event: AutocompleteSearchEvent
1

Enable the feature

// Enable via props
<VeltComments customAutocompleteSearch={true} />


// Or, enable via Comment Element API
const commentElement = client.getCommentElement();
commentElement.enableCustomAutocompleteSearch();
commentElement.disableCustomAutocompleteSearch();
2

Set initial list

contactElement.updateContactList(users);
3

Handle search event

commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
    const searchText = inputData.searchText;

    if (inputData.type === 'contact') {
        const filteredUsersData = await __your_api_call__(searchText);
        contactElement.updateContactList(filteredUsersData, { merge: false });
    }
});

​
enableAtHere

  • This allows you to notify all the users explicitly added to the current document.
  • It won’t notify users in the organization who are not explicitly added to the document.
Default: Disabled.
Hooks:
const contactElement = useContactUtils();

useEffect(() => {
  contactElement.enableAtHere();
  contactElement.disableAtHere();
}, [contactElement]);
API:
const contactElement = client.getContactElement();
contactElement.enableAtHere();
contactElement.disableAtHere();

​
enableUserMentions

  • This allows you to enable or disable user @mentions.
Whether user @mentions are enabled. Default: true
Using Props:
<VeltComments userMentions={false} />
Using Hooks:
const contactElement = useContactUtils();

useEffect(() => {
  contactElement.enableUserMentions();
  contactElement.disableUserMentions();
}, [contactElement]);
Using API Method:
const contactElement = client.getContactElement();
contactElement.enableUserMentions();
contactElement.disableUserMentions();

​
expandMentionGroups

  • Expand the user groups and show individual users inside the groups in the @mentions dropdown menu.
<VeltComments expandMentionGroups={true} />

​
getContactList

  • Subscribe to the list of users added to organization, folder, document, user groups or the ones overwritten using the updateContactList API.
  • Params: none
  • Returns: GetContactListResponse
Using Hooks:
const contactList = useContactList();
console.log(contactList); // initial value will be null
Using API:
const contactElement = useContactUtils();
contactElement.getContactList().subscribe((response) => {
  console.log(response); // initial value will be null
});

​
onContactSelected

  • This event is triggered when a contact is selected from the contact dropdown in the Comment Dialog.
  • Use the event object to determine if the selected contact has access to the document using fields like isOrganizationContact, isDocumentContact and documentAccessType.
  • If the selected contact doesn’t have access to the document, you can show an invite dialog to the user to invite the contact to the document.
The returned data will be in the following schema: 
export class UserContactSelectedPayload {
    contact!: UserContact; // Selected Contact.
    isOrganizationContact!: boolean; // Is user part of organization contact.
    isDocumentContact!: boolean; // Is user part of document contact.
    documentAccessType!: string; // Document access type.
}
Using Hooks:
const selectedContact = useContactSelected();

useEffect(() => {
  console.log('selectedContact: ', selectedContact);
}, [selectedContact]);
Using API:
const contactElement = client.getContactElement();

contactElement.onContactSelected().subscribe((selectedContact: any) => {
  console.log('selectedContact : ', selectedContact);
});

​
setAtHereLabel

  • This allows you to modify the default text of the @here feature. eg: @all, @everyone, @team, etc.
Using Props:
<VeltComments atHereLabel='@all'>
Using Hooks:
const contactElement = useContactUtils();

useEffect(() => {
  contactElement.setAtHereLabel('@all');
}, [contactElement]);
Using API Method:
const contactElement = client.getContactElement();
contactElement.setAtHereLabel('@all');

​
setAtHereDescription

  • Customize the description that appears for the @here mention.
Using Props:
<VeltComments atHereDescription="Notify all users in this document" />
Using Hooks:
const contactElement = useContactUtils();

useEffect(() => {
  contactElement.setAtHereDescription('Notify all users in this document');
}, [contactElement]);
Using API Method:
const contactElement = client.getContactElement();
contactElement.setAtHereDescription('Notify all users in this document');

​
showMentionGroupsFirst

  • Show the user groups in the @mentions dropdown menu before the non-group users.
<VeltComments showMentionGroupsFirst={true} />

​
showMentionGroupsOnly

  • Show only the user groups in the @mentions dropdown menu and not the non-group users.
<VeltComments showMentionGroupsOnly={true} />

​
subscribeCommentAnnotation

const subscribeCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { subscribeCommentAnnotation } = useSubscribeCommentAnnotation();
const subscribeCommentAnnotationEvent = await subscribeCommentAnnotation(subscribeCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const subscribeCommentAnnotationEvent = await commentElement.subscribeCommentAnnotation(subscribeCommentAnnotationRequest);

​
unsubscribeCommentAnnotation

const unsubscribeCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { unsubscribeCommentAnnotation } = useUnsubscribeCommentAnnotation();
const unsubscribeCommentAnnotationEvent = await unsubscribeCommentAnnotation(unsubscribeCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const unsubscribeCommentAnnotationEvent = await commentElement.unsubscribeCommentAnnotation(unsubscribeCommentAnnotationRequest);

​
updateContactList

  • By default, the contact list is generated using the users in the organization and the document.
  • However, if you do not want to use that feature or want to provide a custom list of contacts, you can use this method.
  • By default, it will overwrite the current contact list. You can merge the provided contacts with the existing list by passing the merge flag as {merge:true}.
  • This method will only update the contact list in the current user session. It doens’t update the user contacts in the database or change the access control.
Using Hooks:
const contactElement = useContactUtils();

useEffect(() => {
  contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: '[email protected]'}], {merge: false});
}, [contactElement]);
Using API:
const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: '[email protected]'}], {merge: false});

​
updateContactListScopeForOrganizationUsers

  • Sometimes you may want to show only certain types of contacts in the contact dropdown.
  • By default, organization users will see all contacts in the organization, any user groups and any contacts added to the document.
  • Using this method, you can restrict the contacts shown in the dropdown to only certain types.
  • This only affects the Organization Users and not the Document Users. Document Users will always only see contacts added to the document.
Here are the available options:
  • all: Show all the contacts
  • organization: Show organization contacts.
  • organizationUserGroup: Show organization user groups.
  • document: Show document contacts.
const contactElement = client.getContactElement();
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);

​
Metadata

​
addContext

Custom metadata allows you to add extra information to comments, enhancing their functionality. Here’s what you can do with it:
  • Render additional data on comments
  • Position comment pins manually
  • Create custom UI components
  • Enable comment filtering on custom data
To add custom metadata, use the event.addContext() method when a comment is added. This method accepts an object with key-value pairs. 
// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
  if (commentEventCallbackData) {
    commentEventCallbackData.addContext({ customKey: 'customValue' });
  }
}, [commentEventCallbackData]);

// API Method
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
    event.addContext({ customKey: 'customValue' });
});

​
updateContext

  • Update the custom metadata associated with a comment annotation using the updateContext method.
  • Utilize this method to update the context of a comment annotation at any time. For example, you might use this when the name of the dashboard containing the comment annotation changes.
The commentElement.updateContext() method accepts three parameters:
  • The Comment Annotation ID
  • The new metadata object
  • An optional updateContextConfig object. Specify how the new metadata should be applied:
    • { merge: true }: Merges the new metadata with the existing metadata
    • { merge: false } or omitted: Replaces the existing metadata entirely (default behavior)
Using API:

const updatedContext = { customKey: 'customValue' };
const updateContextConfig = { merge: true };

const commentElement = client.getCommentElement();
commentElement.updateContext(COMMENT_ANNOTATION_ID, updatedContext, updateContextConfig);

​
Aggregation

​
Overview

Aggregation lets you filter, group, and render comments that match specific criteria — without writing any custom logic.
It’s especially powerful when comments are tied to structured data such as products, categories, or financial entities. You can group comments by:
  • Metadata (context)
  • Element IDs (targetElementId)
  • Resource identifiers (documentId, folderId, locationId)
In short: aggregation helps you query comments like data.

​
When to Use Aggregation

Use aggregation when your app involves complex relationships or taxonomy-based filtering.

​
🧩 Tables & Dashboards

Supply Chain Example
A product can belong to multiple categories. When viewing data by category, you may want to display all comments made on products within that category — or even across product variants. Financial Planning Example
A budget item (e.g., Marketing Q1) can have multiple subcategories (e.g., Paid Ads, Sponsorships).
Aggregation allows you to show all comments related to a specific period, department, or account group — even if those comments live across different documents or views.

​
How It Works

​
Comment Metadata Fields

Each comment can include one or more of the following identifiers or metadata fields:
FieldDescription
folderIdTarget folder ID
documentIdTarget document ID
locationIdTarget location ID
targetElementIdTarget DOM element ID
contextCustom metadata object for grouping or filtering

​
Comment Creation

When you use any of the above identifiers or metadata fields in the following supported components, they automatically get attached to the comment at the time it’s created.
This ensures that each comment carries the correct folder, document, element, or context metadata — so it can later be filtered or grouped accurately. Supported Components
  • Inline Comments Section
  • Comment Tool
// Comment Tool with context metadata
<VeltCommentTool
  targetElementId="cell-jan-cheese-zurich"
  context={{
    month: "jan",
    year: "2024",
    product: "cheese",
    location: "zurich"
  }}
/>

// Inline Comments Section with context
<VeltInlineCommentsSection
  targetElementId="budget-item-marketing-q1"
  context={{
    department: "marketing",
    quarter: "Q1",
    category: "paid-ads"
  }}
/>

​
Comment Rendering

When the above identifiers or metadata fields are passed to the following rendering components, they determine which comments are displayed.
Only comments that match the provided folder, document, element, or context values will be rendered in that component. Supported Components
  • Comment Bubble
  • Inline Comments Section
  • Comment Pin (Standalone) — does not support targetElementId
// Comment Bubble - filter by context
<VeltCommentBubble
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

// Comment Bubble - filter by target element
<VeltCommentBubble targetElementId="cell-jan-cheese-zurich" />

// Inline Comments Section - filter by context
<VeltInlineCommentsSection
  context={{ department: "marketing" }}
  contextOptions={{ partialMatch: true }}
/>

// Comment Pin - filter by context (no targetElementId support)
<VeltCommentPin
  context={{ product: "cheese", month: "jan" }}
/>

​
Filtering Behavior

When filtering comments, only annotations matching all provided fields will be shown: 
folderId
documentId
locationId
targetElementId
context

​
Context Matching

You can choose between two matching modes for the context field: Full Match (default) or Partial Match.

​
🔒 Full Match (Default)

A comment matches only if all fields in its context exactly match your filter criteria. Example: 
// Comment context
{ month: "jan", product: "cheese", location: "zurich" }

// Filters
{ month: "jan", product: "cheese", location: "zurich" }  ✅ Matches
{ month: "jan", product: "cheese" }                      ❌ No match (missing field)
{ month: "jan", product: "cheese", year: "2024" }        ❌ No match (extra field)

// Full match (default)
<VeltCommentBubble
  context={{ month: "jan", product: "cheese", location: "zurich" }}
/>

​
🔍 Partial Match

Enable partial matching with contextOptions={{ partialMatch: true }}. A comment matches if all fields in your filter exist in the comment’s context.
Extra fields in the comment context don’t prevent a match. Example: 
// Comment context
{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }

// Filters
{ product: "cheese" }                   ✅ Matches
{ day: "01", product: "cheese" }        ✅ Matches
{ product: "cheese", category: "dairy"} ❌ No match (missing field)
Example 
{/* Comment Bubble with Partial Match */}
<VeltCommentBubble
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

{/* Comment Tool with Partial Match */}
<VeltCommentTool
  targetElementId="element_id"
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

​
Grouping Matched Comment Annotations

When multiple comments match your filter criteria, you can group them into a single visual element — such as a Comment Bubble, Comment Pin, or Inline Comments Section — for a cleaner, multi-threaded UI. How it works:
  • Enable grouping globally with groupMatchedComments
  • All matching annotations are shown as one grouped thread
  • The comment count shows total grouped annotations
  • Users can expand to view and interact with all related threads
Example If there are three comments for "product: cheese" across different months, they can all appear in one Comment Bubble when you filter by { product: "cheese" }. 
// Enable grouping globally
<VeltComments groupMatchedComments={true} />

// Grouped Comment Bubble
<VeltCommentBubble
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

// Enable/disable via API
const commentElement = client.getCommentElement();
commentElement.enableGroupMatchedComments();
commentElement.disableGroupMatchedComments();

​
Custom Lists

​
createCustomListDataOnAnnotation

  • Add a custom dropdown list at the Comment Annotation level.
  • Use this to add custom tags or categories to the comment.
let customList = [
    { id: 'violent', label: 'Violent' },
    { id: 'inappropriate', label: 'Inappropriate' },
    { id: 'robbery', label: 'Robbery' },
    { id: 'nsfw', label: 'NSFW' },
];

const customListDataOnCommentAnnotation = {
	  type: 'multi', // choose from 'multi' or 'single'
    placeholder: 'Select a category',
    data: customList, // your customList data here
};
Using Props:
<VeltComments customListDataOnAnnotation={customListDataOnCommentAnnotation} />
API Method:
const commentElement = useCommentUtils();		
commentElement.createCustomListDataOnAnnotation(customListDataOnCommentAnnotation);

​
createCustomListDataOnComment

You can have custom dropdown lists appear when certain hotkeys are pressed. When you press a hotkey inside the Comment Dialog composer, it will open a dropdown list of items that you can select. Selecting an item frop the dropdown list will add a chip that inside the comment text.
Grouped lists: Useful for workflows like issue trackers (e.g., group by “Priority” or “Status”), allowing users to quickly refer and insert custom entities from your app. With this feature, you can combine multiple entity types into one drop down just like Linear.
Make sure the hotkey is a single character such as # or /.
The items in the list must be in the following schema:
Use AutocompleteGroup only for grouped lists. For flat lists, do not include groups on the config object or groupId on items.
export class AutocompleteGroup {
    id!: string;
    name!: string;
}

export class AutocompleteItem {
    id!: string; // Unique identifier
    name!: string; // Item name. This appears as the main item text in the UI.
    description?: string; // Item description. This appears as the secondary item text in the UI.
    icon?: { url?: string; svg?: string }; // Item icon. Either URL or inline SVG.
    link?: string; // Item link. You can use this to open a link when the item is clicked. Check the event listener below for more details.
    groupId?: string; // Optional: assigns item to a group (by AutocompleteGroup.id)
}
Flat List Implementation
let customList = [
  { id: '1', name: 'File 1', description: 'File Description 1', icon: { url: 'https://cdn-icons-png.flaticon.com/512/9496/9496432.png' } },
  { id: '2', name: 'File 2', description: 'File Description 2', icon: { url: 'https://cdn-icons-png.flaticon.com/512/11471/11471469.png' } },
  { id: '3', name: 'File 3', description: 'File Description 3', icon: { url: 'https://cdn-icons-png.flaticon.com/512/2656/2656402.png' } }
];

const customListDataOnComment = {
	hotkey: 'UNIQUE_HOTKEY', // only single charater is allowed. eg: '#'
	type: 'custom',
    data: customList, // your customList data here
};

// Using Props
<VeltComments customListDataOnComment={customListDataOnComment} />

// Hook
const commentElement = useCommentUtils();
commentElement.createCustomListDataOnComment(customListDataOnComment);
Grouped List Implementation
const customListWithGroups = {
  hotkey: '$',
  type: 'custom',
  groups: [
    { id: 'categories', name: 'Categories' },
    { id: 'priorities', name: 'Priorities' }
  ],
  data: [
    // Categories group
    { id: 'bug_1', name: 'Bug 1', description: 'Bug report 1', groupId: 'categories', icon: { svg: '<svg></svg>' } },
    { id: 'feature_2', name: 'Feature Request 2', description: 'New feature 2', groupId: 'categories', icon: { url: 'https://random.png' } },
    // Priorities group
    { id: 'high_1', name: 'High Priority 1', description: 'Urgent task 1', groupId: 'priorities', icon: { url: 'https://random.png' } },
    { id: 'medium_2', name: 'Medium Priority 2', description: 'Normal task 2', groupId: 'priorities', icon: { svg: '<svg></svg>' } },
    // Ungrouped items
    { id: 'misc_1', name: 'Miscellaneous 1', description: 'Other items 1', icon: { url: 'https://random.png' } },
    { id: 'note_2', name: 'Note 2', description: 'General note 2', icon: { svg: '<svg></svg>' } }
  ]
};

// Using Props
<VeltComments customListDataOnComment={customListWithGroups} />

// Hook
const commentElement = useCommentUtils();
commentElement.createCustomListDataOnComment(customListWithGroups);
Listen to click events on chips
After the comment is saved, the item will be rendered as a chip on the comment content. When the user clicks on it, you will get an event callback with the data of the clicked chip (AutocompleteItem).
This event will also be triggered when the user clicks on the contact chips added via the @mentions feature.
let autocompleteChipData = useAutocompleteChipClick();

​
customAutocompleteSearch

  • Handle autocomplete search for custom list. You should use this if you have a large list that you want to plug into the autocomplete dropdown, and search directly your own data source.
  • Event: AutocompleteSearchEvent
1

Enable the feature

// Enable via props
<VeltComments customAutocompleteSearch={true} />


// Or, enable via Comment Element API
const commentElement = client.getCommentElement();
commentElement.enableCustomAutocompleteSearch();
commentElement.disableCustomAutocompleteSearch();
2

Set initial list

// For @mentions feature
contactElement.updateContactList(users);

// For custom list feature
commentElement.createCustomListDataOnComment({
    hotkey: "#",
    type: "custom",
    data: customListData,
});
3

Handle search event

commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
    const searchText = inputData.searchText;

    // For @mentions feature
    if (inputData.type === 'contact') {
        const filteredUsersData = await __your_api_call__(searchText);
        contactElement.updateContactList(filteredUsersData, { merge: false });
    }

    // For custom list feature
    if (inputData.type === 'custom') {
        const filteredListData = await __your_api_call__(searchText, autocompleteData);
        commentElement.createCustomListDataOnComment({
            hotkey: "#",
            type: "custom",
            data: filteredListData,
        });
    }
});

​
Event Subscription

​
on

Subscribe to Comment Events. Here is the list of events you can subscribe to and the event objects you will receive.
CategoryEvent TypeDescriptionEvent Object
ThreadsaddCommentAnnotationAdd a new comment annotationAddCommentAnnotationEvent
ThreadsdeleteCommentAnnotationDelete a comment annotationDeleteCommentAnnotationEvent
MessagesaddCommentAdd a new commentAddCommentEvent
MessagesupdateCommentUpdate an existing commentUpdateCommentEvent
MessagesdeleteCommentDelete a commentDeleteCommentEvent
@MentionsassignUserAssign a user to a commentAssignUserEvent
@MentionssubscribeCommentAnnotationSubscribe to a comment annotationSubscribeCommentAnnotationEvent
@MentionsunsubscribeCommentAnnotationUnsubscribe from a comment annotationUnsubscribeCommentAnnotationEvent
@MentionsautocompleteSearchWhen user starts searching for a contact in the @mentions dropdown or for a list item in the custom list dropdownAutocompleteSearchEvent
AttachmentsaddAttachmentAdd an attachment to a commentAddAttachmentEvent
AttachmentsdeleteAttachmentDelete an attachment from a commentDeleteAttachmentEvent
ReactionsaddReactionAdd a reaction to a commentAddReactionEvent
ReactionsdeleteReactionDelete a reaction from a commentDeleteReactionEvent
ReactionstoggleReactionToggle a reaction on a commentToggleReactionEvent
Status & PriorityupdateStatusUpdate the status of a commentUpdateStatusEvent
Status & PriorityresolveCommentResolve a commentResolveCommentEvent
Status & PriorityupdatePriorityUpdate the priority of a commentUpdatePriorityEvent
Status & PriorityapproveCommentAnnotationApprove a comment annotationApproveCommentAnnotationEvent
Status & PriorityacceptCommentAnnotationAccept a comment annotationAcceptCommentAnnotationEvent
Status & PriorityrejectCommentAnnotationReject a comment annotationRejectCommentAnnotationEvent
RecordingsdeleteRecordingDelete a recording from a commentDeleteRecordingEvent
Deep LinkscopyLinkCopy a deep link to a commentCopyLinkEvent
AccessupdateAccessUpdate access settings for a commentUpdateAccessEvent
Comment SidebarcommentSidebarDataInitTriggered when comment sidebar data is first loadedCommentSidebarDataInitEvent
Comment SidebarcommentSidebarDataUpdateTriggered when comment sidebar data is updatedCommentSidebarDataUpdateEvent
UIcomposerClickedTriggered when comment composer is clickedComposerClickedEvent
UIcommentPinClickedTriggered when a comment pin is clickedCommentPinClickedEvent
UIlinkClickedTriggered when a clickable link in comment content is clickedLinkClickedEvent
RecordertranscriptionDoneTriggered when a transcription is generated and readyTranscriptionDoneEvent
// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
  if (commentEventCallbackData) {
    // Handle comment action callback event response
  }
}, [commentEventCallbackData]);

// API Method
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
    // Handle the event response
});

​
Attachments

​
enableAttachments

Whether file attachments are enabled. Default: true When this is on, users can attach image files to their comments. Users can download or delete an attachment. Users can attach multiple files at once. Currently we support .png, .jpg, .gif (static & animated), .svg file types up to 15MB per file. 
<VeltComments attachments={true} />

const commentElement = client.getCommentElement();
commentElement.enableAttachments();
commentElement.disableAttachments();

​
enableScreenshot

Whether screenshot option is enabled in comments. Default: false When enabled, users can attach screenshots when adding comments. This provides a quick way to capture and share visual context. 
// Using Component Props
<VeltComments screenshot={true} />

// Using API methods
const commentElement = client.getCommentElement();
commentElement.enableScreenshot();
commentElement.disableScreenshot();

​
addAttachment

const addAttachmentRequest = {
  annotationId: 'ANNOTATION_ID',
  files: '<Files[]>'
};

// Hook
const { addAttachment } = useAddAttachment();
const attachmentResponses = await addAttachment(addAttachmentRequest);

// API Method
const commentElement = client.getCommentElement();
const attachmentResponses = await commentElement.addAttachment(addAttachmentRequest);

​
deleteAttachment

const deleteAttachmentRequest = {
  annotationId: 'ANNOTATION_ID',
  commentId: COMMENT_ID,
  attachmentId: 'ATTACHMENT_ID'
};

// Hook
const { deleteAttachment } = useDeleteAttachment();
const deleteAttachmentEvent = await deleteAttachment(deleteAttachmentRequest);

// API Method
const commentElement = client.getCommentElement();
const deleteAttachmentEvent = await commentElement.deleteAttachment(deleteAttachmentRequest);

​
getAttachment

const getAttachmentRequest = {
  annotationId: 'ANNOTATION_ID',
  commentId: COMMENT_ID,
};

// Hook
const { getAttachment } = useGetAttachment();
const attachments = await getAttachment(getAttachmentRequest);

// API Method
const commentElement = client.getCommentElement();
const attachments = await commentElement.getAttachment(getAttachmentRequest);

​
allowedFileTypes

Limit file types in comment attachments by specifying allowed file extensions. Default: Not specified (all supported file types allowed) When this property is set, users can only attach files with the specified extensions. This helps you maintain security standards and ensure only approved file types are shared in collaborative discussions. By default, Velt supports .png, .jpg, .gif (static & animated), .svg file types up to 15MB per file. With allowedFileTypes, you can restrict to a subset of these or any other file extensions your application requires. 
// Using component prop
<VeltComments allowedFileTypes={['jpg', 'png']} />

// Using API method
const commentElement = client.getCommentElement();
commentElement.setAllowedFileTypes(['jpg', 'png']);

​
attachmentNameInMessage

Display the attachment filename in the message when a file is attached. Default: false When this property is enabled, the attachment filename will appear in the message text when a user selects a file to attach. This provides immediate visual confirmation of which file they’ve attached to their comment, improving clarity before submitting. 
<VeltComments attachmentNameInMessage={true} />

​
setComposerFileAttachments

Programmatically add file attachments to the comment composer from your application instead of requiring users to select files from the file system. This method enables workflows where you want to attach files programmatically, such as:
  • Attaching screenshots captured within your application
  • Including generated reports or documents
  • Adding files from your own storage system
  • Pre-populating attachments based on user context
Params: UploadFileData The UploadFileData object accepts the following properties:
  • files (required): Array of File objects to attach to the comment composer
  • annotationId (optional): ID of the target comment annotation. Use this to add attachments to an existing comment thread
  • targetElementId (optional): ID of the target element where the comment composer is attached. Use this to add attachments to a specific element
const commentElement = client.getCommentElement();

// Add attachments to a new comment composer
commentElement.setComposerFileAttachments({
  files: [file1, file2],
});

// Add attachments to an existing comment annotation
commentElement.setComposerFileAttachments({
  files: [file1, file2],
  annotationId: 'annotation-123',
});

// Add attachments to a comment composer on a specific element
commentElement.setComposerFileAttachments({
  files: [file1, file2],
  targetElementId: 'element-456',
});

​
Reactions

​
enableReactions

Whether emoji reactions are enabled. Default: true 
<VeltComments reactions={true} />

const commentElement = client.getCommentElement();
commentElement.enableReactions();
commentElement.disableReactions();

​
setCustomReactions

  • You can set custom reactions by passing a map that contains information about the reactions you want to add.
  • The map keys should be the reaction ID, and the map value should contain an object with either an url or emoji field to represent the reaction icon you want to use.
const commentElement = client.getCommentElement();

const customReactions = {
    "reactionId1": {
        "emoji": "🤣" // This will default to system emoji
    },
    "reactionId2": {
        "emoji": "🎉" // This will default to system emoji
    },
    "reactionId3": {
        "emoji": "🚀" // This will default to system emoji
    }
}
commentElement.setCustomReactions(customReactions);

​
addReaction

const addReactionRequest = {
  annotationId: '-OCWolieeXVOfPqTa0G-',
  commentId: 384399,
  reaction: {
    reactionId: 'fire',
    customReaction: {
          "emoji": "🔥"
    }
  }
};

// Hook
const { addReaction } = useAddReaction();
const addReactionEvent = await addReaction(addReactionRequest);

// API Method
const commentElement = client.getCommentElement();
const addReactionEvent = await commentElement.addReaction(addReactionRequest);

​
deleteReaction

const deleteReactionRequest = {
  annotationId: '-OCWolieeXVOfPqTa0G-',
  commentId: 384399,
  reaction: {
    reactionId: 'fire'
  }
};

// Hook
const { deleteReaction } = useDeleteReaction();
const deleteReactionEvent = await deleteReaction(deleteReactionRequest);

// API Method
const commentElement = client.getCommentElement();
const deleteReactionEvent = await commentElement.deleteReaction(deleteReactionRequest);

​
toggleReaction

const toggleReactionRequest = {
  annotationId: '-OCWolieeXVOfPqTa0G-',
  commentId: 384399,
  reaction: {
    reactionId: 'fire'
  }
};

// Hook
const { toggleReaction } = useToggleReaction();
const toggleReactionEvent = await toggleReaction(toggleReactionRequest);

// API Method
const commentElement = client.getCommentElement();
const toggleReactionEvent = await commentElement.toggleReaction(toggleReactionRequest);

​
Status & Priority

​
enableStatus

Whether to enable the default status dropdown & filters. Default: true When this is on, users can assign a status to each comment & filter comment by status in the sidebar. You can customize the list of status options as shown below on this page. 
<VeltComments status={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableStatus();
commentElement.disableStatus();

​
setCustomStatus

  • With custom statuses, you can replace the default statuses with your own values.
  • These statuses are also used in the comment sidebar to filter comments by status.
  • There are three types of statuses:
    • default: This will be the default status assigned to each comment.
    • ongoing: This is treated as an intermediary status, you can add as many statuses with type ongoing as you want.
    • terminal: This represents a status that is completed. Comments with this status type are no longer shown in the DOM.
  • Ensure that there are at least 2 statuses set.
const commentElement = client.getCommentElement();
commentElement.setCustomStatus([
  {
    id: 'open',
    name: 'Open',
    color: '#625df5',
    lightColor: '#f2f2fe',
    type: 'default',
  },
  {
    id: 'resolved',
    name: 'Resolved',
    color: '#198f65',
    lightColor: '#edf6f3',
    type: 'terminal',
  },
])

​
enableResolveButton

Whether to show resolve button on comments. Default: true This adds a tick mark button on the top right corner of the comment dialog. Clicking on this button will mark the comment as resolved. 
<VeltComments resolveButton={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableResolveButton();
commentElement.disableResolveButton();

​
updateStatus

const updateStatusRequest = {
  annotationId: 'ANNOTATION_ID',
  status: {
    "id": "open",
    "name": "Open",
    "color": "white",
    "lightColor":"green",
    "type": "default"
  }
};

// Hook
const { updateStatus } = useUpdateStatus();
const updateStatusEvent = await updateStatus(updateStatusRequest);

// API Method
const commentElement = client.getCommentElement();
const updateStatusEvent = await commentElement.updateStatus(updateStatusRequest);

​
resolveCommentAnnotation

const resolveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { resolveCommentAnnotation } = useResolveCommentAnnotation();
const resolveCommentAnnotationEvent = await resolveCommentAnnotation(resolveCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const resolveCommentAnnotationEvent = await commentElement.resolveCommentAnnotation(resolveCommentAnnotationRequest);

​
enablePriority

Whether to enable setting priority on comments. Default: false When this is on, users can assign a priority to each comment & filter comment by priority in the sidebar. You can customize the list of priority options as shown later on this page in the Set Custom Priorities section. 
<VeltComments priority={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enablePriority();
commentElement.disablePriority();

​
setCustomPriority

Pass custom priorities in the customPriority prop.Default priorities: P0, P1, P2With custom priorities, you can replace the default priorities with your own values. These priorities are also used in the comment sidebar to filter comments by priority.This will work if you have enabled the priority feature.The color property is used to set the priority pill background color.The lightColor property sets the background color of the filter.

<VeltComments customPriority={[
  {
    "id": "low",
    "name": "Low",
    "color": "red",
    "lightColor": "pink",
  },
]}/>
API Method: 
const commentElement = client.getCommentElement();
commentElement.setCustomPriority([
  {
    "id": "low",
    "name": "Low",
    "color": "red",
    "lightColor": "pink",
  },
])
Make sure to have at least 2 categories set.

​
updatePriority

const updatePriorityRequest = {
  annotationId: 'ANNOTATION_ID',
  priority: {
    "id": "low",
    "name": "Low",
    "color": "red",
    "lightColor": "pink",
  }
};

// Hook
const { updatePriority } = useUpdatePriority();
const updatePriorityEvent = await updatePriority(updatePriorityRequest);

// API Method
const commentElement = client.getCommentElement();
const updatePriorityEvent = await commentElement.updatePriority(updatePriorityRequest);

​
Recording

​
deleteRecording

const deleteRecordingRequest = {
  annotationId: 'ANNOTATION_ID',
  commentId: COMMENT_ID,
  recordingId: 'RECORDING_ID'
};

// Hook
const { deleteRecording } = useDeleteRecording();
const deleteRecordingEvent = await deleteRecording(deleteRecordingRequest);

// API Method
const commentElement = client.getCommentElement();
const deleteRecordingEvent = await commentElement.deleteRecording(deleteRecordingRequest);

​
getRecording

const getRecordingRequest = {
  annotationId: 'ANNOTATION_ID',
  commentId: COMMENT_ID
};

// Hook
const { getRecording } = useGetRecording();
const recordings = await getRecording(getRecordingRequest);

// API Method
const commentElement = client.getCommentElement();
const recordings = await commentElement.getRecording(getRecordingRequest);

​
setAllowedRecordings

Set the Recorder media options within Comments: (audio, screen, video, all).
  • audio: enables audio recording
  • screen: enables screen recording
  • video: enables video recording
  • all: enables all recording options
  • none: disables all recording options
Default: "audio" 
<VeltComments recordings="video,screen" />
Using API:
const commentElement = client.getCommentElement();
commentElement.setAllowedRecordings("video"); // set video mode only
commentElement.setAllowedRecordings("audio,screen"); // set audio and screen mode only
commentElement.setAllowedRecordings("all"); // set all modes
commentElement.setAllowedRecordings("none"); // disable all modes

​
enableRecordingCountdown

Whether the Recorder countdown is enabled. Default: true 
<VeltComments recordingCountdown={false} />

const recorderElement = client.getRecorderElement();
recorderElement.enableRecordingCountdown();
recorderElement.disableRecordingCountdown();

​
enableRecordingTranscription

Controls whether to enable AI transcription for recordings. Default: enabled
Using Props:
<VeltComments recordingTranscription={false} />
Using API Methods:
// Using comment element
const commentElement = client.getCommentElement();
commentElement.enableRecordingTranscription();
commentElement.disableRecordingTranscription();

// Or using recorder element 
const recorderElement = client.getRecorderElement();
recorderElement.enableRecordingTranscription();
recorderElement.disableRecordingTranscription();

​
Deep Link

const getLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { getLink } = useGetLink();
const getLinkResponse = await getLink(getLinkRequest);

// API Method
const commentElement = client.getCommentElement();
const getLinkResponse = await commentElement.getLink(getLinkRequest);

const copyLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { copyLink } = useCopyLink();
const copyLinkEvent = await copyLink(copyLinkRequest);

// API Method
const commentElement = client.getCommentElement();
const copyLinkEvent = await commentElement.copyLink(copyLinkRequest);

​
Navigation

​
scrollToCommentByAnnotationId

  • This will scroll the page to the element directly. This will work if the element is present on the DOM.
const commentElement = client.getCommentElement();
commentElement.scrollToCommentByAnnotationId('annotationId')

​
selectCommentByAnnotationId

  • Use this to programmatically select a comment annotation by its ID.
  • When called without arguments or with an invalid ID, it will close the currently selected annotation.
  • Example: If the user opens a comment URL from an email notification, you can use this to open the comment dialog after your page has finished rendering.
// Using Hooks
const commentElement = useCommentUtils();

// Open a specific annotation
commentElement.selectCommentByAnnotationId('COMMENT_ANNOTATION_ID');

// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');

// Using API methods
const commentElement = client.getCommentElement();

// Open a specific annotation
commentElement.selectCommentByAnnotationId('COMMENT_ANNOTATION_ID');

// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');

​
onCommentSelectionChange

The useCommentSelectionChangeHandler hook can be used to subscribe to Comment selection changes.
import React, { useEffect } from 'react';
import { useCommentSelectionChangeHandler } from '@veltdev/react';

function YourComponent() {
    const commentSelectionChange = useCommentSelectionChangeHandler();

    useEffect(() => {
        console.log('commentSelectionChange', commentSelectionChange);
    }, [commentSelectionChange]);

    return (
        <>
            Selected Comment: {commentSelectionChange.annotation.id}
        </>
    );
}

​
enablescrollToComment

Whether, users will be scrolled to the location of a Comment when it is clicked. Default: true By default, users will be redirected to a Comment if the comment id is provided in the url. But sometimes this experience is annoying, so we have provided a way to disable the option to automatically scroll users to the location of the Comment.
To disable the feature, set scrollToComment to false.
<VeltComments scrollToComment={false}/>
API methods: 
const commentElement = client.getCommentElement();
// To enable scroll to component
commentElement.enablescrollToComment();
// To disable scroll to component
commentElement.disablescrollToComment();

​
DOM Controls

​
allowedElementIds

​
allowedElementClassNames

​
allowedElementQuerySelectors

Provide a list of element DOM IDs, class names, or query selectors where commenting should be allowed. Comments will be disabled for all other elements. Note, this does not impact Popover mode.
Using Props:
<VeltComments 
  allowedElementIds={['some-element']} 
  allowedElementClassNames={["class-name-1", "class-name-2"]}
  allowedElementQuerySelectors={["#id1.class-name-1"]}
/>
Using API Method:
const commentElement = client.getCommentElement();
commentElement.allowedElementIds(['some-element']);
commentElement.allowedElementClassNames(["class-name-1", "class-name-2"]);
commentElement.allowedElementQuerySelectors(["#id1.class-name-1"]);

​
data-velt-comment-disabled

Disable certain elements from being commented on. Add the data-velt-comment-disabled attribute to elements where you want to disable commenting. 
<div data-velt-comment-disabled></div>

​
sourceId

  • When you have multiple elements with the same DOM ID, you can use the sourceId attribute to control which element displays the comment dialog when adding a new comment.
  • By default, comments appear on all matching elements.
  • This is useful in cases where you have multiple instances of the same data component on a page and want the comment to appear on each instance, such as Popover comments on a table.
  • You can randomly generate the sourceId. It just needs to be unique for each element in the current session.
<VeltCommentTool sourceId="sourceId1" />

​
AI Categorization

​
enableAutoCategorize

Whether AI auto-categorization of comments is enabled. Default: false We use AI to analyze your comment content and auto-categorize it so users can filter comments easily. You can provide a list of custom categories that we should use to categorize the comments (shown below). 
<VeltComments autoCategorize={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableAutoCategorize();
commentElement.disableAutoCategorize();

​
setCustomCategory

Pass custom categories in the customCategory prop.Default categories: Question, Feedback, Bug, Other.With custom categories, you can replace the default categories with your own values.These categories are used in the Comments Sidebar to filter comments by category. The AI autoCategorize feature uses the list of categories to determine the closest category to choose from.The input format to the customCategory prop should be an array of objects with an id, name, and color.The color property is used to set the category pill background color.
<VeltComments customCategory={[
  {
    "id": "bug",
    "name": "Bug",
    "color": "red"
  }
]}/>
API Method: 
const commentElement = client.getCommentElement();
commentElement.setCustomCategory([
  {
    "id": "bug",
    "name": "Bug",
    "color": "red"
  }
])
Make sure to have at least 2 categories set.

​
UI/UX

​
composerMode

By default, the Composer in the Comments Dialog only shows the text input box and does not show the actions bar until the Composer is clicked on or the user starts typing. You can modify this behavior by setting the Composer Mode prop to "expanded". This will make the actions bar always visible. To keep the default behavior you can set the property to "default". Default: "default" 
<VeltComments composerMode="expanded"/>

​
commentToNearestAllowedElement

Attach comment pins to the closest allowed element when clicking on a non-allowed element. Default: false 
<VeltComments commentToNearestAllowedElement={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableCommentToNearestAllowedElement();
commentElement.disableCommentToNearestAllowedElement();

​
deleteThreadWithFirstComment

Whether deleting the first comment in a thread will delete the entire thread. Default: true 
<VeltComments deleteThreadWithFirstComment={false} />

​
draftMode

Whether to store comments in draft if they are not submitted. Default: true 
<VeltComments draftMode={false} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableDraftMode();
commentElement.disableDraftMode();

​
enableCollapsedComments

You can control whether comments inside the annotation should be collapsed. Default: false
Using Props:
<VeltComments collapsedComments={true} />
Using API:
const commentElement = client.getCommentElement();
// To enable collapsed comments
commentElement.enableCollapsedComments();
// To disable collapsed comments
commentElement.disableCollapsedComments();

​
enableFullExpanded

  • You can control whether comments should be shown in fully expanded state by default.
  • Available on all comment-related components and can be controlled via props or API methods.
Default: false
Using Props:
// Apply this change globally to all types of comments
<VeltComments fullExpanded={true} />

// Apply this change only in comments sidebar
<VeltCommentsSidebar fullExpanded={true} />

// Apply this change only in inline comments section
<VeltInlineCommentsSection fullExpanded={true} />

// Apply this change only in the standalone comment thread
<VeltCommentThread fullExpanded={true} />
Using API:
// API Method
const commentElement = client.getCommentElement();
commentElement.enableFullExpanded();
commentElement.disableFullExpanded();

​
enableShortUserName

You can control whether long user names should be shortened. For long names, this will first create an initial of the second name and if the name is still long, it will truncate it with ellipses. Default: true
Using Props:
<VeltComments shortUserName={false} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableShortUserName();
commentElement.disableShortUserName();

​
enableSignInButton

Whether to enable Sign In button on comment dialog when user is anonymous or signed out. Default: false This allows anonymous or signed out users to still read the comments but encourages them to sign in if they want to respond to the comments. 
<VeltComments signInButton={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableSignInButton();
commentElement.disableSignInButton();

​
enableSidebarButtonOnCommentDialog

Whether the Sidebar Button on Comment Dialogs show up. Default: true By Default, each Comment Dialog has a button at the bottom that will open the Comments Sidebar when clicked. To disable it, you can set it to false:
Using Props:
<VeltComments sidebarButtonOnCommentDialog={true} />
Using API methods:
const commentElement = client.getCommentElement();
commentElement.enableSidebarButtonOnCommentDialog()
commentElement.disableSidebarButtonOnCommentDialog()

​
enableDeleteReplyConfirmation

You can enable a confirmation dialog before deleting a reply in comment threads. This feature helps prevent accidental deletions and improves user experience.
Using Props:
<VeltComments deleteReplyConfirmation={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableDeleteReplyConfirmation();
commentElement.disableDeleteReplyConfirmation();

​
enableMobileMode

Whether mobile mode is enabled. When mobile mode is enabled and the screen width is small enough, comment windows will appear fixed to the bottom of the screen and full width instead of the usual popup window. Default: false 
<VeltComments mobileMode={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableMobileMode();
commentElement.disableMobileMode();

​
enableCommentPinHighlighter

Wheter the pin highlighter outline is enabled or not. Default: true 
<VeltComments commentPinHighlighter={false} />
API Methods: 
const commentElement = client.getCommentElement();
commentElement.enableCommentPinHighlighter(); // to enable comment pin highlight
commentElement.disableCommentPinHighlighter(); // to disable comment pin highlight

​
enableDialogOnHover

Whether the comment dialog shows on hover over the comment pin or the target element. Default: true 
<VeltComments dialogOnHover={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableDialogOnHover();
commentElement.disableDialogOnHover();

​
enableFloatingCommentDialog

Whether floating comment dialog is shown next to comment pin on hover or click. Default: true 
<VeltComments floatingCommentDialog={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableFloatingCommentDialog();
commentElement.disableFloatingCommentDialog();

​
excludeLocationIds

Use this to filter out Comments at a specific Location for certain Users. 
const locationIds = ['location1', 'location2']; // list of location ids
client.excludeLocationIds(locationIds);
To reset it, you can pass an empty array:
client.excludeLocationIds([]);

​
filterCommentsOnDom

  • Filter out comments in the DOM when they are filtered in the sidebar.
  • When the sidebar is closed (default mode) or unmounted (embed mode), the DOM filter will be removed.
Default: false
Using Props:
<VeltComments filterCommentsOnDom={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableFilterCommentsOnDom();
commentElement.disableFilterCommentsOnDom();

​
onSidebarButtonOnCommentDialogClick

Use this to act on clicks on the Sidebar Button at the bottom of the Comment Dialog.
Using Props:
<VeltComments onSidebarButtonOnCommentDialogClick={(event)=>yourMethod(event)} />
Using Hooks:
const commentDialogSidebarClickEvent = useCommentDialogSidebarClickHandler();
useEffect(() => {
  console.log('CommentDialog Sidebar button clicked');
}, [commentDialogSidebarClickEvent]);
Using API methods:
const commentElement = client.getCommentElement();
let subscription = commentElement.onSidebarButtonOnCommentDialogClick().subscribe((event) => yourMethod(event));
To unsubscribe from the subscription:
subscription?.unsubscribe()

​
onSignIn

When the user clicks on the sign in button, we will emit an onSignIn event that you can handle with your own sign in method. No data is passed with the event. 
<VeltComments onSignIn={() => yourSignInMethod()} />

​
enableReplyAvatars

This shows the avatars of unique users who have replied to a comment.
  • replyAvatars: Whether the reply avatar component is enabled.
  • maxReplyAvatars: The maximum number of reply avatars to show. It will show the count of remaining unque users as the next avatar.
Default: false
Using props:
<VeltComments maxReplyAvatars={2} replyAvatars={true} />
Using API:
const commentsElement = client.getCommentsElement();
commentsElement.enableReplyAvatars(); // Enables the reply avatar component.
commentsElement.disableReplyAvatars(); // Disables the reply avatar component.
commentsElement.setMaxReplyAvatars(2); // Sets the maximum number of reply avatars to show.

​
showCommentsOnDom

Whether comments are shown on the DOM. Default: true By default, all the comments will be visible on DOM whenever we are able to detect to elements for that. But users can hide it from DOM if required. There are 2 ways to show/hide comments on DOM: Configuring attributes on the React Component: 
{/* `true` to show comments, `false` to hide comments */}
<VeltComments commentsOnDom={false} />
Using API methods: 
const commentElement = client.getCommentElement();
// to show comments on DOM
commentElement.showCommentsOnDom();
// to hide comments on DOM
commentElement.hideCommentsOnDom();

​
showResolvedCommentsOnDom

Whether to show resolved comments on the DOM. Default: false 
<VeltComments resolvedCommentsOnDom={true} />
API Methods: 
const commentElement = client.getCommentElement();
// To show resolved comments on dom
commentElement.showResolvedCommentsOnDom();
// To hide resolved comments on dom
commentElement.hideResolvedCommentsOnDom();

​
updateCommentDialogPosition

  • Sometimes when you manually set the position of the Comment Pin, the Comment Dialog might not position itself near the pin in certain scenarios like scrolling, zooming the page when the comment dialog is open.
  • Use this to manually trigger an update. The dialog will reposition itself near the pin.
const commentElement = client.getCommentElement();
commentElement.updateCommentDialogPosition();
You can add custom lists at two levels: a. on the CommentAnnotation and b. on the Comment. Enable a callback when users click on links rendered in comment content. When enabled, links won’t automatically open; instead an event is emitted. How to use:
  • By default linkCallback is false.
  • When false, clicking a link opens it directly and no callback is triggered.
  • When true, clicking a link does not open it; instead a linkClicked event is emitted so you can handle navigation.
// Using Props
<VeltComments linkCallback={true} />

// Using Hooks
const linkEvent = useCommentEventCallback('linkClicked')
useEffect(() => {
  if (linkEvent) {
    console.log('linkClicked', linkEvent);
  }
}, [linkEvent]);

// Using API
const commentElement = client.getCommentElement();
commentElement.on('linkClicked').subscribe((linkData) => {
  console.log('linkClicked', linkData);
});
Types: 
export interface LinkClickedEvent {
  text: string;
  link: string;
  commentAnnotation: CommentAnnotation;
  commentId: Number;
  metadata?: VeltEventMetadata;
}

​
Extra Information

​
enableCommentIndex

Whether comment index is enabled. Default: false This appears in the comment sidebar and on the comment pins. When this is on, we show a small icon indicating the comment index in the order of creation date. This enables users to find and navigate to the desired comment quickly. 
<VeltComments commentIndex={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableCommentIndex();
commentElement.disableCommentIndex();

​
enableDeviceInfo

Whether device type indicator is enabled. Default: false When this is on, we show additional information in the Comment Thread indicating which device the comment was created on. This is useful especially for design tools, where additional context is needed for debugging issues. 
<VeltComments deviceInfo={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableDeviceInfo();
commentElement.disableDeviceInfo();

​
enableDeviceIndicatorOnCommentPins

Whether the device type indicator on Comment Pins is enabled. Default: false When this is on, we show a small device type icon on the Comment Pin indicating which device the comment was created on. This is useful especially for design tools, where additional context is needed for debugging issues. 
<VeltComments deviceIndicatorOnCommentPins={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableDeviceIndicatorOnCommentPins();
commentElement.disableDeviceIndicatorOnCommentPins();

​
enableGhostComments

Whether to show ghost comments on the DOM. Default: false Ghost comments are comments that were once linked to certain content on the DOM but that content is no longer available. If this is on, we display ghost comments in gray, close to where they were originally positioned on the DOM. 
<VeltComments ghostComments={true} />
Using API methods:
const commentElement = client.getCommentElement();
commentElement.enableGhostComments();
commentElement.disableGhostComments();

​
enableGhostCommentsIndicator

Whether to show ghost comment labels in the comment sidebar. Default: true Ghost comments are always shown in the comments sidebar so that users can see the history of all comments. If this is on, we show a label on the comment in the sidebar indicating that the original content on which this comment was added is no longer available. This sets better expectations with the users. 
<VeltComments ghostCommentsIndicator={true} />
Using API methods:
const commentElement = client.getCommentElement();
commentElement.enableGhostCommentsIndicator();
commentElement.disableGhostCommentsIndicator();

​
Special File Type Support

​
Iframe Container Support

  • To enable comments on an iframe, add data-velt-iframe-container="true" to the iframe’s container element.
  • Note this will not insert the comments inside the contents of the iframe, but rather on top of the iframe.
<div data-velt-iframe-container="true">
	<iframe src="https://www.wikipedia.org/" width="500px" height="500px"></iframe>
</div>

​
data-velt-pdf-viewer

To support comments on top of a pdf viewer, add the data-velt-pdf-viewer="true" attribute in the container element of the pdf viewer. 
<!-- Add this attribute to the container of your pdf viewer -->
<div id="viewerContainer" data-velt-pdf-viewer="true">
    <!-- Your pdf viewer here -->
    <div id="viewer" class="pdfViewer"></div>
</div>

​
svgAsImg

  • By default, Velt SDK treats SVGs as layered elements.
  • If you want to treat SVGs as flat images, you can use this.
  • Default: false
Using Props:
<VeltComments svgAsImg={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableSvgAsImg();
commentElement.disableSvgAsImg();

​
Keyboard Controls

​
enableHotkey

Whether Hotkeys are enabled or not. For now, the only hotkey supported is pressing c to enable comment mode. Default: false
Using Props:
<VeltComments hotkey={false} />
Using API Method:
const commentElement = client.getCommentElement();
commentElement.enableHotkey();
commentElement.disableHotkey();

​
enableEnterKeyToSubmit

  • By default, pressing enter will add a new line and pressing shift + enter will submit a comment.
  • You can change this default behavior so that pressing enter will submit a comment by setting the enterKeyToSubmit property to true.
Using Props:
<VeltComments enterKeyToSubmit={true} />
Using API Method:
const commentElement = client.getCommentElement();
commentElement.enableEnterKeyToSubmit();
commentElement.disableEnterKeyToSubmit();

​
enableDeleteOnBackspace

  • Use this to enable or disable deleting comments when backpsace key is pressed.
Default: enabled
Using Props:
<VeltComments deleteOnBackspace={false} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableDeleteOnBackspace();
commentElement.disableDeleteOnBackspace();

​
Moderation

​
enableModeratorMode

Whether comments require moderator approval. Default: false By default, when a user adds a comment it is visible to all authenticated users on the same document. Moderator mode makes visibility of all comments private to only admin users and the comment author. Admin users will see an approve button on the comment dialog. Once approved the comment will be visible to all users who can access the document. You can set some users as admin by setting the isAdmin property in the User object, during the identify() call. 
<VeltComments moderatorMode={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableModeratorMode();
commentElement.disableModeratorMode();

​
enableResolveStatusAccessAdminOnly

  • Restrict the resolve action to admin users and the comment author only.
Using props:
<VeltComments resolveStatusAccessAdminOnly={true} />
Using API:
const commentElement = client.getCommentElement();
// To enable resolve status access admin only
commentElement.enableResolveStatusAccessAdminOnly();
// To disable resolve status access admin only
commentElement.disableResolveStatusAccessAdminOnly();

​
approveCommentAnnotation

const approveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { approveCommentAnnotation } = useApproveCommentAnnotation();
const approveCommentAnnotationEvent = await approveCommentAnnotation(approveCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const approveCommentAnnotationEvent = await commentElement.approveCommentAnnotation(approveCommentAnnotationRequest);

​
acceptCommentAnnotation

const acceptCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { acceptCommentAnnotation } = useAcceptCommentAnnotation();
const acceptCommentAnnotationEventData = await acceptCommentAnnotation(acceptCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const acceptCommentAnnotationEventData = await commentElement.acceptCommentAnnotation(acceptCommentAnnotationRequest);

​
rejectCommentAnnotation

const rejectCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

// Hook
const { rejectCommentAnnotation } = useRejectCommentAnnotation();
const rejectCommentAnnotationEventData = await rejectCommentAnnotation(rejectCommentAnnotationRequest);

// API Method
const commentElement = client.getCommentElement();
const rejectCommentAnnotationEventData = await commentElement.rejectCommentAnnotation(rejectCommentAnnotationRequest);

​
enableSuggestionMode

Whether to enable suggestion mode to accept or reject comments. Default: false
To accept comments, set the suggestionMode attribute to true.
<VeltComments suggestionMode={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableSuggestionMode();
commentElement.disableSuggestionMode();

​
updateAccess

const updateAccessRequest = {
  annotationId: 'ANNOTATION_ID',
  accessMode: 'private';
};

// Hook
const { updateAccess } = useUpdateAccess();
const updateAccessEvent = await updateAccess(updateAccessRequest);

// API Method
const commentElement = client.getCommentElement();
const updateAccessEvent = await commentElement.updateAccess(updateAccessRequest);

​
enablePrivateComments

  • Private comment mode enables admin users to add comments that are only visible to other admin users.
  • Use this to enable or disable private comment mode.
Default: false
To enable private comment mode, set the privateCommentMode attribute to true:
<VeltComments privateCommentMode={true} />
API Methods: API to enable/disable private comment mode: 
const commentElement = client.getCommentElement();
// To enable private comment mode
commentElement.enablePrivateCommentMode();
// To disable private comment mode
commentElement.disablePrivateCommentMode();

​
enableReadOnly

Control whether comments are in read-only mode. When enabled, any features requiring user interaction (e.g., Composer, Reactions, Status) will be removed. Default: false
Using Props:
<VeltComments readOnly={true} />
Using API:
  const commentElement = client.getCommentElement();
  commentElement.enableReadOnly();
  commentElement.disableReadOnly();

​
Comment Read Status

​
enableSeenByUsers

Control whether the “Seen By” feature is enabled for comments. When enabled, it shows which users have seen each comment. Default: true
Using Props:
<VeltComments seenByUsers={false} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableSeenByUsers();
commentElement.disableSeenByUsers();

​
setUnreadIndicatorMode

Whether verbose mode is enabled for unread Comments. Default: 'minimal' Unread Comments can be in minimal mode or verbose mode. In minimal mode, a small red dot indicator appears for unread Comments. In verbose mode, a larger badge with the text “UNREAD” will appear for unread Comments. 
<VeltComments unreadIndicatorMode={"verbose"} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.setUnreadIndicatorMode("verbose"); // use badge with text UNREAD
commentElement.setUnreadIndicatorMode("minimal"); // use small red dot indicator

​
Toggle Comment Types

​
enableAreaComment

Area comments allows users to draw a rectangle and attach a comment to it. Use this to enable or disable area comments. Default: true
Using Props:
<VeltComments areaComment={false} />
Using API Method:
const commentElement = client.getCommentElement();
commentElement.enableAreaComment();
commentElement.disableAreaComment();

​
enablePopoverMode

For a complete setup guide for Popover mode, read here.
Whether Popover Mode is enabled. Default: false 
<VeltComments popoverMode={true}/>
Using API:
const commentElement = client.getCommentElement();
commentElement.enablePopoverMode();
commentElement.disablePopoverMode();

​
enableStreamMode

For a complete setup guide for Stream mode, read here.
Whether Stream Mode is enabled. Default: false 
<VeltComments streamMode={true}/>
Using API:
const commentElement = client.getCommentElement();
commentElement.enableStreamMode();
commentElement.disableStreamMode();

​
enableTextMode

For a complete setup guide for Text mode, read here.
Whether Text Mode is enabled. Default: true
Using Props:
<VeltComments textMode={true}/>
Using API:
const commentElement = client.getCommentElement();
commentElement.enableTextComments();
commentElement.disableTextComments();

​
enableInlineCommentMode

Whether In-line comment mode is enabled. When In-line comment mode is enabled, comments will appear under the text they are associated with in the DOM, instead of as a pop up window. Default: false 
<VeltComments inlineCommentMode={true}/>

const commentElement = client.getCommentElement();
commentElement.enableInlineCommentMode();
commentElement.disableInlineCommentMode();

​
enableMultithread

  • By default comments are single threaded.
  • You can make it multithreaded by setting multiThread prop to true.
  • If you had previously used a wireframe for the comment dialog, you will need to add the multithread wireframe.
  • Default: false
<VeltComments multiThread={true} />

​
Comment Tool

​
context

  • Add context to the Velt Comment Tool component to associate custom metadata with comments created using that tool.
  • Predefine context directly within the component itself.
  • Currently, this feature is specific to popover comments. This allows you to, for example, assign unique context to each cell in a table if you place a Velt Comment Tool in each cell.
  • The context prop accepts an object with key-value pairs.
// For popover comments
<VeltCommentTool context={{ key1: 'value1' }} />

​
enableCommentMode

Turns Comment mode on or off. When you click on the comment tool, it turns on comment mode and user can attach comment to any element on the DOM. Using this method you can programmatically turn on the commenting mode. 
const commentElement = client.getCommentElement();
commentElement.enableCommentMode();
commentElement.disableCommentMode();

​
onCommentModeChange

The comment mode is toggled on and off when you click on the Comment Tool.
The useCommentModeState() hook can be used to get the Comment mode without having to subscribe to changes. When the Comment mode changes, the hook return value will update.The subscription is automatically unsubscribed when the component dismounts.
import { useCommentModeState } from '@veltdev/react';

export default function YourDocument() {

  let commentModeState = useCommentModeState()

  return (
    <div>
       Comment Mode is turned on: {commentModeState}
    </div>
  )
}

​
enableCommentTool

Whether the Comment Tool button is Enabled. Default: true When the Comment Tool is disabled, it can not be used to leave comments. Other ways to leave comments, such as highlighting text, will also be disabled.
Using Props:
<VeltComments commentTool={false} />
Using API methods:
const commentElement = client.getCommentElement();
commentElement.enableCommentTool();
commentElement.disableCommentTool();

​
disabled

Disables the comment tool and prevents users from adding new comments. This is helpful when you want to temporarily or conditionally restrict comment creation while still allowing users to view existing comments. Default: false
This prop disables the specific comment tool instance it is applied to; the disableCommentTool() API disables all comment tools globally.
<VeltCommentTool disabled={true} />

​
enableChangeDetectionInCommentMode

  • By default, DOM Change Detection is disabled in Comment Mode for better performance.
  • You can enable it to automatically reposition comment pins when the DOM changes while in Comment Mode.
Default: false
Using Props:
<VeltComments changeDetectionInCommentMode={true} />
Using API Method:
const commentElement = client.getCommentElement();
commentElement.enableChangeDetectionInCommentMode();
commentElement.disableChangeDetectionInCommentMode();

​
enablePersistentCommentMode

  • When Persistent comment mode is enabled, you can continue leave additional comments after finishing a comment.
  • When it is disabled, you will need to reclick the Comment Tool every time when you want to make a comment.
Default: false 
<VeltComments persistentCommentMode={true}/>

const commentElement = client.getCommentElement();
commentElement.enablePersistentCommentMode();
commentElement.disablePersistentCommentMode();

​
forceCloseAllOnEsc

  • When enabled, pressing the ESC key will force close persistent comment mode even if a comment thread is currently active.
  • When disabled (default), pressing ESC will only close the active comment thread but keep persistent comment mode enabled.
  • This provides more control over the ESC key behavior in persistent comment mode.
Default: false 
<VeltComments forceCloseAllOnEsc={true}/>

const commentElement = client.getCommentElement();
commentElement.enableForceCloseAllOnEsc();
commentElement.disableForceCloseAllOnEsc();

​
setPinCursorImage

You can set custom mouse cursor when the comment mode is on. The custom cursor image must be 32 x 32 pixels. 
<VeltComments pinCursorImage={BASE64_IMAGE_STRING} />
API Methods: 
const commentElement = client.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);

​
Minimap

​
enableMinimap

  • The minimap shows a bar on the edge of the screen with indicators that show where comments exist.
  • Use this to enable/disable the minimap. By default it’s disabled.
  • It can be positioned left or right. By default, it’s positioned on the right side of the screen.
Option a. Enable using config: 
<VeltComments minimap={true} minimapPosition="left" />
API Method:
const commentElement = client.getCommentElement();
commentElement.enableMinimap();
commentElement.disableMinimap();
Option b. Enable using Minimap Component: This offers greater flexibility to customize and position the minimap. 
<div className="relative-container">
  <VeltCommentsMinimap targetScrollableElementId="scrollableElement" position="left" />
  <div id="scrollableElement">
      {/* scrollable content */}
  </div>
</div>

<style>
  .relative-container {
    position: relative;
  }

  #scrollableElement {
    width: 100%;
    height: 200px; /* or any value */
    overflow: auto;
  }
</style>

​
Inline Comments

​
sortBy and sortOrder

  • Change the default sorting order of Comments in the Inline Comments Section.
  • Params:
    • sortBy: The field to sort by. Currently supports createdAt and lastUpdated. Default: lastUpdated for multithread and createdAt for single thread.
    • sortOrder: The order to sort by. It can be asc or desc. Default: desc for multithread and asc for single thread.
  <VeltInlineCommentsSection 
    sortBy="createdAt" 
    sortOrder="desc"
  />

​
multiThread

  • By default inline comment section is multithreaded.
  • You can make it single threaded by setting multiThread prop to false.
  • Default: true
<VeltInlineCommentsSection multiThread={false} />

​
composerPosition

  • Change the position of the comment composer in the inline comments section to top or bottom.
  • Default: bottom
<VeltInlineCommentsSection composerPosition="top" />

​
Popover Comments

​
enableDialogOnTargetElementClick

Whether the comment dialog opens when target element is clicked. This is relevant only for Popover mode. Default: true 
<VeltComments dialogOnTargetElementClick={true} />
API Method: 
const commentElement = client.getCommentElement();
commentElement.enableDialogOnTargetElementClick();
commentElement.disableDialogOnTargetElementClick();

​
enablePopoverTriangleComponent

Whether the popover triangle appears when Popover Mode is enabled. Default: true 
<VeltComments popoverTriangleComponent={true}/>
API Method: 
const commentElement = client.getCommentElement();
commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();

​
Comment Bubble

​
annotationId

  • The id of the comment annotation to show the comment bubble on.
  • The bubble will be rendered only if there is a comment annotation that matches the provided annotationId in the current document.
<VeltCommentBubble annotationId="annotation-id-1" />

​
targetElementId

  • The DOM ID of the element where comment bubble is added.
  • This binds the comment bubble to the element with the provided ID.
  • The bubble will be rendered only if there is a comment annotation that was added to the element with the provided ID.
<VeltCommentBubble targetElementId="cell-id-1" />

​
context

  • The context object to filter which comment annotations to show the comment bubble for.
  • The bubble will be rendered only if there is a comment annotation that matches the provided context in the current document.
  • Works only with popover mode comments.
  • Perfect for complex tables with filtering and segmentation needs.
  • Set flexible comment anchoring and filtering logic at the cell level using key-value pairs.
  • Supports aggregate views: Eg: comments added in day view can appear in week/month views automatically.
  • Context commonly has combined use with context options and the group matched comments feature.
<VeltCommentTool context={{ 'key1': 'value1', 'key2': 'value2' }} />
// Full match
<VeltCommentBubble context={{ 'key1': 'value1', 'key2': 'value2' }} />
// Partial match
<VeltCommentBubble context={{ 'key1': 'value1' }} contextOptions={{ partialMatch: true }} />

​
contextOptions

  • Matching behavior for the context object (default: full match, or set partialMatch: true for flexible matching).
  • How Partial Match Works:
    • A comment will match if ALL provided filter criteria exist in the comment’s context
    • Extra fields in the comment’s context don’t prevent matching
    • Missing fields in the comment’s context prevent matching
    • Example: Comment has { day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }
      • Filter { day: "01", product: "cheese" } → ✅ matches (both fields exist in comment)
      • Filter { day: "01", category: "dairy" } → ❌ no match (category doesn’t exist in comment)
  • Partial Match Examples:
    • Comment has { day: "01", week: "01", month: "jan", product: "cheese" }
    • Filter with { day: "01", week: "01", month: "jan", product: "cheese" } → matches (full)
    • Filter with { week: "01", month: "jan", product: "cheese" } → matches (partial)
    • Filter with { day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" } → no match

​
groupMatchedComments

Whether to group multiple comment annotations in Comment Bubble component when multiple annotations match the provided context or targetElementId. Default: false
Using Props:
<VeltComments groupMatchedComments={true} />
Using API:
const commentElement = client.getCommentElement();
commentElement.enableGroupMatchedComments();
commentElement.disableGroupMatchedComments();

​
commentCountType

Whether to show unread or total comment replies count on Comment Bubble Component.
  • total: Shows the total number of replies. (default)
  • unread: Shows the number of unread replies.
<VeltCommentBubble commentCountType={"unread"} />

​
readOnly

The readOnly flag prevents users from replying or editing existing comments in the target bubble while still displaying them. This is useful when you want to display comments in a read-only mode where users can view but not modify or respond to comments. Default: false 
<VeltCommentBubble readOnly={true} />

​
Video Timeline Comments

​
setTotalMediaLength

Set the total length of media (in frames or seconds) for the timeline.
Using Props:
<VeltCommentPlayerTimeline totalMediaLength={120} />
Using API Method:
const commentElement = client.getCommentElement();
commentElement.setTotalMediaLength(120);

​
offset

  • Allows comment bubbles to be positioned relative to both parent and child video clips by specifying an offset value.
  • Default: 0
<VeltCommentPlayerTimeline offset={10} />

​
Comment Pin

​
enableBubbleOnPin

Show a Comment Bubble when user hovers or clicks on the Comment Pin vs showing the Comment Dialog. The comment dialog will open only on clicking the comment bubble. Default: 'false'
Using Props:
<VeltComments bubbleOnPin={true} />
Using API Method:
const commentElement = useCommentUtils();
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();

​
enableBubbleOnPinHover

Show a Comment Bubble when user hovers on the Comment Pin vs clicks on it. Default: 'true'
Using Props:
<VeltComments bubbleOnPin={true} bubbleOnPinHover={false} />
Using API Method:
const commentElement = useCommentUtils();

// To enable/disable showing bubble on pin
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();

// To enable/disable showing bubble on hover
commentElement.enableBubbleOnPinHover();
commentElement.disableBubbleOnPinHover();

​
Legacy Methods

​
onCommentAdd

Using Props:
<VeltComments onCommentAdd={(event) => yourMethod(event)} />

const yourMethod = (event) => {
  event?.addContext({ customKey: 'customValue' });
}
Using Hooks:
import { useCommentAddHandler} from '@veltdev/react';

export default function YourDocument() {

  const commentAddEvent = useCommentAddHandler();

  useEffect(() => {
    console.log('commentAddEvent', commentAddEvent);
  }, [commentAddEvent]);

  return (
    <div></div>
  )
}
Using API:
const commentElement = client.getCommentElement();

commentElement.onCommentAdd().subscribe((event) => {
  console.log('commentAddEvent', event);
});
onCommentAdd Event Data Schema
Field NameTypeDescription
addContextFunctionUse this to set custom data on the comment
annotationCommentAnnotationThe annotation that is associated with the comment that was updated
documentIdstringThe document ID where the comment was added
locationObjectThe location where the comment was added
targetAnnotationIdstringThe id of the target annotation

​
onCommentUpdate

Using Props:
<VeltComments onCommentUpdate={(event) => yourMethod(event)} />

const yourMethod = (event) => {
  console.log('commentUpdateEvent', event);
}
Using Hooks:
import { useCommentUpdateHandler} from '@veltdev/react';

export default function YourDocument() {

  const commentUpdateEvent = useCommentUpdateHandler();
  useEffect(() => {
    console.log('commentUpdateEvent', commentUpdateEvent);
  }, [commentUpdateEvent]);

  return (
    <div></div>
  )
}
Using API:
const commentElement = client.getCommentElement();

commentElement.onCommentUpdate().subscribe((event) => {
  console.log('commentUpdateEvent', event);
});
onCommentUpdate Event Data Schema
Field NameTypeDescription
annotationCommentAnnotationThe annotation that is associated with the comment that was updated
typestringThe type of comment that was updated
targetAnnotationIdstringThe ID of the target annotation that contains the comment that was updated
targetCommentIdnumberThe ID of the target comment that was updated
updateContextFunctionUse this to update the custom metadata on the comment annotation.

​
getAllCommentAnnotations

  • Get all comment annotations for a given document and location.
  • By default, it will return data for the current documentId and location.
  • Params (optional):
    • documentId: string; it will return all comments in the given documentId.
    • location: Object; it will return all comments in the given location.
Using Hooks:
  const commentAnnotations = useCommentAnnotations();
  useEffect(() => {
    if (commentAnnotations) {
      console.log('commentAnnotations', commentAnnotations);
    }
  }, [commentAnnotations]);
Using API:
const commentElement = client.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
  console.log('commentAnnotations', comments);
});
To unsubscribe from the subscription:
subscription?.unsubscribe()