Getting Started

Installation

#

Install react-fathom and its peer dependency fathom-client:

npm install react-fathom fathom-client

Peer Dependencies

#

Use Node.js 20 or newer. Install the peer dependencies for the integrations you use; React Native requires react-native-webview only when using the native entrypoint.

Basic Setup

#

1. Get Your Site ID

#

Your Fathom site ID is an 8-character alphanumeric string (e.g., ABCD1234). Find it in your Fathom dashboard under Settings → Site ID.

2. Add the Provider

#

Wrap your application with FathomProvider:

import { FathomProvider } from 'react-fathom'

function App() {
  return (
    <FathomProvider siteId="YOUR_SITE_ID">
      <YourApp />
    </FathomProvider>
  )
}

3. Track Events

#

Use the useFathom hook to track custom events:

import { useFathom } from 'react-fathom'

function SignUpButton() {
  const { trackEvent } = useFathom()

  return <button onClick={() => trackEvent('signup-click')}>Sign Up</button>
}

Pageviews are tracked automatically by default.

Next Steps

#

• React usage guide — Hooks and declarative components
• React Router integration — Automatic pageview tracking for React Router and Remix
• Gatsby integration — Automatic pageview tracking for Gatsby
• TanStack Router integration — Type-safe routing with automatic tracking
• Next.js integration — App Router and Pages Router
• React Native setup — Mobile apps with offline queuing
• API Reference — Full provider props and options

Environment Variables

#

For production apps, store your site ID in an environment variable:

<FathomProvider siteId={process.env.REACT_APP_FATHOM_SITE_ID}>

For Next.js, use the NEXT_PUBLIC_ prefix:

# .env.local
NEXT_PUBLIC_FATHOM_SITE_ID=YOUR_SITE_ID

<FathomProvider siteId={process.env.NEXT_PUBLIC_FATHOM_SITE_ID}>

Local Development

#

By default, Fathom only tracks events from configured domains. To track during local development:

<FathomProvider
  siteId="YOUR_SITE_ID"
  clientOptions={{
    includedDomains: ['localhost', 'yourdomain.com']
  }}
>