useGrainAnalytics

useGrainAnalytics() returns the GrainAnalytics client that GrainProvider holds. Use it for every client method that has no hook of its own: identification, user properties, template events, flush, and configuration preload.

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

function UpgradeButton() {
  const grain = useGrainAnalytics();

  const handleUpgrade = async () => {
    await grain.setProperty({ plan: 'premium' });
  };

  return <button onClick={handleUpgrade}>Upgrade</button>;
}

Signature

function useGrainAnalytics(): GrainAnalytics;

The hook throws an error when no GrainProvider is above the component. Read GrainProvider. The returned reference is the client of the provider. It changes only when the provider receives a new client prop. It is safe in a dependency array.

Client methods for components

For events and configuration values, prefer the hooks. useTrack sends an event, useConfig and useAllConfigs read values and re-render on change. The client methods below have no hook.

Method	Use	Read
`identify(userId)`	Set the user after login.	Identify users
`login({ userId?, authToken?, authStrategy? })` and `logout()`	Set and clear the user and the auth token.	Identify users
`setUserId(userId \| null)`, `getUserId()`	Set or read the user ID without the login flow.	Identify users
`setProperty(properties, { userId? })`	Set user properties.	User properties
`trackLogin`, `trackSignup`, `trackCheckout`, `trackPurchase`, `trackSearch`, `trackAddToCart`, `trackRemoveFromCart`, `trackPageView`	Send a template event.	Template events
`flush()`	Send the event queue now, for example before navigation.	Track an event
`preloadConfig(immediateKeys?, properties?)`	Fill the cache before the first render of a child.	Configuration methods
`fetchConfig(options?)`	Fetch configuration values and read `snapshotId` from the response.	Configuration methods
`grantConsent`, `revokeConsent`, `getConsentState`, `hasConsent`	Consent without the `useConsent` hook.	Privacy and consent

The full method list is in Core methods.

function AuthSync() {
  const grain = useGrainAnalytics();
  const { user } = useAuth();

  useEffect(() => {
    if (user) {
      grain.identify(user.id);
      grain.setProperty({ plan: user.plan });
    } else {
      grain.logout();
    }
  }, [user, grain]);

  return null;
}

Read Authentication flow.

Preload configuration values

preloadConfig fills the cache. After it resolves, useConfig in a child shows the fetched value on its first render.

function App() {
  const grain = useGrainAnalytics();
  const [ready, setReady] = useState(false);

  useEffect(() => {
    grain.preloadConfig(['hero_text', 'feature_enabled']).then(() => setReady(true));
  }, [grain]);

  if (!ready) return null;

  return <HomePage />;
}

Do not destroy the client

A provider-managed client is destroyed when the provider unmounts. Do not call destroy() from a component. After destroy(), every hook under the same provider calls a dead client.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Signature

Client methods for components

Preload configuration values

Do not destroy the client

​Signature

​Client methods for components

​Identify after login

​Preload configuration values

​Do not destroy the client

Signature

Client methods for components

Identify after login

Preload configuration values

Do not destroy the client