Threads

addCommentAnnotation

Adds a new comment annotation.
Params: AddCommentAnnotationRequest
Returns: AddCommentAnnotationEvent

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

// Using props on VeltComments
<VeltComments commentPlaceholder="Text Comment" replyPlaceholder="Text Reply" />

deleteCommentAnnotation

Deletes a comment annotation
Params: DeleteCommentAnnotationRequest
Returns: DeleteCommentAnnotationEvent

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

Get the currently selected comment annotations.
Returns: CommentAnnotation[].

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
let elementRef = commentElement.getElementRefByAnnotationId('annotationId')

Messages

addComment

Add a comment to a specific comment annotation
Params: AddCommentRequest
Returns: AddCommentEvent

React / Next.js
Other Frameworks

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

Update a comment in a specific comment annotation
Params: UpdateCommentRequest
Returns: UpdateCommentEvent

React / Next.js
Other Frameworks

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

Delete a comment from a specific comment annotation
Params: DeleteCommentRequest
Returns: DeleteCommentEvent

React / Next.js
Other Frameworks

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

Get comments from a specific comment annotation
Params: GetCommentRequest
Returns: Comment[]

React / Next.js
Other Frameworks

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

React / Next.js with Hooks
React / Next.js
Other Frameworks

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

React / Next.js with Hooks
React / Next.js
React / HTML

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

React / Next.js with Hooks
React / Next.js
Other Frameworks

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

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>

React / Next.js
Other Frameworks

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>

React / Next.js
Other Frameworks

const markAsUnreadRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

@Mentions

assignUser

Assigns a user to a comment annotation
Params: AssignUserRequest
Returns: AssignUserEvent

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

Enable the feature

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


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

Set initial list

contactElement.updateContactList(users);

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments showMentionGroupsFirst={true} />

showMentionGroupsOnly

Show only the user groups in the @mentions dropdown menu and not the non-group users.

React / Next.js
Other Frameworks

<VeltComments showMentionGroupsOnly={true} />

subscribeCommentAnnotation

Subscribes to a comment annotation
Params: SubscribeCommentAnnotationRequest
Returns: SubscribeCommentAnnotationEvent

React / Next.js
Other Frameworks

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

Unsubscribes from a comment annotation
Params: UnsubscribeCommentAnnotationRequest
Returns: UnsubscribeCommentAnnotationEvent

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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:

Field	Description
`folderId`	Target folder ID
`documentId`	Target document ID
`locationId`	Target location ID
`targetElementId`	Target DOM element ID
`context`	Custom 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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltCommentBubble
  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" }.

React / Next.js
Other Frameworks

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

React / Next.js with hooks
React / Next.js
Other Frameworks

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

React / Next.js with Hooks
React / Next.js
Other Frameworks

// 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>' } }
  ]
};

React / Next.js with Hooks
React / Next.js
Other Frameworks

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

React / Next.js with Hooks
React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

Enable the feature

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


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

Set initial list

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

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

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.

Category	Event Type	Description	Event Object
Threads	`addCommentAnnotation`	Add a new comment annotation	AddCommentAnnotationEvent
Threads	`deleteCommentAnnotation`	Delete a comment annotation	DeleteCommentAnnotationEvent
Messages	`addComment`	Add a new comment	AddCommentEvent
Messages	`updateComment`	Update an existing comment	UpdateCommentEvent
Messages	`deleteComment`	Delete a comment	DeleteCommentEvent
@Mentions	`assignUser`	Assign a user to a comment	AssignUserEvent
@Mentions	`subscribeCommentAnnotation`	Subscribe to a comment annotation	SubscribeCommentAnnotationEvent
@Mentions	`unsubscribeCommentAnnotation`	Unsubscribe from a comment annotation	UnsubscribeCommentAnnotationEvent
@Mentions	`autocompleteSearch`	When user starts searching for a contact in the @mentions dropdown or for a list item in the custom list dropdown	AutocompleteSearchEvent
Attachments	`addAttachment`	Add an attachment to a comment	AddAttachmentEvent
Attachments	`deleteAttachment`	Delete an attachment from a comment	DeleteAttachmentEvent
Reactions	`addReaction`	Add a reaction to a comment	AddReactionEvent
Reactions	`deleteReaction`	Delete a reaction from a comment	DeleteReactionEvent
Reactions	`toggleReaction`	Toggle a reaction on a comment	ToggleReactionEvent
Status & Priority	`updateStatus`	Update the status of a comment	UpdateStatusEvent
Status & Priority	`resolveComment`	Resolve a comment	ResolveCommentEvent
Status & Priority	`updatePriority`	Update the priority of a comment	UpdatePriorityEvent
Status & Priority	`approveCommentAnnotation`	Approve a comment annotation	ApproveCommentAnnotationEvent
Status & Priority	`acceptCommentAnnotation`	Accept a comment annotation	AcceptCommentAnnotationEvent
Status & Priority	`rejectCommentAnnotation`	Reject a comment annotation	RejectCommentAnnotationEvent
Recordings	`deleteRecording`	Delete a recording from a comment	DeleteRecordingEvent
Deep Links	`copyLink`	Copy a deep link to a comment	CopyLinkEvent
Access	`updateAccess`	Update access settings for a comment	UpdateAccessEvent
Comment Sidebar	`commentSidebarDataInit`	Triggered when comment sidebar data is first loaded	CommentSidebarDataInitEvent
Comment Sidebar	`commentSidebarDataUpdate`	Triggered when comment sidebar data is updated	CommentSidebarDataUpdateEvent
UI	`composerClicked`	Triggered when comment composer is clicked	ComposerClickedEvent
UI	`linkClicked`	Triggered when a clickable link in comment content is clicked	LinkClickedEvent
Recorder	`transcriptionDone`	Triggered when a transcription is generated and ready	TranscriptionDoneEvent

