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

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