feat: add a component to capture when wrapped components are in view in the browser

Author: pauldambra

packages/react/src/components/PostHogCaptureOnViewed.tsx

@@ -0,0 +1,126 @@
+import React, { Children, useCallback, useRef } from 'react'
+import { usePostHog } from '../hooks'
+import { VisibilityAndClickTracker } from './internal/VisibilityAndClickTracker'
+
+export type PostHogCaptureOnViewedProps = React.HTMLProps<HTMLDivElement> & {
+    name?: string
+    properties?: Record<string, any>
+    observerOptions?: IntersectionObserverInit
+    trackAllChildren?: boolean
+}
+
+function TrackedChild({
+    child,
+    index,
+    name,
+    properties,
+    observerOptions,
+}: {
+    child: React.ReactNode
+    index: number
+    name?: string
+    properties?: Record<string, any>
+    observerOptions?: IntersectionObserverInit
+}): JSX.Element {
+    const trackedRef = useRef(false)
+    const posthog = usePostHog()
+
+    const onIntersect = useCallback(
+        (entry: IntersectionObserverEntry) => {
+            if (entry.isIntersecting && !trackedRef.current) {
+                posthog.capture('$element_viewed', {
+                    element_name: name,
+                    child_index: index,
+                    ...properties,
+                })
+                trackedRef.current = true
+            }
+        },
+        [posthog, name, index, properties]
+    )
+
+    return (
+        <VisibilityAndClickTracker onIntersect={onIntersect} trackView={true} options={observerOptions}>
+            {child}
+        </VisibilityAndClickTracker>
+    )
+}
+
+/**
+ * PostHogCaptureOnViewed - Track when elements are scrolled into view
+ *
+ * Wraps any children and automatically sends a `$element_viewed` event to PostHog
+ * when the element comes into the viewport. Only fires once per component instance.
+ *
+ * @example
+ * ```tsx
+ * <PostHogCaptureOnViewed name="hero-banner">
+ *   <div>Important content here</div>
+ * </PostHogCaptureOnViewed>
+ *
+ * // With custom properties
+ * <PostHogCaptureOnViewed
+ *   name="product-card"
+ *   properties={{ product_id: '123', category: 'electronics' }}
+ * >
+ *   <ProductCard />
+ * </PostHogCaptureOnViewed>
+ *
+ * // With custom intersection observer options
+ * <PostHogCaptureOnViewed
+ *   name="footer"
+ *   observerOptions={{ threshold: 0.5 }}
+ * >
+ *   <Footer />
+ * </PostHogCaptureOnViewed>
+ * ```
+ */
+export function PostHogCaptureOnViewed({
+    name,
+    properties,
+    observerOptions,
+    trackAllChildren,
+    children,
+    ...props
+}: PostHogCaptureOnViewedProps): JSX.Element {
+    const trackedRef = useRef(false)
+    const posthog = usePostHog()
+
+    const onIntersect = useCallback(
+        (entry: IntersectionObserverEntry) => {
+            if (entry.isIntersecting && !trackedRef.current) {
+                posthog.capture('$element_viewed', {
+                    element_name: name,
+                    ...properties,
+                })
+                trackedRef.current = true
+            }
+        },
+        [posthog, name, properties]
+    )
+
+    // If trackAllChildren is enabled, wrap each child individually
+    if (trackAllChildren) {
+        const trackedChildren = Children.map(children, (child, index) => {
+            return (
+                <TrackedChild
+                    key={index}
+                    child={child}
+                    index={index}
+                    name={name}
+                    properties={properties}
+                    observerOptions={observerOptions}
+                />
+            )
+        })
+
+        return <div {...props}>{trackedChildren}</div>
+    }
+
+    // Default behavior: track the container as a single element
+    return (
+        <VisibilityAndClickTracker onIntersect={onIntersect} trackView={true} options={observerOptions} {...props}>
+            {children}
+        </VisibilityAndClickTracker>
+    )
+}

packages/react/src/components/__tests__/PostHogCaptureOnViewed.test.tsx

@@ -0,0 +1,110 @@
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { PostHog, PostHogProvider } from '../../context'
+import { PostHogCaptureOnViewed } from '../'
+import '@testing-library/jest-dom'
+
+describe('PostHogCaptureOnViewed component', () => {
+    let mockObserverCallback: any = null
+
+    let fakePosthog: PostHog
+
+    beforeEach(() => {
+        fakePosthog = {
+            capture: jest.fn(),
+        } as unknown as PostHog
+
+        const mockIntersectionObserver = jest.fn((callback) => {
+            mockObserverCallback = callback
+            return {
+                observe: jest.fn(),
+                unobserve: jest.fn(),
+                disconnect: jest.fn(),
+            }
+        })
+
+        mockIntersectionObserver.prototype = {}
+        // eslint-disable-next-line compat/compat
+        window.IntersectionObserver = mockIntersectionObserver as unknown as typeof IntersectionObserver
+    })
+
+    it('should render children', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+
+    it('should track when element comes into view', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        expect(fakePosthog.capture).not.toHaveBeenCalled()
+
+        mockObserverCallback([{ isIntersecting: true }])
+
+        expect(fakePosthog.capture).toHaveBeenCalledWith('$element_viewed', {
+            element_name: 'test-element',
+        })
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should only track visibility once', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: true }])
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+
+        mockObserverCallback([{ isIntersecting: true }])
+        mockObserverCallback([{ isIntersecting: true }])
+        expect(fakePosthog.capture).toHaveBeenCalledTimes(1)
+    })
+
+    it('should include custom properties', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element" properties={{ category: 'hero', priority: 'high' }}>
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: true }])
+
+        expect(fakePosthog.capture).toHaveBeenCalledWith('$element_viewed', {
+            element_name: 'test-element',
+            category: 'hero',
+            priority: 'high',
+        })
+    })
+
+    it('should not track when element is not intersecting', () => {
+        render(
+            <PostHogProvider client={fakePosthog}>
+                <PostHogCaptureOnViewed name="test-element">
+                    <div data-testid="child">Hello</div>
+                </PostHogCaptureOnViewed>
+            </PostHogProvider>
+        )
+
+        mockObserverCallback([{ isIntersecting: false }])
+
+        expect(fakePosthog.capture).not.toHaveBeenCalled()
+    })
+})

packages/react/src/components/index.ts

@@ -1,4 +1,5 @@
 export * from './PostHogFeature'
+export * from './PostHogCaptureOnViewed'
 export {
     PostHogErrorBoundary,
     PostHogErrorBoundaryProps,