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

# @tolt/tracking

> Load tolt.js from npm with types, a React component and a useTolt hook.

`@tolt/tracking` injects [tolt.js](/sdks/tolt-js) for you and gives you typed access to the referral and the signup call. Same script, same cookies, no `<script>` tag to manage.

![](https://mintcdn.com/tolt-29/IdZ6_r2VYMOh5a6x/images/logos/react.svg?fit=max\&auto=format\&n=IdZ6_r2VYMOh5a6x\&q=85\&s=95ed23faae93d9a6aaea81ee8fa63d28)

\<ToltTracking />

tolt.js
&#x20;useTolt()
signup(id)
&#x20;Tolt

Returned by useTolt()

**hook**ReactdataToltData | nullreadytruesignup(identifier) => …

Inside data

**ToltData**ref=samclick\_id"clk\_3hTq…"partner\_id"part\_8fKq…"program\_id"prg\_2wXc…"customer\_id"cus\_7Lm2…"

## Install

```bash theme={"system"}
npm install @tolt/tracking
```

You need your public key from **Dashboard → Settings → Integrations**. React is an optional peer dependency (17+).

## Use it

**React**

Render `ToltTracking` once near the root. It renders nothing.

```tsx app.tsx theme={"system"}
import { ToltTracking } from "@tolt/tracking/react";

export function App() {
  return (
    <>
      <ToltTracking publicKey="YOUR_PUBLIC_KEY" />
      <Routes />
    </>
  );
}
```

Then bind the signup once your own signup succeeds:

```ts track-signup.ts theme={"system"}
import { init, signup } from "@tolt/tracking";

// init() resolves once tolt.js has loaded (a no-op after the
// first call). signup() then waits for the recorded click and
// resolves without a customer_id when the visitor wasn't referred.
export async function trackSignup(userId: string) {
  await init({ publicKey: "YOUR_PUBLIC_KEY" });
  const result = await signup(userId);
  if (result?.customer_id) {
    // store result.customer_id (cus_...) on your user
  }
}
```

If the page navigates away right after signup, bind on the next page instead, or from your server with [`POST /v2/customers`](/tracking/server-side).

**Next.js**

The components use hooks, so wrap them in a client component and render it from your root layout.

```tsx components/tolt.tsx theme={"system"}
"use client";

export { ToltTracking } from "@tolt/tracking/react";
```

```tsx app/layout.tsx theme={"system"}
import { ToltTracking } from "@/components/tolt";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ToltTracking
          publicKey={process.env.NEXT_PUBLIC_TOLT_PUBLIC_KEY!}
        />
        {children}
      </body>
    </html>
  );
}
```

Then call `trackSignup()` from a client component, as in the React tab.

**Vanilla**

```ts theme={"system"}
import { init, signup } from "@tolt/tracking";

await init({ publicKey: "YOUR_PUBLIC_KEY" });

// After your own signup succeeds. Resolves without a
// customer_id when the visitor wasn't referred.
const result = await signup("jane@example.com");
// cus_...
if (result?.customer_id) console.log(result.customer_id);
```

## API

### Vanilla (`@tolt/tracking`)

| Function | Returns | |
| - | - | - |
| `init({ publicKey, scriptUrl? })` | `Promise<void>` | Injects the script once and resolves when it has loaded. The click may still be in flight. A no-op on the server. |
| `getData()` | `ToltData \| null` | The current referral, or `null` if this visit wasn't referred or the click isn't recorded yet. |
| `isReferred()` | `boolean` | Whether a referral is recorded. Can be `false` for a moment on the landing page. |
| `signup(identifier)` | `Promise<ToltSignupResult \| undefined>` | Waits for the click, then binds the visitor as a customer. Check `result?.customer_id`: it's missing when the visitor wasn't referred, on a repeat signup, or on a network error. Rejects if the script hasn't loaded yet. |

`scriptUrl` defaults to `https://cdn.tolt.io/v2/tolt.js`. `ToltData` has the fields described on the [tolt.js page](/sdks/tolt-js#toltdata).

### React (`@tolt/tracking/react`)

| Export | |
| - | - |
| `<ToltTracking publicKey scriptUrl? />` | Loads the script on mount and renders nothing. Load errors are logged to the console. |
| `useTolt()` | Returns `{ data, ready, signup }`. `data` is the current `ToltData` or `null`, `ready` turns `true` once tolt.js has loaded, and `signup(identifier)` binds the customer and refreshes `data`. |

> [!NOTE]
>
> Unlike `window.tolt.signup()`, the package's `signup()` rejects when tolt.js isn't loaded yet. Gate on `ready` from `useTolt()`, or `await init()` first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.