npm package: @quotientjs/react
Description: React provider for the Quotient SDK client.
Latest version: 0.10.3

# @quotientjs/react

React provider for the Quotient SDK client.

## Installation

```bash
npm install @quotientjs/react
# or
yarn add @quotientjs/react
# or
pnpm add @quotientjs/react
```

## Usage

### Provider Setup

Wrap your application with the `QuotientProvider`:

```tsx
import { QuotientProvider } from "@quotientjs/react";

function App() {
  return (
    <QuotientProvider
      clientOptions={{
        apiKey: "your_api_key",
        baseUrl: "https://api.quotient.com",
      }}
      // Automatically track page views on initial load and route changes
      autoTrackPageViews={true}
    >
      <YourApp />
    </QuotientProvider>
  );
}
```

### Using the Client

Access the Quotient client with the `useQuotient` hook:

```tsx
import { useQuotient } from "@quotientjs/react";

function YourComponent() {
  // Get the client context - includes all needed functionality
  const { client, isInitializing, error, reset, trackPageView } = useQuotient();

  // Example: manually track page view
  const handleTrackPageView = () => {
    trackPageView();
  };

  // Example: track a person
  const handleSubmit = async (email) => {
    if (client) {
      await client.people.upsert({
        emailAddress: email,
        emailMarketingState: "SUBSCRIBED",
      });
    }
  };

  return (
    <div>
      {isInitializing ? (
        <p>Initializing client...</p>
      ) : error ? (
        <p>Error: {error.message}</p>
      ) : (
        <p>Client ready!</p>
      )}

      <button onClick={handleTrackPageView}>Track Page View</button>
      <button onClick={reset}>Reset Client</button>
    </div>
  );
}
```

### Automatic Page View Tracking

When `autoTrackPageViews` is enabled, the provider will:

1. Track a page view when the component mounts
2. Track page views when the pathname changes (works with history API)
3. Works with most modern React routers like React Router

This is ideal for Single Page Applications where you want analytics for each virtual page.

### Additional Hooks

For components that only need to know the client status:

```tsx
import { useQuotientStatus } from "@quotientjs/react";

function ClientStatus() {
  // Get just the client status without the client itself
  const { isInitializing, error } = useQuotientStatus();

  return (
    <div>
      {isInitializing
        ? "Initializing..."
        : error
          ? `Error: ${error.message}`
          : "Ready"}
    </div>
  );
}
```

## Manual Initialization

If you need to initialize the client manually:

```tsx
import { QuotientProvider, useQuotient } from "@quotientjs/react";

function App() {
  return (
    <QuotientProvider
      clientOptions={{
        apiKey: "your_api_key",
        baseUrl: "https://api.quotient.com",
      }}
      autoInitialize={false}
    >
      <InitializeButton />
    </QuotientProvider>
  );
}

function InitializeButton() {
  const { initialize, isInitializing, client } = useQuotient();

  return (
    <div>
      {client ? (
        <p>Client initialized!</p>
      ) : (
        <button onClick={initialize} disabled={isInitializing}>
          {isInitializing ? "Initializing..." : "Initialize Client"}
        </button>
      )}
    </div>
  );
}
```

## License

MIT