> ## Documentation Index > Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # velt-cursors-best-practices > Velt Cursors implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time cursor tracking, collaborative cursor sharing, avatar-mode cursors, cursor element whitelisting, cursor inactivity timeouts, cursor position subscriptions, customizing the cursor pointer wireframe and its flat-config componentConfig template variables (cursorUser, showAvatar / showAudio / showVideo, huddle-on-cursor flags, helper functions), or customizing the Live Selection remote-user indicator wireframe (VeltSelectionElementPortalWireframe / velt-selection-element-portal, live-selection, selection-element-portal, userIndicatorPosition / userIndicatorType, selections). Triggers on any task involving live cursors, collaborative cursor display, live selection indicators, VeltCursor, VeltCursorPointerWireframe, VeltSelection*, cursor tracking on canvas or whiteboard, or showing where other users are pointing or selecting — even if the user doesn't explicitly say 'cursors' or 'live-selection'. This page is generated from the actual `SKILL.md` file on disk. ## Metadata | Field | Value | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Source group | User Skills | | Source root | `/Users/meganharrison/.agents/skills` | | Relative skill path | `velt-cursors-best-practices/SKILL.md` | | Actual file | `/Users/meganharrison/.agents/skills/velt-cursors-best-practices/SKILL.md` | | Description | Velt Cursors implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time cursor tracking, collaborative cursor sharing, avatar-mode cursors, cursor element whitelisting, cursor inactivity timeouts, cursor position subscriptions, customizing the cursor pointer wireframe and its flat-config componentConfig template variables (cursorUser, showAvatar / showAudio / showVideo, huddle-on-cursor flags, helper functions), or customizing the Live Selection remote-user indicator wireframe (VeltSelectionElementPortalWireframe / velt-selection-element-portal, live-selection, selection-element-portal, userIndicatorPosition / userIndicatorType, selections). Triggers on any task involving live cursors, collaborative cursor display, live selection indicators, VeltCursor, VeltCursorPointerWireframe, VeltSelection\*, cursor tracking on canvas or whiteboard, or showing where other users are pointing or selecting — even if the user doesn't explicitly say 'cursors' or 'live-selection'. | | Docs overview | [User Skills](/skills/user-skills) | ## Why this exists Use this page when you want to review the real instructions behind a skill without leaving the docs site. The content below is copied from the actual `SKILL.md` file, not rewritten by hand. ## Raw SKILL.md ````md theme={null} --- name: velt-cursors-best-practices description: "Velt Cursors implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time cursor tracking, collaborative cursor sharing, avatar-mode cursors, cursor element whitelisting, cursor inactivity timeouts, cursor position subscriptions, customizing the cursor pointer wireframe and its flat-config componentConfig template variables (cursorUser, showAvatar / showAudio / showVideo, huddle-on-cursor flags, helper functions), or customizing the Live Selection remote-user indicator wireframe (VeltSelectionElementPortalWireframe / velt-selection-element-portal, live-selection, selection-element-portal, userIndicatorPosition / userIndicatorType, selections). Triggers on any task involving live cursors, collaborative cursor display, live selection indicators, VeltCursor, VeltCursorPointerWireframe, VeltSelection*, cursor tracking on canvas or whiteboard, or showing where other users are pointing or selecting — even if the user doesn't explicitly say 'cursors' or 'live-selection'." license: MIT metadata: author: velt version: "1.1.1" --- # Velt Cursors Best Practices Comprehensive implementation guide for Velt's real-time cursor tracking feature (and the sibling Live Selection indicator). Contains 13 rules across 7 categories covering setup, configuration, data access, events, UI customization, wireframe template variables, and debugging. ## When to Apply Reference these guidelines when: - Adding real-time cursor tracking to a canvas, whiteboard, or collaborative page - Configuring cursor display (avatar mode, name labels) - Restricting cursor visibility to specific page elements - Subscribing to cursor position data or user changes - Customizing cursor pointer appearance with wireframes - Debugging cursors not showing or tracking incorrectly ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Core Setup | CRITICAL | `core-` | | 2 | Data Access | HIGH | `data-` | | 3 | Configuration | HIGH-MEDIUM | `config-` | | 4 | Events | MEDIUM | `events-` | | 5 | UI Customization | MEDIUM | `ui-` | | 6 | Wireframe Variables | MEDIUM | `wireframe-variables-` | | 7 | Debugging | LOW-MEDIUM | `debug-` | ## Quick Reference ### Core Setup (CRITICAL) - `core-auth-provider` — Use authProvider on VeltProvider, never identify() - `core-setup` — Add VeltCursor component inside content area (not toolbar) - `core-document-setup` — Set document context to scope cursors per document ### Data Access (HIGH) - `data-cursor-hooks` — useCursorUsers, useCursorUtils React hooks - `data-cursor-api` — getCursorElement, getOnlineUsersOnCurrentDocument Observable ### Configuration (HIGH-MEDIUM) - `config-allowed-elements` — Restrict cursors to specific DOM elements - `config-avatar-mode` — Show user avatars instead of name labels - `config-inactivity-time` — Configure inactive timeout threshold ### Events (MEDIUM) - `events-cursor-change` — onCursorUserChange callback for position updates ### UI Customization (MEDIUM) - `ui-wireframes` — Cursor pointer wireframe variants (Arrow, Avatar, Default, Huddle) ### Wireframe Variables (MEDIUM) - `wireframe-variables-cursors` — Flat-config `componentConfig.` variables for `` and `` (cursorUser, showAvatar / showAudio / showVideo, huddle flags, helper functions) - `wireframe-variables-live-selection` — Flat-config `componentConfig.` variables for `` (selections, userIndicatorPosition, userIndicatorType, position) plus `UserIndicatorPosition` / `UserIndicatorType` / `CursorPosition` / `Selection` type reference ### Debugging (LOW-MEDIUM) - `debug-common-issues` — Troubleshooting cursor tracking issues ## How to Use Read individual rule files for detailed explanations and code examples: ``` rules/shared/core/core-setup.md rules/shared/config/config-allowed-elements.md rules/shared/data/data-cursor-hooks.md ``` ## Compiled Documents - `AGENTS.md` — Compressed index of all rules with file paths (start here) - `AGENTS.full.md` — Full verbose guide with all rules expanded inline ````