> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# React SDK

> React provider and hooks for Tell analytics.

```bash theme={null}
npm install @tell-rs/react @tell-rs/browser
```

Wrap your app with `TellProvider`, then use hooks for tracking.

<Info>
  `@tell-rs/react` is a thin wrapper around the [browser SDK](/tracking/sdks/javascript/browser). It connects Tell to React's component lifecycle — the provider calls `configure()` on mount and `close()` on unmount. You install `@tell-rs/browser` alongside because that's where the actual tracking, sessions, and transport live.
</Info>

## Setup

```tsx theme={null}
import { TellProvider } from "@tell-rs/react";

function App() {
  return (
    <TellProvider apiKey="YOUR_API_KEY" options={{ captureErrors: true }}>
      <MyApp />
    </TellProvider>
  );
}
```

### With redaction

```tsx theme={null}
import { TellProvider } from "@tell-rs/react";
import { redact, SENSITIVE_PARAMS } from "@tell-rs/browser";

function App() {
  return (
    <TellProvider
      apiKey="YOUR_API_KEY"
      options={{
        beforeSend: redact({ stripParams: SENSITIVE_PARAMS }),
        captureErrors: true,
      }}
    >
      <MyApp />
    </TellProvider>
  );
}
```

## Hooks

```tsx theme={null}
import { useTell, useTrack, useIdentify } from "@tell-rs/react";

function SignUpButton() {
  const track = useTrack();
  const identify = useIdentify();

  function handleSignUp(user) {
    identify(user.id, { name: user.name });
    track("Sign Up Completed", { plan: "pro" });
  }

  return <button onClick={handleSignUp}>Sign Up</button>;
}
```

| Hook            | Returns                        | Notes                                  |
| --------------- | ------------------------------ | -------------------------------------- |
| `useTell()`     | Full browser SDK instance      | For advanced use cases                 |
| `useTrack()`    | `(event, properties?) => void` | Stable ref, safe for dependency arrays |
| `useIdentify()` | `(userId, traits?) => void`    | Stable ref, safe for dependency arrays |

## Direct access

For code outside of React components (utilities, background tasks):

```typescript theme={null}
import { tell } from "@tell-rs/react";
tell.track("Background Task");
```

## What you get from the browser SDK

All features documented in the [browser SDK guide](/tracking/sdks/javascript/browser) are available — sessions, device context, super properties, structured logging, opt-out, and `beforeSend` hooks. The React package only adds lifecycle integration and hooks.