Get Started

Key Concepts

Overview
Organizations
Documents
Locations
Users
Access Control

Async Collaboration

Comments
- Overview
- Setup
- Customize Behavior
- Comments Sidebar
- Comments Notifications
- Build Yourself - Standalone Components
In-app Notifications
Inline Reactions
Recorder
View Analytics
Arrows

Realtime Collaboration

Presence
Cursors
Follow Me Mode
Huddle
Live Selection
Live State Sync
Single Editor Mode
Video Player Sync

Email Notifications

Overview

Webhooks

Security

Miscellaneous

Migrate From Cord
Common Integration Questions

Threads

addCommentAnnotation

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

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

deleteCommentAnnotation

Deletes a comment annotation
Params: DeleteCommentAnnotationRequest
Returns: DeleteCommentAnnotationEvent

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

addCommentOnSelectedText

By default, when you highlight over any text in textMode a Comment Tool button will appear. Clicking the button will add a comment on the highlighted text.

If you want to trigger the comment using an API method call instead of clicking the button, you can do the following:

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

addCommentOnElement

Adds a Comment on a specific element by ID.

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

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

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

addManualComment

This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins.
Using this you can manually set the position of Comment Annotations.
Handle click events on your canvas/document and use the this method to create a comment with custom metadata.

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

deleteSelectedComment

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

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

getElementRefByAnnotationId

This will return the Xpath of the DOM element on which the comment was added.

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

getAllCommentAnnotations

To retreive all comments in the frontend, use the useCommentAnnotations() hook. The hook will return an array that contains all current comments.

Whenever there is a change to the comments structure, the hook return value will be updated to the latest change.

The hook will automatically unsubscribe from the subscription when the component dismounts.

import { useCommentAnnotations } from '@veltdev/react';

export default function YourDocument() {

  let commentAnnotations = useCommentAnnotations()

  return (
    <div>
       {commentAnnotations.map(x => <div>{x.annotationId}</div>)}
    </div>
  )
}

By default, useCommentAnnotations() will return data for the current documentId and location.

If you pass in a documentId as an argument, it will return all comments in the given documentId.

If you pass in a documentId as the first argument and a location object as the second argument, it will return all comments in the given documentId and location.

import { useCommentAnnotations } from '@veltdev/react';

export default function YourDocument() {

  let commentAnnotations = useCommentAnnotations('my-document-id', { id:'my-location-id',locationName:"MyLocationName"})

  return (
    <div>
       {commentAnnotations.map(x => <div>{x.annotationId}</div>)}
    </div>
  )
}

getUnreadCommentAnnotationCountOnCurrentDocument

You can get the number of CommentAnnotations that have at least 1 unread Comment on the current Document by using the useUnreadCommentAnnotationCountOnCurrentDocument() hook:

const count = useUnreadCommentAnnotationCountOnCurrentDocument();
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

getUnreadCommentAnnotationCountByLocationId

You can get the number of CommentAnnotations with at least 1 unread Comment by Location Id by using the useUnreadCommentAnnotationCountByLocationId() hook:

const count = useUnreadCommentAnnotationCountByLocationId(locationId);
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

getSelectedComments

Get the currently selected comment annotations.
This returns an array of CommentAnnotation objects.

const commentElement = client.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
  console.log('Selected comments:', selectedComments);
});

Unsubscribe from the subscription when you’re done:

subscription?.unsubscribe()

getCommentAnnotationById

Retrieve a specific comment annotation by its ID.
By default, it will return the comment annotation for the current documentId.
If you pass in a documentId, it will return the comment annotation for the given documentId.

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

Messages

addComment

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

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

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

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

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

updateComment

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

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

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

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

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

deleteComment

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

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

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

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

getComment

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

const getCommentRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

getUnreadCommentCountOnCurrentDocument

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

const count = useUnreadCommentCountOnCurrentDocument();
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

getUnreadCommentCountByLocationId

You can get the number of unread Comments by Location Id by using the useUnreadCommentCountByLocationId() hook:

const count = useUnreadCommentCountByLocationId(locationId);
useEffect(() => {
  console.log(count, 'countObj')
}, [count])

getUnreadCommentCountByAnnotationId

You can get the number of unread Comments by annotation id by using the useUnreadCommentCountByAnnotationId() hook:

const count = useUnreadCommentCountByAnnotationId(annotationId);
useEffect(() => {
   console.log(count, 'countObj')
}, [count])

@Mentions

updateContactList

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

Using Hooks:

const contactElement = useContactUtils();

useEffect(() => {
  contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: false});
}, [contactElement]);

Using API:

const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: false});

updateContactListScopeForOrganizationUsers

Sometimes you may want to show only certain types of contacts in the contact dropdown.
By default, organization users will see all contacts in the organization, any user groups and any contacts added to the document.
Using this method, you can restrict the contacts shown in the dropdown to only certain types.
This only affects the Organization Users and not the Document Users. Document Users will always only see contacts added to the document.

