Cursors Wireframe Variables

Template variables exposed by the Cursors wireframe — read them with velt-data, velt-if, and velt-class to drive dynamic content, conditional rendering, and class toggling.

New to wireframes? Start with UI Customization Concepts and the Template Variables overview.

Overview

The Live Cursors feature renders collaborative cursor pointers showing where each remote user is on the page. Variables below are available inside any <velt-cursor-pointer-...-wireframe> tag via three forms:

You want to…	Use	Example
Display a value as text	<velt-data field="var" />	<velt-data field="componentConfig.cursorUser.name" />
Hide / show conditionally	velt-if="{var}"	velt-if="{componentConfig.showAvatar}"
Toggle a CSS class	velt-class="'cls': {var}"	velt-class="'is-self': {componentConfig.selfCursorPointer}"

This feature uses the flat-config access pattern — variables are referenced via the explicit componentConfig.<path> form. The orchestrating <velt-cursor> element controls visibility but is not itself wireframed; only the per-user pointer (<velt-cursor-pointer-wireframe>) is customizable.

Component Config — Cursor (root)

State on the root <velt-cursor> element. These variables describe the full set of remote cursors and the local user.

Variable	Type	Description	Example
componentConfig.user	User	Currently identified end-user.	<velt-data field="componentConfig.user.name" />
componentConfig.cursorUsers	CursorUser[]	Remote users — one entry per pointer to render.	<velt-data field="componentConfig.cursorUsers.length" />
componentConfig.currentCursorUser	CursorUser	The current iteration cursor user.	<velt-data field="componentConfig.currentCursorUser.name" />
componentConfig.huddleOnCursorMode	boolean	Global “huddle-on-cursor” mode is active.	velt-class="'huddle-mode': {componentConfig.huddleOnCursorMode}"
componentConfig.huddleJoined	boolean	Local user has joined a huddle.	velt-if="{componentConfig.huddleJoined}"
componentConfig.huddleOnCursorModeByAttendeeId	Record<string, boolean>	Per-attendee huddle-on-cursor mode flag.	velt-class="'huddle-active': {componentConfig.huddleOnCursorModeByAttendeeId[user.userId]}"
componentConfig.attendeesByUserId	Record<string, Attendee>	Remote attendees keyed by user id.	<velt-data field="componentConfig.attendeesByUserId[user.userId].name" />
componentConfig.remoteStreamsByUserId	Record<string, Record<string, MediaStream>>	Remote audio / video streams keyed by user id then stream id.	Internal — not user-addressable.
componentConfig.localStream	MediaStream | undefined	Local media stream (when in a huddle).	velt-if="{componentConfig.localStream}"
componentConfig.isFirstComponent	boolean	True only on the first instance of the element on the page.	velt-if="{componentConfig.isFirstComponent}"

Component Config — Cursor Pointer (per-user)

The cursor-pointer’s componentConfigSignal is per-user — it carries data for one specific cursor. Use these variables inside <velt-cursor-pointer-wireframe> and its child tags.

Variable	Type	Description	Example
componentConfig.cursorUser	CursorUser	The user this pointer represents. Includes name, color, textColor, photoUrl, userId, etc.	<velt-data field="componentConfig.cursorUser.name" />
componentConfig.selfCursorPointer	boolean	True when this pointer represents the local user. (Used for testing / demos; production hides own cursor.)	velt-class="'is-self': {componentConfig.selfCursorPointer}"
componentConfig.showDefault	boolean	Default arrow icon should render.	velt-if="{componentConfig.showDefault}"
componentConfig.showAvatar	boolean	Avatar bubble should render.	velt-if="{componentConfig.showAvatar}"
componentConfig.showAudio	boolean	Audio indicator (huddle mode) should render.	velt-if="{componentConfig.showAudio}"
componentConfig.showVideo	boolean	Video tile (huddle mode) should render.	velt-if="{componentConfig.showVideo}"
componentConfig.stream	MediaStream | undefined	Audio / video stream when available.	velt-if="{componentConfig.stream}"
componentConfig.gainVolume	number	Audio gain level for the animated speaking ring.	<velt-data field="componentConfig.gainVolume" />
componentConfig.lightenedColor	string	Lightened version of cursorUser.color (used for ring highlights).	Internal — used to compute inline style.
componentConfig.variant	string	Wireframe variant id.	<velt-data field="componentConfig.variant" />

Helper functions

The cursor-pointer config also exposes three helper functions you can call from your wireframe markup:

