Refport Docs

@refport/react provides React components and hooks for click ID tracking, partner portal data, and embedded referral portal rendering.

@refport/react wraps the browser SDK in idiomatic React APIs. Use RefportProvider and the data hooks for custom partner portal UIs, or use <RefportEmbed> when you want the fastest iframe-based portal.

Installation

npm install @refport/react @tanstack/react-query
# or
pnpm add @refport/react @tanstack/react-query

@refport/react requires React 18 or 19 and TanStack Query 5 as peer dependencies.

Partner portal data

Use RefportProvider with a backend-created public embed token, then read partner data with useRefportPartner() or one of the granular hooks.

The token must be generated server-side with embedTokens.create(). Do not create embed tokens in the browser, because token creation requires your private Refport API key.

"use client";

import { RefportProvider, useRefportPartner } from "@refport/react";

export function ReferralPortal({ token }: { token: string }) {
  return (
    <RefportProvider token={token}>
      <ReferralPortalContent />
    </RefportProvider>
  );
}

function ReferralPortalContent() {
  const partner = useRefportPartner();

  if (partner.isLoading) {
    return <p>Loading...</p>;
  }

  if (partner.error) {
    return <p>Could not load referral data.</p>;
  }

  const { earnings, link, stats } = partner.data;

  return (
    <section>
      <input readOnly value={link.referralUrl} />
      <p>Clicks: {stats.clicks}</p>
      <p>Leads: {stats.leads}</p>
      <p>Sales: {stats.sales}</p>
      <p>Total earnings: {earnings.total}</p>
    </section>
  );
}

`RefportProvider`

Wrap every component that calls a Refport data hook.

Prop	Type	Default	Description
`token`	`string`	—	Public embed token from your backend
`baseUrl`	`string`	`https://app.refport.co`	Override the Refport app/API URL
`queryClient`	`QueryClient`	—	Optional TanStack Query client
`children`	`React.ReactNode`	—	Components that use the Refport data hooks

If your app already owns a TanStack Query client, pass it to RefportProvider:

"use client";

import { QueryClient } from "@tanstack/react-query";
import { RefportProvider } from "@refport/react";

const queryClient = new QueryClient();

export function ReferralPortal({ token }: { token: string }) {
  return (
    <RefportProvider queryClient={queryClient} token={token}>
      <ReferralPortalContent />
    </RefportProvider>
  );
}

Data hooks

useRefportPartner() is the primary hook. It performs one request and returns the full portal dataset.

Hook	Data
`useRefportPartner()`	Stats, timeseries, referral link, earnings, payouts, config

Granular hooks select from the same TanStack Query cache, so using multiple hooks with the same payout params does not create duplicate data fetches.

Hook	Data
`useRefportAffiliateStats()`	Click, lead, sale, and earnings totals
`useRefportAffiliateTimeseries()`	30-day click, lead, and sale timeseries
`useRefportAffiliateLink()`	Referral code, referral URL, and program name
`useRefportAffiliateEarnings()`	Earnings breakdown and commission settings
`useRefportAffiliatePayouts()`	Payout history
`useRefportPortalConfig()`	Portal branding and visibility configuration
`useRefportAffiliateData()`	All granular query results in one object

Pass payout pagination params to useRefportPartner() or useRefportAffiliatePayouts():

const partner = useRefportPartner({ limit: 10 });
const payouts = useRefportAffiliatePayouts({ limit: 10 });

Use refportQueryKeys for cache invalidation:

"use client";

import { useQueryClient } from "@tanstack/react-query";
import { refportQueryKeys } from "@refport/react";

export function RefreshButton({ token }: { token: string }) {
  const queryClient = useQueryClient();

  return (
    <button
      type="button"
      onClick={() =>
        queryClient.invalidateQueries({
          queryKey: refportQueryKeys.partner("https://app.refport.co", token),
        })
      }
    >
      Refresh
    </button>
  );
}

Click ID tracking

`useRefportTracking(options?)`

A hook that runs init() from refport-js on mount and returns the tracking result. Re-renders the component whenever the result changes.

"use client";

import { useRefportTracking } from "@refport/react";

export function MyComponent() {
  const { clickId } = useRefportTracking();

  return <p>Click ID: {clickId ?? "none"}</p>;
}

Pass any RefportTrackingOptions as the argument.

`<RefportTracker>`

A renderless component that runs tracking on mount. Place it once in your root layout so you don't need to import the hook in every page.

import { RefportTracker } from "@refport/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <RefportTracker />
        {children}
      </body>
    </html>
  );
}

Props:

Prop	Type	Description
`options`	`RefportTrackingOptions`	Options forwarded to `init()`
`onTrack`	`(result: RefportTrackingResult) => void`	Called whenever a click ID is present

`getClickId(cookieName?)`

Re-exported from refport-js. Returns the current click ID synchronously from the cookie — useful in event handlers where you don't want to subscribe to state.

import { getClickId } from "@refport/react";

function handleSubmit() {
  const clickId = getClickId();
  return clickId;
}

import { RefportEmbed } from "@refport/react";

export default function ReferralPage({ token }: { token: string }) {
  return <RefportEmbed token={token} theme="system" />;
}

The token must be a short-lived public token generated server-side with embedTokens.create(). See Embedded Portal for the full server + client setup.

Props:

Prop	Type	Default	Description
`token`	`string`	—	Required. Public embed token from `embedTokens.create()`
`theme`	`"light" \| "dark" \| "system"`	—	Color scheme for the portal iframe
`cssVars`	`Record<string, string>`	—	Inject arbitrary CSS variables into the portal
`baseUrl`	`string`	`https://app.refport.co`	Override the Refport app URL
`onError`	`(error: { code: string; message: string }) => void`	—	Called if the portal reports an error
`style`	`CSSProperties`	—	Styles applied to the wrapping `<div>`

Any additional div props, such as className and id, are forwarded to the container element.

TypeScript types

import type {
  RefportAffiliateEarnings,
  RefportAffiliateLink,
  RefportAffiliatePayout,
  RefportAffiliatePayouts,
  RefportAffiliatePayoutsParams,
  RefportAffiliateStats,
  RefportAffiliateTimeseries,
  RefportEmbedProps,
  RefportPartnerData,
  RefportPortalConfig,
  RefportProviderProps,
  RefportTrackingOptions,
  RefportTrackingResult,
} from "@refport/react";

React

Installation

Partner portal data

`RefportProvider`

Data hooks

Click ID tracking

`useRefportTracking(options?)`

`<RefportTracker>`

`getClickId(cookieName?)`

`reset(options?)`

Iframe embed

`<RefportEmbed>`

TypeScript types

On this page