Here are the available options:

all: Show all the contacts
organization: Show organization contacts.
organizationUserGroup: Show organization user groups.
document: Show document contacts.

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

assignUser

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

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

enableUserMentions

This allows you to enable or disable user @mentions.

Whether user @mentions are enabled.

Default: true

Using Props:

<VeltComments userMentions={false} />

Using Hooks:

const contactElement = useContactUtils();

useEffect(() => {
  contactElement.enableUserMentions();
  contactElement.disableUserMentions();
}, [contactElement]);

Using API Method:

const contactElement = client.getContactElement();
contactElement.enableUserMentions();
contactElement.disableUserMentions();

onContactSelected

This event is triggered when a contact is selected from the contact dropdown in the Comment Dialog.
Use the event object to determine if the selected contact has access to the document using fields like isOrganizationContact, isDocumentContact and documentAccessType.
If the selected contact doesn’t have access to the document, you can show an invite dialog to the user to invite the contact to the document.

The returned data will be in the following schema:

export class UserContactSelectedPayload {
    contact!: UserContact; // Selected Contact.
    isOrganizationContact!: boolean; // Is user part of organization contact.
    isDocumentContact!: boolean; // Is user part of document contact.
    documentAccessType!: string; // Document access type.
}

Using Hooks:

const selectedContact = useContactSelected();

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

Using API:

const contactElement = client.getContactElement();

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

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.

Hooks:

const contactElement = useContactUtils();

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

API:

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

setAtHereLabel

This allows you to modify the default text of the @here feature. eg: @all, @everyone, @team, etc.

Using Props:

<VeltComments atHereLabel='@all'>

Using Hooks:

const contactElement = useContactUtils();

useEffect(() => {
  contactElement.setAtHereLabel('@all');
}, [contactElement]);

Using API Method:

const contactElement = client.getContactElement();
contactElement.setAtHereLabel('@all');

setAtHereDescription

Customize the description that appears for the @here mention.

Using Props:

<VeltComments atHereDescription="Notify all users in this document" />

Using Hooks:

const contactElement = useContactUtils();

useEffect(() => {
  contactElement.setAtHereDescription('Notify all users in this document');
}, [contactElement]);

Using API Method:

const contactElement = client.getContactElement();
contactElement.setAtHereDescription('Notify all users in this document');

subscribeCommentAnnotation

Subscribes to a comment annotation
Params: SubscribeCommentAnnotationRequest
Returns: SubscribeCommentAnnotationEvent

const subscribeCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

unsubscribeCommentAnnotation

Unsubscribes from a comment annotation
Params: UnsubscribeCommentAnnotationRequest
Returns: UnsubscribeCommentAnnotationEvent

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

Metadata

addContext

Custom metadata allows you to add extra information to comments, enhancing their functionality. Here’s what you can do with it:

Render additional data on comments
Position comment pins manually
Create custom UI components
Enable comment filtering on custom data

To add custom metadata, use the event.addContext() method when a comment is added. This method accepts an object with key-value pairs.

// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
  if (commentEventCallbackData) {
    commentEventCallbackData.addContext({ customKey: 'customValue' });
  }
}, [commentEventCallbackData]);

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

updateContext

Update the custom metadata associated with a comment annotation using the updateContext method.
Utilize this method to update the context of a comment annotation at any time. For example, you might use this when the name of the dashboard containing the comment annotation changes.

The commentElement.updateContext() method accepts three parameters:

The Comment Annotation ID
The new metadata object
An optional updateContextConfig object. Specify how the new metadata should be applied:
- { merge: true }: Merges the new metadata with the existing metadata
- { merge: false } or omitted: Replaces the existing metadata entirely (default behavior)

Using API:

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

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

Custom Lists

createCustomListDataOnAnnotation

Add a custom dropdown list at the Comment Annotation level.
Use this to add custom tags or categories to the comment.

let customList = [
    { id: 'violent', label: 'Violent' },
    { id: 'inappropriate', label: 'Inappropriate' },
    { id: 'robbery', label: 'Robbery' },
    { id: 'nsfw', label: 'NSFW' },
];

const customListDataOnCommentAnnotation = {
	  type: 'multi', // choose from 'multi' or 'single'
    placeholder: 'Select a category',
    data: customList, // your customList data here
};

Using Props:

<VeltComments customListDataOnAnnotation={customListDataOnCommentAnnotation} />

API Method:

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

createCustomListDataOnComment

You can have custom dropdown lists appear when certain hotkeys are pressed.

When you press a hotkey inside the Comment Dialog composer, it will open a dropdown list of items that you can select.

Selecting an item frop the dropdown list will add a chip that inside the comment text.

Set hotkey and list data

Make sure the hotkey is a single character such as # or /

Create the list of data will be shown when the hotkey is pressed. Eg: When the user presses #, the list of files or links from other parts of your app is shown.
The items in the list must be in the following schema:

