GrainProvider

GrainProvider puts one GrainAnalytics client into React context. Every hook under @grainql/analytics-web/react reads the client from this context. Mount the provider one time, above every component that calls a hook.

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

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

Props

Prop	Type	Rule
`config`	`GrainConfig`	The provider creates the client from it. Any option of Analytics Web is accepted. Read Configuration options.
`client`	`GrainAnalytics`	A client that you created. The provider uses it as is.
`children`	`React.ReactNode`	The component tree that calls the hooks.

Pass config or client, not both. The provider throws an error when it receives both props, and when it receives neither.

Provider-managed client

Pass config. The provider creates the client on its first render and calls destroy() on the client when the provider unmounts.

<GrainProvider
  config={{
    tenantId: 'your-tenant-id',
    authStrategy: 'JWT',
    authProvider: { getToken: () => getAccessToken() },
    defaultConfigurations: {
      hero_text: 'Welcome',
      feature_enabled: 'false',
    },
  }}
>
  <App />
</GrainProvider>

The provider reads config one time. A later change to the config prop does not reach the client. To change the user after login, call identify or login on the client. Read useGrainAnalytics.

External client

Create the client yourself and pass it as client. The provider does not destroy this client. You own its lifecycle.

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

export const grain = createGrainAnalytics({ tenantId: 'your-tenant-id' });

function App() {
  return (
    <GrainProvider client={grain}>
      <YourApp />
    </GrainProvider>
  );
}

Use this pattern when code outside React sends events with the same client, for example a router hook or an API layer.

Position in the tree

Place the provider above the router and above every component that calls a hook. A hook called in a component outside the provider throws an error with the text useGrainAnalytics must be used within a GrainProvider. Nested providers are allowed. A component reads the nearest provider above it.

Next.js

The provider uses React context, so it must be in a Client Component. In the App Router, put the provider in a file with the 'use client' directive and mount that file in the root layout.

// app/providers.tsx
'use client';

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

export function Providers({ children }: { children: React.ReactNode }) {
  return <GrainProvider config={{ tenantId: 'your-tenant-id' }}>{children}</GrainProvider>;
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

In the Pages Router, wrap the page component in pages/_app.tsx.

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { GrainProvider } from '@grainql/analytics-web/react';

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <GrainProvider config={{ tenantId: 'your-tenant-id' }}>
      <Component {...pageProps} />
    </GrainProvider>
  );
}

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Props

Provider-managed client

External client

Position in the tree

Next.js

​Props

​Provider-managed client

​External client

​Position in the tree

​Next.js

Props

Provider-managed client

External client

Position in the tree

Next.js