Function	Returns	Description
componentConfig.onImageLoadError()	—	Call from your custom <img onerror>. Falls back to the initials avatar.
componentConfig.getGainAnimationBorderStyle()	string	Returns the inline border-color: ... string for the speaking-ring animation.
componentConfig.getTextColor()	string	Returns the contrast-correct text colour for the user’s name label.

Common Props

The root <velt-cursor> element accepts these public attributes (each maps onto componentConfig.<name>):

React Prop	HTML Attribute	Type	Default	Description
darkMode	dark-mode	boolean	false	Force dark-mode rendering.
variant	variant	string	—	Wireframe variant id.

The per-user <velt-cursor-pointer-wireframe> does not accept additional public props — its config is supplied by the cursor service for each remote user.

Type Reference

Types referenced by the variables above:

Type	Description
User	Identified end-user object (used by componentConfig.user).
CursorUser	Per-cursor user record — name, color, textColor, photoUrl, userId, etc.
Attendee	Huddle attendee record (used by attendeesByUserId).

Subcomponents

cursor (root, no wireframe registration)

The orchestrating element. Reads cursor positions from the realtime feed and instantiates one cursor-pointer per remote user.

• Public element: <velt-cursor>

Property	Value
Wireframe tag	No <velt-...-wireframe> registration on the root. Customize the per-user pointer via <velt-cursor-pointer-wireframe> instead.

---

cursor-pointer

The per-user cursor visual.

• Public element: <velt-cursor-pointer> (rarely used directly; usually rendered by <velt-cursor>)
• Wireframe tag: <velt-cursor-pointer-wireframe>

Property	Value
Extra variables	All per-user variables in Component Config — Cursor Pointer.
shouldShow	No primitive-level override — visibility is controlled by the parent <velt-cursor> (one pointer per active remote user).
Host class	velt-cursor-pointer-container user-presence-pointer (always). no-transition when componentConfig.selfCursorPointer is true.

React / Next.js

<VeltCursorPointerWireframe>
  <div className="my-cursor" style={{ background: '{componentConfig.cursorUser.color}' }}>
    <span className="my-cursor__name" style={{ color: '{componentConfig.getTextColor()}' }}>
      <VeltData field="componentConfig.cursorUser.name" />
    </span>
  </div>
</VeltCursorPointerWireframe>

Other Frameworks

<velt-cursor-pointer-wireframe>
  <div class="my-cursor" [style.background]="'{componentConfig.cursorUser.color}'">
    <span class="my-cursor__name" [style.color]="'{componentConfig.getTextColor()}'">
      {{ '{componentConfig.cursorUser.name}' }}
    </span>
  </div>
</velt-cursor-pointer-wireframe>

Deeply-Nested Wireframe Tags

The cursor-pointer decomposes into the tags below — each registered as <velt-cursor-pointer-...-wireframe>. Inside each, the per-user componentConfig (from the cursor-pointer config) resolves.

Cursor Pointer child tags

Tag	Notes	Example
<velt-cursor-pointer-arrow-wireframe>	The arrow-icon part of the pointer.	velt-class="'is-self': {componentConfig.selfCursorPointer}"
<velt-cursor-pointer-default-wireframe>	The default (non-huddle) pointer surround.	<velt-data field="componentConfig.cursorUser.name" />
<velt-cursor-pointer-default-name-wireframe>	The name pill on the default pointer.	<velt-data field="componentConfig.cursorUser.name" />
<velt-cursor-pointer-default-comment-wireframe>	An inline comment label that can appear next to the pointer.	Action-specific — wire your own UI inside.
<velt-cursor-pointer-avatar-wireframe>	The user’s avatar bubble.	<velt-data field="componentConfig.cursorUser.photoUrl" />
<velt-cursor-pointer-audio-huddle-wireframe>	Audio-huddle pointer variant (shows speaking ring).	velt-class="'gain-{componentConfig.gainVolume}': true"
<velt-cursor-pointer-audio-huddle-avatar-wireframe>	Audio-huddle avatar inside the pointer.	<velt-data field="componentConfig.cursorUser.photoUrl" />
<velt-cursor-pointer-audio-huddle-audio-wireframe>	Audio waveform / VU indicator inside the pointer.	<velt-data field="componentConfig.gainVolume" />
<velt-cursor-pointer-video-huddle-wireframe>	Video-huddle pointer variant (shows live video tile).	velt-if="{componentConfig.stream}"

Related

• Cursors — wireframe overview and default markup for this primitive.
• Template Variables — overview of the velt-data / velt-if / velt-class system.