export class AutocompleteItem {
    id!: string; // Unique identifier
    name!: string; // Item name. This appears as the main item text in the UI.
    description?: string; // Item description. This appears as the secondary item text in the UI.
    icon?: { url?: string, svg?: string }; // Item icon. This appears as the icon in the UI.
    link?: string; // Item link. You can use this to open a link when the item is clicked. Check the event listener below for more details.
}

let customList = [
    {
        id: '1',
        name: 'File 1',
        description: 'File Description 1',
        icon: {url: 'https://cdn-icons-png.flaticon.com/512/9496/9496432.png'}
    },
    {
        id: '2',
        name: 'File 2',
        description: 'File Description 2',
        icon: {url: 'https://cdn-icons-png.flaticon.com/512/11471/11471469.png'}
    },
    {
        id: '3',
        name: 'File 3',
        description: 'File Description 3',
        icon: {url: 'https://cdn-icons-png.flaticon.com/512/2656/2656402.png'}
    }
];

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

Using Props:

<VeltComments customListDataOnComment={customListDataOnComment} />

API Method:

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

Listen to click event data on chips

After the comment is saved, the item will be rendered as a chip on the comment content.
When the user clicks on it, you will get an event callback with the data of the clicked chip (AutocompleteItem).

This event will also be triggered when the user clicks on the contact chips added via the @mentions feature.

let autocompleteChipData = useAutocompleteChipClick(); 

Event Subscription

on

Subscribe to Comment Events.
Here is the list of events you can subscribe to.
Here is the list of objects you will receive in the callback.

// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
  if (commentEventCallbackData) {
    // Handle comment action callback event response
  }
}, [commentEventCallbackData]);

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

Attachments

enableAttachments

Whether file attachments are enabled.

Default: true

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

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

<VeltComments attachments={true} />

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

addAttachment

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

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

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

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

deleteAttachment

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

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

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

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

getAttachment

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

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

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

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

Reactions

enableReactions

Whether emoji reactions are enabled.

Default: true

<VeltComments reactions={true} />

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

setCustomReactions

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

const commentElement = client.getCommentElement();

const customReactions = {
    "reactionId1": {
        "url": "EMOJI_URL"
    },
    "reactionId2": {
        "svg": "EMOJI_SVG"
    },
    "reactionId3": {
        "emoji": "🤣" // emoji as a text
    }
}
commentElement.setCustomReactions(customReactions);

addReaction

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

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

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

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

deleteReaction

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

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

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

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

toggleReaction

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

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

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

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

Status & Priority

enableStatus

Whether to enable the default status dropdown & filters.

Default: true

When this is on, users can assign a status to each comment & filter comment by status in the sidebar. You can customize the list of status options as shown below on this page.

<VeltComments status={true} />

API Method:

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

setCustomStatus

Set custom statuses in the customStatus prop.

Default statuses: Open, In Progress, Resolved

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.

Setting the Status type using the type property:

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.

Setting the Status Icon using the svg property:

You can pass in a serialized SVG. We automatically parse and colorize SVGs. If instead you pass in an icon URL, you will have to colorize each icon yourself to match the status color.

<VeltComments customStatus={[
  {
    "id": "open",
    "name": "Open",
    "color": "white",
    "lightColor":"green",
    "type": "default",
    "svg": "<svg></svg>" // Pass in a serialized SVG
  }
]}/>

API Method:

const commentElement = client.getCommentElement();
commentElement.setCustomStatus([
  {
    "id": "open",
    "name": "Open",
    "color": "white",
    "lightColor":"green",
    "type": "default",
    "svg": "<svg></svg>" // Pass in a serialized SVG
  }
])

Make sure to have at least 2 categories set.

enableResolveButton

Whether to show resolve button on comments.

Default: true

This adds a tick mark button on the top right corner of the comment dialog. Clicking on this button will mark the comment as resolved.

<VeltComments resolveButton={true} />

API Method:

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

updateStatus

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

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

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

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

resolveCommentAnnotation

Resolves a comment annotation
Params: ResolveCommentAnnotationRequest
Returns: ResolveCommentAnnotationEvent

const resolveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

enablePriority

Whether to enable setting priority on comments.

Default: false

When this is on, users can assign a priority to each comment & filter comment by priority in the sidebar. You can customize the list of priority options as shown later on this page in the Set Custom Priorities section.

<VeltComments priority={true} />

API Method:

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

setCustomPriority

Pass custom priorities in the customPriority prop.

Default priorities: P0, P1, P2

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

This will work if you have enabled the priority feature.

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

The lightColor property sets the background color of the filter.

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

API Method:

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

Make sure to have at least 2 categories set.

updatePriority

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

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

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

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

Recording

deleteRecording

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

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

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

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

getRecording

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

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

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

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

setAllowedRecordings

Set the Recorder media options within Comments: (audio, screen, video, all).

audio: enables audio recording
screen: enables screen recording
video: enables video recording
all: enables all recording options

