Presence & Live Cursors

Real-time “who’s here” avatars (presence) and live remote cursors. Both are wireframed at the per-item level and use flat-config variables ({componentConfig.<x>}).

Components

	Primitive	Wireframe
Presence	`VeltPresence`	`VeltPresenceWireframe`
Presence tooltip	None (no standalone mount)	`VeltPresenceTooltipWireframe`
Live cursor pointer	`VeltCursor`	`VeltCursorPointerWireframe` (per-user pointer only)

The root <velt-cursor> just spawns one pointer per remote user and isn’t wireframable; only the per-user pointer is.

Config props

Presence

Prop	Default	What it does
`maxUsers`	`5`	Caps avatars before the “+N” overflow
`self`		Include the local user
`inactivityTime`	5 min	Time until a user shows as away
`offlineInactivityTime`	10 min	Time until a user drops offline
`flockMode` / `defaultFlockNavigation`		Follow-along mode
`location` / `locationId`		Scope presence to a location
`variant` / `shadowDom`		Wireframe variant / shadow-DOM toggle

Live Cursors

Prop	Default	What it does
`avatarMode`		Avatar bubbles vs arrows
`inactivityTime`	5	Time until a cursor hides
`allowedElementIds`		Restrict cursors to specific elements
`variant` / `darkMode`		Wireframe variant / dark theme

CSS: stateful classes

(Override with !important, R9b.)

Class	Applied when
`velt-presence-avatar--away` (and `.away`)	`onlineStatus === 'away'`
`velt-presence-avatar-outline`	Always; tinted by `presenceUser.color`
`no-transition`	Self pointer
`…default-container-comment-border`	`cursorUser.comment` present
`flip` (on the huddle `<video>`)	Self pointer

Wireframes: slot trees + tokens

Presence

VeltPresenceWireframe → .AvatarList → .AvatarList.Item   ·   .AvatarRemainingCount
VeltPresenceTooltipWireframe → .Avatar · .UserName · .UserActive · .UserInactive · .StatusContainer

Tooltip slots are status-gated: .UserActive renders only for online, .UserInactive only for away (neither for offline). Key tokens ({componentConfig.<x>}): filteredPresenceUsers (list hidden when length === 0), user (hidden if user.isAnonymous), maxUsers; per-item presenceUser (.name/.email/.onlineStatus/.color), index (renders when index < maxUsers); remaining-count renders when filteredPresenceUsers.length > maxUsers.

Live Cursors

VeltCursorPointerWireframe
├── .Arrow                         (the cursor glyph; fill bound to cursorUser.color)
├── .Default → .Name / .Comment
├── .Avatar
├── .AudioHuddle → .Avatar / .Audio
└── .VideoHuddle

Key tokens (per-user, flat): cursorUser (.name/.color/.photoUrl/.comment/.position), selfCursorPointer, showDefault/showAvatar/showAudio/showVideo (derived from stream + avatarMode), variant.

Headless hooks

Hook	Returns
`usePresenceData(query?)`	`{ data: PresenceUser[] \| null }` (current; `usePresenceUsers()` is deprecated)
`usePresenceUtils()`	Imperative presence element
`useCursorUsers()`	`CursorUser[] \| null`
`useCursorUtils()`	Imperative cursor element (`setInactivityTime`, `allowedElementIds`)

Limitations

Presence

Anonymous local users never see presence; maxUsers both caps avatars and gates the overflow badge; a custom template needs explicit shadowDom="true" to use shadow DOM.

Live Cursors

There is no live-cursor pin/image prop. (pin-cursor-image is a VeltComments prop for the comment-placement cursor, not live cursors.) To change the live cursor glyph, use the <slot name="cursor"> or the .Arrow wireframe.
The root <velt-cursor> isn’t wireframable: only the per-user pointer is.
Your own cursor is hidden in normal use (selfCursorPointer shows only in huddle-on-cursor mode).
Requires an identified (non-anonymous) user.

Concepts

AI Agent Workflow

Approaches

Feature Guides

Components: Async Collaboration

Components: Realtime Collaboration

Guidance

Reference

Presence & Live Cursors

Components

Config props

Presence

Live Cursors

CSS: stateful classes

Wireframes: slot trees + tokens

Presence

Live Cursors

Headless hooks

Limitations

Presence

Live Cursors

​Components

​Config props

​Presence

​Live Cursors

​CSS: stateful classes

​Wireframes: slot trees + tokens

​Presence

​Live Cursors

​Headless hooks

​Limitations

​Presence

​Live Cursors

Components

Config props

Presence

Live Cursors

CSS: stateful classes

Wireframes: slot trees + tokens

Presence

Live Cursors

Headless hooks

Limitations

Presence

Live Cursors