Documentation Index
Fetch the complete documentation index at: https://docs.velt.dev/llms.txt
Use this file to discover all available pages before exploring further.
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. |
<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
Other Frameworks
<VeltCursorPointerWireframe
velt-class="'is-self': {componentConfig.selfCursorPointer}">
<div className="my-cursor">
<span className="my-cursor__name">
<velt-data field="componentConfig.cursorUser.name" />
</span>
</div>
</VeltCursorPointerWireframe>
<velt-cursor-pointer-wireframe
velt-class="'is-self': {componentConfig.selfCursorPointer}">
<div class="my-cursor">
<span class="my-cursor__name">
<velt-data field="componentConfig.cursorUser.name"></velt-data>
</span>
</div>
</velt-cursor-pointer-wireframe>
<velt-cursor-pointer-...-wireframe>. Inside each, the per-user componentConfig (from the cursor-pointer config) resolves.
| 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}" |
Putting it together
A typical cursor-pointer that highlights the local user, swaps between default / huddle modes, and shows a name pill plus avatar:
React / Next.js
Other Frameworks
<VeltCursorPointerWireframe
velt-class="'is-self': {componentConfig.selfCursorPointer}, 'is-huddle': {componentConfig.showAudio} || {componentConfig.showVideo}">
<VeltCursorPointerWireframe.Default
velt-if="{componentConfig.showDefault}">
<VeltCursorPointerWireframe.DefaultName>
<velt-data field="componentConfig.cursorUser.name" />
</VeltCursorPointerWireframe.DefaultName>
</VeltCursorPointerWireframe.Default>
<VeltCursorPointerWireframe.Avatar
velt-if="{componentConfig.showAvatar}">
<img />
</VeltCursorPointerWireframe.Avatar>
<VeltCursorPointerWireframe.AudioHuddle
velt-if="{componentConfig.showAudio}">
<VeltCursorPointerWireframe.AudioHuddle.Audio />
</VeltCursorPointerWireframe.AudioHuddle>
<VeltCursorPointerWireframe.VideoHuddle
velt-if="{componentConfig.showVideo} && {componentConfig.stream}" />
</VeltCursorPointerWireframe>
<velt-cursor-pointer-wireframe
velt-class="'is-self': {componentConfig.selfCursorPointer}, 'is-huddle': {componentConfig.showAudio} || {componentConfig.showVideo}">
<velt-cursor-pointer-default-wireframe velt-if="{componentConfig.showDefault}">
<velt-cursor-pointer-default-name-wireframe>
<velt-data field="componentConfig.cursorUser.name"></velt-data>
</velt-cursor-pointer-default-name-wireframe>
</velt-cursor-pointer-default-wireframe>
<velt-cursor-pointer-avatar-wireframe velt-if="{componentConfig.showAvatar}">
<img />
</velt-cursor-pointer-avatar-wireframe>
<velt-cursor-pointer-audio-huddle-wireframe velt-if="{componentConfig.showAudio}">
<velt-cursor-pointer-audio-huddle-audio-wireframe></velt-cursor-pointer-audio-huddle-audio-wireframe>
</velt-cursor-pointer-audio-huddle-wireframe>
<velt-cursor-pointer-video-huddle-wireframe
velt-if="{componentConfig.showVideo} && {componentConfig.stream}"></velt-cursor-pointer-video-huddle-wireframe>
</velt-cursor-pointer-wireframe>
- Cursors — wireframe overview and default markup for this primitive.
- Template Variables — overview of the
velt-data / velt-if / velt-class system.