Default: "audio"

Using Props:

enableRecordingCountdown

Whether the Recorder countdown is enabled.

Default: true

<VeltComments recordingCountdown={false} />

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

enableRecordingTranscription

Controls whether to enable AI transcription for recordings.

Default: enabled

Using Props:

<VeltComments recordingTranscription={false} />

Using API Methods:

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

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

Deep Link

getLink

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

const getLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

copyLink

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

const copyLinkRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

scrollToCommentByAnnotationId

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

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

selectCommentByAnnotationId

Use this to programatically select a comment annotation by its id.
Example: If the user opens a comment url from an email notification, you can use this open the comment dialog after your page has finished rendering.

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

onCommentSelectionChange

The useCommentSelectionChangeHandler hook can be used to subscribe to Comment selection changes.

import React, { useEffect } from 'react';
import { useCommentSelectionChangeHandler } from '@veltdev/react';

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

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

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

enablescrollToComment

Whether, users will be scrolled to the location of a Comment when it is clicked.

Default: true

By default, users will be redirected to a Comment if the comment id is provided in the url. But sometimes this experience is annoying, so we have provided a way to disable the option to automatically scroll users to the location of the Comment.

To disable the feature, set scrollToComment to false.

<VeltComments scrollToComment={false}/>

API methods:

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

DOM Controls

allowedElementIds

allowedElementClassNames

allowedElementQuerySelectors

Provide a list of element DOM IDs, class names, or query selectors where commenting should be allowed.

Comments will be disabled for all other elements. Note, this does not impact Popover mode.

Using Props:

<VeltComments 
  allowedElementIds={['some-element']} 
  allowedElementClassNames={["class-name-1", "class-name-2"]}
  allowedElementQuerySelectors={["#id1.class-name-1"]}
/>

Using API Method:

const commentElement = client.getCommentElement();
commentElement.allowedElementIds['some-element'];
commentElement.allowedElementClassNames(["class-name-1", "class-name-2"]);
commentElement.allowedElementQuerySelectors(["#id1.class-name-1"]);

data-velt-comment-disabled

Disable certain elements from being commented on.

Add the data-velt-comment-disabled attribute to elements where you want to disable commenting.

<div data-velt-comment-disabled></div>

sourceId

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

<VeltCommentTool sourceId="sourceId1" />

AI Categorization

enableAutoCategorize

Whether AI auto-categorization of comments is enabled.

Default: false

We use AI to analyze your comment content and auto-categorize it so users can filter comments easily. You can provide a list of custom categories that we should use to categorize the comments (shown below).

<VeltComments autoCategorize={true} />

API Method:

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

setCustomCategory

Pass custom categories in the customCategory prop.

Default categories: Question, Feedback, Bug, Other.

With custom categories, you can replace the default categories with your own values.

These categories are used in the Comments Sidebar to filter comments by category. The AI autoCategorize feature uses the list of categories to determine the closest category to choose from.

The input format to the customCategory prop should be an array of objects with an id, name, and color.

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

<VeltComments customCategory={[
  {
    "id": "bug",
    "name": "Bug",
    "color": "red"
  }
]}/>

API Method:

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

Make sure to have at least 2 categories set.

UI

updateCommentDialogPosition

Sometimes when you manually set the position of the Comment Pin, the Comment Dialog might not position itself near the pin in certain scenarios like scrolling, zooming the page when the comment dialog is open.
Use this to manually trigger an update. The dialog will reposition itself near the pin.

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

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

enableSidebarButtonOnCommentDialog

Whether the Sidebar Button on Comment Dialogs show up.

Default: true

By Default, each Comment Dialog has a button at the bottom that will open the Comments Sidebar when clicked.

To disable it, you can set it to false:

Using Props:

<VeltComments sidebarButtonOnCommentDialog={true} />

Using API methods:

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

onSidebarButtonOnCommentDialogClick

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

Using Props:

<VeltComments onSidebarButtonOnCommentDialogClick={(event)=>yourMethod(event)} />

Using Hooks:

const commentDialogSidebarClickEvent = useCommentDialogSidebarClickHandler();
useEffect(() => {
  console.log('CommentDialog Sidebar button clicked');
}, [commentDialogSidebarClickEvent]);

Using API methods:

const commentElement = client.getCommentElement();
let subscription = commentElement.onSidebarButtonOnCommentDialogClick().subscribe((event) => yourMethod(event));

To unsubscribe from the subscription:

subscription?.unsubscribe()

enableDeleteReplyConfirmation

You can enable a confirmation dialog before deleting a reply in comment threads. This feature helps prevent accidental deletions and improves user experience.

Using Props:

<VeltComments deleteReplyConfirmation={true} />

Using API:

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

enableMobileMode

Whether mobile mode is enabled.

When mobile mode is enabled and the screen width is small enough, comment windows will appear fixed to the bottom of the screen and full width instead of the usual popup window.

Default: false

<VeltComments mobileMode={true} />

