Customize Behavior

Threads

addCommentAnnotation

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.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

const commentElement = client.getCommentElement();
// to add comment on selected text
commentElement.addCommentOnSelectedText();

Other Frameworks

const commentElement = Velt.getCommentElement();
// to add comment on selected text
commentElement.addCommentOnSelectedText();

addCommentOnElement

Adds a Comment on a specific element by ID.

To add a comment on a specific element through an API method, use the addCommentOnElement() method and pass in an object with the schema shows in the example:

Example 1: Add comment with targetElementId only:

React / Next.js

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

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

const context = {
  position: {x: 200, y: 100},
};
const commentElement = client.getCommentElement();
const config: ManualCommentAnnotationConfig = {
	context: context, // your context here
};
commentElement.addManualComment(config);

Other Frameworks

const context = {
  position: {x: 200, y: 100},
};
const commentElement = Velt.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

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

Other Frameworks

<velt-comments comment-placeholder="test comment placeholder" reply-placeholder="test reply placeholder"></velt-comments>

To customize placeholder text shown when editing an existing comment or reply, use editPlaceholder, editCommentPlaceholder, and editReplyPlaceholder. See VeltCommentsProps for details.

deleteCommentAnnotation

• Deletes a comment annotation
• Params: DeleteCommentAnnotationRequest
• Returns: DeleteCommentAnnotationEvent

React / Next.js

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

Other Frameworks

const deleteCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const deleteCommentAnnotationEvent = await commentElement.deleteCommentAnnotation(deleteCommentAnnotationRequest);

deleteSelectedComment

To delete a comment using an API method, use the deleteSelectedComment() method.

React / Next.js

if (client) {
  const commentElement = client.getCommentElement();
  commentElement.deleteSelectedComment();
}

Other Frameworks

if (Velt) {
  const commentElement = Velt.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 also use this api without setting the document.
• Auto-batching: When 2+ documentIds are provided, requests are automatically batched to reduce persistence listeners. Use debounceMs to control batching delay (default: 5000ms).
• Params: (optional) CommentRequestQuery
  • 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.
  • Set batchedPerDocument to true if you want to display comment count for a large number of documents (e.g., 100 documents) on the same page. This is now automatically enabled when 2+ documentIds are provided.
  • Refer to CommentRequestQuery for more parameters you can use.
• Returns: GetCommentAnnotationsCountResponse

React / Next.js

Organization Level

const { data } = useCommentAnnotationsCount({ organizationId: 'org1' });

useEffect(() => {
if (data) {
console.log('Comment annotations count for org1:', data);
}
}, [data]);

const { data } = useCommentAnnotationsCount({
  organizationId: 'org1',
  folderId: 'folder2',
  allDocuments: true
});

useEffect(() => {
  if (data) {
    console.log('Comment annotations count for folder2:', data);
  }
}, [data]);

const { data } = useCommentAnnotationsCount();

useEffect(() => {
  if (data) {
    console.log("Comment annotations count:", data);
  }
}, [data]);

const { data } = useCommentAnnotationsCount({
  documentIds: ["doc1", "doc2", "doc3"],
});

useEffect(() => {
  if (data) {
    // Auto-batching reduces listeners from 3 to 1 for this example
    console.log("Comment annotations count for multiple documents:", data);
  }
}, [data]);

const { data } = useCommentAnnotationsCount({ aggregateDocuments: true });

useEffect(() => {
  if (data) {
    console.log("Aggregated comment annotations count:", data);
  }
}, [data]);

const { data } = useCommentAnnotationsCount({
  documentIds: ["doc1", "doc2", "doc3"],
  aggregateDocuments: true,
});

useEffect(() => {
  if (data) {
    // Auto-batching reduces listeners from 3 to 1 for this example
    console.log(
      "Aggregated comment annotations count for multiple documents:",
      data,
    );
  }
}, [data]);

const { data } = useCommentAnnotationsCount({ filterGhostComments: true });

useEffect(() => {
  if (data) {
    console.log("Filtered comment annotations count:", data);
  }
}, [data]);

const { data } = useCommentAnnotationsCount({
  documentIds: ["doc1", "doc2", "doc3"],
  debounceMs: 3000, // customize debounce (default is 5000ms)
});

useEffect(() => {
  if (data) {
    // Auto-batching reduces listeners from 3 to 1 for this example
    // Custom debounce triggers updates faster (3s instead of default 5s)
    console.log("Comment annotations count with custom debounce:", data);
  }
}, [data]);

Using API:

Organization Level

const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((response) => {
  console.log('getCommentAnnotationsCount with organizationId', response.data);
});

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    organizationId: "org1",
    folderId: "folder2",
    allDocuments: true,
  })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with organizationId and folderId and allDocuments",
      response.data,
    );
  });

const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount().subscribe((response) => {
  console.log("getCommentAnnotationsCount", response.data);
});

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    documentIds: ["doc1", "doc2", "doc3"],
  })
  .subscribe((response) => {
    // Auto-batching reduces listeners from 3 to 1 for this example
    console.log(
      "getCommentAnnotationsCount for multiple documents",
      response.data,
    );
  });

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({ aggregateDocuments: true })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with aggregateDocuments",
      response.data,
    );
  });

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    documentIds: ["doc1", "doc2", "doc3"],
    aggregateDocuments: true,
  })
  .subscribe((response) => {
    // Auto-batching reduces listeners from 3 to 1 for this example
    console.log(
      "getCommentAnnotationsCount for aggregated multiple documents",
      response.data,
    );
  });

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({ filterGhostComments: true })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with filterGhostComments",
      response.data,
    );
  });

const commentElement = client.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    documentIds: ["doc1", "doc2", "doc3"],
    debounceMs: 3000, // customize debounce (default is 5000ms)
  })
  .subscribe((response) => {
    // Auto-batching reduces listeners from 3 to 1 for this example
    // Custom debounce triggers updates faster (3s instead of default 5s)
    console.log(
      "Comment annotations count with custom debounce:",
      response.data,
    );
  });

Other Frameworks

Organization Level

const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((response) => {
  console.log('getCommentAnnotationsCount with organizationId', response.data);
});

const commentElement = Velt.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    organizationId: "org1",
    folderId: "folder2",
    allDocuments: true,
  })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with organizationId and folderId and allDocuments",
      response.data,
    );
  });

const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount().subscribe((response) => {
  console.log("getCommentAnnotationsCount", response.data);
});

const commentElement = Velt.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    documentIds: ["doc1", "doc2", "doc3"],
  })
  .subscribe((response) => {
    // Auto-batching reduces listeners from 3 to 1 for this example
    console.log(
      "getCommentAnnotationsCount for multiple documents",
      response.data,
    );
  });

const commentElement = Velt.getCommentElement();
commentElement
  .getCommentAnnotationsCount({ aggregateDocuments: true })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with aggregateDocuments",
      response.data,
    );
  });

const commentElement = Velt.getCommentElement();
commentElement
  .getCommentAnnotationsCount({ filterGhostComments: true })
  .subscribe((response) => {
    console.log(
      "getCommentAnnotationsCount with filterGhostComments",
      response.data,
    );
  });

const commentElement = Velt.getCommentElement();
commentElement
  .getCommentAnnotationsCount({
    documentIds: ["doc1", "doc2", "doc3"],
    debounceMs: 3000, // customize debounce (default is 5000ms)
  })
  .subscribe((response) => {
    // Auto-batching reduces listeners from 3 to 1 for this example
    // Custom debounce triggers updates faster (3s instead of default 5s)
    console.log(
      "Comment annotations count with custom debounce:",
      response.data,
    );
  });

getUnreadCommentAnnotationCountByLocationId

• Get the number of CommentAnnotations with at least 1 unread Comment by Location Id.

React / Next.js

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

Other Frameworks

if (Velt) {
  const commentElement = Velt.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

Available on SDK version 4.0.0 and above.

React / Next.js

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

Other Frameworks

Using API:

const commentElement = Velt.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

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

Other Frameworks

// Get all annotations for a specific folder
const commentElement = Velt.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

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

Other Frameworks

const commentElement = Velt.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

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

Other Frameworks

Using API:

const commentElement = Velt.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

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

Other Frameworks

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

submitComment

Programmatically submit a comment from a composer. Enables custom buttons or keyboard shortcuts for submitting comments. The composer must have a targetComposerElementId set for this method to work.

• Params: SubmitCommentRequest
• Returns: void
• See also: Comment Composer targetComposerElementId

React / Next.js

<VeltCommentComposer targetComposerElementId="composer-1" />
<VeltCommentDialogComposer targetComposerElementId="composer-2" />

// Using hook
const commentElement = useCommentUtils();
commentElement.submitComment({ targetComposerElementId: 'composer-1' });

// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.submitComment({ targetComposerElementId: 'composer-1' });

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.submitComment({ targetComposerElementId: 'composer-1' });

clearComposer

Reset composer state including text, attachments, recordings, tagged users, assignments, and custom lists.

• Params: ClearComposerRequest
• Returns: void

React / Next.js

// Hook
const commentElement = useCommentUtils();
commentElement.clearComposer({ targetComposerElementId: "composer-1" });

// API Method
const commentElement = client.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: "composer-1" });

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: 'composer-1' });

getComposerData

Fetch current composer state on-demand. Returns same data structure as composerTextChange event.

• Params: GetComposerDataRequest
• Returns: ComposerTextChangeEvent

React / Next.js

// Hook
const commentElement = useCommentUtils();
const composerData = commentElement.getComposerData({
  targetComposerElementId: "composer-1",
});

// API Method
const commentElement = client.getCommentElement();
const composerData = commentElement.getComposerData({
  targetComposerElementId: "composer-1",
});

Other Frameworks

const commentElement = Velt.getCommentElement();
const composerData = commentElement.getComposerData({
  targetComposerElementId: 'composer-1'
});

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

const markAsReadRequest = {
  annotationId: "ANNOTATION_ID",
};

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

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

Other Frameworks

const markAsReadRequest = {
  annotationId: "ANNOTATION_ID",
};

const commentElement = Velt.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

const markAsUnreadRequest = {
  annotationId: "ANNOTATION_ID",
};

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

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

Other Frameworks

const markAsUnreadRequest = {
  annotationId: "ANNOTATION_ID",
};

const commentElement = Velt.getCommentElement();
await commentElement.markAsUnread(markAsUnreadRequest);

Messages

addComment

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

React / Next.js

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

Other Frameworks

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

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

const commentElement = Velt.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);

updateComment

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

React / Next.js

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

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

const commentElement = Velt.getCommentElement();
const updateCommentEvent = await commentElement.updateComment(updateCommentRequest);

