Easily compose Fathom Analytics into your React/Next.js apps with automatic pageview tracking and full TypeScript support.
- 🚀 Zero-config Fathom Analytics integration for React
- 📦 Tree-shakeable - Only bundle what you use
- 🔄 Automatic pageview tracking for Next.js (Pages Router & App Router)
- 💪 Full TypeScript support with type definitions
- 🎯 Flexible - Works with any React app or Next.js
- ⚡ Lightweight - Minimal bundle size impact
Via npm
npm install react-fathom fathom-clientVia Yarn
yarn add react-fathom fathom-clientreact>= 16.8react-dom>= 16.8fathom-client>= 3.0.0next>= 10.0.0 (only if using Next.js providers)
Wrap your app with FathomProvider:
import { FathomProvider } from 'react-fathom'
function App() {
return <FathomProvider siteId="YOUR_SITE_ID">{/* Your app */}</FathomProvider>
}Access Fathom methods via the useFathom hook:
import { useFathom } from 'react-fathom'
function MyComponent() {
const { trackPageview, trackEvent, trackGoal, load } = useFathom()
const handleClick = () => {
trackEvent?.('button-click', { id: 'signup-button' })
}
const handlePurchase = () => {
trackGoal?.('purchase', 2999) // $29.99 in cents
}
return (
<>
<button onClick={handleClick}>Sign Up</button>
<button onClick={handlePurchase}>Buy Now</button>
</>
)
}Track events and pageviews with convenience hooks:
import {
useTrackOnMount,
useTrackOnClick,
useTrackOnVisible,
} from 'react-fathom'
function MyComponent() {
// Track pageview on mount
useTrackOnMount({ url: '/custom-page' })
// Track event on click
const handleClick = useTrackOnClick({
eventName: 'button-click',
id: 'signup-button',
callback: (e) => {
console.log('Tracked click!', e)
},
})
// Track event when element becomes visible
const ref = useTrackOnVisible({
eventName: 'section-viewed',
section: 'hero',
callback: (entry) => {
console.log('Element is visible!', entry)
},
})
return (
<>
<button onClick={handleClick}>Sign Up</button>
<div ref={ref}>This will be tracked when visible</div>
</>
)
}Use declarative components for tracking:
import { TrackPageview, TrackClick, TrackVisible } from 'react-fathom'
function MyPage() {
return (
<>
{/* Track pageview on mount */}
<TrackPageview url="/custom-page">
<div>Page content</div>
</TrackPageview>
{/* Track click events */}
<TrackClick eventName="button-click" id="signup-button">
<button>Sign Up</button>
</TrackClick>
{/* Track when element becomes visible */}
<TrackVisible eventName="section-viewed" section="hero">
<div>Hero section</div>
</TrackVisible>
</>
)
}Use FathomProvider with NextFathomTrackViewApp for automatic route tracking:
// app/layout.tsx
import { FathomProvider } from 'react-fathom'
import { NextFathomTrackViewApp } from 'react-fathom/next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<FathomProvider siteId="YOUR_SITE_ID">
<NextFathomTrackViewApp />
{children}
</FathomProvider>
</body>
</html>
)
}Use FathomProvider with NextFathomTrackViewPages for automatic route tracking:
// pages/_app.tsx
import { FathomProvider } from 'react-fathom'
import { NextFathomTrackViewPages } from 'react-fathom/next'
function MyApp({ Component, pageProps }) {
return (
<FathomProvider siteId="YOUR_SITE_ID">
<NextFathomTrackViewPages />
<Component {...pageProps} />
</FathomProvider>
)
}
export default MyAppMain provider component for React apps. Supports composable nesting - nested providers can override client, defaultPageviewOptions, or defaultEventOptions.
Props:
siteId(string, optional): Your Fathom Analytics site IDclient(FathomClient, optional): Custom Fathom client instanceclientOptions(LoadOptions, optional): Options passed tofathom-clientdefaultPageviewOptions(PageViewOptions, optional): Default options merged into alltrackPageviewcallsdefaultEventOptions(EventOptions, optional): Default options merged into alltrackEventcalls
Example:
<FathomProvider
siteId="YOUR_SITE_ID"
defaultPageviewOptions={{ referrer: 'https://example.com' }}
defaultEventOptions={{ id: 'global-id' }}
>
{/* Your app */}
</FathomProvider>Component that tracks pageviews for Next.js App Router. Must be used within a FathomProvider.
Props:
disableAutoTrack(boolean, optional): Disable automatic pageview tracking on route changes (defaults to false)
Example:
<FathomProvider siteId="YOUR_SITE_ID">
<NextFathomTrackViewApp />
{/* Your app */}
</FathomProvider>Component that tracks pageviews for Next.js Pages Router. Must be used within a FathomProvider.
Props:
disableAutoTrack(boolean, optional): Disable automatic pageview tracking on route changes (defaults to false)
Example:
<FathomProvider siteId="YOUR_SITE_ID">
<NextFathomTrackViewPages />
{/* Your app */}
</FathomProvider>Hook to access Fathom methods and context.
Returns:
trackPageview(options?): Track a pageview (automatically mergesdefaultPageviewOptions)trackEvent(eventName, options?): Track a custom event (automatically mergesdefaultEventOptions)trackGoal(code, cents): Track a goal conversionload(siteId, options?): Load Fathom with a site IDsetSite(siteId): Change the site IDblockTrackingForMe(): Block tracking for current userenableTrackingForMe(): Enable tracking for current userisTrackingEnabled(): Check if tracking is enabledclient: The Fathom client instancedefaultPageviewOptions: Current default pageview optionsdefaultEventOptions: Current default event options
Hook to track a pageview when a component mounts.
Options:
url(string, optional): URL to trackreferrer(string, optional): Referrer URL- All other
PageViewOptionsfromfathom-client
Hook that returns a click handler function to track events.
Options:
eventName(string, required): Event name to trackpreventDefault(boolean, optional): Whether to prevent default behavior (defaults to false)callback((e?: MouseEvent) => void, optional): Callback function to run after tracking- All other
EventOptionsfromfathom-client
Hook that returns a ref to attach to an element. Tracks an event when the element becomes visible.
Options:
eventName(string, required): Event name to trackcallback((entry: IntersectionObserverEntry) => void, optional): Callback function to run after trackingthreshold(number, optional): IntersectionObserver threshold (defaults to 0.1)rootMargin(string, optional): IntersectionObserver rootMargin- All other
EventOptionsfromfathom-client
Component that tracks a pageview when it mounts.
Props:
url(string, optional): URL to trackreferrer(string, optional): Referrer URLchildren(ReactNode, optional): Child elements to render- All other
PageViewOptionsfromfathom-client
Component that tracks an event when clicked.
Props:
eventName(string, required): Event name to trackpreventDefault(boolean, optional): Whether to prevent default behavior (defaults to false)children(ReactNode, required): Child element(s) to render- All other
EventOptionsfromfathom-client
Component that tracks an event when it becomes visible.
Props:
eventName(string, required): Event name to trackthreshold(number, optional): IntersectionObserver threshold (defaults to 0.1)rootMargin(string, optional): IntersectionObserver rootMarginchildren(ReactNode, required): Child element(s) to renderas(string, optional): HTML element type to render (defaults to 'div')- All other
EventOptionsfromfathom-client
This library is optimized for tree-shaking. When you import only what you need:
import { useFathom } from 'react-fathom'Bundlers will automatically exclude unused code, keeping your bundle size minimal.
Full TypeScript support is included. Types are automatically generated and exported.
