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

# Presence Wireframe Variables

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

## Overview

The **Presence** wireframe powers the user-avatar list showing who is currently active in the document. Variables below are available inside any `<velt-presence-...-wireframe>` tag via three forms:

| You want to… | Use | Example |
| - | - | - |
| Display a value as text | `<velt-data field="var" />` | `<velt-data field="componentConfig.user.name" />` |
| Hide / show conditionally | `velt-if="{var}"` | `velt-if="{componentConfig.filteredPresenceUsers.length} > 0"` |
| Toggle a CSS class | `velt-class="'cls': {var}"` | `velt-class="'is-active': {componentConfig.isActive}"` |

<Note>
  This feature uses the **flat-config** access pattern — variables are referenced via the explicit `componentConfig.<path>` form.
</Note>

## Component Config

Root-level state shared with every Presence primitive.

| Variable | Type | Description | Example |
| - | - | - | - |
| `componentConfig.filteredPresenceUsers` | [`PresenceUser`](/docs/api-reference/sdk/models/data-models#presenceuser)`[]` | Active users (after filters) — drives the avatar list. | `<velt-data field="componentConfig.filteredPresenceUsers.length" />` |
| `componentConfig.user` | [`User`](/docs/api-reference/sdk/models/data-models#user) | Currently identified end-user. | `<velt-data field="componentConfig.user.name" />` |
| `componentConfig.shadowDom` | `boolean` | Shadow-DOM rendering is enabled. | *Host config — set via element attribute.* |
| `componentConfig.variant` | `string` | Per-instance variant tag. | `<velt-data field="componentConfig.variant" />` |
| `componentConfig.maxUsers` | `number` | Max avatars to show before collapsing into "+N" (default `5`). | `<velt-data field="componentConfig.maxUsers" />` |
| `componentConfig.tooltipContent` | `TemplateRef<any>` | Custom tooltip template (set programmatically via the `[template]` input — not used in wireframes). | *Internal — programmatic only.* |
| `componentConfig.trackById` | `Function` | Identity function used internally to track list items. | *Internal — used as a track-by function.* |
| `componentConfig.showTooltip` | `Function` | Hover-in handler. Wire to `(mouseenter)` on a custom avatar. | *Call this from your custom avatar markup.* |
| `componentConfig.closeTooltip` | `Function` | Hover-out handler. | *Call this from your custom avatar markup.* |
| `componentConfig.onPresenceUserClick` | `Function` | Click handler for an avatar row. | *Call this from your custom avatar markup.* |

## Context-Specific Variables

These are only resolvable inside the nested wireframe tags noted in the **Available in** column. Each is injected by the iteration / tooltip primitive that owns the tag.

| Variable | Type | Available in | Example |
| - | - | - | - |
| `componentConfig.user` | [`PresenceUser`](/docs/api-reference/sdk/models/data-models#presenceuser) | `<velt-presence-tooltip-wireframe>` and tooltip children | `<velt-data field="componentConfig.user.name" />` |
| `componentConfig.isActive` | `boolean` | Tooltip context — `true` when the hovered user is currently active. | `velt-class="'is-active': {componentConfig.isActive}"` |
| `componentConfig.lastActiveAt` | `number` | Tooltip context — Unix timestamp when the user was last active. | `<velt-data field="componentConfig.lastActiveAt" />` |

## Type Reference

Types referenced by the variables above are documented in [Data Models](/docs/api-reference/sdk/models/data-models):

| Type | Description |
| - | - |
| [`PresenceUser`](/docs/api-reference/sdk/models/data-models#presenceuser) | Active-user record (id, name, photoUrl, lastActive, etc.). |
| [`User`](/docs/api-reference/sdk/models/data-models#user) | Identified end-user object. |

## Subcomponents

Each subcomponent below has its own wireframe tag.

### `presence` (root)

The root primitive — the `<velt-presence>` element customers place in their app.

* **Public element:** `<velt-presence>`
* **Wireframe tag (HTML):** `<velt-presence-wireframe>`
* **Wireframe (React):** `<VeltPresenceWireframe />`

| Property | Value |
| - | - |
| Extra variables | None — root only sees common variables. |

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltWireframe>
      <VeltPresenceWireframe>
        <VeltPresenceWireframe.AvatarList />
        <VeltPresenceWireframe.AvatarRemainingCount />
      </VeltPresenceWireframe>
    </VeltWireframe>
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-wireframe>
      <velt-presence-wireframe>
        <velt-presence-avatar-list-wireframe></velt-presence-avatar-list-wireframe>
        <velt-presence-avatar-remaining-count-wireframe></velt-presence-avatar-remaining-count-wireframe>
      </velt-presence-wireframe>
    </velt-wireframe>
    ```
  </Tab>
</Tabs>

***

### `presence-avatar-list`

The list container that iterates `filteredPresenceUsers` and renders one avatar per active user.

* **Public element:** `<velt-presence-avatar-list>`
* **Wireframe tag (HTML):** `<velt-presence-avatar-list-wireframe>`
* **Wireframe (React):** `<VeltPresenceWireframe.AvatarList />`
* **Children:** `presence-avatar-list-item` — `<velt-presence-avatar-list-item-wireframe>` (per-user avatar).

| Property | Value |
| - | - |
| Extra variables | None at the list level. The per-iteration child receives the user from `componentConfig.user`. |

***

### `presence-avatar-list-item`

A single avatar in the list. Iterates over `filteredPresenceUsers`.

* **Public element:** `<velt-presence-avatar-list-item>`
* **Wireframe tag:** `<velt-presence-avatar-list-item-wireframe>`

| Property | Value |
| - | - |
| Extra variables | Resolves the iteration's `componentConfig.user` ([`PresenceUser`](/docs/api-reference/sdk/models/data-models#presenceuser)). |

***

### `presence-avatar-remaining-count`

The "+N more" badge shown when there are more active users than `componentConfig.maxUsers`.

* **Public element:** `<velt-presence-avatar-remaining-count>`
* **Wireframe tag (HTML):** `<velt-presence-avatar-remaining-count-wireframe>`
* **Wireframe (React):** `<VeltPresenceWireframe.AvatarRemainingCount />`

| Property | Value |
| - | - |
| Extra variables | None. |
| `shouldShow` | `componentConfig.filteredPresenceUsers.length > componentConfig.maxUsers` |

***

### `presence-tooltip`

Hover tooltip that opens over an avatar.

* **Public element:** `<velt-presence-tooltip>`
* **Wireframe tag (HTML):** `<velt-presence-tooltip-wireframe>`
* **Wireframe (React):** `<VeltPresenceTooltipWireframe />`
* **Children:** `presence-tooltip-avatar`, `presence-tooltip-status-container`, `presence-tooltip-user-name`, `presence-tooltip-user-active`, `presence-tooltip-user-inactive`.

| Property | Value |
| - | - |
| Extra variables | Per-tooltip context — `componentConfig.user`, `componentConfig.isActive`, `componentConfig.lastActiveAt`. |

## Deeply-Nested Wireframe Tags

The tooltip decomposes further. Each tag below has its own `<velt-presence-tooltip-...-wireframe>` registration and inherits the tooltip's per-user context.

### Tooltip child tags

| Tag | Notes | Example |
| - | - | - |
| `<velt-presence-tooltip-avatar-wireframe>` | The hovered user's avatar. | `<velt-data field="componentConfig.user.photoUrl" />` |
| `<velt-presence-tooltip-status-container-wireframe>` | Wrapper for the active / inactive status row. | (composes the two children below) |
| `<velt-presence-tooltip-user-name-wireframe>` | The hovered user's name. | `<velt-data field="componentConfig.user.name" />` |
| `<velt-presence-tooltip-user-active-wireframe>` | Renders when the user is currently active. | `velt-if="{componentConfig.isActive}"` |
| `<velt-presence-tooltip-user-inactive-wireframe>` | Renders when the user is not currently active. Show the relative `lastActiveAt` here. | `velt-if="!{componentConfig.isActive}"` |

## Related

* [Presence](./presence) — wireframe overview and default markup for this primitive.
* [Template Variables](/docs/ui-customization/template-variables) — 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.