deleteComment

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const deleteCommentEvent = await commentElement.deleteComment(deleteCommentRequest);

getComment

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

React / Next.js

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

Other Frameworks

const getCommentRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const comments = await commentElement.getComment(getCommentRequest);

getUnreadCommentCountOnCurrentDocument

React / Next.js with Hooks

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

React / Next.js

You can get the number of unread Comments on the current Document by using the getUnreadCommentCountOnCurrentDocument() method:

if (client) {
  const commentElement = client.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountOnCurrentDocument()
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

Other Frameworks

You can get the number of unread Comments on the current Document by using the getUnreadCommentCountOnCurrentDocument() method:

if (Velt) {
  const commentElement = Velt.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountOnCurrentDocument()
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

getUnreadCommentCountByLocationId

React / Next.js with Hooks

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

React / Next.js

You can get the number of unread Comments by Location Id by using the getUnreadCommentCountByLocationId() method:

if (client) {
  const commentElement = client.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountByLocationId(locationId)
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

React / HTML

You can get the number of unread Comments by Location Id by using the getUnreadCommentCountByLocationId() method:

if (Velt) {
  const commentElement = Velt.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountByLocationId(locationId)
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

getUnreadCommentCountByAnnotationId

React / Next.js with Hooks

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

React / Next.js

You can get the number of unread Comments by annotation id by subscribing to the getUnreadCommentCountByAnnotationId() method:

if (client) {
  const commentElement = client.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountByAnnotationId(annotationId)
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

Other Frameworks

You can get the number of unread Comments by annotation id by subscribing to the getUnreadCommentCountByAnnotationId() method:

if (Velt) {
  const commentElement = Velt.getCommentElement();
  let subscription = commentElement
    .getUnreadCommentCountByAnnotationId(annotationId)
    .subscribe((countObj) => {
      console.log(countObj);
    });
}

To unsubscribe from the subscription:

subscription?.unsubscribe();

@Mentions

assignUser

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const assignUserEventData = await commentElement.assignUser(assignUserRequest);

setAssignToType

Configure the assign-to UI mode as dropdown or checkbox.

API Method: setAssignToType()

• Params: AssignToConfig
• Returns: void

React / Next.js

// Using props
<VeltComments assignToType="checkbox" />

// Using API methods
const commentElement = useCommentUtils();
commentElement.setAssignToType({ type: 'checkbox' }); // or 'dropdown'

// Using API methods with client
const commentElement = client.getCommentElement();
commentElement.setAssignToType({ type: 'checkbox' }); // or 'dropdown'

Other Frameworks

<velt-comments assign-to-type="checkbox"></velt-comments>

<script>
const commentElement = Velt.getCommentElement();
commentElement.setAssignToType({ type: 'checkbox' }); // or 'dropdown'
</script>

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

1. Enable the feature

   // Enable via props
   <VeltComments customAutocompleteSearch={true} />
   
   // Or, enable via Comment Element API
   const commentElement = client.getCommentElement();
   commentElement.enableCustomAutocompleteSearch();
   commentElement.disableCustomAutocompleteSearch();
   
   
2. Set initial list

   contactElement.updateContactList(users);
   
3. Handle search event

   commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
       const searchText = inputData.searchText;
   
       if (inputData.type === 'contact') {
           const filteredUsersData = await __your_api_call__(searchText);
           contactElement.updateContactList(filteredUsersData, { merge: false });
       }
   
   });
   
   

Other Frameworks

1. Enable the feature

   // Enable via attribute
   <velt-comments custom-autocomplete-search="true"></velt-comments>
   
   // Or, enable via Comment Element API
   const commentElement = Velt.getCommentElement();
   commentElement.enableCustomAutocompleteSearch();
   commentElement.disableCustomAutocompleteSearch();
   
2. Set initial list

   contactElement.updateContactList(users);
   
3. Handle search event

   commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
       const searchText = inputData.searchText;
   
       if (inputData.type === 'contact') {
           const filteredUsersData = await __your_api_call__(searchText);
           contactElement.updateContactList(filteredUsersData, { merge: false });
       }
   
   });
   
   

enableAtHere

• This allows you to notify all the users explicitly added to the current document.
• It won’t notify users in the organization who are not explicitly added to the document.

Default: Disabled.

React / Next.js

Hooks:

const contactElement = useContactUtils();

useEffect(() => {
  contactElement.enableAtHere();
  contactElement.disableAtHere();
}, [contactElement]);

API:

const contactElement = client.getContactElement();
contactElement.enableAtHere();
contactElement.disableAtHere();

Other Frameworks

const contactElement = Velt.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

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

Other Frameworks

Using props:

<velt-comments user-mentions="false"></velt-comments>

Using API Method:

const commentElement = Velt.getCommentElement();
commentElement.enableUserMentions(); // to enable user mentions
commentElement.disableUserMentions(); // to disable user mentions

enablePaginatedContactList

• Limits users downloaded for customers with thousands of users.
• Performance optimization that reduces initial download.

Default: false

React / Next.js

Using Props:

<VeltComments paginatedContactList={true} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enablePaginatedContactList();
commentElement.disablePaginatedContactList();

Other Frameworks

Using HTML Attribute:

<velt-comments paginated-contact-list="true"></velt-comments>

Using API Method:

const commentElement = Velt.getCommentElement();
commentElement.enablePaginatedContactList();
commentElement.disablePaginatedContactList();

anonymousEmail

• Controls whether unrecognized email addresses (not in the contact list) are resolved in the @mention flow.
• When disabled:
  • Freeform email addresses entered in the composer are ignored: they won’t show up in @mention suggestions, won’t be added to taggedUserContacts, and won’t be converted to contacts. However, known contacts (users matched from your contact list by email) will always appear, no matter this setting.
  • Notifications will not be sent to anonymous (unrecognized) email addresses.

Default: true

React / Next.js

Using Props:

<VeltComments anonymousEmail={false} />
<VeltInlineCommentsSection anonymousEmail={false} />
<VeltCommentDialog anonymousEmail={false} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableAnonymousEmail();
commentElement.disableAnonymousEmail();

Other Frameworks

Using HTML Attribute:

<velt-comments anonymous-email="false"></velt-comments>
<velt-inline-comments-section target-element-id="article-body" anonymous-email="false"></velt-inline-comments-section>
<velt-comment-dialog anonymous-email="false"></velt-comment-dialog>

Using API Method:

const commentElement = Velt.getCommentElement();
commentElement.enableAnonymousEmail();
commentElement.disableAnonymousEmail();

expandMentionGroups

• Expand the user groups and show individual users inside the groups in the @mentions dropdown menu.

React / Next.js

<VeltComments expandMentionGroups={true} />

Other Frameworks

<velt-comments expand-mention-groups="true"></velt-comments>

Mention Span CSS Classes

• When a user selects an @mention from the autocomplete dropdown, the inserted <span> element receives CSS classes that indicate the mention type.
• velt-mention is always present on every mention span.
• velt-mention--name is added when the mention is a user name.
• velt-mention--email is added when the mention is an email address.

Use these classes to apply distinct visual treatments to name vs. email mentions in the composer:

.velt-mention {
  font-weight: 600;
}
.velt-mention--name {
  color: #1a73e8;
}
.velt-mention--email {
  color: #7c3aed;
}

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

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

Other Frameworks

const contactElement = Velt.getContactElement();
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

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

Other Frameworks

const contactElement = Velt.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

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

Other Frameworks

Using Props:

<velt-comments at-here-label="@all">

Using API Method:

const contactElement = Velt.getContactElement();
contactElement.setAtHereLabel("@all");

setAtHereDescription

• Customize the description that appears for the @here mention.

React / Next.js

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

Other Frameworks

Using Props:

<velt-comments
  at-here-description="Notify all users in this document"
></velt-comments>

Using API Method:

const contactElement = Velt.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

<VeltComments showMentionGroupsFirst={true} />

Other Frameworks

<velt-comments show-mention-groups-first="true"></velt-comments>

showMentionGroupsOnly

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

React / Next.js

<VeltComments showMentionGroupsOnly={true} />

Other Frameworks

<velt-comments show-mention-groups-only="true"></velt-comments>

subscribeCommentAnnotation

• Subscribes to a comment annotation
• Params: SubscribeCommentAnnotationRequest
• Returns: SubscribeCommentAnnotationEvent

React / Next.js

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

Other Frameworks

const subscribeCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const subscribeCommentAnnotationEvent = await commentElement.subscribeCommentAnnotation(subscribeCommentAnnotationRequest);

unsubscribeCommentAnnotation

• Unsubscribes from a comment annotation
• Params: UnsubscribeCommentAnnotationRequest
• Returns: UnsubscribeCommentAnnotationEvent

React / Next.js

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

Other Frameworks

const unsubscribeCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.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}.
• When filters: true is passed, the sidebar People, Assigned, Tagged, and Involved filters are restricted to the custom contact list plus the current user.
• This method will only update the contact list in the current user session. It doesn’t update the user contacts in the database or change the access control.

React / Next.js

Using Hooks:

const contactElement = useContactUtils();

useEffect(() => {
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: '[e-mail]'}], {merge: false});
}, [contactElement]);

Using API:

const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: '[e-mail]'}], {merge: false});

Restrict sidebar filters to the contact list:

contactElement.updateContactList(contacts, { filters: true });

Other Frameworks

const contactElement = Velt.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: '[e-mail]'}], {merge: false});

Restrict sidebar filters to the contact list:

contactElement.updateContactList(contacts, { filters: true });

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

const contactElement = client.getContactElement();
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);

Other Frameworks

const contactElement = Velt.getContactElement();
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);

setAnonymousUserDataProvider

Register a provider to resolve email → userId mappings for users who are tagged by email in comments but are not part of the contact list. When a comment is saved and a tagged contact or to recipient has an email but no userId, the SDK calls the provider to look up the userId and backfills it into the comment data before persisting.

Full implementation guide →

autoCompleteScrollConfig

Customize virtual scroll behavior in autocomplete dropdown for @mentions.

Type: AutoCompleteScrollConfig

React / Next.js

<VeltComments
  autoCompleteScrollConfig={{
    itemSize: 28,
    minBufferPx: 100,
    maxBufferPx: 200,
    templateCacheSize: 20,
  }}
/>

Other Frameworks

<velt-comments
  autocomplete-scrollconfig='{
"itemSize": 28,
"minBufferPx": 100,
"maxBufferPx": 200,
"templateCacheSize": 20
}'
></velt-comments>

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 one of the following events which has the addContext method. This method accepts an object with key-value pairs.

