Patterns & tips

Reusable recipes, grouped by the approach they belong to: jump to the bucket for the layer you’re using:

General workflow: applies to any approach
CSS-specific: pure styling tricks
Wireframe-specific: slot + token tricks
Primitives-specific: composition tricks
Mixed: recipes that combine layers

All class-based CSS uses !important (R9b: Velt’s runtime styles are high-specificity).

General workflow (any approach)

Progressive escalation. Start at the cheapest layer; escalate only when blocked: CSS → Wireframes → Primitives → Headless. Never start at headless “to be safe”: it’s the most expensive. See Decision tree. Per-feature layering. Decide approach per surface; theme everything with one CSS file. Typical healthy mix: wireframe the dialog, primitive sidebar, headless badge in your header, CSS on top. See Combining approaches. Gate rendering on init. Velt is client-side: don’t render custom UI against an uninitialized client:

const ready = useVeltInitState();
if (!ready) return <MySkeleton/>;

Compare against default. When something looks wrong, temporarily remove your customization to see Velt’s default: it isolates “my styling” from “Velt behavior.” One feature at a time. Finish + verify a surface before starting the next. Look up every name. CSS var / class / slot / {…} / prop / hook → it’s in reference/ or it doesn’t exist. The reference map: Wireframe components (slots), Wireframe variables (tokens), CSS classes (stateful classes), Component config (props). 'use client' (Next.js): customization components and anything using hooks must be client components.

CSS-specific

Theme-token layer. Define your brand once as your own variables, then map them onto --velt-*:

:root {
  --brand-accent: #FF6B35;
  --velt-light-mode-accent: var(--brand-accent);
  --velt-light-mode-accent-hover: color-mix(in srgb, var(--brand-accent) 85%, black);
}

One place to change your brand; Velt + your app stay in sync. Reveal actions only on hover. Hide the kebab/options/reaction icons; show on hover. Velt already wires this on .velt-thread-card--container:hover; you can also force it with .velt-thread-card--show-actions.

.hw-comment-actions { opacity: 0; transition: opacity .12s ease; }
.hw-comment:hover .hw-comment-actions,
.hw-comment-actions:focus-within { opacity: 1; }

Reaction tool when empty vs reaction panel when populated. The pin carries velt-reaction-pin--no-reactions only when count is 0. Use it (and :has(app-reaction-pin)) to swap/position the reaction UI by count.

.velt-thread-card--reactions:not(:has(app-reaction-pin)) { display: none !important; }

Style the unread dot.

.velt-thread-card--name--unread {
  width:6px !important; height:6px !important; border-radius:50% !important;
  background: var(--brand) !important; margin-left:0 !important;
}

Style resolved threads (no --resolved class: detect the unresolve button):

.velt-comment-dialog--sidebar-mode:has(velt-comment-dialog-unresolve-button-internal .icon)
  .velt-thread-card--message { color: var(--muted) !important; }

Hide a container when its data slot is empty.

.context-row:has(app-data:empty) { display:none !important; }
app-if:empty { display:none !important; }   /* unwrap empty conditionals */

Resize the default avatar.

snippyly-user-avatar {
  --legacy-velt-user-avatar-height:20px !important;
  --legacy-velt-user-avatar-width:20px !important;
}

Neutralize an SDK popover so your menu takes over.

velt-comment-dialog-options-dropdown-content-internal,
div:has(> velt-comment-dialog-options-dropdown-content-internal) {
  background:transparent !important; box-shadow:none !important;
  border:none !important; padding:0 !important; width:max-content !important;
}

Indent threaded replies.

app-comment-dialog-threads > :not(:first-child) { padding-left: 26px; }

Wireframe-specific

Reuse one wireframe template across surfaces. Define a wireframe template once (e.g. your own DialogWireframe component) and register it inside your single <VeltWireframe>; every place that renders that component picks it up. One source of truth for a surface’s look. Conditional UI with velt-if. Branch on live state: empty states, role-gated bits, root-vs-reply:

<VeltIf condition="{noCommentsFound}"><EmptyA/></VeltIf>
<VeltIf condition="!{noCommentsFound}"><EmptyB/></VeltIf>
<VeltIf condition="{commentIndex} === 0"><RootOnlyBadge/></VeltIf>