React / Next.js
Other Frameworks

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

Link Callback for Clickable Links

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.

React / Next.js
Other Frameworks

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

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.

React / Next.js
Other Frameworks

<VeltComments attachments={true} />

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

addAttachment

Add an attachment to a specific comment annotation
Params: AddAttachmentRequest
Returns: Promise<AddAttachmentResponse[]>

React / Next.js
Other Frameworks

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

Delete an attachment from a specific comment annotation
Params: DeleteAttachmentConfig
Returns: Promise<DeleteAttachmentEvent | null>

React / Next.js
Other Frameworks

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

Get attachments from a specific comment annotation
Params: GetAttachmentRequest
Returns: Promise<Attachment[]>

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

Add a reaction to a specific comment annotation
Params: AddReactionRequest
Returns: Promise<AddReactionEvent | null>

React / Next.js
Other Frameworks

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

Delete a reaction from a specific comment annotation
Params: DeleteReactionRequest
Returns: Promise<DeleteReactionEvent | null>

React / Next.js
Other Frameworks

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

Toggle a reaction for a specific comment annotation
Params: ToggleReactionRequest
Returns: Promise<ToggleReactionEvent | null>

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments status={true} />

API Method:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments resolveButton={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableResolveButton();
commentElement.disableResolveButton();

updateStatus

Updates the status of a comment annotation.
Params: UpdateStatusRequest
Returns: UpdateStatusEvent

React / Next.js
Other Frameworks

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

Resolves a comment annotation
Params: ResolveCommentAnnotationRequest
Returns: ResolveCommentAnnotationEvent

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments priority={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enablePriority();
commentElement.disablePriority();

setCustomPriority

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.setCustomPriority([
  {
    "id": "low",
    "name": "Low",
    "color": "red",
    "lightColor": "pink",
  },
])

Make sure to have at least 2 categories set.

updatePriority

Updates the priority of a comment annotation
Params: UpdatePriorityRequest
Returns: UpdatePriorityEvent

React / Next.js
Other Frameworks

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

Delete a recording from a specific comment annotation
Params: DeleteRecordingRequest
Returns: Promise<DeleteRecordingEvent | null>

React / Next.js
Other Frameworks

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

Get recordings from a specific comment annotation
Params: GetRecordingRequest
Returns: Promise<RecordedData[]>

React / Next.js
Other Frameworks

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"

React / Next.js
Tab Title
Other Frameworks

<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

React / Next.js
Other Frameworks

<VeltComments recordingCountdown={false} />

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

enableRecordingTranscription

Controls whether to enable AI transcription for recordings. Default: enabled

React / Next.js
Other Frameworks

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

getLink

Get a link to a specific comment annotation
Params: GetLinkRequest
Returns: GetLinkResponse

React / Next.js
Other Frameworks

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

copyLink

Copy a link to a specific comment annotation to clipboard
Params: CopyLinkRequest
Returns: CopyLinkEvent

React / Next.js
Other Frameworks

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

scrollToCommentByAnnotationId

This will scroll the page to the element directly. This will work if the element is present on the DOM.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.selectCommentByAnnotationId("COMMENT_ANNOTATION_ID");

onCommentSelectionChange

React / Next.js with Hooks
React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

To disable the feature, set scrollToComment to false.

<VeltComments scrollToComment={false}/>

API methods:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments autoCategorize={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableAutoCategorize();
commentElement.disableAutoCategorize();

setCustomCategory

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

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"

React / Next.js
Other Frameworks

<VeltComments composerMode="expanded"/>

commentToNearestAllowedElement

Attach comment pins to the closest allowed element when clicking on a non-allowed element. Default: false

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

<VeltComments deleteThreadWithFirstComment={false} />

draftMode

Whether to store comments in draft if they are not submitted. Default: true

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments signInButton={true} />

API Method:

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments mobileMode={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableMobileMode();
commentElement.disableMobileMode();

enableCommentPinHighlighter

Wheter the pin highlighter outline is enabled or not. Default: true

React / Next.js
Other Frameworks

<VeltComments commentPinHighlighter={false} />

API Methods:

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments dialogOnHover={true} />

API Method:

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments floatingCommentDialog={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableFloatingCommentDialog();
commentElement.disableFloatingCommentDialog();

excludeLocationIds

Use this to filter out Comments at a specific Location for certain Users.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
HTML

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.

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

{/* `true` to show comments, `false` to hide comments */}
<VeltComments commentsOnDom={false} />

Using API methods:

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments resolvedCommentsOnDom={true} />

API Methods:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments commentIndex={true} />

API Method:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments deviceInfo={true} />

API Method:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments deviceIndicatorOnCommentPins={true} />

API Method:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments moderatorMode={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableModeratorMode();
commentElement.disableModeratorMode();

enableResolveStatusAccessAdminOnly

Restrict the resolve action to admin users and the comment author only.

React / Next.js
Other Frameworks

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

Approves a comment annotation in moderator mode
Params: ApproveCommentAnnotationRequest
Returns: ApproveCommentAnnotationEvent

React / Next.js
Other Frameworks

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

Accepts a comment annotation in suggestion mode
Params: AcceptCommentAnnotationRequest
Returns: AcceptCommentAnnotationEvent

React / Next.js
Other Frameworks

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

Rejects a comment annotation in suggestion mode
Params: RejectCommentAnnotationRequest
Returns: RejectCommentAnnotationEvent

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

To accept comments, set the suggestionMode attribute to true.

<VeltComments suggestionMode={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableSuggestionMode();
commentElement.disableSuggestionMode();

updateAccess

Updates access permissions for a comment annotation
Params: UpdateAccessRequest
Returns: UpdateAccessEvent

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

To enable private comment mode, set the privateCommentMode attribute to true:

<VeltComments privateCommentMode={true} />

API Methods: API to enable/disable private comment mode:

React / Next.js
Other Frameworks

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

React / Next.JS
Other Frameworks

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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<VeltComments unreadIndicatorMode={"verbose"} />

API Method:

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
HTML

// 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 programatically turn on the commenting mode.

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableCommentMode();
commentElement.disableCommentMode();

onCommentModeChange

The comment mode is toggled on and off when you click on the Comment Tool.

React / Next.js with Hooks
React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<VeltComments pinCursorImage={BASE64_IMAGE_STRING} />

API Methods:

React / Next.js
Other Frameworks

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:

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

  <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

React / Next.js
Other Frameworks

<VeltInlineCommentsSection multiThread={false} />

composerPosition

Change the position of the comment composer in the inline comments section to top or bottom.
Default: bottom

React / Next.js
Other Frameworks

<VeltInlineCommentsSection composerPosition="top" />

enableDialogOnTargetElementClick

Whether the comment dialog opens when target element is clicked. This is relevant only for Popover mode. Default: true

React / Next.js
Other Frameworks

<VeltComments dialogOnTargetElementClick={true} />

API Method:

React / Next.js
Other Frameworks

const commentElement = client.getCommentElement();
commentElement.enableDialogOnTargetElementClick();
commentElement.disableDialogOnTargetElementClick();

enablePopoverTriangleComponent

Whether the popover triangle appears when Popover Mode is enabled. Default: true

React / Next.js
Other Frameworks

<VeltComments popoverTriangleComponent={true}/>

API Method:

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

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.

React / Next.js
Other Frameworks

<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

React / Next.js
Other Frameworks

<VeltCommentBubble readOnly={true} />

Video Timeline Comments

setTotalMediaLength

Set the total length of media (in frames or seconds) for the timeline.

React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

<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'

React / Next.js with Hooks
React / Next.js
Other Frameworks

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'

React / Next.js with Hooks
React / Next.js
Other Frameworks

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

React / Next.js
Other Frameworks

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 Name	Type	Description
addContext	Function	Use this to set custom data on the comment
annotation	CommentAnnotation	The annotation that is associated with the comment that was updated
documentId	string	The document ID where the comment was added
location	Object	The location where the comment was added
targetAnnotationId	string	The id of the target annotation

onCommentUpdate

React / Next.js
Other Frameworks

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 Name	Type	Description
annotation	CommentAnnotation	The annotation that is associated with the comment that was updated
type	string	The type of comment that was updated
targetAnnotationId	string	The ID of the target annotation that contains the comment that was updated
targetCommentId	number	The ID of the target comment that was updated
updateContext	Function	Use 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.

React / Next.js
Other Frameworks

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

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

​Threads

​addCommentAnnotation

​addCommentOnSelectedText

​addCommentOnElement

​addManualComment

​Comment and Reply Placeholders

​deleteCommentAnnotation

​deleteSelectedComment

​getCommentAnnotationsCount

​getUnreadCommentAnnotationCountByLocationId

​getCommentAnnotations

​fetchCommentAnnotations

​getSelectedComments

​getCommentAnnotationById

​getElementRefByAnnotationId

​Messages

​addComment

​updateComment

​deleteComment

​getComment

​getUnreadCommentCountOnCurrentDocument

​getUnreadCommentCountByLocationId

​getUnreadCommentCountByAnnotationId

​markAsRead

​markAsUnread

​@Mentions

​assignUser

​customAutocompleteSearch

​enableAtHere

​enableUserMentions

​expandMentionGroups

​getContactList

​onContactSelected

​setAtHereLabel

​setAtHereDescription

​showMentionGroupsFirst

​showMentionGroupsOnly

​subscribeCommentAnnotation

​unsubscribeCommentAnnotation

​updateContactList

​updateContactListScopeForOrganizationUsers

​Metadata

​addContext

​updateContext

​Aggregation

​Overview

​When to Use Aggregation

​🧩 Tables & Dashboards

​How It Works

​Comment Metadata Fields

​Comment Creation

​Comment Rendering

​Filtering Behavior

​Context Matching

​🔒 Full Match (Default)

​🔍 Partial Match

​Grouping Matched Comment Annotations

​Custom Lists

​createCustomListDataOnAnnotation

​createCustomListDataOnComment

Flat List Implementation

Grouped List Implementation

Listen to click events on chips

​customAutocompleteSearch

​Event Subscription

​on

​Link Callback for Clickable Links

​Attachments

​enableAttachments

​addAttachment

​deleteAttachment

Threads

addCommentAnnotation

addCommentOnSelectedText

addCommentOnElement

addManualComment

Comment and Reply Placeholders

deleteCommentAnnotation

deleteSelectedComment

getCommentAnnotationsCount

getUnreadCommentAnnotationCountByLocationId

getCommentAnnotations

fetchCommentAnnotations

getSelectedComments

getCommentAnnotationById

getElementRefByAnnotationId

Messages

addComment

updateComment

deleteComment

getComment

getUnreadCommentCountOnCurrentDocument

getUnreadCommentCountByLocationId

getUnreadCommentCountByAnnotationId

markAsRead

markAsUnread

@Mentions

assignUser

customAutocompleteSearch

enableAtHere

enableUserMentions

expandMentionGroups

getContactList

onContactSelected

setAtHereLabel

setAtHereDescription

showMentionGroupsFirst

showMentionGroupsOnly

subscribeCommentAnnotation

unsubscribeCommentAnnotation

updateContactList

updateContactListScopeForOrganizationUsers

Metadata

addContext

updateContext

Aggregation

Overview

When to Use Aggregation

🧩 Tables & Dashboards

How It Works

Comment Metadata Fields

Comment Creation

Comment Rendering

Filtering Behavior

`Context` Matching

🔒 Full Match (Default)

🔍 Partial Match

Grouping Matched Comment Annotations

Custom Lists

createCustomListDataOnAnnotation

createCustomListDataOnComment

customAutocompleteSearch

Event Subscription

on

Link Callback for Clickable Links

Attachments

enableAttachments

addAttachment

deleteAttachment

getAttachment

allowedFileTypes

attachmentNameInMessage

setComposerFileAttachments

Reactions

enableReactions

setCustomReactions

addReaction

deleteReaction

toggleReaction

Status & Priority

enableStatus