• addCommentAnnotationDraft
• addCommentAnnotation

Alternatively, you can pass context as a prop to most components that helps with creating new comment annotations. Eg:

• VeltCommentTool
• VeltCommentComposer
• VeltCommentDialogComposer
• VeltInlineCommentsSection

React / Next.js

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

Other Frameworks

const commentElement = Velt.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

Using API:

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

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

Other Frameworks

Using API method:

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

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

setContextProvider

Provide custom context (metadata) dynamically for comments using a provider function. This method allows you to return context based on the document and location where a comment is being added. The SDK will call this function whenever a new comment annotation is created so you can provide dynamic values for the context.

The provider function receives documentId and optional location parameters and can return a CommentContext object, null, undefined, or a Promise resolving to any of these values.

React / Next.js

// Hook
import { useCallback, useEffect } from 'react';
import { useSetContextProvider } from '@veltdev/react';

const contextProvider = useCallback((documentId, location) => {
return {
customKey: 'customValue'
};
}, []);

const { setContextProvider } = useSetContextProvider();

useEffect(() => {
if (setContextProvider && contextProvider) {
setContextProvider(contextProvider);
}
}, []);

// API Method
const commentElement = client.getCommentElement();
commentElement.setContextProvider((documentId, location) => {
return {
customKey: 'customValue'
};
});

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.setContextProvider((documentId, location) => {
  return {
    customKey: 'customValue'
  };
});

setContextInPageModeComposer

Set context data for the page mode composer programmatically.

Accepts a PageModeComposerConfig object. Pass custom context data that will be included when a comment is created through the page mode composer.

API Method: setContextInPageModeComposer()

For automatic context passing when opening the comment sidebar via the comment tool, see contextInPageModeComposer.

React / Next.js

// Using Hook
const commentElement = useCommentUtils();

// Set context with optional target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1'
});

// Using API Method
const commentElement = client.getCommentElement();
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1'
});

// Set only context without target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123' }
});

// Clear the context and target element
commentElement.setContextInPageModeComposer({
context: null,
targetElementId: null
});

// Preserve context after submission
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1',
clearContext: false
});

Other Frameworks

const commentElement = Velt.getCommentElement();

// Set context with optional target element
commentElement.setContextInPageModeComposer({
  context: { documentId: 'doc-123', section: 'intro' },
  targetElementId: 'element-1'
});

// Set only context without target element
commentElement.setContextInPageModeComposer({
  context: { documentId: 'doc-123' }
});

// Clear the context and target element
commentElement.setContextInPageModeComposer({
  context: null,
  targetElementId: null
});

// Preserve context after submission
commentElement.setContextInPageModeComposer({
  context: { documentId: 'doc-123', section: 'intro' },
  targetElementId: 'element-1',
  clearContext: false
});

clearPageModeComposerContext

Clear context data from page mode composer. This is useful when you are using sidebar in embed mode and have to clear the context from page mode composer manually.

API Method: clearPageModeComposerContext()

• Params: none
• Returns: void

React / Next.js

const commentElement = client.getCommentElement();
commentElement.clearPageModeComposerContext();

Other Frameworks

<script>
  const commentElement = Velt.getCommentElement();
  commentElement.clearPageModeComposerContext();
</script>

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

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

Other Frameworks

<!-- Comment Tool with context metadata -->
<velt-comment-tool
  target-element-id="cell-jan-cheese-zurich"
  context='{
    "month": "jan",
    "year": "2024",
    "product": "cheese",
    "location": "zurich"
  }'
>
</velt-comment-tool>

<!-- Inline Comments Section with context -->

<velt-inline-comments-section
target-element-id="budget-item-marketing-q1"
context='{
"department": "marketing",
"quarter": "Q1",
"category": "paid-ads"
}'

> </velt-inline-comments-section>

---

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

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

Other Frameworks

<!-- Comment Bubble - filter by context -->
<velt-comment-bubble
  context='{ "product": "cheese" }'
  context-options='{ "partialMatch": true }'
>
</velt-comment-bubble>

<!-- Comment Bubble - filter by target element -->

<velt-comment-bubble target-element-id="cell-jan-cheese-zurich"></velt-comment-bubble>

<!-- Inline Comments Section - filter by context -->

<velt-inline-comments-section
context='{ "department": "marketing" }'
context-options='{ "partialMatch": true }'

> </velt-inline-comments-section>

<!-- Comment Pin - filter by context (no targetElementId support) -->

<velt-comment-pin
context='{ "product": "cheese", "month": "jan" }'

> </velt-comment-pin>

---

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

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

Other Frameworks

<!-- Full match (default) -->
<velt-comment-bubble
  context='{ "month": "jan", "product": "cheese", "location": "zurich" }'
>
</velt-comment-bubble>

---

🔍 Partial Match

Enable partial matching with contextOptions={{ partialMatch: true }}.

A comment matches if all fields in your filter exist in the comment’s context.
Extra fields in the comment context don’t prevent a match.

Example:

// Comment context
{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }

// Filters
{ product: "cheese" }                   ✅ Matches
{ day: "01", product: "cheese" }        ✅ Matches
{ product: "cheese", category: "dairy"} ❌ No match (missing field)

Example

React / Next.js

{/* Comment Bubble with Partial Match */}
<VeltCommentBubble
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

{/* Comment Tool with Partial Match */}

<VeltCommentTool
  targetElementId="element_id"
  context={{ product: "cheese" }}
  contextOptions={{ partialMatch: true }}
/>

Other Frameworks

<!-- Comment Bubble with Partial Match -->
<velt-comment-bubble
  context='{ "product": "cheese" }'
  context-options='{ "partialMatch": true }'
>
</velt-comment-bubble>

<!-- Comment Tool with Partial Match -->

<velt-comment-tool
target-element-id="element_id"
context='{ "product": "cheese" }'
context-options='{ "partialMatch": true }'

> </velt-comment-tool>

---

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

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

Other Frameworks

<!-- Enable grouping globally -->
<velt-comments group-matched-comments="true"></velt-comments>

<!-- Grouped Comment Bubble -->

<velt-comment-bubble
context='{ "product": "cheese" }'
context-options='{ "partialMatch": true }'
comment-count-type="total"

> </velt-comment-bubble>

<script>
  const commentElement = Velt.getCommentElement();
  commentElement.enableGroupMatchedComments();
  commentElement.disableGroupMatchedComments();
</script>

---

Private Comments (beta)

The visibility system uses two separate sets of values:

• API methods (on this page) use CommentVisibilityConfig with 3 values: 'public', 'organizationPrivate', 'restricted'.
• UI wireframes use the CommentVisibilityOption enum with 4 values: 'restrictedSelf', 'restrictedSelectedPeople', 'organizationPrivate', 'public'.

The API’s single 'restricted' value covers both “self-only” and “selected people” — distinguished by whether userIds is provided.

To use this feature, you need to first enable it in Velt Console.

updateVisibility

Manage who can view a comment annotation by updating its visibility settings. Use this method to control whether a comment is public, restricted to your organization, or visible only to specific users. The resulting setting is stored on the annotation as visibilityConfig.

• To use this feature, you need to first enable it in Velt Console
• Params: CommentVisibilityConfig
  • type:
    • 'public': Comment visible to all users
    • 'organizationPrivate': Comment visible only to users in the specified organization. Even if someone is added to the document but not to the organization, they will not be able to view the comment.
    • 'restricted': Comment visible only to the specified users; the current user is always included
  • organizationId: string; required if type is organizationPrivate
  • userIds: string[]; optional when type is 'restricted' — current user is always appended
• Returns: void

When type is 'restricted', the SDK automatically appends the current user’s userId to userIds if it is not already present. This applies whether userIds is empty or contains an explicit list that excludes the author.

React / Next.js

const commentElement = client.getCommentElement();

// Set comment to be visible only to the organization
commentElement.updateVisibility({
  annotationId: "annotationId",
  type: 'organizationPrivate',
  organizationId: 'org-123'
});

// Set comment to be private (current user always included in restricted access)
commentElement.updateVisibility({
  annotationId: "annotationId",
  type: 'restricted'
});

// Set comment to be private (visible only to specific users)
commentElement.updateVisibility({
  annotationId: "annotationId",
  type: 'restricted',
  userIds: ['user-1', 'user-2']
});

// Set comment to be public
commentElement.updateVisibility({
  annotationId: "annotationId",
  type: 'public'
});

Other Frameworks

const commentElement = Velt.getCommentElement();

// Set comment to be visible only to the organization
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'organizationPrivate',
organizationId: 'org-123'
});

// Set comment to be private (current user always included in restricted access)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted'
});

// Set comment to be private (visible only to specific users)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted',
userIds: ['user-1', 'user-2']
});

// Set comment to be public
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'public'
});

enablePrivateMode

Set the default visibility for all new comments created by the current user.

• Params: PrivateModeConfig
  • type:
    • 'restricted': New comments visible only to the specified users; the current user is always included
    • 'organizationPrivate': New comments visible only to users in the current organization
  • userIds: string[]; optional when type is 'restricted' — current user is always appended
• Returns: void

When type is 'restricted', the SDK automatically appends the current user’s userId to userIds if it is not already present. This applies whether userIds is empty or contains an explicit list that excludes the author.

React / Next.js

const commentElement = client.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });

Other Frameworks

const commentElement = Velt.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });

disablePrivateMode

Revert new comment visibility to default public visibility.

• Returns: void

React / Next.js

const commentElement = client.getCommentElement();
// Revert to default public visibility
commentElement.disablePrivateMode();

Other Frameworks

const commentElement = Velt.getCommentElement();
// Revert to default public visibility
commentElement.disablePrivateMode();

visibilityOptions

Show a visibility banner on the comment composer that lets users set a comment’s visibility to public, organization-private, restricted-self, or restricted before submitting. Users can also change visibility after submission from the thread options menu.

Default: false

React / Next.js

Using Props:

<VeltComments visibilityOptions={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableVisibilityOptions();
commentElement.disableVisibilityOptions();

Other Frameworks

Using Props:

<velt-comments visibility-options="true"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
commentElement.enableVisibilityOptions();
commentElement.disableVisibilityOptions();

visibilityOptionClicked

Subscribe to this event to be notified when a user selects a visibility option. Emits a VisibilityOptionClickedEvent.

Setting visibility at comment creation time

If you are creating comments using API, then pass a CommentVisibilityConfig as the optional visibility field on AddCommentRequest to pre-set visibility when programmatically adding a comment.

React / Next.js

Using Hooks:

const addCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  comment: {
    commentText: 'This is a comment',
    commentHtml: '<p>This is a comment</p>',
  },
  visibility: {
    type: 'restricted',
    userIds: ['user-1', 'user-2']
  }
};

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

