useTrack - Grain Analytics

useTrack() returns the track method of the client as a function with a stable reference. Use it in event handlers and effects.

import { useTrack } from '@grainql/analytics-web/react';

function SignupButton() {
  const track = useTrack();

  return (
    <button onClick={() => track('signup_clicked', { location: 'header' })}>
      Sign up
    </button>
  );
}

Signature

function useTrack(): TrackFunction;

type TrackFunction = (
  eventName: string,
  properties?: Record<string, unknown>,
  options?: SendEventOptions
) => Promise<void>;

interface SendEventOptions {
  flush?: boolean;
}

Parameter	Type	Rule
`eventName`	`string`	The event name. Read Name events.
`properties`	`Record<string, unknown>`	Optional. Properties of the event.
`options.flush`	`boolean`	Optional. When `true`, the client sends the queue at once and the promise resolves after the send.

The function calls client.track(eventName, properties, options). Read Track an event.

Stable reference

The hook wraps track in useCallback with the client as its only dependency. The reference changes only when the provider gives a new client. Because of this:

Pass track to child components without a wrapper. A memoized child does not re-render because of it.
List track in the dependency array of an effect. The effect runs one time on mount.
Do not call track in the render body. Each render sends one more event. Call it in a handler or an effect.

The client batches events. If the page unloads before the next flush, the queue is lost. Pass { flush: true } and wait for the promise before you navigate.

function CheckoutButton() {
  const track = useTrack();
  const router = useRouter();

  const handleComplete = async () => {
    await track('checkout_completed', { order_id: 'order_123' }, { flush: true });
    router.push('/success');
  };

  return <button onClick={handleComplete}>Complete</button>;
}

Send on mount

function Dashboard() {
  const track = useTrack();

  useEffect(() => {
    track('dashboard_viewed');
  }, [track]);

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

Template events

useTrack sends custom events only. For trackLogin, trackPurchase, and the other template methods, read the client with useGrainAnalytics. Read Template events and useGrainAnalytics.