React integration

There are two layers, and most apps use both:

• The web components. Drop <frak-button-share>, <frak-banner>, and <frak-post-purchase> straight into your JSX. No provider, no hooks. Start here.
• @frak-labs/react-sdk. Providers and hooks for custom flows: wallet status, modals, referrals, SSO, transactions.

Prerequisites

1. A React 18 or 19 project.
2. A merchant account on the Frak business dashboard with your domain registered. The main domain is registered at sign-up; add subdomains under Allowed Domains.

If you have not done that yet, start with the Get started guide.

The components in JSX

Install @frak-labs/components, set the config in its own module, and import the components you use before rendering. The package manager guide covers that setup, and Add Frak to a custom website shows a full React example including the TypeScript declaration for the <frak-*> tags.

The React SDK

1. Install

@tanstack/react-query and viem are peer dependencies: the hooks are React Query queries and mutations, and the SDK ships no QueryClient of its own.

npm

npm install @frak-labs/react-sdk @tanstack/react-query viem

yarn

yarn add @frak-labs/react-sdk @tanstack/react-query viem

pnpm

pnpm add @frak-labs/react-sdk @tanstack/react-query viem

bun

bun add @frak-labs/react-sdk @tanstack/react-query viem

2. Set up the providers

Three providers, in this order: your QueryClientProvider, then FrakConfigProvider (holds the config), then FrakIFrameClientProvider (creates the listener iframe and the client).

FrakProvider.tsx

import {
    FrakConfigProvider,
    FrakIFrameClientProvider,
} from "@frak-labs/react-sdk";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { PropsWithChildren } from "react";

const queryClient = new QueryClient();

const frakConfig = {
    metadata: {
        name: "Your App Name",
    },
    // The domain will be automatically set to window.location.host
};

export function FrakProvider({ children }: PropsWithChildren) {
    return (
        <QueryClientProvider client={queryClient}>
            <FrakConfigProvider config={frakConfig}>
                <FrakIFrameClientProvider>{children}</FrakIFrameClientProvider>
            </FrakConfigProvider>
        </QueryClientProvider>
    );
}

Wrap your app with it:

App.tsx

import { FrakProvider } from './FrakProvider';

function App() {
  return (
    <FrakProvider>
      {/* Your app content */}
    </FrakProvider>
  );
}

export default App;

domain is filled in for you

FrakConfigProvider defaults domain to window.location.host. Set it explicitly if you render server-side, otherwise it falls back to not-found during SSR.

The config takes the same fields as everywhere else. See FrakSetup and Configuration.

Targeting the dev stage

env states both origins the SDK talks to: "prod" (the default), "dev", or an explicit { wallet, backend } pair for local development. It replaces walletUrl and lands in the next major of the SDK, so on the version published today use walletUrl instead. See Configuration.

3. Read the wallet status

WalletStatus.tsx

/**
 * Simple wallet status component
 */
function WalletStatus() {
    const { data: walletStatus, isLoading, error } = useWalletStatus();

    if (isLoading) return <div>Loading wallet status...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return (
        <div>
            Wallet status:{" "}
            {walletStatus?.key === "connected" ? "Connected" : "Not connected"}
        </div>
    );
}

4. Open a modal

LoginButton.tsx

/**
 * Simple login with frak button
 */
function LoginButton() {
    const { mutate: displayModal, isPending } = useDisplayModal();

    const handleLogin = () => {
        displayModal({
            steps: {
                login: {},
            },
            metadata: {
                i18n: {
                    "sdk.modal.login.description":
                        "Login with Frak to receive up to {{ estimatedReward }}!",
                },
            },
        });
    };

    return (
        <button onClick={handleLogin} disabled={isPending} type={"button"}>
            {isPending ? "Logging in..." : "Login with Frak"}
        </button>
    );
}

5. Put it together

App.tsx

function App() {
    return (
        <FrakProvider>
            <h1>My Frak Powered app</h1>
            <WalletStatus />
            <LoginButton />
        </FrakProvider>
    );
}
export default App;

App.tsx (complete)

