Primitives

Velt’s building-block components, composed by you. Each one ships Velt’s default design and full behavior, and there’s a sub-component for nearly every child piece. You fetch the data, loop it, arrange the pieces into any layout, and wrap them in any UI library. Most control, most effort. Use it when you need your own UI component library inside the comment UI, your own interactivity, to place Velt pieces anywhere in your tree, or layouts beyond what wireframe slots offer. Don’t when a wireframe already expresses the layout: Velt does the data-fetching and looping there, so it’s less work.

Have this design in Figma? The UI Customization Plugin for Cursor and Claude Code runs this whole loop for you: it picks the approach, builds it in your app, and verifies the result against the design in a real browser (comments and notifications today).

The model

A primitive is a real component: VeltCommentDialog in React, <velt-comment-dialog> as a custom element everywhere else. Because it’s real, your design-system components work normally around it, and your own state and click handlers keep working. The trade versus wireframes is the data plumbing: you write what Velt would otherwise do. To show every thread you fetch the annotations, loop them, and pass each annotationId into a VeltCommentDialog. In exchange you get full layout control and your UI library.

The one limit: leaf pieces (the deepest components, with no children) can’t be restructured as primitives. Customize a leaf with that leaf’s wireframe, even inside an otherwise-primitive build.

Names: Component catalog. Props: Component config. You can also explore every primitive interactively in Storybook.

Steps

Drop in the component

React / Next.js
Other Frameworks

import { VeltComments, VeltCommentsSidebar } from '@veltdev/react';

<VeltComments shadowDom={false} />
<VeltCommentsSidebar shadowDom={false} />

<velt-comments shadow-dom="false"></velt-comments>
<velt-comments-sidebar shadow-dom="false"></velt-comments-sidebar>

That alone gives you fully working comments with Velt’s default design. Keep shadowDom={false} if you’ll style them (see CSS).

Toggle features with props

Trim the UI to your design by switching features off, never by hiding them with CSS:

React / Next.js
Other Frameworks

<VeltComments
  shadowDom={false}
  userMentions={true}
  reactions={false}
  recordings="none"
  attachments={false}
  status={false}
  priority={false}
  commentTool={false}
  collapsedComments={true}
  commentPlaceholder="Add a comment…"
  replyPlaceholder="Reply…"
/>

<velt-comments
  shadow-dom="false"
  user-mentions="true"
  reactions="false"
  recordings="none"
  attachments="false"
  status="false"
  priority="false"
  comment-tool="false"
  collapsed-comments="true"
  comment-placeholder="Add a comment…"
  reply-placeholder="Reply…"
></velt-comments>

Every <VeltComments> prop is in Props; layout and mode props for the sidebar, dialog, and notifications are in Component config. Don’t guess prop names.

Fetch, loop, render

For your own layout, you do the data plumbing: fetch the annotations, loop them, and render a dialog per annotation by passing its annotationId.

React / Next.js
Other Frameworks

import { VeltCommentDialog, useCommentAnnotations, useVeltInitState } from '@veltdev/react';
import type { CommentAnnotation } from '@veltdev/types';

function MyCommentsList() {
  const ready = useVeltInitState();
  // 1) FETCH: reactive; re-renders when comments change (incl. other users live)
  const annotations: CommentAnnotation[] = useCommentAnnotations() ?? [];

  if (!ready) return <MySkeleton />;
  if (annotations.length === 0) return <MyEmptyState />;

  return (
    <div className="my-list">
      {/* 2) LOOP: one row per annotation */}
      {annotations.map((a) => (
        <section key={a.annotationId} className="my-row">
          <header>{a.comments?.[0]?.from?.name}</header>
          {/* 3) RENDER: Velt fills in the thread (comments, composer, reactions,
                 resolve) with full behavior, inside YOUR row layout. */}
          <VeltCommentDialog annotationId={a.annotationId} fullExpanded defaultCondition={false} />
        </section>
      ))}
    </div>
  );
}

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

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

