Source of truth: exhaustive for what it covers. Generated from Velt hook metadata. If a name isn’t on this page, it doesn’t exist: don’t use it (a missing identifier resolves to undefined / renders nothing). Never invent or guess a name; use only identifiers that appear verbatim here or that you verified against ground truth and added here. Scope: exhaustive over @veltdev/react’s hook exports. Comment + notification + core hooks are documented in full; the remaining other-feature hooks are listed by name + return type + one-line purpose in “Other features (brief)” below: enough to keep the “a hook not listed doesn’t exist” invariant true, without full per-hook depth.
Headless) or to add data-driven extras alongside any approach. All from @veltdev/react. Types from @veltdev/types.
Grouped by purpose: read (data/state you render), mutate (actions you call), events (callbacks), control (init/scope/imperative). This lists the commonly-used comment hooks plus a brief map of other features; the SDK exports many more hooks following the same naming, but everything you need for the patterns in this guide is here.
Exhaustive over @veltdev/react’s hook exports: a hook not listed here doesn’t exist (source-of-truth invariant).
Read: data & state
| Hook | Returns / use |
|---|
useCommentAnnotations() | Reactive CommentAnnotation[] (or null before load) on the current document. The main data source. Use useCommentAnnotations() ?? []. |
useGetCommentAnnotations(query?) | Reactive, filtered query → GetCommentAnnotationsResponse ({ annotations, count, … }), not a bare array. |
useCommentAnnotationById({ annotationId }) | One annotation by id. |
useCommentAnnotationsCount(query?) | GetCommentAnnotationsCountResponse (read its count field), not a bare number. |
useCommentModeState() | Whether comment mode is active. |
useCommentSidebarData() | Data backing the sidebar (filters/sorted list). |
useUnreadCommentCountOnCurrentDocument() | Unread comment count on the current document → UnreadCommentsCount object { count } | null. Read .count. |
useCurrentUser() | The identified user. |
useCurrentUserPermissions() | Current user’s permissions. |
useUnreadCommentAnnotationCountOnCurrentDocument() | Returns UnreadCommentsCount: an object { count } | null, not a number. Read .count (e.g. data?.count ?? 0). Great for badges. |
useUnreadCommentCountByAnnotationId() / useUnreadCommentCountByLocationId() | Unread counts scoped to a thread / location. |
useUnreadCommentAnnotationCountByLocationId() | Unread annotation count by location. |
Return shapes matter. Several read hooks return wrapper objects, not bare values (…Count* → { count }; useGetCommentAnnotations → a response object). Read the field, don’t render the object. When unsure of a return shape, console.log the hook’s value in your component to see it before rendering.
Mutate: actions
| Hook | Action |
|---|
useAddCommentAnnotation() | Create a new annotation (a new thread). |
useAddComment() | Add a comment/reply to an annotation. |
useUpdateComment() | Edit a comment. |
useDeleteComment() | Delete a single comment. |
useDeleteCommentAnnotation() | Delete a whole thread. |
useResolveCommentAnnotation() | Resolve a thread. |
useApproveCommentAnnotation() / useRejectCommentAnnotation() | Approval flows. |
useUpdateStatus() | Set a thread’s status. |
useUpdatePriority() | Set priority. |
useAssignUser() | Assign a user to a thread. |
useUpdateAccess() | Change a thread’s access/visibility. Returns { updateAccess }; await updateAccess(request: UpdateAccessRequest) → Promise<UpdateAccessEvent | null>. Writes CommentAnnotation.iam.accessMode (public vs private). |
useAddReaction() / useDeleteReaction() / useToggleReaction() | Reactions. |
useAddAttachment() / useDeleteAttachment() / useGetAttachment() | Attachments. |
useGetLink() / useCopyLink() | Deep link to a comment. |
useGetComment() | Returns { getComment }; await getComment(request) → Comment[] (imperative fetch, not reactive). |
useGetRecording() / useDeleteRecording() | Returns { getRecording } / { deleteRecording }; fetch or delete a recording attached to a comment. |
const { addComment } = useAddComment(); then await addComment({ annotationId, comment }).
Events: callbacks
| Hook | Fires on |
|---|
useCommentEventCallback() | Generic comment events. |
useCommentAddHandler() / useCommentUpdateHandler() | A comment added / updated. |
useCommentSelectionChangeHandler() | Selected thread changes. |
useCommentCopyLinkHandler() | A copy-link action. |
useCommentActionCallback(action) | Typed callback for a specific comment action (CommentEventTypesMap[action]). |
useCommentSidebarActionButtonClick() | A custom sidebar action-button click → CommentSidebarCustomActionEventData | null. |
useCommentSidebarInit() | Fires when the comment sidebar initializes. |
useCommentDialogSidebarClickHandler() | A click on the sidebar from a comment dialog. |
useNotificationEventCallback(action) | Typed notification event callback (NotificationEventTypesMap[action]). |
usePresenceEventCallback(action) | Typed presence event callback (PresenceEventTypesMap[action]). |
useRecorderAddHandler() | Fires when a recording is added → RecordedData | null. |
useServerConnectionStateChangeHandler() | Live-state server connection state changes → ServerConnectionState. |
useVeltEventCallback(eventName) | Custom events (e.g. 'veltButtonClick' from a wireframe button). |
Control: init, scope, imperative
| Hook | Use | |
|---|
useVeltClient() | The Velt client (const { client } = useVeltClient()); imperative API + client.getCommentElement(). (useClient() is a newer alias.) | |
useIdentify() | Returns { identify }; call identify(user). | |
useSetDocuments() / useSetDocument() | Return a setter: const { setDocuments } = useSetDocuments(); then setDocuments(documents, options). Not useSetDocuments([...]). | |
useSetDocumentId(documentId) | Argument-form setter for a single document id (no returned setter; pass the id directly). | |
useUnsetDocuments() / useUnsetDocumentId() | Clear the current document(s) scope. | |
useSetRootDocument() | Returns { setRootDocument }; setRootDocument(document) sets the root document. | |
useSetLocation(location, appendLocation?) | Argument-form location setter. | |
useSetLocations() | Returns { setLocations }; setLocations(locations, options). | |
useSetRootLocation() | Returns { setRootLocation }; setRootLocation(location). | |
useSetPageInfo() / useClearPageInfo() | Return { setPageInfo } / { clearPageInfo }; set or clear page metadata. | |
useHeartbeat(config?) | Reactive GetHeartbeatResponse (presence heartbeat). | |
useSetContextProvider() | Provide custom context to comments. | |
useVeltInitState() | Whether Velt finished initializing (gate rendering on this). | |
useUiState() / useSetLiveStateData() | Shared UI state between users. | |
useSubscribeCommentAnnotation() / useUnsubscribeCommentAnnotation() | Subscribe to a specific annotation. | |
useCommentUtils() | The underlying comment element (`CommentElement | undefined`); the imperative element backing most comment hooks. |
Imperative API via the client
Some controls aren’t hooks: call them on the comment element:
const { client } = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.openCommentSidebar();
commentElement.enableCommentMode();
commentElement.setCommentSidebarFilters({ status: ["open"], priority: ["high"] });
commentElement.setCustomStatus([{ id: "new", title: "New", color: "#FF5733" }]);
client.getCommentElement().)
Other features (brief)
| Feature | Representative hooks |
|---|
| Presence | usePresenceUsers, usePresenceData, usePresenceUtils, usePresenceEventCallback, useHeartbeat |
| Cursors | useCursorUsers, useCursorUtils |
| Notifications | useNotificationsData, useUnreadNotificationsCount, useNotificationSettings, useNotificationUtils, useNotificationEventCallback |
| Reactions | useAddReaction, useToggleReaction, useDeleteReaction |
| Recorder | useRecordings, useRecordingDataByRecorderId, useRecorderUtils, useRecorderEventCallback, useRecorderAddHandler |
| Suggestions | useSuggestions, useSuggestionUtils, usePendingSuggestion, useStartSuggestion, useCommitSuggestion, useEnableSuggestionMode / useDisableSuggestionMode, useSuggestionModeState, useSuggestionEventCallback |
| Activity log | useAllActivities, useActivityUtils |
| Autocomplete | useAutocompleteUtils, useAutocompleteChipClick, useContactList, useContactSelected, useContactUtils |
| Tags | useTagAnnotations, useTagUtils |
| Views/Analytics | useUniqueViewsByUser, useUniqueViewsByDate, useViewsUtils |
| Live state sync | useLiveState, useLiveStateData, useSetLiveStateData |
Other features for how customization applies to these.
Other-feature hook exports (verified return types)
These are exported from @veltdev/react but belong to out-of-scope features. They are listed here only to keep the “a hook not listed doesn’t exist” invariant true: name, category, return type, and one-line purpose. Return types verified against ground truth.
| Hook | Category | Returns | Purpose |
|---|
useLiveStateSyncUtils() | Live state sync | LiveStateSyncElement | undefined | The imperative live-state-sync element backing the live-state hooks. |
useUserEditorState() | Live state sync | UserEditorAccess | null | undefined | Whether the current user is the editor in single-editor mode. |
useEditor() | Live state sync | User | null | The current editor user in single-editor mode. |
useEditorAccessTimer() | Live state sync | EditorAccessTimer (defaults to { state: 'idle' }) | Editor-access countdown/timer state. |
useEditorAccessRequestHandler() | Live state sync | { requestStatus: string; requestedBy: User } | null | The pending editor-access request, if any. |
useLiveStateSyncEventCallback(action) | Live state sync | LiveStateEventTypesMap[action] | Latest live-state-sync event payload (access/editor events). |
useRegisterTarget() | Suggestion targets | { registerTarget(config: RegisterTargetConfig<T>): void } | Register a complex-object getter for a suggestion target. |
useUnregisterTarget() | Suggestion targets | { unregisterTarget(targetId: string): void } | Drop a registered suggestion-target getter. |
useLiveSelectionUtils() | Live selection | SelectionElement | undefined | The imperative live-selection element. |
useLiveSelectionDataHandler() | Live selection | LiveSelectionData | null | Reactive live-selection data. |
useCrdtUtils() | CRDT | CrdtElement | undefined | The imperative CRDT element. |
useCrdtEventCallback(action) | CRDT | CrdtEventTypesMap[action] | Latest CRDT event payload (e.g. updateData). |
useHuddleUtils() | Huddle | HuddleElement | undefined (typed any in source) | The imperative huddle element. |
useAIRewriterUtils() | AI rewriter | RewriterElement | undefined | The imperative rewriter element (subscribe to textSelected; call askAi/replaceText/addComment). |
