React

This page installs Grain Tag in a React app with the @grainql/tag package. Grain Tag needs no provider and no wrapper component. For Next.js, read Next.js.

Before you start

You need three things:

Your tenant alias. The dashboard at https://grainql.com/dashboard shows it. It is not the UUID.
A React app with a build tool that reads environment variables, for example Vite (VITE_GRAIN_TENANT_ID) or Create React App (REACT_APP_GRAIN_TENANT_ID).
A browser with developer tools, to make sure that events arrive.

For remote configuration, feature flags, and the hooks useConfig, useTrack, and GrainProvider, use Analytics Web instead of Grain Tag. Read React hooks.

1. Install the package

npm install @grainql/tag

The package ships TypeScript declarations.

2. Initialize Grain Tag

Call init one time, in a useEffect at the root of the app. The isInitialized guard keeps a second render from a second initialization. The cleanup calls destroy, so hot module replacement and tests start clean.

import { useEffect } from 'react';
import { init, destroy, isInitialized } from '@grainql/tag';

function App() {
  useEffect(() => {
    if (!isInitialized()) {
      init({ tenantId: import.meta.env.VITE_GRAIN_TENANT_ID });
    }

    return () => {
      destroy();
    };
  }, []);

  return <YourApp />;
}

After init, Grain Tag tracks page views, heatmap clicks, scroll depth, and DOM snapshots. React Router and every other router that uses the History API needs no page view code.

3. Make sure that events arrive

Open the app in a browser. In the developer console, run:

GrainTag.track('installation_test');

The dashboard shows the installation_test event within 30 seconds. Pass debug: true to init to see the batching and sending activity in the console. If the event does not appear, read Troubleshooting.

4. Track an event

Import track and call it in an event handler.

import { track } from '@grainql/tag';

function SignupButton() {
  const handleClick = () => {
    track('signup_clicked', { location: 'hero', button_text: 'Get Started' });
  };

  return <button onClick={handleClick}>Get Started</button>;
}

Grain Tag batches events and sends them in groups. A manual flush is not necessary. track and identify called before init are queued and replayed after initialization. Read Track an event.

5. Identify a user

After a login, pass the user ID to identify. Every later event holds this user ID.

import { identify } from '@grainql/tag';

function LoginForm() {
  const handleLogin = async (email: string, password: string) => {
    const user = await yourLoginFunction(email, password);
    identify(user.id);
  };

  return <form onSubmit={handleLogin}>...</form>;
}

Read Identify users. Grain Tag is cookieless by default and uses daily rotating IDs. When your app asks for consent, call the consent methods on the instance. getInstance returns null before init.

import { getInstance } from '@grainql/tag';

function ConsentBanner() {
  const handleAccept = () => {
    getInstance()?.consent.grant();
  };

  const handleDecline = () => {
    getInstance()?.consent.revoke();
  };

  return (
    <div>
      <p>We use analytics to improve this site.</p>
      <button onClick={handleAccept}>Accept analytics</button>
      <button onClick={handleDecline}>Decline</button>
    </div>
  );
}

grant enables persistent tracking. Read Privacy and consent.

Next steps

Core methods

Every method of both SDKs, with signatures.

Identify users

Anonymous IDs, daily rotating IDs, and identify.

Next.js

App Router, Pages Router, and server-side events.

React hooks

Analytics Web, the provider, and remote configuration in React.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

Advanced

React

Before you start

1. Install the package

2. Initialize Grain Tag

3. Make sure that events arrive

4. Track an event

5. Identify a user

Next steps

Core methods

Identify users

Next.js

React hooks

​Before you start

​1. Install the package

​2. Initialize Grain Tag

​3. Make sure that events arrive

​4. Track an event

​5. Identify a user

​6. Grant consent

​Next steps

Core methods

Identify users

Next.js

React hooks

Before you start

1. Install the package

2. Initialize Grain Tag

3. Make sure that events arrive

4. Track an event

5. Identify a user

6. Grant consent

Next steps