API Method:

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

enableCommentPinHighlighter

Wheter the pin highlighter outline is enabled or not.

Default: true

<VeltComments commentPinHighlighter={false} />

API Methods:

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

composerMode

By default, the Composer in the Comments Dialog only shows the text input box and does not show the actions bar until the Composer is clicked on or the user starts typing.

You can modify this behavior by setting the Composer Mode prop to "expanded". This will make the actions bar always visible.

To keep the default behavior you can set the property to "default".

Default: "default"

<VeltComments composerMode="expanded"/>

showCommentsOnDom

Whether comments are shown on the DOM.

Default: true

By default, all the comments will be visible on DOM whenever we are able to detect to elements for that. But users can hide it from DOM if required.

There are 2 ways to show/hide comments on DOM:

Configuring attributes on the React Component:

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

Using API methods:

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

enableDialogOnHover

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

Default: true

<VeltComments dialogOnHover={true} />

API Method:

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

enableFloatingCommentDialog

Whether floating comment dialog is shown next to comment pin on hover or click.

Default: true

<VeltComments floatingCommentDialog={true} />

API Method:

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

showResolvedCommentsOnDom

Whether to show resolved comments on the DOM.

Default: false

<VeltComments resolvedCommentsOnDom={true} />

API Methods:

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

enableCollapsedComments

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

Default: true

Using Props:

<VeltComments collapsedComments={false} />

Using API:

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

enableShortUserName

You can control whether long user names should be shortened. For long names, this will first create an initial of the second name and if the name is still long, it will truncate it with ellipses.

Default: true

Using Props:

<VeltComments shortUserName={false} />

Using API:

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

excludeLocationIds

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

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

To reset it, you can pass an empty array:

client.excludeLocationIds([]);

enableSignInButton

Whether to enable Sign In button on comment dialog when user is anonymous or signed out.

Default: false

This allows anonymous or signed out users to still read the comments but encourages them to sign in if they want to respond to the comments.

<VeltComments signInButton={true} />

API Method:

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

onSignIn

When the user clicks on the sign in button, we will emit an onSignIn event that you can handle with your own sign in method.

No data is passed with the event.

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

Extra Information

enableCommentIndex

Whether comment index is enabled.

Default: false

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

<VeltComments commentIndex={true} />

API Method:

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

enableDeviceInfo

Whether device type indicator is enabled.

Default: false

When this is on, we show additional information in the Comment Thread indicating which device the comment was created on. This is useful especially for design tools, where additional context is needed for debugging issues.

<VeltComments deviceInfo={true} />

API Method:

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

enableDeviceIndicatorOnCommentPins

Whether the device type indicator on Comment Pins is enabled.

Default: false

When this is on, we show a small device type icon on the Comment Pin indicating which device the comment was created on. This is useful especially for design tools, where additional context is needed for debugging issues.

<VeltComments deviceIndicatorOnCommentPins={true} />

API Method:

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

enableGhostComments

Whether to show ghost comments on the DOM.

Default: false

Ghost comments are comments that were once linked to certain content on the DOM but that content is no longer available. If this is on, we display ghost comments in gray, close to where they were originally positioned on the DOM.

<VeltComments ghostComments={true} />

Using API methods:

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

enableGhostCommentsIndicator

Whether to show ghost comment labels in the comment sidebar.

Default: true

Ghost comments are always shown in the comments sidebar so that users can see the history of all comments. If this is on, we show a label on the comment in the sidebar indicating that the original content on which this comment was added is no longer available. This sets better expectations with the users.

<VeltComments ghostCommentsIndicator={true} />

Using API methods:

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

Special File Type Support

Iframe Container Support

To enable comments on an iframe, add data-velt-iframe-container="true" to the iframe’s container element.
Note this will not insert the comments inside the contents of the iframe, but rather on top of the iframe.

<div data-velt-iframe-container="true">
	<iframe src="https://www.wikipedia.org/" width="500px" height="500px"></iframe>
</div>

data-velt-pdf-viewer

To support comments on top of a pdf viewer, add the data-velt-pdf-viewer="true" attribute in the container element of the pdf viewer.

<!-- Add this attribute to the container of your pdf viewer -->
<div id="viewerContainer" data-velt-pdf-viewer="true">
    <!-- Your pdf viewer here -->
    <div id="viewer" class="pdfViewer"></div>
</div>

Keyboard Controls

enableHotkey

Whether Hotkeys are enabled or not. For now, the only hotkey supported is pressing c to enable comment mode.

Default: false

Using Props:

<VeltComments hotkey={false} />

Using API Method:

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

enableEnterKeyToSubmit

By default, pressing enter will add a new line and pressing shift + enter will submit a comment.
You can change this default behavior so that pressing enter will submit a comment by setting the enterKeyToSubmit property to true.

Using Props:

<VeltComments enterKeyToSubmit={true} />

Using API Method:

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

enableDeleteOnBackspace

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

Default: enabled

