Litemetrics for React - Provider, hooks, and Next.js

React integration

@litemetrics/react wraps the browser tracker in a Provider and three hooks. It works in any React 17+ app, including Next.js (Pages Router and App Router), Vite, Remix, and React Native web.

Install

npm install @litemetrics/react

Wrap your app with the Provider

Mount the Provider once at the top of your tree. It boots the tracker and exposes it via context.

import { LitemetricsProvider } from '@litemetrics/react';

function App() {
  return (
    <LitemetricsProvider
      siteId="your-site-id"
      endpoint="https://your-server.com/api/collect"
    >
      <YourApp />
    </LitemetricsProvider>
  );
}

SPA route changes are auto-tracked. You do not need to call page() manually unless you want to (see usePageView below).

Hooks

useTrackEvent

Track named events with optional metadata:

import { useTrackEvent } from '@litemetrics/react';

function SignupButton() {
  const track = useTrackEvent();
  return (
    <button onClick={() => track('Signup', { plan: 'pro' })}>
      Sign Up
    </button>
  );
}

usePageView

Manually fire a pageview on mount. Useful inside virtualized routes, modals you treat as pages, or stepper screens.

import { usePageView } from '@litemetrics/react';

function CheckoutStep({ step }) {
  usePageView({ path: `/checkout/step-${step}` });
  return <div>...</div>;
}

useLitemetrics

Access the underlying tracker for advanced calls like identify(), page() with overrides, or reading the current visitor id.

import { useLitemetrics } from '@litemetrics/react';

function UserProfile({ user }) {
  const tracker = useLitemetrics();

  useEffect(() => {
    tracker.identify(user.id, { name: user.name, plan: user.plan });
  }, [user]);

  return <div>...</div>;
}

Next.js App Router

The Provider needs to run on the client, so wrap it in a 'use client' boundary, then mount it in your root layout.

// app/providers.tsx
'use client';
import { LitemetricsProvider } from '@litemetrics/react';

export function Providers({ children }) {
  return (
    <LitemetricsProvider
      siteId={process.env.NEXT_PUBLIC_LITEMETRICS_SITE_ID}
      endpoint={process.env.NEXT_PUBLIC_LITEMETRICS_ENDPOINT}
    >
      {children}
    </LitemetricsProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

App Router navigations fire history.pushState, which the tracker auto-detects. No router-specific glue is required.

Embedding the dashboard

For the white-label dashboard component, install @litemetrics/ui and pair it with your customers' siteId:

import {
  LitemetricsProvider,
  AnalyticsDashboard,
} from '@litemetrics/ui';

function CustomerAnalytics({ customerId }) {
  return (
    <LitemetricsProvider
      baseUrl="/api"
      siteId={customerId}
      secretKey={getSecretFor(customerId)}
    >
      <AnalyticsDashboard theme="midnight" />
    </LitemetricsProvider>
  );
}

See the embedded analytics use case for the multi-tenant pattern in detail, or jump straight to the Quickstart if you have not set up a server yet.