Headless

Build fully custom Velt UI with headless hooks, data, and actions.

What it is: Velt gives you the data and the actions through React hooks, or the equivalent API methods in other frameworks. You build 100% of the UI with your own components. Velt renders nothing.

Hooks are React-only. In other frameworks, the same data and actions live on the Velt client’s elements (e.g. Velt.getCommentElement()), shown in the Other Frameworks tabs below. The full mapping is in API methods.

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). (This is the last question in the decision tree.)

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; each maps to an API method on the Velt client for other frameworks, e.g. useAddComment → commentElement.addComment(), useCommentAnnotations → commentElement.getAllCommentAnnotations()):

• Read (data/state): useCommentAnnotations, useCommentAnnotationById, useUnreadCommentCountOnCurrentDocument, 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 source

React / Next.js

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

Other Frameworks

<div id="my-panel" class="my-panel"></div>

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

const subscription = commentElement.getAllCommentAnnotations().subscribe((annotations) => {
  const panel = document.getElementById('my-panel');
  panel.innerHTML = '';
  (annotations || []).forEach((a) => {
    panel.appendChild(renderMyThreadCard(a));   // renderMyThreadCard is defined in Step 2
  });
});

// when your panel is destroyed:
subscription?.unsubscribe();
</script>

The read source is reactive: it updates when comments change anywhere (including other users in real time). You never poll.

Step 2: Wire your buttons to actions

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

React / Next.js

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

Other Frameworks

const commentElement = Velt.getCommentElement();
// currentUser: the same User object you passed to Velt.identify()

async function reply(annotation, text, html) {
  const comment = buildComment(currentUser, text, html);   // buildComment is defined in Step 3
  await commentElement.addComment({ annotationId: annotation.annotationId, comment });
}

function renderMyThreadCard(annotation) {
  const card = document.createElement('article');
  // your fully custom, interactive UI
  const resolveButton = document.createElement('button');
  resolveButton.textContent = 'Resolve';
  resolveButton.addEventListener('click', () => {
    commentElement.resolveCommentAnnotation({ annotationId: annotation.annotationId });
  });
  card.appendChild(resolveButton);
  return card;
}

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:

React / Next.js

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
}

Other Frameworks

// currentUser: the same User object you passed to Velt.identify()
function buildComment(currentUser, text, html) {
  return {
    commentId: Date.now(),
    type: 'text',
    from: currentUser,
    status: 'added',
    commentText: text,
    commentHtml: html,
    taggedUserContacts: [],
    attachments: [],
    reactionAnnotationIds: [],
    customList: [],
  };
}

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)

Actions take a single request object, not loose args. In other frameworks, the same methods live on Velt.getCommentElement() with identical names and request shapes (commentElement.addComment(request), commentElement.updateStatus(request), …). 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 the rule above: 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. Before committing to headless, consider pointing the UI Customization Plugin at your design: it will tell you if a cheaper layer can express it.

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