import { useDisplayModal, useWalletStatus } from "@frak-labs/react-sdk";
import { FrakProvider } from "./FrakProvider";

function App() {
    return (
        <FrakProvider>
            <h1>My Frak Powered app</h1>
            <WalletStatus />
            <LoginButton />
        </FrakProvider>
    );
}
export default App;

/**
 * Simple wallet status component
 */
function WalletStatus() {
    const { data: walletStatus, isLoading, error } = useWalletStatus();

    if (isLoading) return <div>Loading wallet status...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return (
        <div>
            Wallet status:{" "}
            {walletStatus?.key === "connected" ? "Connected" : "Not connected"}
        </div>
    );
}

/**
 * Simple login with frak button
 */
function LoginButton() {
    const { mutate: displayModal, isPending } = useDisplayModal();

    const handleLogin = () => {
        displayModal({
            steps: {
                login: {},
            },
            metadata: {
                i18n: {
                    "sdk.modal.login.description":
                        "Login with Frak to receive up to {{ estimatedReward }}!",
                },
            },
        });
    };

    return (
        <button onClick={handleLogin} disabled={isPending} type={"button"}>
            {isPending ? "Logging in..." : "Login with Frak"}
        </button>
    );
}

FrakProvider.tsx

import {
    FrakConfigProvider,
    FrakIFrameClientProvider,
} from "@frak-labs/react-sdk";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { PropsWithChildren } from "react";

const queryClient = new QueryClient();

const frakConfig = {
    metadata: {
        name: "Your App Name",
    },
    // The domain will be automatically set to window.location.host
};

export function FrakProvider({ children }: PropsWithChildren) {
    return (
        <QueryClientProvider client={queryClient}>
            <FrakConfigProvider config={frakConfig}>
                <FrakIFrameClientProvider>{children}</FrakIFrameClientProvider>
            </FrakConfigProvider>
        </QueryClientProvider>
    );
}

Every hook

Hook	Returns	What it does
useWalletStatus()	query	Current wallet status, kept in sync
useDisplayModal()	mutation	Open a modal from steps, with an optional placement
useDisplaySharingPage()	mutation	Open the sharing page
useReferralInteraction()	value	Processes an inbound referral once the client is ready, returns the state or an error
useSetupReferral()	side effect	Wires referral handling, emits frak:referral-success
useGetMerchantInformation()	query	Your merchant data as resolved by the backend
useGetUserReferralStatus()	query	The user’s referral state
useGetMergeToken()	query	Token used to merge a wallet
useSiweAuthenticate()	mutation	Sign-In with Ethereum
useSendTransactionAction()	mutation	Ask the wallet to send a transaction
useOpenSso()	mutation	Open the SSO flow
usePrepareSso(params)	query	Prepare an SSO session
usePrepareSsoUrl(params)	query	Build the SSO URL ahead of time, so the open is a direct user gesture and dodges popup blockers
useFrakClient()	value	The raw client, or undefined before it is ready
useFrakConfig()	value	The resolved config. Throws outside a FrakConfigProvider

Most mutation hooks take an optional { mutations } object of React Query options, and most query hooks take { query }. Two exceptions: useWalletStatus() takes no argument, and usePrepareSso(params) takes the SSO parameters directly.

Full signatures live in the generated SDK reference.

Handle an inbound referral

One hook is enough on the page a referred visitor lands on:

import { useReferralInteraction } from "@frak-labs/react-sdk";

export function ReferralHandler() {
  const state = useReferralInteraction();
  // "idle" | "processing" | a referral state | an Error
  return null;
}

Track a purchase

Purchase tracking has no hook: call the action, which needs no client.

import { trackPurchaseStatus } from "@frak-labs/core-sdk/actions";

await trackPurchaseStatus({
  customerId: "cust_123",
  orderId: "order_456",
  token: "a-unique-order-token",
});

Rewards are only released once your backend confirms the order with a signed webhook. See Validate purchases from your backend.

Next steps

Components referenceEvery element and every attribute.

SDK referenceGenerated reference for every hook and provider.

InteractionsWhat each interaction means and when to send it.

Backend validationConfirm real orders with a signed webhook.