Using API:

const addCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  comment: {
    commentText: 'This is a comment',
    commentHtml: '<p>This is a comment</p>',
  },
  visibility: {
    type: 'restricted',
    userIds: ['user-1', 'user-2']
  }
};

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

Other Frameworks

const addCommentRequest = {
  annotationId: 'ANNOTATION_ID',
  comment: {
    commentText: 'This is a comment',
    commentHtml: '<p>This is a comment</p>',
  },
  visibility: {
    type: 'restricted',
    userIds: ['user-1', 'user-2']
  }
};

const commentElement = Velt.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);

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

Using Props:

<VeltComments customListDataOnAnnotation={customListDataOnCommentAnnotation} />

API Method:

const commentElement = useCommentUtils();
commentElement.createCustomListDataOnAnnotation(
  customListDataOnCommentAnnotation,
);

React / Next.js

Using Props:

<VeltComments customListDataOnAnnotation={customListDataOnCommentAnnotation} />

API Method:

const commentElement = client.getCommentElement();
commentElement.createCustomListDataOnAnnotation(
  customListDataOnCommentAnnotation,
);

Other Frameworks

const commentElement = Velt.getCommentElement();			
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

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

// Hook
const commentElement = useCommentUtils();
commentElement.createCustomListDataOnComment(customListDataOnComment);

React / Next.js

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

// Hook
const commentElement = client.getCommentElement();
commentElement.createCustomListDataOnComment(customListDataOnComment);

Other Frameworks

const commentElement = Velt.getCommentElement();
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

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

// Hook
const commentElement = useCommentUtils();
commentElement.createCustomListDataOnComment(customListWithGroups);

React / Next.js

const commentElement = client.getCommentElement();
commentElement.createCustomListDataOnComment(customListWithGroups);

Other Frameworks

const commentElement = Velt.getCommentElement();
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

let autocompleteChipData = useAutocompleteChipClick(); 

React / Next.js

const autocompleteElement = client.getAutocompleteElement();
const subscription = autocompleteElement.onAutocompleteChipClick().subscribe((_data) => {
  console.log(_data);
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

Other Frameworks

const autocompleteElement = Velt.getAutocompleteElement();
const subscription = autocompleteElement.onAutocompleteChipClick().subscribe((_data) => {
  console.log(_data);
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

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

1. Enable the feature

   // Enable via props
   <VeltComments customAutocompleteSearch={true} />
   
   // Or, enable via Comment Element API
   const commentElement = client.getCommentElement();
   commentElement.enableCustomAutocompleteSearch();
   commentElement.disableCustomAutocompleteSearch();
   
   
2. Set initial list

   // For @mentions feature
   contactElement.updateContactList(users);
   
   // For custom list feature
   commentElement.createCustomListDataOnComment({
       hotkey: "#",
       type: "custom",
       data: customListData,
   });
   
3. Handle search event

   commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
       const searchText = inputData.searchText;
   
       // For @mentions feature
       if (inputData.type === 'contact') {
           const filteredUsersData = await __your_api_call__(searchText);
           contactElement.updateContactList(filteredUsersData, { merge: false });
       }
   
       // For custom list feature
       if (inputData.type === 'custom') {
           const filteredListData = await __your_api_call__(searchText, autocompleteData);
           commentElement.createCustomListDataOnComment({
               hotkey: "#",
               type: "custom",
               data: filteredListData,
           });
       }
   
   });
   
   

Other Frameworks

1. Enable the feature

   // Enable via attribute
   <velt-comments custom-autocomplete-search="true"></velt-comments>
   
   // Or, enable via Comment Element API
   const commentElement = Velt.getCommentElement();
   commentElement.enableCustomAutocompleteSearch();
   commentElement.disableCustomAutocompleteSearch();
   
2. Set initial list

   commentElement.createCustomListDataOnComment({
       hotkey: "#",
       type: "custom",
       data: customListData,
   });
   
3. Handle search event

   commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
       const searchText = inputData.searchText;
   
       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	addCommentAnnotationDraft	Triggered before addCommentAnnotation event clicks on the comment tool and the composer is rendered.	AddCommentAnnotationDraftEvent
Threads	addCommentAnnotation	Add a new comment annotation	AddCommentAnnotationEvent
Threads	addCommentDraft	Triggered when a user abandons a reply or edit composer without saving	AddCommentDraftEvent
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
Attachments	attachmentDownloadClicked	Triggered when attachment download button is clicked	AttachmentDownloadClickedEvent
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
Agent Suggestions	suggestionAccepted	Triggered when a reviewer accepts an agent suggestion (finding) from the comment dialog	SuggestionAcceptEvent
Agent Suggestions	suggestionRejected	Triggered when a reviewer rejects an agent suggestion (finding) from the comment dialog	SuggestionRejectEvent
Recordings	deleteRecording	Delete a recording from a comment	DeleteRecordingEvent
Deep Links	copyLink	Copy a deep link to a comment	CopyLinkEvent
Comment Sidebar	commentSidebarDataInit	Triggered when comment sidebar data is first loaded	CommentSidebarDataInitEvent
Comment Sidebar	commentSidebarDataUpdate	Triggered when comment sidebar data is updated	CommentSidebarDataUpdateEvent
Comment Sidebar	sidebarOpen	Triggered when the comment sidebar opens	SidebarOpenEvent
Comment Sidebar	sidebarClose	Triggered when the comment sidebar closes	SidebarCloseEvent
Comment Sidebar	commentClick	Triggered when a comment is clicked in the sidebar list	CommentClickEvent
Comment Sidebar	commentNavigationButtonClick	Triggered when the navigation (“go to”) button on a sidebar comment is clicked	CommentNavigationButtonClickEvent
UI	composerClicked	Triggered when comment composer is clicked	ComposerClickedEvent
UI	composerTextChange	Triggered when text changes in any comment composer. Includes full draft annotation object and composer ID.	ComposerTextChangeEvent
UI	commentPinClicked	Triggered when a comment pin is clicked	CommentPinClickedEvent
UI	commentBubbleClicked	Triggered when a comment bubble is clicked	CommentBubbleClickedEvent
UI	linkClicked	Triggered when a clickable link in comment content is clicked	LinkClickedEvent
UI	commentToolClicked	Past-tense alias for commentToolClick, identical payload	CommentToolClickedEvent
UI	sidebarButtonClicked	Past-tense alias for sidebarButtonClick, identical payload	SidebarButtonClickedEvent
Recorder	transcriptionDone	Triggered when a transcription is generated and ready	TranscriptionDoneEvent
Threads	commentSaved	Triggered when a comment annotation is saved to the database	CommentSavedEvent
Threads	commentSaveTriggered	Triggered immediately when the save button is clicked, before async save completes	CommentSaveTriggeredEvent
Visibility	visibilityOptionClicked	Triggered when a user selects a visibility option	VisibilityOptionClickedEvent

React / Next.js

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

Other Frameworks

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

Attachments

enableAttachments

Whether file attachments are enabled.

Default: true

When this is on, users can attach image files to their comments. Users can download or delete an attachment. Users can attach multiple files at once.

Currently we support .png, .jpg, .gif (static & animated), .svg file types up to 15MB per file.

React / Next.js

<VeltComments attachments={true} />

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

Other Frameworks

<velt-comments attachments="true"></velt-comments>

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

enableAttachmentDownload

Controls whether clicking an attachment triggers a file download.

Default: true

When disabled, users can still click attachments but no download is triggered. The attachmentDownloadClicked event fires on every attachment click regardless of this setting.

React / Next.js

// Using Component Props
<VeltComments attachmentDownload={true} />

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

// Listening to the event
const commentEventCallbackData = useCommentEventCallback('attachmentDownloadClicked');
useEffect(() => {
  if (commentEventCallbackData) {
    // Handle attachment download clicked event
  }
}, [commentEventCallbackData]);

Other Frameworks

<!-- Using HTML attributes -->
<velt-comments attachment-download="true"></velt-comments>

// Using API methods
const commentElement = Velt.getCommentElement();
commentElement.enableAttachmentDownload();
commentElement.disableAttachmentDownload();

// Listening to the event
const commentElement = Velt.getCommentElement();
commentElement.on('attachmentDownloadClicked').subscribe((event) => {
  // Handle attachment download clicked event
});

enableScreenshot

Whether screenshot option is enabled in comments.

Default: false

When enabled, users can attach screenshots when adding comments. This provides a quick way to capture and share visual context.

React / Next.js

// Using Component Props
<VeltComments screenshot={true} />

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

Other Frameworks

<!-- Using HTML attributes -->
<velt-comments screenshot="true"></velt-comments>

<script>
// Using API methods
const commentElement = Velt.getCommentElement();
commentElement.enableScreenshot();
commentElement.disableScreenshot();
</script>

addAttachment

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const attachmentResponses = await commentElement.addAttachment(addAttachmentRequest);

deleteAttachment

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const deleteAttachmentEvent = await commentElement.deleteAttachment(deleteAttachmentRequest);

getAttachment

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.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

// Using component prop
<VeltComments allowedFileTypes={['jpg', 'png']} />

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

Other Frameworks

<!-- Using HTML attribute -->
<velt-comments allowed-file-types="['jpg', 'png']"></velt-comments>

// Using API method
const commentElement = Velt.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

<VeltComments attachmentNameInMessage={true} />

Other Frameworks

<velt-comments attachment-name-in-message="true"></velt-comments>

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

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',
});

Other Frameworks

const commentElement = Velt.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',
});

attachmentDownload

Control whether attachment downloads happen automatically when users click the download button.

Default: true

When enabled, clicking the download button on an attachment will automatically download the file. When disabled, the automatic download is prevented, and you can handle the download action with custom logic by subscribing to the attachmentDownloadClicked event.

This is useful for:

• Tracking download analytics before initiating the download
• Implementing custom download URLs or CDN routes
• Adding access control checks before allowing downloads

React / Next.js

// Using component prop
<VeltComments attachmentDownload={false} />

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

// Subscribe to download click events
const commentElement = client.getCommentElement();
commentElement.on('attachmentDownloadClicked').subscribe((event) => {
  // event.annotationId - ID of the comment annotation
  // event.commentAnnotation - Full comment annotation object
  // event.attachment - The attachment that was clicked
  // event.metadata - Event metadata

// Implement custom download logic
console.log('Attachment download clicked:', event.attachment);

// Example: Custom analytics tracking
trackDownload(event.attachment.id);

// Example: Custom download URL
window.open(event.attachment.url, '\_blank');
});