// 1) FETCH: reactive; fires again whenever comments change (incl. other users live)
const subscription = commentElement.getAllCommentAnnotations().subscribe((annotations) => {
  const list = document.getElementById('my-list');
  list.innerHTML = '';

  // 2) LOOP: one row per annotation
  (annotations || []).forEach((a) => {
    const row = document.createElement('section');
    row.className = 'my-row';
    // 3) RENDER: Velt fills in the thread with full behavior, inside YOUR row layout.
    row.innerHTML = `
      <header>${a.comments?.[0]?.from?.name ?? ''}</header>
      <velt-comment-dialog
        annotation-id="${a.annotationId}"
        full-expanded="true"
        default-condition="false"></velt-comment-dialog>
    `;
    list.appendChild(row);
  });
});

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

You can filter, sort, or group the annotations before rendering. To create a thread from your own composer, pair this with the action hooks (useAddCommentAnnotation, useAddComment: see headless).

Prefer VeltCommentDialog for new code. It’s the actively developed per-thread primitive with the same annotationId API. VeltCommentThread still works but is no longer the recommended path (see Comment Thread).

Wrap in your UI library

React / Next.js
Other Frameworks

// MUI, shadcn, Radix, Ant, Chakra, Tailwind: all fine
<Card className="my-thread-card">
  <CardHeader title="Discussion" />
  <CardContent>
    <VeltCommentDialog annotationId={annotationId} fullExpanded />
  </CardContent>
</Card>

<div class="my-thread-card">
  <h3 class="my-thread-card-header">Discussion</h3>
  <div class="my-thread-card-content">
    <velt-comment-dialog
      annotation-id="ANNOTATION_ID"
      full-expanded="true"></velt-comment-dialog>
  </div>
</div>

Your <Card> keeps its own state, handlers, and styling. This is exactly what wireframes cannot do: their slot markup is cloned, so interactive components inside them go dead.

`defaultCondition`: you control show/hide

Every primitive has an internal visibility condition: VeltCommentDialog, for example, renders only when its annotation is selected. Setting defaultCondition={false} bypasses that gate, so the component renders whenever you mount it and you own the show/hide logic (your own {show && …}, routing, tabs).

React / Next.js
Other Frameworks

<VeltCommentDialog annotationId={annotationId} defaultCondition={false} fullExpanded />

<velt-comment-dialog
  annotation-id="ANNOTATION_ID"
  default-condition="false"
  full-expanded="true"></velt-comment-dialog>

Omit it and the primitive uses its own built-in condition. This is what makes the fetch-loop-render pattern above work: you’re deliberately rendering a dialog per row, so none of them should wait to be selected.

Wireframes have no equivalent. A wireframe always renders through Velt’s internal condition; velt-if only reacts to Velt’s state, it can’t override whether Velt renders the component at all. If your design needs to force show or hide on your own logic, that’s a reason to pick a primitive.

What it can and can’t do

✅ Primitives can	❌ Primitives can’t
Render fully working Velt UI	Restructure a leaf piece: use that leaf’s wireframe instead
Restructure layout by composing sub-components (custom header, thread card, …)	Save you from writing the composition: you fetch, loop, and pass props
Be composed inside your own UI library, with your own interactivity
Be placed anywhere in your tree, toggled via props, themed with CSS

The two reasons not to reach for primitives: a wireframe already expresses the layout with less work, or you only need to restructure a single leaf. A common need: you build your own comment dialog from primitives, and its header needs status / priority / options dropdowns that use your UI-library dropdown for the open/close shell while still driving Velt’s real behavior. Velt ships a primitive dropdown family for each (…Trigger with name/icon/arrow parts, plus …Content with per-item children). Exact names: Component catalog. You have three ways to make it yours: Option A: Velt’s shell, your item styling (least effort). Use the primitive dropdown as-is and restyle each item by registering its wireframe content (VeltCommentDialogStatusDropdownContentWireframe → .Item → .Icon / .Name). Velt keeps the open/close and set-status behavior; the items look fully custom. Option B: your shell, Velt’s items. Render your library’s dropdown, and inside it render Velt’s primitive content items, which carry the click-to-set behavior. They work interactively here because primitives are real components, so the wireframe cloning limit doesn’t apply. Keep them inside the Velt dropdown container so they receive the annotation context.

