useImpression
Calls your callback once an element has been at least a given share visible for at least a given time, which is what analytics, "mark as read" and ad-view tracking usually mean by "seen". It adds dwell time on top of plain visibility and never re-renders your component.
It differs from useIntersectionObserver,
which reports whether an element is visible as state, right away, and has no
notion of how long it stayed visible.
When to use it
- Analytics events such as "card viewed" or "ad impression".
- Marking messages, notifications or articles as read after the user had time to see them.
- Counting how often a promotion scrolled into view, with
once: false. - Starting work, such as a prefetch, only for content the user actually looked at, not content they scrolled past.
Demo
Scroll the boxes slowly and quickly to compare. The first demo shows the threshold and dwell time options and logs each impression to the Console tab. The second marks messages read and stops tracking them. The third counts repeated views of one banner.
Signature
interface UseImpressionOptions {
threshold?: number;
minDurationMs?: number;
once?: boolean;
root?: Element | Document | null;
rootMargin?: string;
enabled?: boolean;
}
function useImpression<T extends Element = HTMLElement>(
onImpression: (entry: IntersectionObserverEntry) => void,
options?: UseImpressionOptions
): (element: T | null) => void;
| Parameter | Type | Description |
|---|---|---|
onImpression | (entry: IntersectionObserverEntry) => void | Called when an impression is reported, with the latest entry. |
options | UseImpressionOptions? | Optional visibility, timing and observer settings. |
| Option | Type | Description |
|---|---|---|
threshold | number | How much of the element must be visible, from 0 to 1. Values outside the range are clamped. Defaults to 0.5. |
minDurationMs | number | How long it must stay at least threshold visible, in milliseconds. Invalid values fall back to the default. Defaults to 1000. |
once | boolean | Report a single impression per element. With false, it can be reported again after leaving and re-entering. Defaults to true. |
root | Element | Document | null | The viewport used for the check. Pass a scroll container to measure inside it. Defaults to the browser viewport. |
rootMargin | string | Grows or shrinks the root's box, in CSS margin syntax, for example "-50px" to ignore a fixed header. Defaults to "0px". |
enabled | boolean | Set to false to stop observing and discard the timer. Defaults to true. |
Returns: a callback ref. Attach it to the element you want to track.
Usage notes
- A callback ref. It works for elements that mount later, render
conditionally or are swapped for another one. The returned function is stable
across renders. To combine it with another ref, call both from a function
ref:
ref={(el) => { track(el); myRef.current = el; }}. - Dwell time is continuous. The timer starts when the element is at least
thresholdvisible and restarts from zero if it drops below beforeminDurationMshas passed. Changing the visible share while staying abovethresholddoes not affect the timer. - Hidden tabs pause the timer. Time spent while the document is hidden (a background tab, a minimized window) does not count. The timer resumes with the time that was left when the tab is visible again. If the tab is already hidden when the element becomes visible, the timer starts when the tab is shown.
- Once or repeated. By default each element is reported once, and the
observer is disconnected afterwards. With
once: false, the element is reported again after it has left the viewport (dropped belowthreshold) and then stayed visible forminDurationMsagain. Staying visible never reports twice. - The entry.
onImpressionreceives theIntersectionObserverEntrythat was current when the timer finished, so you can readintersectionRatio,boundingClientRectortarget, for example to include the element's id in an analytics event. - The latest callback is always used. Passing an inline function does not
reset the timer or re-observe. Changing
root,rootMargin,threshold,minDurationMs,onceorenableddoes, and starts a fresh dwell timer. With the defaultonce: true, an element that was already reported is not reported again when you toggleenabledor change an option. Attach the ref to a different element to track it again. - Pass a stable
root. To use a scroll container asroot, store it in state with a callback ref (ref={setRoot}), as the demos do, so that the hook re-observes when it mounts. Avoid readingref.currentduring render. - Disabling.
enabled: falsedisconnects the observer and clears the timer, so partial dwell time is thrown away. Use it to stop tracking content that was already handled, such as a message that is already read. - No re-renders. The hook keeps its state in the observer and a timer, not
in React state. Update your own state from
onImpressionif you need the UI to change. - Server rendering and unsupported browsers. Nothing runs on the server.
Where
IntersectionObserveris unavailable the hook does nothing and the callback is never called. - Cleanup. The observer, the timer and the visibility listener are removed on unmount, and the callback is never called after unmount.
- Testing. The dwell timer uses
setTimeoutandDate.now(), so Vitest or Jest fake timers control it. MockIntersectionObserverin a test environment such as jsdom, which does not provide it, and wrap timer advances inact. - Safe under React
StrictMode.
Example
// Report a view after the card was at least half visible for one second
const ref = useImpression<HTMLDivElement>(() => {
analytics.track("card_viewed", { id });
});
return <div ref={ref}>{children}</div>;
// Mark a message as read after 2 seconds with 80% of it on screen
const ref = useImpression<HTMLLIElement>(() => markAsRead(message.id), {
threshold: 0.8,
minDurationMs: 2000,
enabled: !message.read,
});
// Count every time an ad is seen again, inside a scrollable feed
const [feed, setFeed] = useState<HTMLDivElement | null>(null);
const ref = useImpression<HTMLDivElement>(
(entry) => trackAdView(adId, entry.intersectionRatio),
{ once: false, root: feed }
);
Hook source
View useImpression source
useImpression sourceimport { useEffect, useRef, useState } from "react";
import { useLatest } from "./use-latest";
/** Options for {@link useImpression}. */
export interface UseImpressionOptions {
/**
* How much of the element must be visible, from `0` to `1`, to count as
* seen. Values outside that range are clamped. Default is `0.5`.
*/
threshold?: number;
/**
* How long, in milliseconds, the element must stay at least `threshold`
* visible before the impression is reported. Leaving the viewport before
* then resets the timer. A value of `0` reports as soon as the element is
* visible. A negative or non-finite value falls back to the default.
* Default is `1000`.
*/
minDurationMs?: number;
/**
* Report a single impression for the element. When `false`, the element can
* be reported again each time it leaves the viewport and then stays visible
* for `minDurationMs` again. Default is `true`.
*/
once?: boolean;
/**
* The element used as the viewport for the check. Pass a scrollable
* container to track visibility inside it. Passing a new element
* re-observes. Default is the browser viewport (`null`).
*/
root?: Element | Document | null;
/**
* Grows or shrinks the root's box before computing visibility, using CSS
* margin syntax, for example `"-50px"` to ignore a fixed header. Default is
* `"0px"`.
*/
rootMargin?: string;
/**
* Set to `false` to stop observing and discard any running timer. Turning it
* back on starts a fresh dwell timer. Default is `true`.
*/
enabled?: boolean;
}
/** Default for {@link UseImpressionOptions.threshold}. */
const DEFAULT_THRESHOLD = 0.5;
/** Default for {@link UseImpressionOptions.minDurationMs}, in milliseconds. */
const DEFAULT_MIN_DURATION_MS = 1000;
/**
* Calls `onImpression` once an element has been at least `threshold` visible
* for at least `minDurationMs`, which is what analytics, "mark as read" and
* ad-view tracking usually mean by "seen".
*
* It differs from {@link useIntersectionObserver}, which reports visibility as
* state but has no notion of dwell time, and the hook itself never re-renders
* your component.
*
* - **Usage:** attach the returned `ref` to any element. It is a callback ref,
* so it also works when the element mounts later, is rendered conditionally,
* or is swapped for another one.
* - **Dwell time:** the timer starts when the element becomes visible enough
* and is reset if it drops below `threshold` before `minDurationMs` passes.
* - **Hidden tabs:** the timer is paused while the document is hidden, so time
* in a background tab does not count, and it resumes when the tab is visible
* again.
* - **Once or repeated:** by default one impression is reported per element.
* With `once: false`, the element is reported again after it leaves the
* viewport and stays visible for `minDurationMs` again.
* - **Stable:** the latest `onImpression` is always called, so passing an
* inline function never resets the timer or re-observes. Changing `root`,
* `rootMargin`, `threshold`, `minDurationMs`, `once` or `enabled` does.
* - **Pause:** `enabled: false` disconnects the observer and clears the timer.
* - **SSR-safe:** nothing runs on the server, and it does nothing where
* `IntersectionObserver` is unavailable.
* - **Cleanup:** the observer, the timer and the visibility listener are
* removed on unmount, when the element changes and when an option changes.
* The callback is never called after unmount.
*
* @typeParam T - The type of element being observed. Defaults to `HTMLElement`.
* @param onImpression - Called with the latest `IntersectionObserverEntry` when an impression is reported.
* @param options - Optional `threshold`, `minDurationMs`, `once`, `root`, `rootMargin` and `enabled` settings. See {@link UseImpressionOptions | UseImpressionOptions}.
* @returns A callback `ref` to attach to the element you want to track.
*
* @example
* ```tsx
* // Report a view after the card was at least half visible for one second
* const ref = useImpression<HTMLDivElement>(() => {
* analytics.track("card_viewed", { id });
* });
*
* return <div ref={ref}>{children}</div>;
* ```
*
* @example
* ```tsx
* // Mark a message as read after 2 seconds with 80% of it on screen
* const ref = useImpression<HTMLLIElement>(() => markAsRead(message.id), {
* threshold: 0.8,
* minDurationMs: 2000,
* enabled: !message.read,
* });
* ```
*
* @example
* ```tsx
* // Count every time an ad is seen again, inside a scrollable feed
* const ref = useImpression<HTMLDivElement>(
* (entry) => trackAdView(adId, entry.intersectionRatio),
* { once: false, root: feedRef.current }
* );
* ```
*
* For a live, editable example, see the [useImpression docs page](https://altalyst-solutions.github.io/hookify/hooks/use-impression).
*
* @see [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
* @see [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
*/
export const useImpression = <T extends Element = HTMLElement>(
onImpression: (entry: IntersectionObserverEntry) => void,
options?: UseImpressionOptions
): ((element: T | null) => void) => {
/** The threshold as passed, before it is validated. */
const rawThreshold = options?.threshold ?? DEFAULT_THRESHOLD;
/** The visibility ratio to reach, clamped to what `IntersectionObserver` accepts (`0` to `1`). */
const threshold = Number.isNaN(rawThreshold)
? DEFAULT_THRESHOLD
: Math.min(1, Math.max(0, rawThreshold));
/** The dwell time as passed, before it is validated. */
const rawDuration = options?.minDurationMs ?? DEFAULT_MIN_DURATION_MS;
/** The dwell time to wait, in milliseconds. Never negative or non-finite. */
const minDurationMs =
Number.isFinite(rawDuration) && rawDuration >= 0
? rawDuration
: DEFAULT_MIN_DURATION_MS;
/** Whether to report a single impression per element. */
const once = options?.once ?? true;
/** The viewport used for the check, `null` for the browser viewport. */
const root = options?.root ?? null;
/** The margin applied to the root's box, in CSS margin syntax. */
const rootMargin = options?.rootMargin ?? "0px";
/** Whether tracking is on. */
const enabled = options?.enabled ?? true;
/** Holds the latest `onImpression`, so changing it never re-observes. */
const onImpressionRef = useLatest(onImpression);
/** The element being tracked. Set by the returned callback ref. */
const [element, setElement] = useState<T | null>(null);
/**
* The element that already got its impression while `once` was on, so that
* toggling `enabled` or changing an option does not report it a second time.
*/
const reportedRef = useRef<T | null>(null);
useEffect(() => {
if (
!enabled ||
!element ||
(once && reportedRef.current === element) ||
typeof IntersectionObserver === "undefined"
) {
return;
}
/** The latest entry for the element, passed to `onImpression`. */
let latestEntry: IntersectionObserverEntry | undefined;
/** Whether the element is currently visible by at least `threshold`. */
let isVisibleEnough = false;
/** Whether the current visible stretch was already reported. */
let reported = false;
/** The running dwell timer, if any. */
let timer: ReturnType<typeof setTimeout> | undefined;
/** Dwell time still needed, in milliseconds. Shrinks while paused. */
let remainingMs = minDurationMs;
/** When the running timer started, in milliseconds since the epoch. */
let startedAt = 0;
/**
* Stops the running timer, if any, and subtracts the time it already ran
* from `remainingMs`, so a later `startTimer` continues where it left off.
*/
const stopTimer = () => {
if (timer === undefined) return;
clearTimeout(timer);
timer = undefined;
remainingMs = Math.max(0, remainingMs - (Date.now() - startedAt));
};
/**
* Starts the dwell timer for the time left in `remainingMs`. Does nothing
* if it is already running, the current visible stretch was reported, the
* element is not visible enough, or the document is hidden.
*/
const startTimer = () => {
if (
timer !== undefined ||
reported ||
!isVisibleEnough ||
document.visibilityState === "hidden"
) {
return;
}
startedAt = Date.now();
timer = setTimeout(report, remainingMs);
};
/**
* Runs when the dwell time has passed: marks the visible stretch as
* reported, stops observing when `once` is on, and calls `onImpression`
* with the latest entry.
*/
const report = () => {
timer = undefined;
reported = true;
if (once) {
reportedRef.current = element;
observer.disconnect();
document.removeEventListener("visibilitychange", handleVisibility);
}
if (latestEntry) onImpressionRef.current(latestEntry);
};
/** Pauses the timer when the document gets hidden and resumes it when shown. */
const handleVisibility = () => {
if (document.visibilityState === "hidden") stopTimer();
else startTimer();
};
/**
* Tracks whether the element is visible enough. The timer runs while it
* is, and dropping below `threshold` resets the dwell time.
*/
const observer = new IntersectionObserver(
(entries) => {
const entry = entries[entries.length - 1];
if (!entry) return;
latestEntry = entry;
isVisibleEnough =
entry.isIntersecting && entry.intersectionRatio >= threshold;
if (isVisibleEnough) {
startTimer();
} else {
// Leaving the viewport starts the next dwell from zero.
stopTimer();
remainingMs = minDurationMs;
reported = false;
}
},
{ root, rootMargin, threshold }
);
observer.observe(element);
document.addEventListener("visibilitychange", handleVisibility);
return () => {
observer.disconnect();
document.removeEventListener("visibilitychange", handleVisibility);
if (timer !== undefined) clearTimeout(timer);
};
}, [
element,
enabled,
minDurationMs,
once,
onImpressionRef,
root,
rootMargin,
threshold,
]);
return setElement;
};