React Quick Start

Using Next.js? Check out the Next.js Quick Start for App Router and Pages Router examples.

Install the Package

npm

npm install @grainql/tag

yarn

yarn add @grainql/tag

pnpm

pnpm add @grainql/tag

Initialize Grain

Call init() once at your app’s entry point. No provider or wrapper component needed:

// src/main.tsx or src/index.tsx
import { init } from '@grainql/tag';

init({ tenantId: 'your-tenant-id' });

// ... rest of your app setup

Replace 'your-tenant-id' with the alias from your dashboard (not the UUID).

Pro tip: Store your tenant ID in an environment variable like VITE_GRAIN_TENANT_ID or REACT_APP_GRAIN_TENANT_ID.

Page views, heatmap clicks, scroll depth, and DOM snapshots are tracked automatically. No manual setup required.

Track Events

Import track directly from @grainql/tag and call it from any component:

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>;
}

Events are automatically batched and sent every few seconds. No manual flushing needed.

Identify Users

Associate events with a specific user after login:

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>;
}

Grain is cookieless by default with daily rotating IDs. When you need explicit consent handling:

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

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

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

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

Complete Example

Here’s a small app that puts it all together:

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { init } from '@grainql/tag';
import App from './App';

// Initialize Grain once at startup
init({ tenantId: 'your-tenant-id' });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

// src/App.tsx
import { track, identify, getInstance } from '@grainql/tag';

function App() {
  const handleSignup = (userId: string) => {
    identify(userId);
    track('signup_completed', { method: 'email' });
  };

  return (
    <div>
      <h1>Welcome!</h1>
      <button onClick={() => track('cta_clicked', { location: 'hero' })}>
        Get Started
      </button>
    </div>
  );
}

export default App;

Automatic page views: Grain Tag hooks into the History API to track navigation automatically. You do not need a PageViewTracker component or manual page_viewed calls — this works out of the box with React Router and other History API-based routers.

Cleanup on Unmount

If you need to tear down Grain (e.g., for testing or HMR), use destroy():

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

function App() {
  useEffect(() => {
    if (!isInitialized()) {
      init({ tenantId: 'your-tenant-id' });
    }

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

  return <YourApp />;
}

What’s Next?

Core API Reference

See all available methods and options

User Identification

Learn about tracking users across sessions

Next.js Integration

App Router and Pages Router setup

Event Best Practices

Learn what to track and how to structure events

TypeScript users: @grainql/tag ships with full TypeScript declarations. You’ll get autocomplete and type checking out of the box.

Need Remote Config or React Hooks?

If you need remote configuration, feature flags, or React hooks (useConfig, useTrack, GrainProvider), install @grainql/analytics-web instead. See the Analytics Web React SDK for details.

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Install the Package

Initialize Grain

Track Events

Identify Users

Complete Example

Cleanup on Unmount

What’s Next?

Core API Reference

User Identification

Next.js Integration

Event Best Practices

Need Remote Config or React Hooks?

​Install the Package

​Initialize Grain

​Track Events

​Identify Users

​Consent Management

​Complete Example

​Cleanup on Unmount

​What’s Next?

Core API Reference

User Identification

Next.js Integration

Event Best Practices

​Need Remote Config or React Hooks?

Install the Package

Initialize Grain

Track Events

Identify Users

Consent Management

Complete Example

Cleanup on Unmount

What’s Next?

Need Remote Config or React Hooks?