Using Props:

<VeltComments deleteOnBackspace={false} />

Using API:

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

Moderation

enableModeratorMode

Whether comments require moderator approval.

Default: false

By default, when a user adds a comment it is visible to all authenticated users on the same document. Moderator mode makes visibility of all comments private to only admin users and the comment author. Admin users will see an approve button on the comment dialog. Once approved the comment will be visible to all users who can access the document.

You can set some users as admin by setting the isAdmin property in the User object, during the identify() call.

<VeltComments moderatorMode={true} />

API Method:

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

enableResolveStatusAccessAdminOnly

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

Using props:

<VeltComments resolveStatusAccessAdminOnly={true} />

Using API:

const commentElement = client.getCommentElement();
// To enable resolve status access admin only
commentElement.enableResolveStatusAccessAdminOnly();
// To disable resolve status access admin only
commentElement.disableResolveStatusAccessAdminOnly();

approveCommentAnnotation

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

const approveCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

acceptCommentAnnotation

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

const acceptCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

rejectCommentAnnotation

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

const rejectCommentAnnotationRequest = {
  annotationId: 'ANNOTATION_ID'
};

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

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

enableSuggestionMode

Whether to enable suggestion mode to accept or reject comments.

Default: false

To accept comments, set the suggestionMode attribute to true.

<VeltComments suggestionMode={true} />

API Method:

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

updateAccess

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

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

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

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

enablePrivateComments

Private comment mode enables admin users to add comments that are only visible to other admin users.
Use this to enable or disable private comment mode.

Default: false

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

<VeltComments privateCommentMode={true} />

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

const commentElement = client.getCommentElement();
// To enable private comment mode
commentElement.enablePrivateCommentMode();
// To disable private comment mode
commentElement.disablePrivateCommentMode();

enableReadOnly

Control whether comments are in read-only mode. When enabled, any features requiring user interaction (e.g., Composer, Reactions, Status) will be removed.

Default: false

Using Props:

<VeltComments readOnly={true} />

Using API:

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

Comment Read Status

enableSeenByUsers

Control whether the “Seen By” feature is enabled for comments. When enabled, it shows which users have seen each comment.

Default: true

Using Props:

<VeltComments seenByUsers={false} />

Using API:

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

setUnreadIndicatorMode

Whether verbose mode is enabled for unread Comments.

Default: 'minimal'

Unread Comments can be in minimal mode or verbose mode.

In minimal mode, a small red dot indicator appears for unread Comments.

In verbose mode, a larger badge with the text “UNREAD” will appear for unread Comments.

<VeltComments unreadIndicatorMode={"verbose"} />

API Method:

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

Toggle Comment Types

enableAreaComment

Area comments allows users to draw a rectangle and attach a comment to it. Use this to enable or disable area comments.

Default: true

Using Props:

<VeltComments areaComment={false} />

Using API Method:

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

enableInboxMode

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

Whether Inbox Mode is enabled.

Default: false

Using Props:

<VeltComments inboxMode={true} />

Using API:

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

enablePopoverMode

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

Whether Popover Mode is enabled.

Default: false

<VeltComments popoverMode={true}/>

Using API:

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

enableStreamMode

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

Whether Stream Mode is enabled.

Default: false

<VeltComments streamMode={true}/>

Using API:

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

enableTextMode

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

Whether Text Mode is enabled.

Default: true

Using Props:

<VeltComments textMode={true}/>

Using API:

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

enableInlineCommentMode

Whether In-line comment mode is enabled.

When In-line comment mode is enabled, comments will appear under the text they are associated with in the DOM, instead of as a pop up window.

Default: false

<VeltComments inlineCommentMode={true}/>

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

enableMultithread

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

<VeltComments multiThread={true} />

Comment Tool

enableCommentMode

Turns Comment mode on or off.

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

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

onCommentModeChange

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

The useCommentModeState() hook can be used to get the Comment mode without having to subscribe to changes. When the Comment mode changes, the hook return value will update.

The subscription is automatically unsubscribed when the component dismounts.

import { useCommentModeState } from '@veltdev/react';

