velt-view-analytics-best-practices

Implement Velt View Analytics badges, view-count hooks, and wireframe customizations.

1|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/velt-js/agent-skills --skill velt-view-analytics-best-practices-velt-js
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: velt-view-analytics-best-practices
Source: https://github.com/velt-js/agent-skills/tree/main/skills/velt-view-analytics-best-practices
Command: npx skills add https://github.com/velt-js/agent-skills --skill velt-view-analytics-best-practices-velt-js

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @veltdev/react, and includes references (resource) components.

What problem does it solve? Adding a "who viewed this document today" indicator with Velt involves several easy-to-get-wrong details: scoping counts to sub-documents, choosing between React hooks and observable subscriptions, and binding wireframe template variables with non-obvious names like treadsVisible. This Skill provides verified implementation rules so AI agents generate correct Velt View Analytics code without hallucinating APIs like getViewElement(). ## Core Features & Use Cases - Component Setup & Location Scoping: Place <VeltViewAnalytics> correctly and scope view counts to sub-regions using type="location" plus location-id. - Programmatic View Counts: Read unique views by user or by date via React hooks (useUniqueViewsByUser, useUniqueViewsByDate, useViewsElement) or the non-React observable form client.getViewsElement().get*().subscribe(...) with proper cleanup. - Custom UI via Wireframes: Build fully custom trigger badges, viewer-list dialogs, and mobile bottom sheets using the three wireframe tags and their componentConfig.* template variables. - Use Case: You are building a multi-tab collaborative document and want a per-tab "viewed today" badge with a custom-styled recent-viewers popover — this Skill gives the exact props, hooks, and wireframe bindings to implement it. ## Quick Start Ask the agent to add a Velt View Analytics badge to your toolbar and show the count of unique viewers using the appropriate React hook.

Frequently Asked Questions about velt-view-analytics-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a 'who viewed this document' badge with Velt?▼

Place the <VeltViewAnalytics> component from @veltdev/react in your toolbar, inside a tree wrapped by VeltProvider with a document set. The single component renders the trigger badge, desktop dialog, and mobile bottom sheet.

How do I scope Velt view counts to a specific tab or sub-document?▼

Pass both type="location" and a location-id prop on <VeltViewAnalytics>, for example location-id="tab-3". The location-id alone is ignored without type="location", and counts then roll up to the whole document.

Which React hook returns the count of unique viewers in Velt?▼

Use useUniqueViewsByUser() from @veltdev/react and read .length on the returned array, null-guarding with ?. and ?? 0 since it is undefined on first render. An optional locationId argument scopes the count to a sub-document.

Why does client.getViewElement() fail in my Velt integration?▼

The correct handle is client.getViewsElement() — plural. getViewElement() (singular) does not exist in the SDK and is a common hallucination; use the plural form before calling getUniqueViewsByUser() or getUniqueViewsByDate().

Why is my velt-class binding on componentConfig.threadsVisible not working?▼

The variable is spelled componentConfig.treadsVisible — a legacy SDK spelling of 'treads', not 'threads'. Also keep the componentConfig. prefix, since the flat-config pattern resolves nothing without it.

Can I build custom Velt view analytics UI without the default component?▼

Yes, either subscribe via the hooks or observable directly, or use the wireframe tags (velt-view-analytics-wireframe, -dialog-wireframe, -bottom-sheet-wireframe) bound to componentConfig.* variables. If a hooks-only badge shows zero viewers, mount a hidden <VeltViewAnalytics> as a fallback.