React / Next.js
Other Frameworks

// `statuses` is your customStatus config
<VeltCommentDialogStatusDropdown
  annotationId={annotationId}
  onChangeStatus={(e) => setMyLabel(e.status)}   // keep your trigger label in sync
>
  <VeltCommentDialogStatusDropdownTrigger>
    <MyLibraryDropdownButton>{myLabel}</MyLibraryDropdownButton>   {/* YOUR shell */}
  </VeltCommentDialogStatusDropdownTrigger>

  <VeltCommentDialogStatusDropdownContent>
    <MyLibraryMenu>                                                {/* YOUR popover */}
      {statuses.map((s, i) => (
        // Velt primitive item = carries the set-status behavior
        <VeltCommentDialogStatusDropdownContentItem
          key={s.id} annotationId={annotationId} statusObj={s} statusId={s.id} statusIndex={i}
        >
          <VeltCommentDialogStatusDropdownContentItemIcon />
          <VeltCommentDialogStatusDropdownContentItemName />
        </VeltCommentDialogStatusDropdownContentItem>
      ))}
    </MyLibraryMenu>
  </VeltCommentDialogStatusDropdownContent>
</VeltCommentDialogStatusDropdown>

<velt-comment-dialog-status-dropdown annotation-id="ANNOTATION_ID">
  <velt-comment-dialog-status-dropdown-trigger>
    <button class="my-dropdown-button">Status</button>   <!-- YOUR shell -->
  </velt-comment-dialog-status-dropdown-trigger>

  <velt-comment-dialog-status-dropdown-content>
    <div class="my-menu">                                <!-- YOUR popover -->
      <!-- Repeat one item per status in your customStatus config -->
      <velt-comment-dialog-status-dropdown-content-item
        annotation-id="ANNOTATION_ID"
        status-id="OPEN"
        status-index="0">
        <velt-comment-dialog-status-dropdown-content-item-icon></velt-comment-dialog-status-dropdown-content-item-icon>
        <velt-comment-dialog-status-dropdown-content-item-name></velt-comment-dialog-status-dropdown-content-item-name>
      </velt-comment-dialog-status-dropdown-content-item>
    </div>
  </velt-comment-dialog-status-dropdown-content>
</velt-comment-dialog-status-dropdown>

onChangeStatus is a React prop; in other frameworks read the current status from the annotation data (getAllCommentAnnotations()).

The statuses list is the same one you pass to the customStatus prop (see Component config). To restyle the item internals, register the item’s wireframe (VeltCommentDialogStatusDropdownContentWireframe.Item). The same shape works for Priority and the Options actions. Option C: fully headless (max control). Render your own dropdown entirely and set the value with hooks: useUpdateStatus(), useUpdatePriority(), and the options actions (useResolveCommentAnnotation, useDeleteComment, useAssignUser). No Velt dropdown component at all. See Headless.

Want Velt’s behavior with your looks? Option A or B. Want to own everything? Option C. All three keep Velt’s data and sync intact.

Checklist

Used real component and prop names (from Component catalog and Component config).
Features trimmed with props, not display:none.
shadowDom={false} on anything you style, and theming done with --velt-* variables (CSS).
UI-library wrappers go around the primitive, never as interactivity inside a wireframe.

Concepts

Approaches

Recipes & Troubleshooting

Components: Async Collaboration

Components: Realtime Collaboration

Reference

The model

Steps

Drop in the component

Toggle features with props

Fetch, loop, render

Wrap in your UI library

`defaultCondition`: you control show/hide

What it can and can’t do

Checklist

​The model

​Steps

Drop in the component

Toggle features with props

Fetch, loop, render

Wrap in your UI library

​defaultCondition: you control show/hide

​What it can and can’t do

​Worked example: a custom dropdown in a custom header

​Checklist

The model

Steps

`defaultCondition`: you control show/hide

What it can and can’t do

Worked example: a custom dropdown in a custom header

Checklist