Wireframes Overview

Keep all of Velt’s behavior and data wiring, but supply your own HTML layout. You decompose a Velt component into named slots (header, thread card, composer, …) and fill each slot with your markup. Velt fetches the data, loops the threads and comments, and wires each slot’s behavior; you only lay out the slots. This is the default for structural customization, and it’s less work than primitives, where you’d write the data plumbing yourself. Use it when the design changes the structure of Velt’s UI (custom header, reordered parts, custom thread card, custom empty state) while the features stay the same, and your custom parts are non-interactive markup. Don’t when you need your own interactive components inside the UI (that’s primitives) or you only need recoloring (that’s CSS). Still unsure? Run the decision tree.

This page is the concepts and rules. The rest of the section:

Setup Wireframes: step-by-step setup with React and Other Frameworks examples.
Layout Customization: targeted vs full-tree overrides, variants, replace/remove/reorder recipes.
Template Variables: the complete {…} variable catalog per component.
Conditional Templates: show or hide parts with velt-if.
Conditional Classes: toggle CSS classes with velt-class.
Action Components: custom buttons, toggles, and select groups.

Prefer automation? The UI Customization Plugin builds wireframe customizations from a Figma design and verifies them in a real browser.

The model

Two pieces work together:

<VeltWireframe>: an invisible registry (display:none). You put your wireframe templates inside it. Use one per app: more than one merges first-with-content-wins, which causes hard-to-debug conflicts.
Velt…Wireframe slot components: e.g. VeltCommentDialogWireframe, VeltCommentsSidebarWireframe, with nested static slots like .Header, .Body, .ThreadCard, .Composer. You fill these with your own markup.

Then, separately, you mount the normal feature component (VeltComments, VeltCommentsSidebar, VeltCommentDialog, …). It renders using the template you registered. So a wireframe doesn’t render anything by itself: it registers a template that the live feature component picks up.

Quick example

Register a template inside the (single) <VeltWireframe> registry, then mount the live feature component as normal. Your own elements provide structure and visuals; the Velt…Wireframe.X slots are where Velt’s behavior renders.

React / Next.js
Other Frameworks

import { VeltWireframe, VeltCommentDialogWireframe, VeltComments } from "@veltdev/react";

<VeltWireframe>
  <VeltCommentDialogWireframe>
    <div className="vcd-shell">
      <VeltCommentDialogWireframe.Header>
        <header className="vcd-header">
          <VeltCommentDialogWireframe.Status />
          <VeltCommentDialogWireframe.ResolveButton />
          <VeltCommentDialogWireframe.CloseButton />
        </header>
      </VeltCommentDialogWireframe.Header>
      <VeltCommentDialogWireframe.Body />
      <VeltCommentDialogWireframe.Composer />
    </div>
  </VeltCommentDialogWireframe>
</VeltWireframe>

// elsewhere: the live component renders using the template above
<VeltComments shadowDom={false} />

<velt-wireframe style="display:none;">
  <velt-comment-dialog-wireframe>
    <div class="vcd-shell">
      <velt-comment-dialog-header-wireframe>
        <header class="vcd-header">
          <velt-comment-dialog-status-wireframe></velt-comment-dialog-status-wireframe>
          <velt-comment-dialog-resolve-button-wireframe></velt-comment-dialog-resolve-button-wireframe>
          <velt-comment-dialog-close-button-wireframe></velt-comment-dialog-close-button-wireframe>
        </header>
      </velt-comment-dialog-header-wireframe>
      <velt-comment-dialog-body-wireframe></velt-comment-dialog-body-wireframe>
      <velt-comment-dialog-composer-wireframe></velt-comment-dialog-composer-wireframe>
    </div>
  </velt-comment-dialog-wireframe>
</velt-wireframe>

<!-- elsewhere: the live component renders using the template above -->
<velt-comments shadow-dom="false"></velt-comments>

Full step-by-step setup, with Other Frameworks equivalents for every step: Setup Wireframes.

Slots take inputs too. Some slots accept props, such as Composer.ActionButton type="submit", Composer.Input placeholder="...", and ThreadCard.Reactions excludeReactionIds={[...]}. The complete slot list, per-slot props, and every wireframe component are in Wireframe components.

The interactivity rule

Read this before you write any wireframe. It is the #1 source of wireframe bugs.

Inside a wireframe, your own React interactivity does NOT run. Behavior comes only from Velt’s Velt…Wireframe.X slot components.

When Velt renders a wireframe it copies your slot markup into its own render tree: it serializes your slot to HTML and re-instantiates only the velt-* slot elements inside it. The copy is plain DOM, which strips React listeners. So for markup you put in a slot:

