Headless

What it is: Velt gives you the data and the actions through React hooks. You build 100% of the UI with your own components. Velt renders nothing. Use it when: the design needs your own interactive components inside the collaboration UI, a layout wireframe slots can’t express, or you’re rendering comments into a surface Velt can’t draw into (a PDF/canvas/video timeline). (Decision tree Q4.) Don’t use it when: a wireframe could express the layout: headless means you own (and maintain) everything, including parity with Velt’s built-in behavior. It’s the most powerful and the most expensive layer.

Headless is the most powerful and most expensive layer: reach for it only when no other layer fits.

The model

Three kinds of hooks (full list grouped in Hooks):

Read (data/state): useCommentAnnotations, useCommentAnnotationById, useUnreadCommentAnnotationCountOnCurrentDocument, useCommentModeState, … → reactive data you render.
Mutate (actions): useAddCommentAnnotation, useAddComment, useUpdateComment, useDeleteComment, useDeleteCommentAnnotation, useResolveCommentAnnotation, useUpdateStatus, useToggleReaction, useGetLink, … → call these from your own buttons.
Control: useVeltClient, useSetDocuments, useIdentify, useVeltInitState, … → init/scope/imperative control.

You wire your UI’s events to the mutate hooks and render the read hooks’ data. Velt still handles storage, sync, mentions, permissions: you’re only replacing the view.

Middle ground: keep Velt’s components but strip their visual styling with setUnstyledMode() (v6.0.0-beta.10+), then style everything with your own CSS. See unstyled mode.

Steps

Step 1: Render data from a read hook

import { useCommentAnnotations } from "@veltdev/react";
import type { CommentAnnotation } from "@veltdev/types";

function CommentsPanel() {
  const annotations: CommentAnnotation[] = useCommentAnnotations() ?? [];
  return (
    <div className="my-panel">
      {annotations.map((a) => (
        <MyThreadCard key={a.annotationId} annotation={a} />
      ))}
    </div>
  );
}

useCommentAnnotations() is reactive: it re-renders when comments change anywhere (including other users in real time). You never poll.

Step 2: Wire your buttons to action hooks

Your components are fully interactive (unlike wireframes). Call the action hooks from your own handlers:

import {
  useAddComment, useResolveCommentAnnotation, useCurrentUser,
} from "@veltdev/react";
import type { CommentAnnotation, User } from "@veltdev/types";

function MyThreadCard({ annotation }: { annotation: CommentAnnotation }) {
  const currentUser = useCurrentUser();            // the identified user
  const { addComment } = useAddComment();
  const { resolveCommentAnnotation } = useResolveCommentAnnotation();

  const reply = async (text: string, html: string) => {
    if (!currentUser) return;
    const comment = buildComment(currentUser, text, html);   // buildComment is defined in Step 3
    await addComment({ annotationId: annotation.annotationId, comment });
  };

  return (
    <article>
      {/* your fully custom, interactive UI */}
      <button onClick={() => resolveCommentAnnotation({ annotationId: annotation.annotationId })}>
        Resolve
      </button>
    </article>
  );
}

Step 3: Build objects to the SDK data model

Mutations expect objects shaped like Velt’s types (from @veltdev/types). You construct them yourself. Example Comment builder:

import type { Comment, User } from "@veltdev/types";

function buildComment(currentUser: User, text: string, html: string): Comment {
  return {
    commentId: Date.now(),
    type: "text",
    from: currentUser,
    status: "added",
    commentText: text,
    commentHtml: html,
    taggedUserContacts: [],
    attachments: [],
    reactionAnnotationIds: [],
    customList: [],
  } as unknown as Comment;   // cast: fill every field your action needs; cast bridges optional fields you omit (R13)
}

Because you hand-build these, read the type (Comment, CommentAnnotation, User in @veltdev/types) and fill every field the action needs. Missing fields are the most common headless bug.

Minimal Comment for addComment / updateComment (from the Comment type): commentId (number: auto if omitted), type ('text' | 'voice', default 'text'), from (a full User: required), commentText, commentHtml, status ('added' | 'updated'), and the array fields you touch (attachments, taggedUserContacts, reactionAnnotationIds). from is the field most often missed.

What each action expects (the request object)

Action hooks take a single request object, not loose args. The required fields per common mutation (optional ones omitted; all also accept options?):