Show live data with velt-data. Render context/metadata Velt owns:

<span>Assigned to <VeltData field="annotation.assignedTo.name" /></span>
<span><VeltData field="annotation.context.questionTitle" /></span>

Conditional empty state. Different copy for “no comments yet” vs “filtered to zero”:

<VeltCommentsSidebarWireframe.EmptyPlaceholder>
  <VeltIf condition="{noCommentsFound}"><h3>Be the first to comment</h3></VeltIf>
  <VeltIf condition="!{noCommentsFound}"><h3>No comments match your filters</h3></VeltIf>
</VeltCommentsSidebarWireframe.EmptyPlaceholder>

Count badge only when there are comments.

<VeltIf condition="{commentAnnotation.comments.length} > 0"><Count/><Icon/></VeltIf>
<VeltIf condition="{commentAnnotation.comments.length} === 0"><Icon/></VeltIf>

Custom skeleton/loading. Fill the .Skeleton slot with your own loading cards so the loading state matches your design.

Bridge a wireframe button to your app logic (the `onClick` escape hatch)

You can’t use onClick inside a wireframe (R4). For a custom action, use VeltButtonWireframe + the veltButtonClick event:

// In the wireframe: give the Velt button an id (your markup goes inside it)
<VeltButtonWireframe id="export-thread" type="button">
  <span className="my-icon-btn"><ExportIcon /> Export</span>
</VeltButtonWireframe>

// In your app: useVeltEventCallback returns the latest click event (a value, not an observable)
const evt = useVeltEventCallback("veltButtonClick");
useEffect(() => {
  if (evt?.buttonContext?.clickedButtonId === "export-thread") {
    exportThread(evt);   // evt also carries commentAnnotation / comment / index
  }
}, [evt]);

For Velt’s built-in actions (resolve, delete, submit) use the dedicated slot, not this. VeltButtonWireframe props:

Prop	Type	Required	What it does
`id`	`string`	Yes	Unique identifier. Static, or dynamic via a template variable: `id="{annotation.annotationId}"`
`type`	`string`	No	`'button'` (default), `'button-toggle'` (maintains pressed state), `'single-select'` (radio-style, needs `group`), `'multi-select'` (checkbox-style, needs `group`)
`group`	`string`	No	Group identifier for `single-select` / `multi-select` buttons
`active`	`boolean`	No	Default active/selected state for `button-toggle` / `single-select` / `multi-select`
`disabled`	`boolean`	No	Disable the button

Every click emits veltButtonClick with buttonContext (clicked id, group, selection state) plus the surrounding commentAnnotation / comment when rendered inside a comment surface.

Reset a VeltButtonWireframe after app logic runs

Use resetVeltButtonState() when your app handles a veltButtonClick and needs to return the button to its idle state. This is most useful for custom action buttons that show a selected, loading, or submitted state while your app logic runs.

const evt = useVeltEventCallback("veltButtonClick");

useEffect(() => {
  if (evt?.buttonContext?.clickedButtonId !== "export-thread") return;

  void exportThread(evt).finally(() => {
    client.resetVeltButtonState({ id: "export-thread" });
  });
}, [client, evt]);

See resetVeltButtonState() for the API shape. Custom accept/reject (or any custom action) buttons in a thread card. Same mechanism:

<VeltButtonWireframe type="button" id="accept-button"><CheckIcon/></VeltButtonWireframe>
<VeltButtonWireframe type="button" id="reject-button"><XIcon/></VeltButtonWireframe>

Customize a list row, not the list. List/repeater slots ignore custom layout: restructure the repeated item wireframe instead. See list/repeater slots. Scope deliberately. Nest a child wireframe inside its parent to scope it to that parent’s render; place it at the <VeltWireframe> root to apply globally. See wireframe scoping.

Primitives-specific

Trim, don’t hide. Turn features off with props (reactions={false}, attachments={false}) rather than display:none. Cleaner DOM, no dead behavior. Compose sub-components for custom layout. There’s a sub-component primitive for nearly every child: rebuild a header/thread-card by arranging its sub-components, instead of accepting the default layout. (Restructure a leaf via that leaf’s wireframe.) Wrap in your UI library. Primitives are real React components, so your library’s components (and their interactivity) work normally around them: <MuiCard><VeltCommentDialog/></MuiCard>.

