> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> New to wireframes? Start with [UI Customization Concepts](https://velt.dev/docs/ui-customization/overview.md) and the [Template Variables](https://velt.dev/docs/ui-customization/template-variables.md) 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}"` |

> [!NOTE]
>
> 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`](https://velt.dev/docs/api-reference/sdk/models/data-models#user) | Currently identified end-user. | `<velt-data field="componentConfig.user.name" />` |
| `componentConfig.cursorUsers` | [`CursorUser`](https://velt.dev/docs/api-reference/sdk/models/data-models#cursoruser)`[]` | Remote users — one entry per pointer to render. | `<velt-data field="componentConfig.cursorUsers.length" />` |
| `componentConfig.currentCursorUser` | [`CursorUser`](https://velt.dev/docs/api-reference/sdk/models/data-models#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`](https://velt.dev/docs/api-reference/sdk/models/data-models#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`](https://velt.dev/docs/api-reference/sdk/models/data-models#user) | Identified end-user object (used by `componentConfig.user`). |
| [`CursorUser`](https://velt.dev/docs/api-reference/sdk/models/data-models#cursoruser) | Per-cursor user record — `name`, `color`, `textColor`, `photoUrl`, `userId`, etc. |
| [`Attendee`](https://velt.dev/docs/api-reference/sdk/models/data-models#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](#component-config--cursor-pointer-per-user). |
| `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. |

> [tab] React / Next.js
>
> ```jsx theme={null}
> <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>
> ```

> [tab] Other Frameworks
>
> ```html theme={null}
> <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](https://velt.dev/docs/ui-customization/features/realtime/cursors.md) — wireframe overview and default markup for this primitive.
* [Template Variables](https://velt.dev/docs/ui-customization/template-variables.md) — overview of the `velt-data` / `velt-if` / `velt-class` system.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.