This library is a JavaScript client for Fathom Analytics.
- Asynchronous script loading. We provide a
loadfunction that will asynchronously inject the Fathom<script>tag (great for single-page app environments). import-able tracking functions. We provide tracking functions (trackPageviewandtrackEvent) that you can import and safely call anywhere (even if the Fathom script has not yet finished loading).
Maintained with
Run the following to install in your project:
npm install fathom-client
The standard installation flow for Fathom is to drop their snippet on your page, which will automatically load the library and track a pageview. This approach works great for server-rendered sites with full page refreshes, but gets tricky when:
- Routing happens on the client-side (e.g. an SPA)
- The DOM is abstracted away (e.g. Next.js)
This library provides an interface you can use to orchestrate Fathom calls at various points in your page lifecycle:
import * as Fathom from 'fathom-client';
// Upon initial page load...
Fathom.load('MY_FATHOM_ID');
// In the route changed event handler...
const onRouteChangeComplete = () => {
Fathom.trackPageview();
};
// In an event handler where a goal is achieved...
const onSignUp = () => {
Fathom.trackEvent('Sign Up');
};Injects the Fathom script into the DOM and loads the script asynchronously.
siteId- The site ID provided in the Fathom UI.opts- An Object of options:auto- Whenfalse, skips automatically tracking page views on script load (defaults totrue).honorDNT- Whentrue, honors the DNT header in the visitor's browsercanonical- Whenfalse, ignores the canonical tag if present (defaults totrue).spa- Accepts one of the following values:auto,history, orhash(see advanced docs).
import { load } from 'fathom-client';
load('MY_FATHOM_ID', {
// Add options here
});Tracks a pageview.
opts- An Object of options:url- When set, overrideswindow.location.referrer- When set, overridesdocument.referrer.
import { trackPageview } from 'fathom-client';
trackPageview();Tracks an event.
See Creating and using events.
eventName- This can be nearly anything you want. Avoid special chars and emojis.opts- An Object of options:_site_id- The Fathom site ID._value- The value of the event (in cents).
import { trackEvent } from 'fathom-client';
trackEvent('checkout completed', { _value: 100 });Tracks a goal. This is now deprecated, see trackEvent instead.
code- the code provided in the Fathom UI.cents- the value of the goal conversion.
import { trackGoal } from 'fathom-client';
trackGoal('MY_GOAL_CODE', 100);Enables tracking for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
import { enableTrackingForMe } from 'fathom-client';
enableTrackingForMe();Blocks tracking for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
import { blockTrackingForMe } from 'fathom-client';
blockTrackingForMe();Checks if tracking is enabled for the current visitor.
See https://usefathom.com/docs/features/exclude.
None.
Boolean.
import { isTrackingEnabled } from 'fathom-client';
const check = isTrackingEnabled(); // `true` by defaultSets the site ID for tracking (overrides the ID used when loading Fathom).
id- The site ID provided in the Fathom UI.
import { load, setSite } from 'fathom-client';
load('MY_FATHOM_ID');
setSite('A_DIFFERENT_FATHOM_ID');Manage your allowed domains within your Fathom site's Firewall settings. Doing so enables the usage of wildcards (e.g., *.example.com). See https://usefathom.com/docs/script/firewall#allowed
The includedDomains and excludedDomains options, while deprecated, are still supported to ensure backward compatibility.
This library is JavaScript framework-agnostic. Below are some usage examples with popular frameworks.
If you are using the latest Next.js beta with the
appdirectory, see the modified instructions below.
Create an _app.js file in your pages directory, like this:
import React, { useEffect } from 'react';
import Router from 'next/router';
import * as Fathom from 'fathom-client';
// Record a pageview when route changes
Router.events.on('routeChangeComplete', (as, routeProps) => {
if (!routeProps.shallow) {
Fathom.trackPageview();
}
});
function App({ Component, pageProps }) {
// Initialize Fathom when the app loads
useEffect(() => {
Fathom.load('MY_FATHOM_ID', {
// Add options here
});
}, []);
return <Component {...pageProps} />;
}
export default App;Create a Fathom client component:
// Fathom.tsx
'use client';
import { load, trackPageview } from 'fathom-client';
import { useEffect, Suspense } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';
function TrackPageView() {
const pathname = usePathname();
const searchParams = useSearchParams();
// Load the Fathom script on mount
useEffect(() => {
load('MY_FATHOM_ID', {
auto: false
});
}, []);
// Record a pageview when route changes
useEffect(() => {
if (!pathname) return;
trackPageview({
url: pathname + searchParams?.toString(),
referrer: document.referrer
});
}, [pathname, searchParams]);
return null;
}
export default function Fathom() {
return (
<Suspense fallback={null}>
<TrackPageView />
</Suspense>
);
}Note that we explicitly pass the url to trackPageview to avoid race conditions that occur when we allow the Fathom script to infer the URL from the browser.
Then, add the client component to your root layout.tsx file:
// layout.tsx
import Fathom from './Fathom';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<head></head>
<body>
<Fathom />
{children}
</body>
</html>
);
}The 3.0 release comes with a new way to load Fathom:
- Fathom.load();
- Fathom.setSiteId('MY_FATHOM_ID');
+ Fathom.load('MY_FATHOM_ID');The load function also accepts an object of options:
Fathom.load('MY_FATHOM_ID', {
// Add options here
});See advanced options for tracking.
Run the following to publish a new version:
npm run release