​
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:


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);

​
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 for all the specified documents.
  • If you don’t specify any query, it will return data from the documents specified in the setDocuments method.
  • You can specify 30 documents at a time.
  • Params: (optional) CommentRequestQuery
  • Returns: GetCommentAnnotationsCountResponse

Avaiable on SDK version 4.0.0 and above.

Using Hooks:

const { data } = useCommentAnnotationsCount(query);

useEffect(() => {
  if (data) {
    // initial data value will be null while the request is in progress
    console.log("Comment Annotations Count:", data);
  }
}, [data]);

Using API:

const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount(query).subscribe((response) => {
  // initial data value will be null while the request is in progress
  console.log("Comment Annotations Count:", 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')

​
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 = {
    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: 'user1@velt.dev'}], {merge: false});
}, [contactElement]);

Using API:

const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {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);

​
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.

1

Set hotkey and list data

Make sure the hotkey is a single character such as # or /
  • Create the list of data will be shown when the hotkey is pressed. Eg: When the user presses #, the list of files or links from other parts of your app is shown.
  • The items in the list must be in the following schema:
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 }; // Item icon. This appears as the icon in the UI.
    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.
}

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} />

API Method:

const commentElement = useCommentUtils();		
commentElement.createCustomListDataOnComment(customListDataOnComment);
2

Listen to click event data 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
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();

​
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);

​
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, P2

With 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 programatically select a comment annotation by its id.
  • Example: If the user opens a comment url from an email notification, you can use this open the comment dialog after your page has finished rendering.
const commentElement = client.getCommentElement();
commentElement.selectCommentByAnnotationId("COMMENT_ANNOTATION_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()} />

​
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.

​
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();

​
enableInboxMode

For a complete setup guide for Inbox mode, read here.

Whether Inbox Mode is enabled.

Default: false

Using Props:

<VeltComments inboxMode={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableInboxMode();
commentElement.disableInboxMode();

​
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 targetElementId="elementId" 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 programatically 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();

​
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();

​
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.
<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

​
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"} />

​
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();

​
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()