> ## 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](/ui-customization/overview) and the [Template Variables](/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`](/api-reference/sdk/models/data-models#presenceuser)`[]` | Active users (after filters) — drives the avatar list.                                              | `<velt-data field="componentConfig.filteredPresenceUsers.length" />` |
| `componentConfig.user`                  | [`User`](/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`](/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](/api-reference/sdk/models/data-models):

| Type                                                                 | Description                                                |
| -------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`PresenceUser`](/api-reference/sdk/models/data-models#presenceuser) | Active-user record (id, name, photoUrl, lastActive, etc.). |
| [`User`](/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`](/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](/ui-customization/template-variables) — overview of the `velt-data` / `velt-if` / `velt-class` system.