Mixed (more than one layer together)

Custom dropdown: your UI library + Velt primitive items + wireframe-styled items. Build the header dropdown (status / priority / options) from your UI-library shell, Velt primitive dropdown items (which carry the set behavior), and a wireframe to style the item internals, or go fully headless with useUpdateStatus() / useUpdatePriority(). Full worked example with the exact component names: Primitives → “custom dialog header with a custom dropdown.” Custom sidebar filters (V2): add your own filters + restyle the filter dropdown/panel. Configure which filters show (and add type:'custom' filters with your own options) via the filters prop; pick the layout with filterPanelLayout / filterOptionLayout; and fully restructure the filter dropdown/panel via the FilterContainer / FilterDropdown / FilterButton wireframe slots: Velt keeps the filtering logic. Full details: Component config → “Sidebar filters.” Collapsed→expanded composer (wireframe layout + CSS state class). Render a collapsed input and an expanded one in the composer slot; let Velt’s state classes switch them:

.velt-composer-open .composer-collapsed { display:none !important; }
.velt-composer-open .composer-expanded  { display:flex !important; }

(velt-composer-open / velt-comment-dialog--no-comments / velt-composer-edit-mode are the switches.) Make the sidebar/list take available height and scroll (wireframe/primitive layout + CSS over Velt’s internals: the tricky one). Velt’s own internal container elements keep their default styles and sit between your layout and the scrollable list. If any link in that flex chain lacks min-height:0 / flex:1 / height:100%, the list grows past the panel and scrolling silently breaks. Inspect the Velt internal element and force the chain (usually !important):

.my-panel { display:flex; flex-direction:column; height:100%; min-height:0; }
/* Velt's internal panel element: the hidden link you find by inspecting */
.my-panel > app-comment-sidebar-panel { display:flex; flex-direction:column; flex:1 1 auto; min-height:0; }
.my-list-body { flex:1; min-height:0; overflow-y:auto; }
/* sometimes Velt's own list viewport needs forcing too: */
velt-comments-sidebar /* …inspect for the exact internal el… */ { height:100% !important; min-height:0 !important; overflow-y:auto !important; }

Rule: min-height:0 (+ flex:1 / height:100%) must hold on every element from your wrapper down to the scroll container: including Velt’s internal ones. One missing link kills the scroll. Re-test that scrolling actually works. Remove leftover default styling a wireframe didn’t replace (wireframe + CSS !important). Wireframing a slot doesn’t strip all of Velt’s surrounding default styles: borders, padding, backgrounds, fixed widths, popover chrome often remain. Inspect → find the velt-* class → override:

.velt-status-dropdown--content {
  border:none !important; background:transparent !important;
  box-shadow:none !important; padding:0 !important;
}

Treat “inspect → find class → override” as part of every wireframe pass, not a failure. Wrap absolutely-positioned pieces in a position: relative container (primitive/wireframe mount + CSS). Some Velt pieces (dialog/pin/overlays, reaction pins) render with position: absolute. If a mounted primitive or wireframe appears in the wrong place (top-left, escaping its box), give its parent position: relative so the absolute child anchors to it:

.my-comment-dialog-host { position: relative; }

The most common “why is my dialog/pin floating in the wrong spot?” fix.

Concepts

AI Agent Workflow

Approaches

Feature Guides

Components: Async Collaboration

Components: Realtime Collaboration

Guidance

Reference

Patterns & tips

General workflow (any approach)

CSS-specific

Wireframe-specific

Bridge a wireframe button to your app logic (the `onClick` escape hatch)

Reset a VeltButtonWireframe after app logic runs

Primitives-specific

Mixed (more than one layer together)

​General workflow (any approach)

​CSS-specific

​Wireframe-specific

​Bridge a wireframe button to your app logic (the onClick escape hatch)

​Reset a VeltButtonWireframe after app logic runs

​Primitives-specific

​Mixed (more than one layer together)

General workflow (any approach)

CSS-specific

Wireframe-specific

Bridge a wireframe button to your app logic (the `onClick` escape hatch)

Reset a VeltButtonWireframe after app logic runs

Primitives-specific

Mixed (more than one layer together)