> ## Documentation Index
> Fetch the complete documentation index at: https://velt-codex-ui-customization-guide-refresh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Presence & Live Cursors

> Customize Velt presence avatars and live cursors with supported components and styling hooks.

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

### Presence

`VeltPresence` (primitive) · `VeltPresenceWireframe` + `VeltPresenceTooltipWireframe`. The tooltip has no standalone mount: customize it only via `VeltPresenceTooltipWireframe`.

### Live Cursors

`VeltCursor` (primitive) · `VeltCursorPointerWireframe`. Only the **per-user pointer** is wireframable: the root `<velt-cursor>` just spawns one pointer per remote user and isn't wireframable.

## Config props

### Presence

`maxUsers` (default **5**: caps avatars before the "+N" overflow), `self` (include local user), `inactivityTime` (→ away, default 5 min), `offlineInactivityTime` (default 10 min), `variant`, `shadowDom`, `flockMode` / `defaultFlockNavigation`, `location`/`locationId`.

### Live Cursors

`avatarMode` (avatar bubbles vs arrows), `inactivityTime` (default 5), `allowedElementIds` (restrict cursors to elements), `variant`, `darkMode`.

## CSS: stateful classes

(Override with `!important`, R9b.)

### Presence

`velt-presence-avatar--away` (and `.away`) when `onlineStatus === 'away'`; `velt-presence-avatar-outline` is tinted by `presenceUser.color`.

### Live Cursors

`no-transition` (self pointer); `…default-container-comment-border` when `cursorUser.comment`; `flip` on the huddle `<video>` for the 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

### Presence

`usePresenceData(query?)` → `{ data: PresenceUser[] | null }` (current); `usePresenceUtils()` (imperative). (`usePresenceUsers()` is deprecated.)

### Live Cursors

`useCursorUsers()` → `CursorUser[] | null`; `useCursorUtils()` (imperative: `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.