Other Frameworks

<!-- Using HTML attribute -->
<velt-comments attachment-download="false"></velt-comments>

// Using API methods
const commentElement = Velt.getCommentElement();
commentElement.enableAttachmentDownload();
commentElement.disableAttachmentDownload();

// Subscribe to download click events
const commentElement = Velt.getCommentElement();
commentElement.on("attachmentDownloadClicked").subscribe((event) => {
  // event.annotationId - ID of the comment annotation
  // event.commentAnnotation - Full comment annotation object
  // event.attachment - The attachment that was clicked
  // event.metadata - Event metadata

  // Implement custom download logic
  console.log("Attachment download clicked:", event.attachment);

  // Example: Custom analytics tracking
  trackDownload(event.attachment.id);

  // Example: Custom download URL
  window.open(event.attachment.url, "_blank");
});

Text Formatting

enableFormatOptions

Enable rich text formatting toolbar in comment composers. Users can apply bold, italic, underline, and strikethrough formatting.

Default: false

React / Next.js

// Using Component Props
<VeltComments formatOptions={true} />

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

Other Frameworks

<!-- Using HTML attributes -->
<velt-comments format-options="true"></velt-comments>

<script>
// Using API methods
const commentElement = Velt.getCommentElement();
commentElement.enableFormatOptions();
commentElement.disableFormatOptions();
</script>

setFormatConfig

Configure which format types are available in the formatting toolbar.

Params: FormatConfig

React / Next.js

// Using Hooks
const commentElement = useCommentUtils();
commentElement.setFormatConfig({
  bold: { enable: true },
  italic: { enable: true },
  underline: { enable: false },
  strikethrough: { enable: false }
});

// Using API methods
const commentElement = client.getCommentElement();
commentElement.setFormatConfig({
bold: { enable: true },
italic: { enable: true },
underline: { enable: false },
strikethrough: { enable: false }
});

Other Frameworks

<script>
const commentElement = Velt.getCommentElement();
commentElement.setFormatConfig({
  bold: { enable: true },
  italic: { enable: true },
  underline: { enable: false },
  strikethrough: { enable: false }
});
</script>

Reactions

enableReactions

Whether emoji reactions are enabled.

Default: true

React / Next.js

<VeltComments reactions={true} />

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

Other Frameworks

<velt-comments reactions="true"></velt-comments>

const commentElement = Velt.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

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

Other Frameworks

const commentElement = Velt.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

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

Other Frameworks

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

const commentElement = Velt.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

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

Other Frameworks

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

const commentElement = Velt.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

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

Other Frameworks

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

const commentElement = Velt.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

<VeltComments status={true} />

Other Frameworks

<velt-comments status="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableStatus();
commentElement.disableStatus();

Other Frameworks

const commentElement = Velt.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

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',
  },
])

Other Frameworks

const commentElement = Velt.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

<VeltComments resolveButton={true} />

Other Frameworks

<velt-comments resolve-button="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

updateStatus

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const updateStatusEvent = await commentElement.updateStatus(updateStatusRequest);

resolveCommentAnnotation

• Resolves a comment annotation
• Params: ResolveCommentAnnotationRequest
• Returns: ResolveCommentAnnotationEvent

React / Next.js

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

Other Frameworks

const resolveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.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

<VeltComments priority={true} />

Other Frameworks

<velt-comments priority="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

setCustomPriority

React / Next.js

Pass custom priorities in the customPriority prop.

Default priorities: P0, P1, P2

With custom priorities, you can replace the default priorities with your own values. These priorities are also used in the comment sidebar to filter comments by priority.

This will work if you have enabled the priority feature.

The color property is used to set the priority pill background color.

The lightColor property sets the background color of the filter.

<VeltComments
  customPriority={[
    {
      id: "low",
      name: "Low",
      color: "red",
      lightColor: "pink",
    },
  ]}
/>

Other Frameworks

Pass custom priorities in the custom-priority.

Default priorities: P0, P1, P2

With custom priorities, you can replace the default priorities with your own values. These priorities are also used in the comment sidebar to filter comments by priority.

This will work if you have enabled the priority feature.

The color property is used to set the priority pill background color.

The lightColor property sets the background color of the filter.

<velt-comments
  custom-priority='[
  {
    "id": "low",
    "name": "Low",
    "color": "red",
    "lightColor": "pink",
  }
]'
></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

const commentElement = Velt.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

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

Other Frameworks

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

const commentElement = Velt.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

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

Other Frameworks

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

const commentElement = Velt.getCommentElement();
const deleteRecordingEvent = await commentElement.deleteRecording(deleteRecordingRequest);

getRecording

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

React / Next.js

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

Other Frameworks

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

const commentElement = Velt.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

<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

Tab TitleUsing Props:

Other Frameworks

<velt-comments recordings="video,screen"></velt-comments>

Using API:

const commentElement = Velt.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

<VeltComments recordingCountdown={false} />

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

Other Frameworks

<velt-comments recording-countdown="false"></velt-comments>

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

enableRecordingTranscription

Controls whether to enable AI transcription for recordings.

Default: enabled

React / Next.js

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

Other Frameworks

Using Props:

<velt-comments recording-transcription="false"></velt-comments>

Using API Methods:

// Using comment element
const commentElement = Velt.getCommentElement();
commentElement.enableRecordingTranscription();
commentElement.disableRecordingTranscription();

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

Deep Link

getLink

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

React / Next.js

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

Other Frameworks

const getLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.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

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

Other Frameworks

const copyLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const copyLinkEvent = await commentElement.copyLink(copyLinkRequest);

Navigation

scrollToCommentByAnnotationId

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

React / Next.js

const commentElement = client.getCommentElement();
commentElement.scrollToCommentByAnnotationId("annotationId");

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.scrollToCommentByAnnotationId('annotationId');

selectCommentByAnnotationId

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

React / Next.js

// Using Hooks
const commentElement = useCommentUtils();

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

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

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

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

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

Other Frameworks

const commentElement = Velt.getCommentElement();

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

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

onCommentSelectionChange

React / Next.js with Hooks

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

React / Next.js

The onCommentSelectionChange() method can be used to listen Comment selection changes.

const onCommentSelectionChange = (data) => {
  console.log('onCommentSelectionChange', data);
}

<VeltComments
  onCommentSelectionChange={(data) => onCommentSelectionChange(data)}
/>
``` Callback response schema:

```jsx
export class CommentSelectionChangeData {
  selected!: boolean;
  annotation!: CommentAnnotation;
}

API Methods:

const commentElement = client.getCommentElement();
let subscription = commentElement
  .onCommentSelectionChange()
  .subscribe((data) => {
    console.log("onCommentSelectionChange: ", data);
  });

To unsubscribe from the subscription:

subscription?.unsubscribe();

Other Frameworks

The onCommentSelectionChange() method can be used to listen Comment selection changes.

<velt-comments></velt-comments>
<script>
const commentTag = document.querySelector('velt-comments');
commentTag.addEventListener('onCommentSelectionChange', (event) => {
	console.log('onCommentSelectionChange event', event.detail);
});
</script>

Callback response schema:

export class CommentSelectionChangeData {
  selected!: boolean;
  annotation!: CommentAnnotation;
}

API Methods:

const commentElement = Velt.getCommentElement();
let subscription = commentElement
  .onCommentSelectionChange()
  .subscribe((data) => {
    console.log("onCommentSelectionChange: ", data);
  });

To unsubscribe from the subscription:

subscription?.unsubscribe();

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

To disable the feature, set scrollToComment to false.

<VeltComments scrollToComment={false}/>

Other Frameworks

To disable the feature, set scroll-to-comment to false.

<velt-comments scroll-to-comment="false"></velt-comments>

API methods:

React / Next.js

const commentElement = client.getCommentElement();
// To enable scroll to component
commentElement.enablescrollToComment();
// To disable scroll to component
commentElement.disablescrollToComment();

Other Frameworks

const commentElement = Velt.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

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

Other Frameworks

Using Props:

<velt-comments 
  allowed-element-ids='["some-element"]'
  allowed-element-class-names='["class-name-1", "class-name-2"]'
  allowed-element-query-selectors='["#id1.class-name-1"]'
>

</velt-comments>

Using API Method:

const commentElement = Velt.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

<VeltCommentTool sourceId="sourceId1" />

Other Frameworks

<velt-comment-tool source-id="sourceId1"></velt-comment-tool>

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

<VeltComments autoCategorize={true} />

Other Frameworks

<velt-comments auto-categorize="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

setCustomCategory

React / Next.js

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",
    },
  ]}
/>

Other Frameworks

Pass custom categories in the custom-category.

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 auto-categorize uses the list of categories to determine the closest category to choose from.

The input format to the custom-category should be an array of objects with an id, name, and color.

The color property is used to set the category pill background color.

<velt-comments
  customCategory='[
  {
    "id": "bug",
    "name": "Bug",
    "color": "red"
  }
]'
></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.setCustomCategory([
  {
    "id": "bug",
    "name": "Bug",
    "color": "red"
  }
])

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.setCustomCategory([
  {
    id: "bug",
    name: "Bug",
    color: "red",
  },
]);

Make sure to have at least 2 categories set.

Agent Comments

Agent comments let your AI agents leave comments and findings directly in Velt by calling the Comment Annotations REST APIs — no SDK changes required. They are built on top of the same Comments feature, but render with a special UI: each agent finding is a suggestion with Accept and Reject buttons on the comment dialog.

For the full guide — the agent block, request/response shapes, and velt vs external agents — see Agent Comments.

Create an agent comment

Your agent calls the Add Comment Annotations API with an agent block attached to the root comment and type: "suggestion". The server stamps sourceType: "agent" on both the comment and the annotation.

cURL

curl -X POST 'https://api.velt.dev/v2/commentannotations/add' \
  -H 'x-velt-api-key: YOUR_API_KEY' \
  -H 'x-velt-auth-token: YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "organizationId": "acme-corp",
      "documentId": "design-mockup-v2",
      "commentAnnotations": [
        {
          "type": "suggestion",
          "commentData": [
            {
              "commentText": "This button has insufficient color contrast.",
              "from": { "userId": "a11y-bot" },
              "agent": {
                "agentSource": "external",
                "agentName": "Accessibility Bot",
                "agentId": "a11y-bot",
                "reason": {
                  "title": "Low color contrast",
                  "description": "Contrast ratio is 2.1:1, below the 4.5:1 WCAG AA threshold.",
                  "severity": "high",
                  "findingType": "pin"
                }
              }
            }
          ]
        }
      ]
    }
  }'

