> ## 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](/ui-customization/overview) and the [Template Variables](/ui-customization/template-variables) overview.
</Note>

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

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

<Tabs>
  <Tab title="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>

  <Tab title="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>
    ```
  </Tab>
</Tabs>

## 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](./cursors) — wireframe overview and default markup for this primitive.
* [Template Variables](/ui-customization/template-variables) — overview of the `velt-data` / `velt-if` / `velt-class` system.