---
title: "@playstack/analytics-react"
description: "React analytics context, consent controls, and router-neutral route tracking."
tags: ["package","operations","analytics","react","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/analytics-react` supplies an existing analytics instance through React context, makes consent reactive, and offers explicit Pages and App Router navigation adapters.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/analytics-react@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

## Compose the provider

```tsx
import { PlaystackAnalyticsProvider, useAnalytics, useAnalyticsConsent } from '@playstack/analytics-react'

function ApplicationProviders({ children }) {
  return (
    <PlaystackAnalyticsProvider analytics={analytics}>
      {children}
    </PlaystackAnalyticsProvider>
  )
}

function UpgradeButton() {
  const analytics = useAnalytics()
  return <button onClick={() => analytics.track('upgrade_selected')}>Upgrade</button>
}
```

The provider accepts only `analytics` and children. `useAnalytics()` returns that exact core instance, including native clients. `useAnalyticsConsent()` returns reactive `{ state, setConsent }` controls.

## Consent ownership

Restore durable consent on the core instance before rendering, then persist changes made through the hook in application settings or compliance storage. This package owns only React reactivity; it does not store evidence.

## Next.js Pages Router bridge

```tsx
import { usePagesRouterAnalytics } from '@playstack/analytics-react/next-pages'

usePagesRouterAnalytics(useRouter(), {
  enabled: true,
  trackShallow: false,
  shouldTrack: ({ url }) => !url.startsWith('/account/private'),
  resolvePage: ({ url }) => ({
    title: document.title,
    properties: { section: url.split('/')[1] || 'home' },
  }),
  onError: (error) => errors.captureError(error),
})
```

| Option         | Purpose                                              |
| -------------- | ---------------------------------------------------- |
| `enabled`      | Disables initial and subsequent tracking when false. |
| `trackShallow` | Treats query-only navigation as a distinct page.     |
| `shouldTrack`  | Product-specific route exclusion policy.             |
| `resolvePage`  | Supplies title and properties for the resolved URL.  |
| `onError`      | Isolated policy/metadata error observer.             |

The structural router bridge records the initial ready URL and completed navigation only, skips duplicate URLs, and has no `next` dependency.

## Next.js App Router bridge

```tsx
'use client'

import { Suspense } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

import { useAppRouterAnalytics } from '@playstack/analytics-react/next-app'

function AnalyticsRoutes() {
  useAppRouterAnalytics(usePathname(), useSearchParams(), {
    shouldTrack: ({ pathname }) => !pathname.startsWith('/account/private'),
  })
  return null
}

export function AnalyticsNavigation() {
  return (
    <Suspense fallback={null}>
      <AnalyticsRoutes />
    </Suspense>
  )
}
```

The App Router effect observes committed pathname and query values, records the first available URL, and skips duplicates. The application owns the Suspense boundary required by `useSearchParams()` in statically rendered routes.

## Boundary

The package does not initialize SDKs, persist consent, emit domain events, publish artifacts, or impose a router. Those choices remain application inputs.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/analytics-react@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/analytics-react` | `./dist/index.d.ts` |
| `@playstack/analytics-react/errors` | `./dist/errors.d.ts` |
| `@playstack/analytics-react/next-pages` | `./dist/next-pages.d.ts` |
| `@playstack/analytics-react/next-app` | `./dist/next-app.d.ts` |
| `@playstack/analytics-react/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

| Peer | Compatible range | When needed |
| --- | --- | --- |
| `@playstack/analytics` | `0.1.0-beta.1` | Required by the package. |
| `@playstack/core` | `0.1.0-beta.1` | Required by the package. |
| `react` | `^18.2.0 \|\| ^19.0.0` | Required by the package. |

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}