In your wireframe markup	Survives into the live UI?
Static elements (`<div>`, `<span>`, `<header>`, icons)	✅ yes
Your UI-library components used as static presentation (a `<Card>`, `<Badge>`, styled button shell)	✅ yes: their rendered markup + CSS classes survive
CSS `className` / inline styles	✅ yes
`{…}` tokens (`velt-if`, `velt-class`, `velt-data`)	✅ yes (Velt resolves them)
`Velt…Wireframe.X` slot components	✅ yes: this is where behavior comes from
Your React `onClick`, `useState`, hooks	❌ no: silently dead
A UI-library component’s behavior (its own click/state/effects)	❌ no: only its static markup renders

What to do instead: want a working button? Use the Velt slot for it (VeltCommentDialogWireframe.ResolveButton, .Options.Content.Delete, .Composer.ActionButton, …). Your markup goes inside that slot as its appearance:

React / Next.js
Other Frameworks

{/* ✅ correct: the Velt slot provides the click behavior; your markup is the look */}
<VeltCommentDialogWireframe.ResolveButton>
  <span className="my-icon-btn"><ResolveIcon /></span>
</VeltCommentDialogWireframe.ResolveButton>

{/* ❌ wrong: this onClick never runs in the rendered dialog */}
<button onClick={() => doSomething()}>Resolve</button>

<!-- ✅ correct: the Velt slot provides the click behavior; your markup is the look -->
<velt-comment-dialog-resolve-button-wireframe>
  <span class="my-icon-btn"><!-- your icon --></span>
</velt-comment-dialog-resolve-button-wireframe>

<!-- ❌ wrong: this listener never runs in the rendered dialog -->
<button onclick="doSomething()">Resolve</button>

You can drop in your design-system components for their look, since markup and classes survive the clone, but their interactivity won’t run. For interactive library components use primitives; for behavior no slot provides, go headless.

See it for yourself. Put a <button onClick={…}> in a wireframe slot and open DevTools: it renders as two nodes. The hidden React original (display:none) still has its React props and a working handler. The visible cloned copy injected into the live dialog has no React props, and its handler never fires. The node users can actually click is the one without the handler.

Scoping: global vs scoped wireframes

Where you place a child wireframe changes where it applies:

Nested inside its parent wireframe → scoped to that parent’s render. It travels as part of the parent’s cloned subtree, so it only customizes the child as it appears inside that parent. A ThreadCard layout placed inside VeltCommentDialogWireframe customizes thread cards in the dialog, not elsewhere.
Placed directly at the <VeltWireframe> root → global. It registers under its own key and applies to that component everywhere it renders (dialog, sidebar, inline section, …).

<VeltWireframe>
  {/* SCOPED: this ThreadCard layout applies only inside the dialog */}
  <VeltCommentDialogWireframe>
    <VeltCommentDialogWireframe.Body>
      <VeltCommentDialogWireframe.Threads>
        <VeltCommentDialogWireframe.ThreadCard>{/* …custom… */}</VeltCommentDialogWireframe.ThreadCard>
      </VeltCommentDialogWireframe.Threads>
    </VeltCommentDialogWireframe.Body>
  </VeltCommentDialogWireframe>

  {/* GLOBAL: a ThreadCard registered at the root would apply to thread cards everywhere */}
</VeltWireframe>

Why: the registry is a flat map keyed by component name (plus optional variant), never by parent. The root scan registers only its direct children as global keys, so a nested child isn’t registered globally: it rides inside the parent’s clone. Collisions resolve first-with-content-wins, so a root definition is not overwritten by a nested one. Rule: nest to scope, root-level to go global; don’t register the same component both ways.

Slot granularity

The slot tree is very fine-grained (hundreds of slots across the SDK). Inside a comment dialog alone you’ll find composer → Input / Attachments / AssignUser; thread-card → Avatar / Name / Time / Message / Options / Reactions; options dropdown → Edit / Delete. You only fill the slots you care about: a slot you never declare falls back to Velt’s default. So you can do a tiny override (just the empty state) or a near-total rebuild (40+ slots across the dialog and sidebar).

Container slots are the exception. The fallback rule holds for leaf slots. Declare a structural/container slot (a feature root like velt-comments-sidebar-v2-wireframe, or a parent like the sidebar panel/header) and you own its whole child tree: structural children you don’t declare disappear rather than falling back. A sidebar root wireframe declaring only a custom empty-placeholder renders the empty state but drops the search box, filter buttons, and list. Fix: declare the full tree you want inside the container (panel → header(search, filter) → list → empty-placeholder). Override a leaf and the rest stays; override a container and you re-declare its children.

List and repeater slots are the other exception. The complete slot list per feature: Wireframe components. Worked targeted-vs-full-tree examples: Layout Customization.

Variants

By default a component has one registered wireframe. Variants let you register several templates for the same component and choose which one renders by name, so one component can look different in different contexts (floating dialog vs sidebar row vs focused thread vs page-mode composer).

