react-global-tracking

Global user interaction tracking for React apps (16–19). Captures clicks, form events, and ambient events via DOM event delegation with automatic React fiber introspection.

Features

• Zero-config — works with any React 16–19 app, no provider or HOC needed
• Fiber introspection — automatically resolves the nearest React component name and props
• Smart filtering — only tracks interactive elements (buttons, links, ARIA roles, elements with React handlers)
• Three event categories — Pointer (click), Form (input/change/focus/blur), Ambient (scroll/keydown/keyup)
• Listener options — debounce, throttle, idle (requestIdleCallback), once, CSS selector filtering
• Global scheduling — set default debounce, throttle, or idle at tracker level; per-listener overrides
• Tree-shakeable — ESM + CJS, zero runtime dependencies

Install

npm install react-global-tracking

Quick Start

import { init } from 'react-global-tracking'

const tracker = init()

// Track all clicks on interactive elements
const unsubscribe = tracker.on('click', (event) => {
  console.log(event.targetElement.tagName)   // 'BUTTON'
  console.log(event.fiber?.componentName)    // 'SubmitButton'
  console.log(event.fiber?.props)            // { variant: 'primary', onClick: [Function] }
})

// Clean up
unsubscribe()     // remove this listener
tracker.destroy() // remove all listeners and DOM bindings

API

init(config?): Tracker

Creates a tracker instance.

const tracker = init({
  enabled: true,
  ignoreSelectors: ['.no-track', '[data-private]'],
  debug: false,
  debounce: 300,               // global default: debounce all callbacks by 300ms
  // throttle: 200,            // or throttle (mutually exclusive with debounce/idle)
  // idle: 2000,               // or idle via requestIdleCallback (mutually exclusive)
})

Option	Type	Description
enabled	boolean	Toggle tracking on/off (default: true)
ignoreSelectors	string[]	CSS selectors to exclude from tracking
debug	boolean	Log events to console.debug (default: false)
debounce	number	Global default: debounce all callbacks (ms)
throttle	number	Global default: throttle all callbacks (ms)
idle	number	Global default: defer all callbacks via requestIdleCallback with timeout (ms)

debounce, throttle, and idle are mutually exclusive — priority: debounce > throttle > idle.

tracker.on(eventType, callback, options?): unsubscribe

Register a listener for a DOM event type. Returns an unsubscribe function.

// Basic
tracker.on('click', (event) => { ... })

// With options
tracker.on('scroll', handler, { throttle: 200 })
tracker.on('input', handler, { debounce: 300 })
tracker.on('click', handler, { once: true })
tracker.on('click', handler, { selector: 'nav a' })

Options:

Option	Type	Description
debounce	number	Debounce the callback by the given milliseconds
throttle	number	Throttle the callback by the given milliseconds
idle	number	Defer callback via requestIdleCallback with the given timeout in milliseconds. Falls back to setTimeout in unsupported environments
once	boolean	Automatically unsubscribe after the first invocation
selector	string	Only fire the callback when the target matches the CSS selector (global ignoreSelectors is still applied first)

debounce, throttle, and idle are mutually exclusive (priority: debounce > throttle > idle). When a listener sets any of these, it overrides the global scheduling config entirely. Use { debounce: 0 }, { throttle: 0 }, or { idle: 0 } to explicitly opt out of a global default.

Multiple listeners can be registered for the same event type — each fires independently, similar to addEventListener.

Global Scheduling

Set a default scheduling strategy at the tracker level. Per-listener options override the global config as a group — setting any scheduling option on a listener ignores all global scheduling.

const tracker = init({ idle: 2000 })

// All listeners inherit idle: 2000
tracker.on('click', cb)                          // idle 2000ms
tracker.on('scroll', cb)                         // idle 2000ms

// Per-listener override (group override — global idle ignored)
tracker.on('input', cb, { debounce: 300 })       // debounce 300ms

// Explicit opt-out
tracker.on('click', importantCb, { idle: 0 })    // sync execution

tracker.getLastEvent(): TrackEvent | null

Returns the most recent tracked event, or null if none. Useful with visibilitychange or beforeunload to capture the last interaction before the user leaves:

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    const last = tracker.getLastEvent()
    if (last) {
      navigator.sendBeacon('/analytics', JSON.stringify({
        component: last.fiber?.componentName,
        element: last.targetElement.tagName,
      }))
    }
  }
})

tracker.destroy()

Removes all listeners and DOM event bindings. The tracker instance is inert after this call.

TrackEvent

Each callback receives a TrackEvent:

interface TrackEvent {
  nativeEvent: Event     // original DOM event
  targetElement: Element // resolved trackable element (may differ from nativeEvent.target)
  fiber: FiberInfo | null
}

interface FiberInfo {
  componentName: string | null              // nearest React component
  props: Readonly<Record<string, unknown>>  // component props (original types, not stringified)
}

The library intentionally keeps TrackEvent minimal — use nativeEvent and targetElement to extract any DOM information you need, and fiber.props to access rich, typed data from React components (avoiding the [object Object] problem of HTML data-* attributes).

Development

pnpm install
pnpm test            # run tests
pnpm test:watch      # watch mode
pnpm test:coverage   # coverage report (80% threshold)
pnpm lint            # oxlint
pnpm format          # oxfmt (write)
pnpm format:check    # oxfmt (check only)
pnpm typecheck       # tsc --noEmit
pnpm build           # ESM + CJS + .d.ts via tsdown

License

MIT