To read agent comments back, use the Get Comment Annotations API with agent-specific filters (agentId, executionId, agentSource, agentSuggestions, agentComments).

Handle accept / reject

Because agent findings render with Accept and Reject buttons on the comment dialog, the outcome is emitted on the comment element as the suggestionAccepted and suggestionRejected events. Subscribe to them to apply the change to your own data or trigger follow-up logic.

React / Next.js

const accepted = useCommentEventCallback('suggestionAccepted');
const rejected = useCommentEventCallback('suggestionRejected');

useEffect(() => {
  if (accepted) {
    // accepted.commentAnnotation contains the agent finding
  }
}, [accepted]);

useEffect(() => {
  if (rejected) {
    // rejected.rejectReason contains the optional reason
  }
}, [rejected]);

Other Frameworks

const commentElement = Velt.getCommentElement();

commentElement.on('suggestionAccepted').subscribe(({ commentAnnotation }) => {
  // commentAnnotation contains the agent finding
});

commentElement.on('suggestionRejected').subscribe(({ commentAnnotation, rejectReason }) => {
  // rejectReason contains the optional reason
});

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

<VeltComments composerMode="expanded" />

Other Frameworks

<velt-comments composer-mode="expanded"></velt-comments>

commentToNearestAllowedElement

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

React / Next.js

