# React SDK

@cohorly/react provides React bindings for Cohorly. <CohorlyProvider> initializes the @cohorly/web client on mount, and useCohorly() gives any descendant access to it.

## Install

```bash
pnpm add @cohorly/react
# or: npm install @cohorly/react
```

Requires React 18+ (peer dependency).

## Wrap your app

`<CohorlyProvider>` is a client component. Its props are the same options
as `@cohorly/web`'s `init()`: `apiHost`, `token`, `trackPageviews`,
`flushIntervalMs`, `batchSize`, `superProperties`, `debug`, and the
error-tracking options (`captureExceptions`, `release`, ...). Place it near
the root of the tree that needs tracking.

```tsx
import { CohorlyProvider, useCohorly } from "@cohorly/react";

function App() {
  return (
    <CohorlyProvider token="YOUR_PROJECT_TOKEN" trackPageviews>
      <Dashboard />
    </CohorlyProvider>
  );
}
```

## useCohorly()

`useCohorly()` returns the same client shape as the `@cohorly/web`
singleton: `track`, `identify`, `reset`, `register`, `unregister`,
`people.*`, `flush`, `getDistinctId`, `isAnonymous`, `captureException`
and `addBreadcrumb`. It throws if
called outside a provider.

```tsx
function Dashboard() {
  const cohorly = useCohorly();
  return (
    <button
      onClick={() => cohorly.track("Button Clicked", { button: "upgrade" })}
    >
      Upgrade
    </button>
  );
}
```

## Identify on login

```tsx
function useAuthTracking(user: { id: string } | null) {
  const cohorly = useCohorly();
  useEffect(() => {
    if (user) cohorly.identify(user.id);
    else cohorly.reset();
  }, [user, cohorly]);
}
```

## Error tracking

`<CohorlyErrorBoundary>` catches render errors below it, captures them as
`$exception` events (`mechanism.type: "react.errorboundary"`, level
`"error"`) and renders `fallback` - a node, or a function that receives the
error and a `reset()` that renders the children again. The React component
stack is attached as a breadcrumb (`react.component_stack`), not as an event
property.

```tsx
import { CohorlyErrorBoundary, CohorlyProvider } from "@cohorly/react";

function App() {
  return (
    <CohorlyProvider
      token="YOUR_PROJECT_TOKEN"
      release="web@2026.11.3"
      captureExceptions
      beforeSendException={(event) => event}
    >
      <CohorlyErrorBoundary
        fallback={({ reset }) => <button onClick={reset}>Try again</button>}
        onError={(error, componentStack) => console.warn(error, componentStack)}
      >
        <Dashboard />
      </CohorlyErrorBoundary>
    </CohorlyProvider>
  );
}
```

The provider takes the same error-tracking options as `init()`:
`captureExceptions`, `release`, `dist`, `beforeSendException` and
`maxExceptionQueueSize`. `useCohorly()` exposes `captureException()` and
`addBreadcrumb()`. Releases, breadcrumbs, scrubbing and delivery are described
in [Web SDK: Error tracking](/sdks/web#error-tracking).

For a full API reference of the returned client (super properties, people
profiles, flush), see the [Web SDK](/sdks/web).