Hook	Request fields (required)	Notes
`useAddCommentAnnotation` → `addCommentAnnotation`	`{ annotation: CommentAnnotation }`	Creates a new thread; build the full `CommentAnnotation`.
`useAddComment` → `addComment`	`{ annotationId: string; comment: Comment }`	Adds a reply to an existing thread. Optional: `assignedTo?: User`, `assigned?: boolean`.
`useUpdateComment` → `updateComment`	`{ annotationId: string; comment: Comment }`	Optional `merge?: boolean` to patch rather than replace.
`useDeleteComment` → `deleteComment`	`{ annotationId: string; commentId: number }`	`commentId` is a number.
`useResolveCommentAnnotation` → `resolveCommentAnnotation`	`{ annotationId: string }`	Toggles resolved.
`useUpdateStatus` → `updateStatus`	`{ annotationId: string; status: CustomStatus }`	`status` is a full `CustomStatus` object (`{ id, name, color, type, … }`), not a string: see `Component config`.
`useToggleReaction` → `toggleReaction`	`{ annotationId: string; commentId: number; reaction: { reactionId: string } }`	Optional `reaction.customReaction?`.

Exact, current shapes are the *Request interfaces in @veltdev/types (AddCommentRequest, UpdateStatusRequest, …): read the type if a call errors. The table is the field-level companion to R13 (“fill every field the action needs”).

What it can and can’t do

✅ Headless can	❌ Headless can’t
Give you 100% custom UI: Velt renders nothing; you build every component	Save you from re-implementing and maintaining thread layout, the composer (@mentions, attachments, reactions, formatting), filtering/sorting, empty/loading states, accessibility, and dark mode
Expose all data + actions through React hooks (Velt still does storage, sync, mentions, permissions)	Auto-inherit new Velt UI features: the upgrade burden is yours; new features won’t appear in your UI automatically
Render comments onto a non-DOM surface (PDF, canvas, a video timeline) where Velt can’t draw	Be the cheap choice: it’s the most expensive layer; if a wireframe can express the layout, use it instead
Build a panel entirely from your own interactive design-system components, and drive bespoke workflows/filtering via hooks + the client API

Notes & deep-dives

The cost (be honest about this)

Going headless means you re-implement and maintain everything Velt’s UI gave you for free:

Thread layout, replies, collapsing, edit-in-place, resolved state.
The composer: @mentions UI, attachments, reactions, formatting.
Filtering/sorting (compute client-side over useCommentAnnotations()).
Empty/loading states, accessibility, dark mode.
Upgrade burden: new Velt features won’t appear in your UI automatically.

If a wireframe can express the layout, prefer it: you keep Velt’s behavior for free and only restyle.

When headless is the right call

Comments rendered onto a non-DOM surface (PDF, canvas, a video timeline) where Velt can’t draw.
A panel built entirely from your own interactive design-system components.
Behavior that no slot offers (custom inline workflows, bespoke filtering UIs): drive Velt via hooks + the client API.

Checklist

Using real hook names from Hooks.
Objects passed to mutations match @veltdev/types (all required fields).
Reactive data comes from read hooks (no manual polling).
You’ve confirmed a wireframe genuinely can’t do it (headless is the costly last resort).

Concepts

AI Agent Workflow

Approaches

Feature Guides

Components: Async Collaboration

Components: Realtime Collaboration

Guidance

Reference

The model

Steps

Step 1: Render data from a read hook

Step 2: Wire your buttons to action hooks

Step 3: Build objects to the SDK data model

What each action expects (the request object)

What it can and can’t do

Notes & deep-dives

The cost (be honest about this)

When headless is the right call

Checklist

​The model

​Steps

​Step 1: Render data from a read hook

​Step 2: Wire your buttons to action hooks

​Step 3: Build objects to the SDK data model

​What each action expects (the request object)

​What it can and can’t do

​Notes & deep-dives

​The cost (be honest about this)

​When headless is the right call

​Checklist

The model

Steps

Step 1: Render data from a read hook

Step 2: Wire your buttons to action hooks

Step 3: Build objects to the SDK data model

What each action expects (the request object)

What it can and can’t do

Notes & deep-dives

The cost (be honest about this)

When headless is the right call

Checklist