useViewTime

Docs

useViewTime

Measure how long a user actually views a component, using visibility tracking and timers instead of simple impressions.

Installation

pnpm dlx uselab@latest add use-view-time

Usage

import * as React from "react"
 
import { useViewTime } from "@/hooks/use-view-time"
 
export function AnalyticsRow() {
  const ref = React.useRef<HTMLDivElement | null>(null)
  const { secondsViewed } = useViewTime(ref, { threshold: 0.5 })
 
  return <div ref={ref}>Viewed for {secondsViewed}s</div>
}

API Reference

`useViewTime(ref, options?)`

Tracks how long the referenced element is considered visible in the viewport, updating a running total in seconds.

Parameters

Name	Type	Description	Optional	Default
`ref`	`React.RefObject<HTMLElement \| null>`	Ref pointing to the DOM node you want to track.	No	—
`options`	`UseViewTimeOptions`	Configuration object for visibility thresholds.	Yes	`{}`
`threshold`	`number`	Intersection ratio required before a period counts as “viewed” (0–1).	Yes	`0.5`

Return value

The hook returns an object { secondsViewed }:

Name	Type	Description
`secondsViewed`	`number`	Total whole seconds the element has been considered visible.

Types

interface UseViewTimeOptions {
  threshold?: number
}
 
interface UseViewTimeResult {
  secondsViewed: number
}

How it works

Uses IntersectionObserver to detect when the element meets the configured threshold (e.g. 50% visible).
Starts a timer when the element enters the viewport and the tab is visible, and stops it when:
- The element scrolls out of view.
- The tab becomes hidden (visibilitychange).
Accumulates elapsed milliseconds and exposes the total as whole seconds via secondsViewed.

Notes

Ideal for content analytics (hero sections, pricing modules, promoted content) where you care about view time, not just page loads.
Works best when each tracked element has a stable ref; re-mounting a component resets its timer.
For per-user or per-session analytics, combine useViewTime with your own event pipeline to send summarized counts to your backend.

useVibration useVisibilityChange

On This Page

Installation
Usage
API Reference
- useViewTime(ref, options?)
- Types
How it works
Notes

Contribute

Usage

import * as React from "react"
 
import { useViewTime } from "@/hooks/use-view-time"
 
export function AnalyticsRow() {
  const ref = React.useRef<HTMLDivElement | null>(null)
  const { secondsViewed } = useViewTime(ref, { threshold: 0.5 })
 
  return <div ref={ref}>Viewed for {secondsViewed}s</div>
}

API Reference

useViewTime(ref, options?)

Tracks how long the referenced element is considered visible in the viewport, updating a running total in seconds.

Parameters

Name	Type	Description	Optional	Default
`ref`	`React.RefObject<HTMLElement \| null>`	Ref pointing to the DOM node you want to track.	No	—
`options`	`UseViewTimeOptions`	Configuration object for visibility thresholds.	Yes	`{}`
`threshold`	`number`	Intersection ratio required before a period counts as “viewed” (0–1).	Yes	`0.5`

Return value

The hook returns an object { secondsViewed }:

Name	Type	Description
`secondsViewed`	`number`	Total whole seconds the element has been considered visible.

Types

interface UseViewTimeOptions {
  threshold?: number
}
 
interface UseViewTimeResult {
  secondsViewed: number
}

How it works

Uses IntersectionObserver to detect when the element meets the configured threshold (e.g. 50% visible).

Starts a timer when the element enters the viewport and the tab is visible, and stops it when:

The element scrolls out of view.
The tab becomes hidden (visibilitychange).

Accumulates elapsed milliseconds and exposes the total as whole seconds via secondsViewed.

Notes

Ideal for content analytics (hero sections, pricing modules, promoted content) where you care about view time, not just page loads.

Works best when each tracked element has a stable ref; re-mounting a component resets its timer.

For per-user or per-session analytics, combine useViewTime with your own event pipeline to send summarized counts to your backend.