React
@refport/react provides React components and hooks for click ID tracking and rendering the embedded referral portal.
@refport/react wraps refport-js in idiomatic React APIs and provides the <RefportEmbed> component for embedding the referral portal.
Installation
npm install @refport/react
# or
pnpm add @refport/react@refport/react requires React 18 or 19 as a peer dependency.
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, tracked, source } = 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();
// send clickId to your server
}reset(options?)
Re-exported from refport-js. Clears the tracking cookie.
Embedded referral portal
<RefportEmbed>
Renders an iframe containing the partner referral portal. The portal adjusts its height dynamically to fit its content.
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 |
themeOptions | object | — | Override individual theme colors |
themeOptions.backgroundColor | string | — | Background color (CSS value) |
themeOptions.primaryColor | string | — | Accent/primary color |
themeOptions.textColor | string | — | Main text color |
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 (e.g. className, id) are forwarded to the container element.
TypeScript types
import type { RefportTrackingOptions, RefportTrackingResult, RefportEmbedProps } from '@refport/react';