How to add analytics to a React app

A client-rendered React app has one HTML document: index.html at the project root in Vite, or public/index.html in a Create React App project. That's the shell every route renders into, so it's the right place for the tag. Putting it in a useEffect would re-add it on remounts and is harder to keep to exactly one copy.

Using Next.js or React Router's framework mode (formerly Remix)? Use the Next.js guide or the Remix guide instead — those render the <head> from a root component.

How to install VisitTrack on React

1. 1

   Step 1: Copy your site id

   Add your site in VisitTrack and copy the snippet from the install step (also in Settings → General). Replace SITE_ID below with your id.

2. 2

   Step 2: Paste the tag into index.html

   Add it inside <head>. defer keeps it from blocking the first render; the script runs after the HTML is parsed and before DOMContentLoaded.

   index.htmlCopy

   <!doctype html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>My app</title>
       <script defer data-site="SITE_ID" src="https://visitrack.app/tracker.js"></script>
     </head>
     <body>
       <div id="root"></div>
       <script type="module" src="/src/main.tsx"></script>
     </body>
   </html>

3. 3

   Step 3: Optional: a different site id per environment

   Localhost is already ignored. To keep staging out of your numbers, the simplest option is Settings → General → Allowed hostnames: once you save your production hosts, hits from any other hostname are dropped. If you'd rather give staging its own VisitTrack site, Vite replaces %VITE_*% placeholders in index.html at build time — set VITE_VISITRACK_SITE_ID for every build, because an unset variable is left in the HTML as literal text.

   index.html (Vite env placeholder)Copy

   <script defer data-site="%VITE_VISITRACK_SITE_ID%" src="https://visitrack.app/tracker.js"></script>

4. 4

   Step 4: Build, deploy and browse

   Run your production build, deploy it, and click through a few routes on the live URL.

How to check VisitTrack is working on React

1. Open the deployed app and navigate between two routes with your in-app links (no full reload).
2. The live view in your VisitTrack dashboard shows you within a few seconds; the Pages tab lists both routes.
3. DevTools → Network: each route change sends a POST to visitrack.app/api/collect.
4. Nothing arriving? Add data-debug to the tag and read the [visitrack] lines in the console.

Does VisitTrack track React page navigation?

React Router's BrowserRouter and data routers (createBrowserRouter) change the URL with history.pushState. The tracker wraps pushState and replaceState and listens for popstate, so <Link>, useNavigate() and the back button all produce pageviews. Pageviews are keyed on location.pathname: query-string-only changes (filters, ?page=2) aren't counted again.

HashRouter keeps the route after # (/#/settings), and the pathname never changes — so only the first load is recorded. If you need per-route numbers, switch to BrowserRouter (your host must serve index.html for unknown paths) or send a custom event per screen.

How to track custom events and goals in React

Call window.visitrack(name, props) right after the thing actually happened — after your API answers ok, not on click. Props are optional: up to 10 keys, lowercase a-z0-9_-, values up to 255 characters.

For simple clicks, data-vt-goal="pricing_cta" on any element records an event with no handler. data-vt-scroll="pricing_viewed" fires once when that element is at least half visible.

// global.d.ts
declare global {
  interface Window {
    visitrack?: ((name: string, props?: Record<string, unknown>) => void) & {
      identify?: (userId: string, traits?: Record<string, unknown>) => void;
      visitorId?: () => string;
    };
  }
}
export {};

// src/hooks/useTrack.ts
export function track(name: string, props?: Record<string, unknown>) {
  window.visitrack?.(name, props);
}

// in a component
<button onClick={async () => {
  const ok = await saveProject();
  if (ok) track("project_created", { template: "blank" });
}}>Create project</button>

After login, call window.visitrack?.identify?.(user.id, { plan: user.plan }) to tie the visitor to your user id; they then appear in People. See People & identify.

Script options you might need on React

All optional — add them to the same tag. Full reference: script configuration.

React troubleshooting

Not on React? See all 29 integration guides.