<VeltComments commentToNearestAllowedElement={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableCommentToNearestAllowedElement();
commentElement.disableCommentToNearestAllowedElement();

Other Frameworks

<velt-comments comment-to-nearest-allowed-element="true"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
commentElement.enableCommentToNearestAllowedElement();
commentElement.disableCommentToNearestAllowedElement();

deleteThreadWithFirstComment

Whether deleting the first comment in a thread will delete the entire thread.

Default: true

React / Next.js

<VeltComments deleteThreadWithFirstComment={false} />

Other Frameworks

<velt-comments delete-thread-with-first-comment="false"></velt-comments>

draftMode

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

When enabled, partial comments are preserved when the dialog closes, including composer text, attachments, and recordings.

Default: true

Behavior:

• Partial comments are saved with isDraft: true when the dialog is closed
• The dialog shows a shake animation on the first click outside if there’s unsaved content
• The data-velt-annotation-draft attribute is set on dialogs with unsaved content for custom styling

React / Next.js

<VeltComments draftMode={false} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableDraftMode();
commentElement.disableDraftMode();

Other Frameworks

<velt-comments draft-mode="false"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
commentElement.enableDraftMode();
commentElement.disableDraftMode();

enableCollapsedComments

You can control whether comments inside the annotation should be collapsed.

Default: false

React / Next.js

Using Props:

<VeltComments collapsedComments={true} />

Using API:

const commentElement = client.getCommentElement();
// To enable collapsed comments
commentElement.enableCollapsedComments();
// To disable collapsed comments
commentElement.disableCollapsedComments();

Other Frameworks

Using Props:

<velt-comments collapsed-comments="true"></velt-comments>

Using API:

const commentElement = Velt.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

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

Other Frameworks

Using Props:

<!-- Apply this change globally to all types of comments -->
<velt-comments full-expanded="true"></velt-comments>

<!-- Apply this change only in comments sidebar -->

<velt-comments-sidebar full-expanded="true"></velt-comments-sidebar>

<!-- Apply this change only in inline comments section -->

<velt-inline-comments-section full-expanded="true"></velt-inline-comments-section>

<!-- Apply this change only in the standalone comment thread -->

<velt-comment-thread full-expanded="true"></velt-comment-thread>

Using API:

const commentElement = Velt.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

Using Props:

<VeltComments shortUserName={false} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableShortUserName();
commentElement.disableShortUserName();

Other Frameworks

Using Props:

<velt-comments short-user-name="false"></velt-comments>

Using API:

const commentElement = Velt.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

<VeltComments signInButton={true} />

Other Frameworks

<velt-comments sign-in-button="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableSignInButton();
commentElement.disableSignInButton();

Other Frameworks

const commentElement = Velt.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

Using Props:

<VeltComments sidebarButtonOnCommentDialog={true} />

Using API methods:

const commentElement = client.getCommentElement();
commentElement.enableSidebarButtonOnCommentDialog();
commentElement.disableSidebarButtonOnCommentDialog();

Other Frameworks

Using Props:

<velt-comments sidebar-button-comment-dialog="true"></velt-comments>

Using API methods:

const commentElement = Velt.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

Using Props:

<VeltComments deleteReplyConfirmation={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableDeleteReplyConfirmation();
commentElement.disableDeleteReplyConfirmation();

Other Frameworks

Using Props:

<velt-comments delete-reply-confirmation="true"></velt-comments>

Using API:

const commentElement = Velt.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

<VeltComments mobileMode={true} />

Other Frameworks

<velt-comments mobile-mode="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

enableCommentPinHighlighter

Wheter the pin highlighter outline is enabled or not.

Default: true

React / Next.js

<VeltComments commentPinHighlighter={false} />

Other Frameworks

<velt-comments comment-pin-highlighter="false"></velt-comments>

API Methods:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableCommentPinHighlighter(); // to enable comment pin highlight
commentElement.disableCommentPinHighlighter(); // to disable comment pin highlight

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.enableCommentPinHighlighter(); // to enable comment pin highlight
commentElement.disableCommentPinHighlighter(); // to disable comment pin highlight

pinDrag

Whether comment pins can be dragged to reposition them.

Default: true

React / Next.js

<VeltComments pinDrag={false} />

Other Frameworks

<velt-comments pin-drag="false"></velt-comments>

API Methods:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enablePinDrag(); // to enable comment pin drag
commentElement.disablePinDrag(); // to disable comment pin drag

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.enablePinDrag(); // to enable comment pin drag
commentElement.disablePinDrag(); // to disable comment pin drag

enableDialogOnHover

Whether the comment dialog shows on hover over the comment pin or the target element.

Default: true

React / Next.js

<VeltComments dialogOnHover={true} />

Other Frameworks

<velt-comments dialog-on-hover="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableDialogOnHover();
commentElement.disableDialogOnHover();

Other Frameworks

const commentElement = Velt.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

<VeltComments floatingCommentDialog={true} />

Other Frameworks

<velt-comments floating-comment-dialog="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

excludeLocationIds

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

React / Next.js

const locationIds = ['location1', 'location2']; // list of location ids
client.excludeLocationIds(locationIds);

To reset it, you can pass an empty array:

client.excludeLocationIds([]);

Other Frameworks

const locationIds = ['location1', 'location2']; // list of location ids
Velt.excludeLocationIds(locationIds);

To reset it, you can pass an empty array:

Velt.excludeLocationIds([]);

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

Using props:

<VeltComments maxReplyAvatars={2} replyAvatars={true} />

Using API:

const commentsElement = client.getCommentElement();
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.

Other Frameworks

Using props:

<velt-comments max-reply-avatars="2" reply-avatars="true"></velt-comments>

Using API:

const commentsElement = Velt.getCommentElement();
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.

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.
• Dual-gate behavior: When setCommentSidebarData() is also active, this feature applies an AND — on-page pins must satisfy both the active sidebar filter criteria and the custom id list from setCommentSidebarData(). Drafts (isDraft: true) bypass both gates so an in-progress unposted comment is never filtered out from under the user.

Default: false

React / Next.js

Using Props:

<VeltComments filterCommentsOnDom={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableFilterCommentsOnDom();
commentElement.disableFilterCommentsOnDom();

Other Frameworks

Using Props:

<velt-comments filter-comments-on-dom="true"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
commentElement.enableFilterCommentsOnDom();
commentElement.disableFilterCommentsOnDom();

focusPageModeComposer

Focus the page mode composer input field programmatically.

Use this to direct user attention to the page mode composer.

API Method: [focusPageModeComposer()](/api-reference/sdk/api/api-methods#focuspagemode composer)

React / Next.js

// Using Hook
const commentElement = useCommentUtils();
commentElement.focusPageModeComposer();

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

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.focusPageModeComposer();

onSidebarButtonOnCommentDialogClick

Use this to act on clicks on the Sidebar Button at the bottom of the Comment Dialog.

React / Next.js

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

HTML

Using Props:

<velt-comments onsidebarbuttononcommentdialogclick="yourMethod(event)"></velt-comments>

Using API Methods:

const commentElement = Velt.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

<VeltComments onSignIn={() => yourSignInMethod()} />

Other Frameworks

const veltCommentsTag = document.querySelector('velt-comments');

veltCommentsTag?.addEventListener('onSignIn', (event) => {
console.log('**_ onCommentSignIn _**');
console.log(event.detail);
});

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

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

Other Frameworks

<!-- `true` to show comments, `false` to hide comments -->
<velt-comments comments-on-dom="false"></velt-comments>

Using API methods:

React / Next.js

const commentElement = client.getCommentElement();
// to show comments on DOM
commentElement.showCommentsOnDom();
// to hide comments on DOM
commentElement.hideCommentsOnDom();

Other Frameworks

const commentElement = Velt.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

<VeltComments resolvedCommentsOnDom={true} />

Other Frameworks

<velt-comments resolved-comments-on-dom="true"></velt-comments>

API Methods:

React / Next.js

const commentElement = client.getCommentElement();
// To show resolved comments on dom
commentElement.showResolvedCommentsOnDom();
// To hide resolved comments on dom
commentElement.hideResolvedCommentsOnDom();

Other Frameworks

const commentElement = Velt.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

const commentElement = client.getCommentElement();
commentElement.updateCommentDialogPosition();

Other Frameworks

const commentElement = Velt.getCommentElement();
commentElement.updateCommentDialogPosition();

You can add custom lists at two levels: a. on the CommentAnnotation and b. on the Comment.

Link Callback

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

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

Other Frameworks

<velt-comments link-callback="true"></velt-comments>

<script>
  const commentElement = Velt.getCommentElement();
  commentElement.on('linkClicked').subscribe((linkData) => {
    console.log('Comment link clicked:', linkData);
  });
</script>

Types:

export interface LinkClickedEvent {
  text: string;
  link: string;
  commentAnnotation: CommentAnnotation;
  commentId: Number;
  metadata?: VeltEventMetadata;
}

commentBubbleClicked

Listen to when a comment bubble is clicked.

This event is triggered whenever a user clicks on a comment bubble. You can use this to implement custom actions like navigation or analytics tracking.

React / Next.js

// Using Hook
const commentBubbleClickedEvent = useCommentEventCallback('commentBubbleClicked');
useEffect(() => {
  if (commentBubbleClickedEvent) {
    console.log('Comment bubble clicked:', commentBubbleClickedEvent);
  }
}, [commentBubbleClickedEvent]);

// Using API
const commentElement = client.getCommentElement();
commentElement.on('commentBubbleClicked').subscribe((eventData) => {
console.log('Comment bubble clicked:', eventData);
});

Other Frameworks

<script>
  const commentElement = Velt.getCommentElement();
  commentElement.on('commentBubbleClicked').subscribe((eventData) => {
    console.log('Comment bubble clicked:', eventData);
  });
</script>

Event Type: CommentBubbleClickedEvent

export interface CommentBubbleClickedEvent {
  annotationId: string;
  commentAnnotation: CommentAnnotation;
  metadata?: VeltEventMetadata;
}

Extra Information

enableCommentIndex

Whether comment index is enabled.

Default: false

This appears in the comment sidebar and on the comment pins. When this is on, we show a small icon indicating the comment index in the order of creation date. This enables users to find and navigate to the desired comment quickly.

React / Next.js

<VeltComments commentIndex={true} />

Other Frameworks

<velt-comments comment-index="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableCommentIndex();
commentElement.disableCommentIndex();

Other Frameworks

const commentElement = Velt.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

<VeltComments deviceInfo={true} />

Other Frameworks

<velt-comments device-info="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableDeviceInfo();
commentElement.disableDeviceInfo();

Other Frameworks

const commentElement = Velt.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

<VeltComments deviceIndicatorOnCommentPins={true} />

Other Frameworks

<velt-comments device-indicator-on-comment-pins="true"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enableDeviceIndicatorOnCommentPins();
commentElement.disableDeviceIndicatorOnCommentPins();

Other Frameworks

const commentElement = Velt.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

<VeltComments ghostComments={true} />

Using API methods:

const commentElement = client.getCommentElement();
commentElement.enableGhostComments();
commentElement.disableGhostComments();

Other Frameworks

<velt-comments ghost-comments="true"></velt-comments>

Using API methods:

const commentElement = Velt.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

<VeltComments ghostCommentsIndicator={true} />

Using API methods:

const commentElement = client.getCommentElement();
commentElement.enableGhostCommentsIndicator();
commentElement.disableGhostCommentsIndicator();

Other Frameworks

<velt-comments ghost-comments-indicator="true"></velt-comments>

Using API methods:

const commentElement = Velt.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

Using Props:

<VeltComments svgAsImg={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableSvgAsImg();
commentElement.disableSvgAsImg();

Other Frameworks

Using Props:

<velt-comments svg-as-img="true"></velt-comments>

Using API:

const commentElement = Velt.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

Using Props:

<VeltComments hotkey={false} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableHotkey();
commentElement.disableHotkey();

Other Frameworks

Using Props:

<velt-comments hotkey="true"></velt-comments>

Using API Method:

const commentElement = Velt.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

Using Props:

<VeltComments enterKeyToSubmit={true} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableEnterKeyToSubmit();
commentElement.disableEnterKeyToSubmit();

Other Frameworks

Using Props:

<velt-comments enter-key-to-submit="true"></velt-comments>

Using API Method:

const commentElement = Velt.getCommentElement();
commentElement.enableEnterKeyToSubmit();
commentElement.disableEnterKeyToSubmit();

enableDeleteOnBackspace

• Use this to enable or disable deleting comments when backpsace key is pressed.

Default: enabled

React / Next.js

Using Props:

<VeltComments deleteOnBackspace={false} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableDeleteOnBackspace();
commentElement.disableDeleteOnBackspace();

Other Frameworks

Using Props:

<velt-comments delete-on-backspace="false"></velt-comments>

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

<VeltComments moderatorMode={true} />

Other Frameworks

<velt-comments moderator-mode="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

enableResolveStatusAccessAdminOnly

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

React / Next.js

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

Other Frameworks

Using Props:

<velt-comments resolve-status-access-admin-only="true"></velt-comments>

Using API:

const commentElement = Velt.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

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

Other Frameworks

const approveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const approveCommentAnnotationEvent = await commentElement.approveCommentAnnotation(approveCommentAnnotationRequest);

acceptCommentAnnotation

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

React / Next.js

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

Other Frameworks

const acceptCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const acceptCommentAnnotationEventData = await commentElement.acceptCommentAnnotation(acceptCommentAnnotationRequest);

rejectCommentAnnotation

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

React / Next.js

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

Other Frameworks

const rejectCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

const commentElement = Velt.getCommentElement();
const rejectCommentAnnotationEventData = await commentElement.rejectCommentAnnotation(rejectCommentAnnotationRequest);

enableSuggestionMode

Whether to enable suggestion mode to accept or reject comments.

Default: false

React / Next.js

To accept comments, set the suggestionMode attribute to true.

<VeltComments suggestionMode={true} />

Other Frameworks

To accept comments, set the suggestion-mode attribute to true.

<velt-comments suggestion-mode="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

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

Using Props:

<VeltComments readOnly={true} />

Using API:

  const commentElement = client.getCommentElement();
  commentElement.enableReadOnly();
  commentElement.disableReadOnly();

Other Frameworks

Using Props:

<velt-comments read-only="true"></velt-comments>

Using API:

  const commentElement = Velt.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

Using Props:

<VeltComments seenByUsers={false} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableSeenByUsers();
commentElement.disableSeenByUsers();

Other Frameworks

Using Props:

<velt-comments seen-by-users="false"></velt-comments>

Using API:

const commentElement = Velt.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

<VeltComments unreadIndicatorMode={"verbose"} />

Other Frameworks

<velt-comments unread-indicator-mode="verbose"></velt-comments>

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.setUnreadIndicatorMode("verbose"); // use badge with text UNREAD
commentElement.setUnreadIndicatorMode("minimal"); // use small red dot indicator

Other Frameworks

const commentElement = Velt.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

Using Props:

<VeltComments areaComment={false} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableAreaComment();
commentElement.disableAreaComment();

Other Frameworks

Using Props:

<velt-comments area-comment="false"></velt-comments>

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

<VeltComments popoverMode={true}/>

Using API:

const commentElement = client.getCommentElement();
commentElement.enablePopoverMode();
commentElement.disablePopoverMode();

Other Frameworks

<velt-comments popover-mode="true"></velt-comments> 

Using API:

const commentElement = Velt.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

<VeltComments streamMode={true}/>

Using API:

const commentElement = client.getCommentElement();
commentElement.enableStreamMode();
commentElement.disableStreamMode();

Other Frameworks

Using Props:

<velt-comments stream-mode="true"></velt-comments>

Using API:

const commentElement = Velt.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

Using Props:

<VeltComments textMode={true}/>

Using API:

const commentElement = client.getCommentElement();
commentElement.enableTextComments();
commentElement.disableTextComments();

Other Frameworks

Using Props:

<velt-comments text-mode="true"></velt-comments> 

Using API:

const commentElement = Velt.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

<VeltComments inlineCommentMode={true}/>

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

Other Frameworks

<velt-comments inline-comment-mode="true"></velt-comments> 

const commentElement = Velt.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

<VeltComments multiThread={true} />

Other Frameworks

<velt-comments multi-thread="true"></velt-comments>

collapsedRepliesPreview

When enabled, a comment dialog’s non-selected preview state shows the collapsed thread teaser (first comment, a “Show N replies…” divider, and the last comment) instead of only the first comment. Clicking the divider selects and expands the dialog in one step.

API Methods: enableCollapsedRepliesPreview(), disableCollapsedRepliesPreview()

• Params: none
• Returns: void

Default: false

This flag is also exposed as the collapsedRepliesPreview wireframe variable (boolean, default false) on the comment dialog’s more reply slot.

React / Next.js

Using Props:

<VeltComments collapsedRepliesPreview={true} />

Using API:

const commentElement = client.getCommentElement();
// Enable the collapsed teaser in the non-selected state
commentElement.enableCollapsedRepliesPreview();
// Revert to the default (only the first comment shown when not selected)
commentElement.disableCollapsedRepliesPreview();

Other Frameworks

Using Props:

<velt-comments collapsed-replies-preview="true"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
// Enable the collapsed teaser in the non-selected state
commentElement.enableCollapsedRepliesPreview();
// Revert to the default (only the first comment shown when not selected)
commentElement.disableCollapsedRepliesPreview();

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

// For popover comments
<VeltCommentTool context={{ key1: 'value1' }} />

HTML

<!-- For popover comments. Make sure to stringify the context object. -->
<velt-comment-tool context='{"key1": "value1"}'></velt-comment-tool>

contextInPageModeComposer

Pass context data to the page mode composer when opening the comment sidebar via the comment tool. Context automatically clears when the sidebar closes.

API Methods: enableContextInPageModeComposer(), disableContextInPageModeComposer()

• Params: none
• Returns: void

For programmatically setting context data, see setContextInPageModeComposer().

React / Next.js

// Using props
import { VeltCommentTool } from '@veltdev/react';

<VeltCommentTool
  contextInPageModeComposer={true}
  context={{ section: "header", elementId: "nav-menu" }}
/>

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

Other Frameworks

<velt-comment-tool
  context-in-page-mode-composer="true"
  context='{"section": "header", "elementId": "nav-menu"}'>
</velt-comment-tool>

<script>
const commentElement = Velt.getCommentElement();
commentElement.enableContextInPageModeComposer();
commentElement.disableContextInPageModeComposer();
</script>

enableCommentMode

Turns Comment mode on or off.

When you click on the comment tool, it turns on comment mode and user can attach comment to any element on the DOM. Using this method you can programmatically turn on the commenting mode.

React / Next.js

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

Other Frameworks

const commentElement = Velt.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

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

React / Next.js

To subscribe to changes in the comment mode, use the onCommentModeChange() method , as a property on VeltCommentTool:

<VeltCommentTool onCommentModeChange={(mode) => onCommentModeChange(mode)} />

API method:

let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
  //mode contains the state after change
});

To unsubscribe from the subscription:

subscription?.unsubscribe();

Other Frameworks

API method:

const commentElement = Velt.getCommentElement();
let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
    //mode contains the state after change
});

To unsubscribe from the subscription:

subscription?.unsubscribe()

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

Using Props:

<VeltComments commentTool={false} />

Using API methods:

const commentElement = client.getCommentElement();
commentElement.enableCommentTool();
commentElement.disableCommentTool();

Other Frameworks

Using Props:

<velt-comments comment-tool="false"></velt-comments>

Using API methods:

const commentElement = Velt.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

<VeltCommentTool disabled={true} />

Other Frameworks

<velt-comment-tool disabled="true"></velt-comment-tool>

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

Using Props:

<VeltComments changeDetectionInCommentMode={true} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableChangeDetectionInCommentMode();
commentElement.disableChangeDetectionInCommentMode();

Other Frameworks

Using Props:

<velt-comments change-detection-in-comment-mode="true"></velt-comments>

Using API Method:

const commentElement = Velt.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

<VeltComments persistentCommentMode={true}/>

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

Other Frameworks

<velt-comments persistent-comment-mode="true"></velt-comments>

const commentElement = Velt.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

<VeltComments forceCloseAllOnEsc={true}/>

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

Other Frameworks

<velt-comments force-close-all-on-esc="true"></velt-comments>

const commentElement = Velt.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

<VeltComments pinCursorImage={BASE64_IMAGE_STRING} />

Other Frameworks

<velt-comments pin-cursor-image="BASE64_IMAGE_STRING"></velt-comments>

API Methods:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);

