react-fathomv0.3.0
On this page
  1. Installation
  2. Basic Setup
  3. How It Works
  4. Tracking Events
  5. Provider Props
  6. Next Steps

React Native

Full React Native support with offline event queuing

react-fathom provides full React Native support with a hidden WebView that loads Fathom's official tracking script, ensuring compatibility with Fathom Analytics.

React Native support uses a WebView-based approach. Events are queued until the WebView is ready, then sent automatically.

Installation

Install react-fathom and the required WebView dependency:

bash
npm install react-fathom react-native-webview

For iOS, install CocoaPods dependencies:

bash
cd ios && pod install

Basic Setup

tsx
import { NativeFathomProvider } from 'react-fathom/native'

function App() {
  return (
    <NativeFathomProvider
      siteId="YOUR_SITE_ID"
      debug={__DEV__}
      onReady={() => console.log('Fathom ready!')}
      onError={(err) => console.error('Fathom error:', err)}
    >
      <YourApp />
    </NativeFathomProvider>
  )
}

How It Works

The NativeFathomProvider:

  1. Renders a hidden WebView (0x0 pixels) that loads the Fathom script
  2. Queues all tracking calls until the WebView is ready
  3. Automatically flushes the queue when the script loads
  4. Provides the same useFathom hook API as web

Tracking Events

Use the same hooks as web:

tsx
import { useFathom } from 'react-fathom/native'

function PurchaseButton({ price }) {
  const { trackEvent, trackGoal } = useFathom()

  const handlePurchase = () => {
    trackEvent('purchase-tap', { _value: price })
    trackGoal('PURCHASE', price)
  }

  return (
    <TouchableOpacity onPress={handlePurchase}>
      <Text>Buy Now</Text>
    </TouchableOpacity>
  )
}

Provider Props

PropTypeDescription
siteIdstringYour Fathom site ID (required)
debugbooleanEnable debug logging
trackAppStatebooleanAuto-track app foreground/background
loadOptionsLoadOptionsOptions passed to fathom.load()
scriptDomainstringCustom domain (default: cdn.usefathom.com)
defaultPageviewOptionsPageViewOptionsDefault pageview options
defaultEventOptionsEventOptionsDefault event options
onReady() => voidCalled when Fathom script loads
onError(error: string) => voidCalled on script load error
clientRefMutableRefObjectRef for direct client access

Next Steps

  • Navigation Tracking — Track React Navigation screen changes
  • App State Tracking — Track foreground/background
  • Advanced Setup — Custom WebView configuration

Last updated: October 8, 2026

By

Commune Software