export default function YourDocument() {

  let commentModeState = useCommentModeState()

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

enableCommentTool

Whether the Comment Tool button is Enabled.

Default: true

When the Comment Tool is disabled, it can not be used to leave comments. Other ways to leave comments, such as highlighting text, will also be disabled.

Using Props:

<VeltComments commentTool={false} />

Using API methods:

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

enableChangeDetectionInCommentMode

By default, DOM Change Detection is disabled in Comment Mode for better performance.
You can enable it to automatically reposition comment pins when the DOM changes while in Comment Mode.

Default: false

Using Props:

<VeltComments changeDetectionInCommentMode={true} />

Using API Method:

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

enablePersistentCommentMode

When Persistent comment mode is enabled, you can continue leave additional comments after finishing a comment.
When it is disabled, you will need to reclick the Comment Tool every time when you want to make a comment.

Default: false

<VeltComments persistentCommentMode={true}/>

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

setPinCursorImage

You can set custom mouse cursor when the comment mode is on. The custom cursor image must be 32 x 32 pixels.

<VeltComments pinCursorImage={BASE64_IMAGE_STRING} />

API Methods:

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

Minimap

enableMinimap

The minimap shows a bar on the edge of the screen with indicators that show where comments exist.
Use this to enable/disable the minimap. By default it’s disabled.
It can be positioned left or right. By default, it’s positioned on the right side of the screen.

Option a. Enable using config:

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

API Method:

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

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

<div className="relative-container">
  <VeltCommentsMinimap targetScrollableElementId="scrollableElement" position="left" />
  <div id="scrollableElement">
      {/* scrollable content */}
  </div>
</div>

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

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

Inline Comments

sortData

Change the default sorting order of Comments in the Inline Comments Section.
Default: none

There are three options for sorting:

asc: Show comment annotations in ascending order of when they were last updated
desc: Show comment annotations in descending order of when they were last updated
none: Show comment annotations in the sequence they were added

<VeltInlineCommentsSection sortData="desc" />

multiThread

By default inline comment section is multithreaded.
You can make it single threaded by setting multiThread prop to false.
Default: true

<VeltInlineCommentsSection multiThread={false} />

enableDialogOnTargetElementClick

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

Default: true

<VeltComments dialogOnTargetElementClick={true} />

API Method:

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

enablePopoverTriangleComponent

Whether the popover triangle appears when Popover Mode is enabled.

Default: true

<VeltComments popoverTriangleComponent={true}/>

API Method:

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

Comment Bubble

commentCountType

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

Default: 'total'

commentCountType: This prop allows you to decide which count to display.

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

<VeltCommentBubble commentCountType={"unread"} />

Video Timeline Comments

setTotalMediaLength

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

Using Props:

<VeltCommentPlayerTimeline totalMediaLength={120} />

Using API Method:

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

offset

Allows comment bubbles to be positioned relative to both parent and child video clips by specifying an offset value.
Default: 0

<VeltCommentPlayerTimeline offset={10} />

Comment Pin

enableBubbleOnPin

Show a Comment Bubble when user hovers or clicks on the Comment Pin vs showing the Comment Dialog. The comment dialog will open only on clicking the comment bubble.

Default: 'false'

Using Props:

<VeltComments bubbleOnPin={true} />

Using API Method:

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

enableBubbleOnPinHover

Show a Comment Bubble when user hovers on the Comment Pin vs clicks on it.

Default: 'true'

Using Props:

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

Using API Method:

const commentElement = useCommentUtils();

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

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

Was this page helpful?

Inbox Setup Overview

On this page

Threads
addCommentAnnotation
deleteCommentAnnotation
addCommentOnSelectedText
addCommentOnElement
addManualComment
deleteSelectedComment
getElementRefByAnnotationId
getAllCommentAnnotations
getUnreadCommentAnnotationCountOnCurrentDocument
getUnreadCommentAnnotationCountByLocationId
getSelectedComments
getCommentAnnotationById
Messages
addComment
updateComment
deleteComment
getComment
getUnreadCommentCountOnCurrentDocument
getUnreadCommentCountByLocationId
getUnreadCommentCountByAnnotationId
@Mentions
updateContactList
updateContactListScopeForOrganizationUsers
assignUser
enableUserMentions
onContactSelected
enableAtHere
setAtHereLabel
setAtHereDescription
subscribeCommentAnnotation
unsubscribeCommentAnnotation
Metadata
addContext
updateContext
Custom Lists
createCustomListDataOnAnnotation
createCustomListDataOnComment
Event Subscription
on
Attachments
enableAttachments
addAttachment
deleteAttachment
getAttachment
Reactions
enableReactions
setCustomReactions
addReaction
deleteReaction
toggleReaction
Status & Priority
enableStatus
setCustomStatus
enableResolveButton
updateStatus
resolveCommentAnnotation
enablePriority
setCustomPriority
updatePriority
Recording
deleteRecording
getRecording
setAllowedRecordings
enableRecordingCountdown
enableRecordingTranscription
Deep Link
getLink
copyLink
Navigation
scrollToCommentByAnnotationId
selectCommentByAnnotationId
onCommentSelectionChange
enablescrollToComment
DOM Controls
allowedElementIds
allowedElementClassNames
allowedElementQuerySelectors
data-velt-comment-disabled
sourceId
AI Categorization
enableAutoCategorize
setCustomCategory
UI
updateCommentDialogPosition
enableSidebarButtonOnCommentDialog
onSidebarButtonOnCommentDialogClick
enableDeleteReplyConfirmation
enableMobileMode
enableCommentPinHighlighter
composerMode
showCommentsOnDom
enableDialogOnHover
enableFloatingCommentDialog
showResolvedCommentsOnDom
enableCollapsedComments
enableShortUserName
excludeLocationIds
enableSignInButton
onSignIn
Extra Information
enableCommentIndex
enableDeviceInfo
enableDeviceIndicatorOnCommentPins
enableGhostComments
enableGhostCommentsIndicator
Special File Type Support
Iframe Container Support
data-velt-pdf-viewer
Keyboard Controls
enableHotkey
enableEnterKeyToSubmit
enableDeleteOnBackspace
Moderation
enableModeratorMode
enableResolveStatusAccessAdminOnly
approveCommentAnnotation
acceptCommentAnnotation
rejectCommentAnnotation
enableSuggestionMode
updateAccess
enablePrivateComments
enableReadOnly
Comment Read Status
enableSeenByUsers
setUnreadIndicatorMode
Toggle Comment Types
enableAreaComment
enableInboxMode
enablePopoverMode
enableStreamMode
enableTextMode
enableInlineCommentMode
enableMultithread
Comment Tool
enableCommentMode
onCommentModeChange
enableCommentTool
enableChangeDetectionInCommentMode
enablePersistentCommentMode
setPinCursorImage
Minimap
enableMinimap
Inline Comments
sortData
multiThread
Popover Comments
enableDialogOnTargetElementClick
enablePopoverTriangleComponent
Comment Bubble
commentCountType
Video Timeline Comments
setTotalMediaLength
offset
Comment Pin
enableBubbleOnPin
enableBubbleOnPinHover

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Email Notifications

Webhooks

Security

Miscellaneous

​Threads

​addCommentAnnotation

​deleteCommentAnnotation

​addCommentOnSelectedText

​addCommentOnElement

​addManualComment

​deleteSelectedComment

​getElementRefByAnnotationId

​getAllCommentAnnotations

​getUnreadCommentAnnotationCountOnCurrentDocument

​getUnreadCommentAnnotationCountByLocationId

​getSelectedComments

​getCommentAnnotationById

​Messages

​addComment

​updateComment

​deleteComment

​getComment

​getUnreadCommentCountOnCurrentDocument

​getUnreadCommentCountByLocationId

​getUnreadCommentCountByAnnotationId

​@Mentions

​updateContactList

​updateContactListScopeForOrganizationUsers

​assignUser

​enableUserMentions

​onContactSelected

​enableAtHere

​setAtHereLabel

​setAtHereDescription

​subscribeCommentAnnotation

​unsubscribeCommentAnnotation

​Metadata

​addContext

​updateContext

​Custom Lists

​createCustomListDataOnAnnotation

​createCustomListDataOnComment

Set hotkey and list data

Listen to click event data on chips

​Event Subscription

​on

​Attachments

​enableAttachments

​addAttachment

​deleteAttachment

​getAttachment

​Reactions

​enableReactions

​setCustomReactions

​addReaction

​deleteReaction

​toggleReaction

​Status & Priority

​enableStatus

​setCustomStatus

​enableResolveButton

​updateStatus

​resolveCommentAnnotation

​enablePriority

​setCustomPriority

​updatePriority

​Recording

​deleteRecording

​getRecording

​setAllowedRecordings

​enableRecordingCountdown

​enableRecordingTranscription

​Deep Link

​getLink

​copyLink

​Navigation

Threads

addCommentAnnotation

deleteCommentAnnotation

addCommentOnSelectedText

addCommentOnElement

addManualComment

deleteSelectedComment

getElementRefByAnnotationId

getAllCommentAnnotations

getUnreadCommentAnnotationCountOnCurrentDocument

getUnreadCommentAnnotationCountByLocationId

getSelectedComments

getCommentAnnotationById

Messages

addComment

updateComment

deleteComment

getComment

getUnreadCommentCountOnCurrentDocument

getUnreadCommentCountByLocationId

getUnreadCommentCountByAnnotationId

@Mentions

updateContactList

updateContactListScopeForOrganizationUsers

assignUser

enableUserMentions

onContactSelected

enableAtHere

setAtHereLabel

setAtHereDescription

subscribeCommentAnnotation

unsubscribeCommentAnnotation

Metadata

addContext

updateContext

Custom Lists

createCustomListDataOnAnnotation

createCustomListDataOnComment

Event Subscription

on

Attachments

enableAttachments

addAttachment

deleteAttachment

getAttachment

Reactions

enableReactions

setCustomReactions

addReaction

deleteReaction

toggleReaction

Status & Priority

enableStatus

setCustomStatus

enableResolveButton

updateStatus

resolveCommentAnnotation

enablePriority

setCustomPriority

updatePriority

Recording

deleteRecording

getRecording

setAllowedRecordings

enableRecordingCountdown

enableRecordingTranscription

Deep Link

getLink

copyLink

Navigation

scrollToCommentByAnnotationId

selectCommentByAnnotationId

onCommentSelectionChange

enablescrollToComment

DOM Controls

allowedElementIds

allowedElementClassNames

allowedElementQuerySelectors

data-velt-comment-disabled

sourceId