Other Frameworks

const commentElement = Velt.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

<VeltComments minimap={true} minimapPosition="left" />

API Method:

const commentElement = client.getCommentElement();
commentElement.enableMinimap();
commentElement.disableMinimap();

Other Frameworks

<velt-comments minimap="true" minimap-position="left"></velt-comments>

API Method:

const commentElement = Velt.getCommentElement();
commentElement.enableMinimap();
commentElement.disableMinimap();

Option b. Enable using Minimap Component: This offers greater flexibility to customize and position the minimap.

React / Next.js

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

Other Frameworks

<div class="relative-container">
  <velt-comments-minimap target-scrollable-element-id="scrollableElement" position="left"></velt-comments-minimap>
  <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 Section

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

<VeltInlineCommentsSection sortBy="createdAt" sortOrder="desc" />

Other Frameworks

<velt-inline-comments-section
  sort-by="createdAt"
  sort-order="desc"
></velt-inline-comments-section>

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

<VeltInlineCommentsSection multiThread={false} />

Other Frameworks

<velt-inline-comments-section multi-thread="false"></velt-inline-comments-section>

commentPlaceholder, replyPlaceholder, composerPlaceholder

• Customize placeholder text for different input fields in the inline comments section.
• Props:
  • commentPlaceholder: Placeholder text for the main comment input field.
  • replyPlaceholder: Placeholder text for the reply input field.
  • composerPlaceholder: Placeholder text for the composer input field.

React / Next.js

<VeltInlineCommentsSection
  commentPlaceholder="ABC Placeholder"
  replyPlaceholder="ABC Reply Placeholder"
  composerPlaceholder="ABC Composer Placeholder"
/>

Other Frameworks

<velt-inline-comments-section
  comment-placeholder="ABC Placeholder"
  reply-placeholder="ABC Reply Placeholder"
  composer-placeholder="ABC Composer Placeholder"
></velt-inline-comments-section>

To customize placeholder text shown when editing an existing comment or reply, use editPlaceholder, editCommentPlaceholder, and editReplyPlaceholder. See VeltInlineCommentsSectionProps for details.

composerPosition

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

React / Next.js

<VeltInlineCommentsSection composerPosition="top" />

Other Frameworks

<velt-inline-comments-section composer-position="top"></velt-inline-comments-section>

context

• Pass a custom context object to the Inline Comments Section component.
• The provided context will be added to any comments created in the inline comments section, allowing you to associate custom metadata with those comments.
• Additionally, the component will filter and display only the comments that match the provided context object.
• This dual behavior makes it easy to scope comments to specific areas of your application (e.g., specific cells in a table, dashboard widgets, or data segments).

React / Next.js

<VeltInlineCommentsSection
  context={{
    department: "marketing",
    quarter: "Q1",
    category: "paid-ads",
  }}
/>

Other Frameworks

<velt-inline-comments-section context='{"department": "marketing", "quarter": "Q1", "category": "paid-ads"}'></velt-inline-comments-section>

contextOptions

• Configure the matching behavior for the context object when filtering comments.
• By default, comments must fully match all key-value pairs in the provided context.
• Set partialMatch: true to enable flexible matching where comments match if they contain all the specified context fields (extra fields in the comment’s context are ignored).
• See Context Matching for detailed explanation and examples.

React / Next.js

{/* Full match (default) - comment must have exact context */}
<VeltInlineCommentsSection 
  context={{ department: "marketing", quarter: "Q1" }} 
/>

{/* Partial match - comment matches if it contains these fields */}

<VeltInlineCommentsSection 
  context={{ department: "marketing" }} 
  contextOptions={{ partialMatch: true }}
/>

Other Frameworks

<!-- Full match (default) -->
<velt-inline-comments-section 
  context='{"department": "marketing", "quarter": "Q1"}'>
</velt-inline-comments-section>

<!-- Partial match -->

<velt-inline-comments-section 
  context='{"department": "marketing"}'
  context-options='{"partialMatch": true}'>
</velt-inline-comments-section>

readOnly

Control read-only mode at the component level. When enabled, users can view comments but cannot reply, edit, or add new comments in the Inline Comments Section.

The local component prop takes precedence over global settings when explicitly set.

Default: false

React / Next.js

<VeltInlineCommentsSection
  targetElementId="my-element"
  readOnly={true}
/>

Other Frameworks

<velt-inline-comments-section
  target-element-id="my-element"
  read-only="true">
</velt-inline-comments-section>

Popover Comments

enableDialogOnTargetElementClick

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

Default: true

React / Next.js

<VeltComments dialogOnTargetElementClick={true} />

Other Frameworks

<velt-comments dialog-on-hover="true"></velt-comments>

API Method:

React / Next.js

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

Other Frameworks

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

enablePopoverTriangleComponent

Whether the popover triangle appears when Popover Mode is enabled.

Default: true

React / Next.js

<VeltComments popoverTriangleComponent={true}/>

Other Frameworks

<velt-comments popover-triangle-component="true"></velt-comments> 

API Method:

React / Next.js

const commentElement = client.getCommentElement();
commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();

Other Frameworks

const commentElement = Velt.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

<VeltCommentBubble annotationId="annotation-id-1" />

Other Frameworks

<velt-comment-bubble annotation-id="annotation-id-1"></velt-comment-bubble>

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

<VeltCommentBubble targetElementId="cell-id-1" />

Other Frameworks

<velt-comment-bubble target-element-id="cell-id-1"></velt-comment-bubble>

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

<VeltCommentTool context={{ 'key1': 'value1', 'key2': 'value2' }} />
// Full match
<VeltCommentBubble context={{ 'key1': 'value1', 'key2': 'value2' }} />
// Partial match
<VeltCommentBubble context={{ 'key1': 'value1' }} contextOptions={{ partialMatch: true }} />

Other Frameworks

<velt-comment-tool context='{"key1": "value1", "key2": "value2"}'></velt-comment-tool>

<!-- Full match -->
<velt-comment-bubble context='{"key1": "value1", "key2": "value2"}'></velt-comment-bubble>
<!-- Partial match -->
<velt-comment-bubble context='{"key1": "value1"}' context-options='{"partialMatch": true}'></velt-comment-bubble>

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

Using Props:

<VeltComments groupMatchedComments={true} />

Using API:

const commentElement = client.getCommentElement();
commentElement.enableGroupMatchedComments();
commentElement.disableGroupMatchedComments();

Other Frameworks

Using Props:

<velt-comments group-matched-comments="true"></velt-comments>

Using API:

const commentElement = Velt.getCommentElement();
commentElement.enableGroupMatchedComments();
commentElement.disableGroupMatchedComments();

commentCountType

Whether to show unread or total comment replies count on Comment Bubble Component.

Type: CommentCountType

• total: Shows the total number of replies. (default)
• unread: Shows the number of unread replies.

React / Next.js

<VeltCommentBubble commentCountType={"unread"} />

Other Frameworks

<velt-comment-bubble comment-count-type="unread">
</velt-comment-bubble>

openDialog

Control whether the comment dialog opens when clicking on the comment bubble.

When disabled, clicking the bubble will not open the comment dialog. This is useful when you want to handle bubble clicks with custom logic using the commentBubbleClicked event.

Default: true

React / Next.js

<VeltCommentBubble openDialog={false} />

Other Frameworks

<velt-comment-bubble open-dialog="false"></velt-comment-bubble>

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

<VeltCommentBubble readOnly={true} />

Other Frameworks

<velt-comment-bubble read-only="true"></velt-comment-bubble>

Video Timeline Comments

setTotalMediaLength

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

React / Next.js

Using Props:

<VeltCommentPlayerTimeline totalMediaLength={120} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.setTotalMediaLength(120);

Other Frameworks

Using Props:

<velt-comment-player-timeline total-media-length="120"></velt-comment-player-timeline>

Using API Method:

const commentElement = Velt.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

<VeltCommentPlayerTimeline offset={10} />

Other Frameworks

<velt-comment-player-timeline offset="10"></velt-comment-player-timeline>

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

Using Props:

<VeltComments bubbleOnPin={true} />

Using API Method:

const commentElement = useCommentUtils();
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();

React / Next.js

Using Props:

<VeltComments bubbleOnPin={true} />

Using API Method:

const commentElement = client.getCommentElement();
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();

Other Frameworks

Using Props:

<velt-comments bubble-on-pin="true">
</velt-comments>

Using API Method:

const commentElement = Velt.getCommentElement();
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

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

React / Next.js

Using Props:

<VeltComments bubbleOnPin={true} bubbleOnPinHover={false} />

Using API Method:

const commentElement = client.getCommentElement();
// To enable/disable showing bubble on pin
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();

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

Other Frameworks

Using Props:

<velt-comments bubble-on-pin="true" bubble-on-pin-hover="false"></velt-comments>

Using API Method:

const commentElement = Velt.getCommentElement();
// 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

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

Other Frameworks

Using Event listener:

const veltCommentsTag = document.querySelector("velt-comments");

veltCommentsTag?.addEventListener("onCommentAdd", (event) => {
  console.log("*** onCommentAdd ***");
  console.log(event.detail);
  event.detail?.addContext({ customKey: "customValue" });
});

Using API method:

const commentElement = Velt.getCommentElement();

commentElement.onCommentAdd().subscribe((event) => {
  event?.addContext({ customKey: "customValue" });
});

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

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

Other Frameworks

Using Event Listener:

const veltCommentsTag = document.querySelector('velt-comments');

veltCommentsTag?.addEventListener('onCommentUpdate', (event) => {
console.log('**_ onCommentUpdate _**');
console.log(event.detail);
});

Using API method:

const commentElement = Velt.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

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

Other Frameworks

if (Velt) {
  const commentElement = Velt.getCommentElement();
  let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
    // Do something with comments
  });
}

To unsubscribe from the subscription:

subscription?.unsubscribe()