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 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}" |
This feature uses the flat-config access pattern — variables are referenced via the explicit componentConfig.<path> form.
Component Config
Root-level state shared with every Presence primitive.
| Variable | Type | Description | Example |
|---|
componentConfig.filteredPresenceUsers | PresenceUser[] | Active users (after filters) — drives the avatar list. | <velt-data field="componentConfig.filteredPresenceUsers.length" /> |
componentConfig.user | 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 | <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:
| Type | Description |
|---|
PresenceUser | Active-user record (id, name, photoUrl, lastActive, etc.). |
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:
<velt-presence-wireframe>
| Property | Value |
|---|
| Extra variables | None — root only sees common variables. |
React / Next.js
Other Frameworks
<VeltPresenceWireframe>
<VeltPresenceWireframe.AvatarList />
<VeltPresenceWireframe.AvatarRemainingCount />
<VeltPresenceWireframe.Tooltip />
</VeltPresenceWireframe>
<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-tooltip-wireframe></velt-presence-tooltip-wireframe>
</velt-presence-wireframe>
presence-avatar-list
The list container that iterates filteredPresenceUsers and renders one avatar per active user.
- Public element:
<velt-presence-avatar-list>
- Wireframe tag:
<velt-presence-avatar-list-wireframe>
- 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). |
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:
<velt-presence-avatar-remaining-count-wireframe>
| Property | Value |
|---|
| Extra variables | None. |
shouldShow | componentConfig.filteredPresenceUsers.length > componentConfig.maxUsers |
Hover tooltip that opens over an avatar.
- Public element:
<velt-presence-tooltip>
- Wireframe tag:
<velt-presence-tooltip-wireframe>
- 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. |
<velt-presence-tooltip-...-wireframe> registration and inherits the tooltip’s per-user context.
| 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}" |
Putting it together
A typical Presence list with custom avatars and a tooltip that swaps between active / inactive states:
React / Next.js
Other Frameworks
<VeltPresenceWireframe>
<VeltPresenceWireframe.AvatarList>
<VeltPresenceWireframe.AvatarListItem>
<img className="my-avatar" />
<span><velt-data field="componentConfig.user.name" /></span>
</VeltPresenceWireframe.AvatarListItem>
</VeltPresenceWireframe.AvatarList>
<VeltPresenceWireframe.AvatarRemainingCount
velt-if="{componentConfig.filteredPresenceUsers.length} > {componentConfig.maxUsers}">
+<velt-data field="componentConfig.filteredPresenceUsers.length" />
</VeltPresenceWireframe.AvatarRemainingCount>
<VeltPresenceWireframe.Tooltip>
<div className="my-tooltip" velt-class="'is-active': {componentConfig.isActive}">
<strong><velt-data field="componentConfig.user.name" /></strong>
<VeltPresenceWireframe.Tooltip.UserActive
velt-if="{componentConfig.isActive}">
Active now
</VeltPresenceWireframe.Tooltip.UserActive>
<VeltPresenceWireframe.Tooltip.UserInactive
velt-if="!{componentConfig.isActive}">
Last seen <velt-data field="componentConfig.lastActiveAt" />
</VeltPresenceWireframe.Tooltip.UserInactive>
</div>
</VeltPresenceWireframe.Tooltip>
</VeltPresenceWireframe>
<velt-presence-wireframe>
<velt-presence-avatar-list-wireframe>
<velt-presence-avatar-list-item-wireframe>
<img class="my-avatar" />
<span><velt-data field="componentConfig.user.name"></velt-data></span>
</velt-presence-avatar-list-item-wireframe>
</velt-presence-avatar-list-wireframe>
<velt-presence-avatar-remaining-count-wireframe
velt-if="{componentConfig.filteredPresenceUsers.length} > {componentConfig.maxUsers}">
+<velt-data field="componentConfig.filteredPresenceUsers.length"></velt-data>
</velt-presence-avatar-remaining-count-wireframe>
<velt-presence-tooltip-wireframe>
<div class="my-tooltip" velt-class="'is-active': {componentConfig.isActive}">
<strong><velt-data field="componentConfig.user.name"></velt-data></strong>
<velt-presence-tooltip-user-active-wireframe velt-if="{componentConfig.isActive}">
Active now
</velt-presence-tooltip-user-active-wireframe>
<velt-presence-tooltip-user-inactive-wireframe velt-if="!{componentConfig.isActive}">
Last seen <velt-data field="componentConfig.lastActiveAt"></velt-data>
</velt-presence-tooltip-user-inactive-wireframe>
</div>
</velt-presence-tooltip-wireframe>
</velt-presence-wireframe>
- Presence — wireframe overview and default markup for this primitive.
- Template Variables — overview of the
velt-data / velt-if / velt-class system.
