# React SDK

> Add Whisperr to a React app with @whisperr/react: one provider, a useWhisperr() hook, and the full @whisperr/web client.

`@whisperr/react` gives a React app one Whisperr client through a provider and a hook. It wraps [`@whisperr/web`](/sdks/web/), so every behavior on that page applies here. On the Next.js App Router, use [`@whisperr/next`](/sdks/next/).

## Install

```bash
npm i @whisperr/react @whisperr/web
```

The packages are [`@whisperr/react`](https://www.npmjs.com/package/@whisperr/react) and [`@whisperr/web`](https://www.npmjs.com/package/@whisperr/web) on npm. They release together; the current version is 0.4.0. React 17 or later is required.

## Quickstart

`App.tsx`

```tsx
import { WhisperrProvider, useWhisperr } from "@whisperr/react";


export function App() {
  return (
    <WhisperrProvider apiKey="wpk_your_publishable_key">
      <NewProject />
    </WhisperrProvider>
  );
}


function NewProject({ createProject }: { createProject: () => Promise<void> }) {
  const whisperr = useWhisperr();
  // Track after the action succeeds. "project_created" is an example name.
  async function create() {
    await createProject();
    whisperr.track("project_created", { template: "blank" });
  }
  return <button onClick={create}>New project</button>;
}
```

Use a publishable key (`wpk_…`), shown as an **App** key in **Settings → API keys**. Never put a server key (`wrk_…`) in React code.

## How do I pass more options to WhisperrProvider?

`WhisperrProvider` takes either `apiKey` or a full `options` object with any [Web SDK option](/sdks/web/#options):

`App.tsx`

```tsx
<WhisperrProvider
  options={{
    apiKey: "wpk_your_publishable_key",
    appVersion: "2.4.0",
    onError: (error) => console.warn("whisperr", error.type, error.message),
  }}
>
  <Routes />
</WhisperrProvider>
```

The provider creates the client once, on first render. Changing its props later has no effect.

## How do I identify the user in React?

Call `identify()` after sign-in and when you restore a signed-in session. Call `reset()` on sign-out.

`useWhisperrIdentity.ts`

```tsx
import { useEffect } from "react";
import { useWhisperr } from "@whisperr/react";


export function useWhisperrIdentity(user: { id: string; plan: string } | null) {
  const whisperr = useWhisperr();
  useEffect(() => {
    if (user) whisperr.identify(user.id, { traits: { plan: user.plan } });
  }, [whisperr, user?.id]);
}
```

Events tracked before `identify()` go out under an anonymous id and move to the user when you identify them. See [What happens before the user signs in?](/sdks/web/#what-happens-before-the-user-signs-in)

## How do I send the app language from React?

Call `setAppLanguage()` with the language the user picked in your product. Calling it with an unchanged value sends nothing.

```tsx
const whisperr = useWhisperr();
useEffect(() => whisperr.setAppLanguage(i18n.language), [i18n.language]);
```

## Server-side rendering

`WhisperrProvider` is safe to render on the server. Outside a browser the client captures and sends nothing.

## Common questions

### Is WhisperrProvider safe under React StrictMode?

Yes. The provider creates the client once, and Whisperr.init() returns the same client on every later call, so a double render does not create a second client.

### What does useWhisperr() return?

The @whisperr/web client: identify(), track(), page(), setAppLanguage(), flush(), reset(), optIn() and optOut(). It throws when it is used outside a WhisperrProvider.

Source: https://docs.whisperr.net/sdks/react/