Register: variant="<name>" on the Velt…Wireframe.
Select: the matching prop on the live component (variant, dialogVariant, focusedThreadDialogVariant, pageModeComposerVariant). Which ones a given component accepts is listed per component in Props.
Fallback: no matching variant means the base (no-variant) wireframe renders.

Create/use walkthroughs, including pre-defined variants: Layout Customization → Variants.

List and repeater slots

A few slots are list/repeater containers: the comments list, the presence avatar list, the reactions panel items, the activity-log list. These keep rendering Velt’s own loop, so your layout around them is ignored.

❌ Wrapping a list slot in your own grid/flex layout, or adding sibling markup inside it, won’t take effect.
✅ Customize the repeated item instead. Velt passes the item template straight to the child component, so you restructure each row through its own item wireframe.

{/* The LIST container keeps Velt's loop: your wrapping layout here is ignored.
    Customize the per-row look via the item/child slot it renders. */}
<VeltCommentsSidebarWireframe.List>
  <VeltCommentsSidebarWireframe.List.Item>{/* ← customize the ROW here */}</VeltCommentsSidebarWireframe.List.Item>
</VeltCommentsSidebarWireframe.List>

Rule: if a slot represents a list of things, don’t relayout the list, restructure the item. If you truly need a custom list layout or virtualization, that’s a signal for primitives, where you own the loop.

Tokens: live data in your markup

Wireframe markup reads Velt’s live state through {…} tokens. There are three things you can do with one:

Token	What it does	Reference
`velt-if`	Show or hide a block on a condition	Conditional Templates
`velt-data`	Print a live value as text	Template Variables
`velt-class`	Toggle CSS classes on a condition	Conditional Classes

Variable names are a fixed set ({user}, {annotation}, {comment}, {commentIndex}, {noCommentsFound}, {darkMode}, …). A name outside the catalog resolves to undefined, so never invent one: the full list is in Template Variables.

Page mode

“Page mode” renders the comments sidebar anchored to elements on your page (one thread per form question, for example), with a per-element comment-count bubble and a page-mode composer. It’s still just wireframes: fill the sidebar, thread, composer, and bubble-count slots and Velt keeps the behavior. Page mode usually pairs with context: attaching your domain data (the question id or title) to each comment and reading it back in the dialog or composer. See Context.

What it can and can’t do

✅ Wireframes can	❌ Wireframes can’t
Give Velt’s UI any layout/structure you want	Run your React handlers/state/hooks inside slots
Add non-interactive custom markup around Velt’s parts	Host live UI-library components (interactivity is stripped)
Conditionally render via `velt-if` and show data via `velt-data`	Change Velt’s behavior (slots give you Velt’s behavior, not custom)
Override only the slots you care about	Relayout a list/repeater slot: customize its item instead (list and repeater slots)
Customize each row via its item slot	Be split across multiple `<VeltWireframe>` roots

Where to look things up

Slots & slot props: Wireframe components (every wireframe + full slot trees) and the overview in Component catalog.
Variables/tokens: the full {…} catalog in Template Variables; condition syntax in Conditional Templates and Conditional Classes.
Stateful CSS classes (to style state without a slot): CSS classes.
Props on the live component (variant selection, shadowDom, feature toggles): Props.

Troubleshooting

Common wireframe symptoms, in Debugging:

Checklist

Exactly one <VeltWireframe> in the app.
The live feature component (VeltComments / VeltCommentsSidebar / VeltCommentDialog) is mounted in addition to the wireframe.
No React onClick/useState/hooks inside slot markup: interactivity comes from Velt…Wireframe.X slots only.
For list/repeater slots, customized the item, not the container layout (list and repeater slots).
Only real slot names (Wireframe components) and real {…} variables (Template Variables).
shadowDom={false} if you style the result.
Decided scope per child wireframe: nested = scoped, root = global (scoping).
Unfilled slots intentionally left to Velt defaults.

Concepts

Approaches

Components: Async Collaboration

Components: Realtime Collaboration

Reference

Wireframes Overview

The model

Quick example

The interactivity rule

Scoping: global vs scoped wireframes

Slot granularity

Variants

List and repeater slots

Tokens: live data in your markup

Page mode

What it can and can’t do

Where to look things up

Troubleshooting

Checklist

​The model

​Quick example

​The interactivity rule

​Scoping: global vs scoped wireframes

​Slot granularity

​Variants

​List and repeater slots

​Tokens: live data in your markup

​Page mode

​What it can and can’t do

​Where to look things up

​Troubleshooting

​Checklist

The model

Quick example

The interactivity rule

Scoping: global vs scoped wireframes

Slot granularity

Variants

List and repeater slots

Tokens: live data in your markup

Page mode

What it can and can’t do

Where to look things up

Troubleshooting

Checklist