@fixture-inc/tracker-react

React hooks and provider for Fixture tracking.

Installation

pnpm add @fixture-inc/tracker-react

Usage

Provider Setup

Wrap your app with FixtureProvider:

import { FixtureProvider } from '@fixture-inc/tracker-react'

function App() {
  return (
    <FixtureProvider propertyId="your-property-id">
      <YourApp />
    </FixtureProvider>
  )
}

Page tracking happens automatically - no additional setup needed.

Track Events

Use the useFixture hook to track custom events:

import { useFixture } from '@fixture-inc/tracker-react'

function SignupButton() {
  const { trackEvent } = useFixture()

  return (
    <button onClick={() => trackEvent('signup_click', { plan: 'pro' })}>
      Sign Up
    </button>
  )
}

Convenience Hooks

import { useTrackEvent, useVisitorId } from '@fixture-inc/tracker-react'

function Component() {
  // Stable callback for tracking (good for event handlers)
  const trackClick = useTrackEvent('button_click', { location: 'header' })

  // Get current visitor ID
  const visitorId = useVisitorId()

  return <button onClick={trackClick}>Click ({visitorId})</button>
}

API

FixtureProvider

interface FixtureProviderProps {
  children: ReactNode
  propertyId: string
  apiUrl?: string              // Default: 'https://api.fixture.app'
  debug?: boolean
  cookieName?: string          // Default: 'fxid'
  cookieDays?: number          // Default: 365
  cookieDomain?: string        // For cross-subdomain tracking
  trackSpaNavigation?: boolean // Default: true
  trackDomEvents?: boolean     // Default: true
}

useFixture

const {
  trackEvent,    // (name: string, properties?: object) => void
  trackPageview, // () => void
  getVisitorId,  // () => string | null
  tracker,       // BrowserTracker | null (for advanced use)
} = useFixture()

useTrackEvent

// Returns a stable callback
const trackClick = useTrackEvent('event_name', { optional: 'properties' })

useVisitorId

const visitorId = useVisitorId() // string | null

SSR Safety

The provider handles SSR automatically:

• No window access during server render
• Tracker initializes on client mount only
• Hooks return no-op functions during SSR

Features

• Automatic page tracking - SPA navigation detected via history API
• SSR safe - Works with Next.js, Remix, etc.
• TypeScript - Full type definitions included
• Minimal - 2.2 KB, zero dependencies beyond tracker-browser