React hooks

The React hooks come from Analytics Web, under @grainql/analytics-web/react. Grain Tag has no hooks. A component reads a configuration value with useConfig and sends an event with useTrack, and the provider owns the client. When this page and the TypeScript types of @grainql/analytics-web disagree, the types win.

Install

npm install @grainql/analytics-web

React 16.8.0 or later is a peer dependency. The package does not bundle React.

The provider

Wrap the application in GrainProvider one time. Every component inside the provider can call the hooks. A hook called outside the provider throws an error.

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

function App() {
  return (
    <GrainProvider config={{ tenantId: 'your-tenant-id' }}>
      <HomePage />
    </GrainProvider>
  );
}

function HomePage() {
  const { value: heroText } = useConfig('hero_text');
  const track = useTrack();

  return (
    <div>
      <h1>{heroText ?? 'Welcome'}</h1>
      <button onClick={() => track('cta_clicked')}>Get started</button>
    </div>
  );
}

Read GrainProvider.

Exports

@grainql/analytics-web/react exports these values. The first six have a page each.

Export	Kind	What it does
`GrainProvider`	Component	Holds the client. Takes `config` or `client`. Read GrainProvider.
`useGrainAnalytics()`	Hook	Returns the `GrainAnalytics` client. Read useGrainAnalytics.
`useTrack()`	Hook	Returns a stable `track` function. Read useTrack.
`useConfig(key, options?)`	Hook	Returns one configuration value, cache first. Read useConfig.
`useAllConfigs(options?)`	Hook	Returns every configuration value, cache first. Read useAllConfigs.
`useConsent()`	Hook	Returns `consentState`, `grantConsent(categories?)`, `revokeConsent(categories?)`, `hasConsent(category?)`, `isGranted`, and `categories`.
`usePrivacyPreferences()`	Hook	Returns `preferences` (`necessary`, `analytics`, `functional`), `updatePreferences(partial)`, `acceptAll()`, and `rejectAll()`.
`useDataDeletion(options)`	Hook	Takes `{ apiUrl, tenantId, onSuccess?, onError? }`. Returns `requestDeletion(userId)`, `requestAnonymization(userId)`, `loading`, and `error`. The deletion runs on the server.
`ConsentBanner`	Component	A consent popup. Props: `position`, `theme`, `customText`, `onAccept`, `onDecline`, `showPreferences`, `privacyPolicyUrl`. All optional.
`PrivacyPreferenceCenter`	Component	A preference modal. Props: `isOpen`, `onClose`, and optional `onSave(categories)`.
`CookieNotice`	Component	A cookie notification bar. Props: `message`, `privacyPolicyUrl`, `onDismiss`, `position`. All optional.

The types GrainProviderProps, UseConfigOptions, UseConfigResult, UseAllConfigsOptions, UseAllConfigsResult, TrackFunction, ConsentBannerProps, PrivacyPreferenceCenterProps, CookieNoticeProps, PrivacyPreferences, and DataDeletionOptions are exported too. The consent hooks and components follow the consent mode of the client. Read Privacy and consent.

Grain Tag or Analytics Web in React

Both packages send custom events, page views, and heatmap clicks. Only Grain Tag takes DOM snapshots and runs dashboard trackers. Only Analytics Web reads remote configuration and has hooks.

You need	Install
DOM snapshots and dashboard trackers without code	Grain Tag. Read React.
Custom events only, with one `init()` call	Grain Tag.
Remote configuration, feature flags, or A/B tests in components	Analytics Web with the hooks on this page.
Both automatic tracking and remote configuration	Both packages. Grain Tag tracks, Analytics Web serves configuration.

Read Install Grain.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Install

The provider

Exports

Grain Tag or Analytics Web in React

​Install

​The provider

​Exports

​Grain Tag or Analytics Web in React

Install

The provider

Exports

Grain Tag or Analytics Web in React