Integrate Claimr into a JavaScript framework

The Claimr widget works in any JavaScript framework. There is no npm package to install: you load one script, claimr.min.js, and it renders the widget inside an element you choose. This page explains how that script behaves inside a single-page app (SPA), and lists the rules that keep an integration stable across route changes, re-renders, and server-side rendering. Read this page first, then follow the guide for your framework:

React

Vite, Create React App, React Router.

Next.js

App Router and Pages Router.

Vue and Nuxt

Vue 3 with Vite, and Nuxt 3 or 4.

Building with an AI coding agent such as Claude Code, Codex, or Cursor? See Use Claimr docs with AI coding agents for a ready-made rules file you can drop into your project.

Before you start

Collect these values from the Claimr admin panel. Open your campaign, click Publish, then click Get embed code.

Value	Where it goes	Secret?
Organization ID	`data-organization`	No. Safe to ship to the browser.
Campaign ID	`data-campaign`	No. Safe to ship to the browser.
Container ID	`data-container`. Any element ID you choose, for example `claimr-widget`.	No
API token	`Authorization` header when you generate user tokens on your server. Only needed if your users sign in through your app.	Yes. Never send it to the browser.

How the loader works

When claimr.min.js runs, it does the following:

Finds the script element with id="claimr-script" and reads every data-* attribute from it. The ID is fixed: the loader looks it up by that exact name.
Creates the SDK object at window.claimr and posts a claimr::ready message to the page window.
Looks for the element whose ID matches data-container. If it exists, the loader appends the widget <iframe> to it. It also appends a full-screen popup layer (#claimr-contest-popup, position: fixed, z-index: 1000) to <body>.
Watches <body> with a MutationObserver:
- When the container element appears, the loader attaches the widget to it.
- When the container element disappears, the loader removes the widget iframe and the popup layer.
When the widget iframes finish loading, the loader sets window.claimr.is_claimr_ready to true and posts a widget::ready message to the page window. Any login() calls made earlier run at this point.
If data-autoresize is set, the loader writes the container’s height as an inline style every time the widget content changes size.

The key consequence for SPAs: the script is loaded once, and the widget follows the container. You show and hide the widget by rendering or removing the container element, exactly like any other component. You never re-inject the script to show the widget on a new route.

Integration rules

Every framework guide in this section follows these rules. If you write your own integration, follow them too.

Load the script once, from the app root

Inject the script from your root component, root layout, or app plugin. Do not inject it from the component that renders the widget, and do not inject it on every route. Guard the injection with document.getElementById('claimr-script') so that React Strict Mode, hot module reload, and double mounts stay idempotent.

Give the script the ID claimr-script

The loader reads its configuration from document.getElementById('claimr-script'). Any other ID breaks the integration. Only one Claimr script can exist on a page.

Render the container as an empty element with a stable ID

Render a single empty <div> whose id matches data-container. Do not render children inside it and do not bind an inline height style to it: the loader owns its content and, with autoresize, its height. Style it with a class instead.

Let the loader attach and detach the widget

To hide the widget, remove the container (conditional rendering, route change). To show it again, render the container again. Do not call destroy() when a component unmounts: destroy() also disconnects the observer and clears the stored wallet session, so the widget will not come back on the next mount.

Read window.claimr at call time

Always call window.claimr?.method() when you need it. Do not store the object in a variable, module constant, or state: reloading the script replaces it with a new object.

Assign callbacks once, right after the script loads

Callbacks such as on_user_info are plain properties, so each one has a single owner. Assign them in the same place that loads the script, inside the script’s load handler, and fan the data out through your app’s state (React context, a Vue reactive object, Pinia, Nuxt useState). Do not assign them from individual components.

Wait for widget::ready before calling widget methods

Most methods send a message into the widget iframe. If the iframe has not loaded yet, the message is lost. See Method readiness.

Run Claimr code in the browser only

window and document do not exist during server-side rendering. Load the script from an effect, a mounted hook, or a client-only plugin. Rendering the empty container on the server is fine.

Keep the API token on the server

Generate user tokens in a server route or server component, then pass only the resulting user token to the browser.

Method readiness

The loader keeps a few values and replays them when the widget loads. Everything else is sent straight to the iframe and is dropped if the widget is not ready.

Method	Safe before `widget::ready`?
`set_user_token(token)`	Yes. The token is stored and sent when the widget loads.
`connect_wallet(...)`	Yes. The wallet is stored and sent when the campaign loads.
`open_quest(quest_id)`	Yes. The quest is stored and opened when the campaign loads.
`login(in_popup)`	Yes. The call is queued and runs when the widget is ready.
`logout()`	Yes for local state. The widget itself is only notified if it is loaded.
`set_language`, `set_theme`, `complete_task`, `select_wallet`, `open_profile_popup`, `platform_login`	No. Call these after `widget::ready`.

To wait for readiness, check window.claimr?.is_claimr_ready, and if it is false, listen for the next widget::ready message. The widget::ready and claimr::ready messages are posted by the loader to your own window, so filter on event.source === window:

function whenWidgetReady(): Promise<void> {
  return new Promise((resolve) => {
    if (window.claimr?.is_claimr_ready) return resolve();
    const onMessage = (event: MessageEvent) => {
      if (event.source !== window || event.data?.event !== 'widget::ready') return;
      window.removeEventListener('message', onMessage);
      resolve();
    };
    window.addEventListener('message', onMessage);
  });
}

widget::ready only fires while a container is mounted. On a page without a container, the promise above stays pending until the user navigates to a page that renders one.

The shared loader module

Every framework guide uses the same framework-agnostic module, claimr.ts. It loads the script once, assigns callbacks on every fresh instance, exposes readiness helpers, and declares TypeScript types for window.claimr. Copy it into your project as src/lib/claimr.ts (or lib/claimr.ts in Nuxt).

lib/claimr.ts

export const CLAIMR_SCRIPT_ID = 'claimr-script';
export const CLAIMR_SCRIPT_SRC = 'https://widgets.claimr.io/claimr.min.js';

export interface ClaimrConfig {
  organization: string;
  campaign: string;
  /** ID of the element the widget renders into. */
  container: string;
  /** Resize the container to fit the widget content. Omit or pass false to disable. */
  autoresize?: boolean;
  language?: string;
  theme?: string;
  /** `dapp` when your app supplies the wallet, `telegram` inside a Telegram Mini App. */
  platform?: string;
  /** Pre-generated user token, when you already know the signed-in user at load time. */
  userToken?: string;
  showTags?: string;
  hideTags?: string;
  groups?: string;
  ref?: string;
  debug?: boolean;
}

export type ClaimrUser = { id?: string; [key: string]: unknown };
export type ClaimrCampaignInfo = Record<string, unknown>;

export type ClaimrWalletRequest =
  | { op: 'connect'; namespaces: string[] }
  | { op: 'sign_message'; address: string; message: string }
  | {
      op: 'send_transaction';
      chain_id: string;
      address: string;
      request: unknown;
      contract: string;
      method: string;
      args: unknown[];
      abi: unknown[];
      fee?: unknown;
    }
  | { op: 'disconnect' };

export interface Claimr {
  // State
  user: ClaimrUser | null;
  campaign_info: ClaimrCampaignInfo | null;
  is_claimr_ready: boolean;

  // Methods
  complete_task(task_id: string): void;
  connect_wallet(
    address: string,
    signature: string,
    message: string,
    chain?: string | number,
    no_reset?: boolean,
  ): void;
  destroy(): void;
  get_user_info(campaign_id: string, public_key: string, account: string, platform: string): Promise<unknown>;
  login(in_popup?: boolean): void;
  logout(): void;
  open_profile_popup(): void;
  open_quest(quest_id: string): void;
  platform_login(platform: string): void;
  select_wallet(address: string): void;
  set_language(language: string): void;
  set_theme(theme: string): void;
  set_user_token(token: string): void;

  // Callbacks: assign your own function to handle an event
  on_user_info: (user: ClaimrUser) => void;
  on_campaign_info: (info: ClaimrCampaignInfo) => void;
  on_campaign_loading: () => void;
  on_campaign_revealed: () => void;
  on_campaign_error: (error: string) => void;
  on_logout: () => void;
  on_analytics_event: (event: Record<string, unknown>) => void;
  on_leaderboards_info: (entries: unknown[]) => void;
  on_contest_open: () => void;
  on_leaderboard_open: () => void;
  on_market_open: () => void;
  on_custom_login: () => void;
  on_wallet_request?: (request: ClaimrWalletRequest) => Promise<object> | object;
}

declare global {
  interface Window {
    claimr?: Claimr;
  }
}

type Setup = (claimr: Claimr) => void;

let loading: Promise<Claimr> | null = null;
let setupFn: Setup | undefined;

/** The live SDK object, or undefined on the server or before the script has run. */
export function getClaimr(): Claimr | undefined {
  return typeof window === 'undefined' ? undefined : window.claimr;
}

function toAttributes(config: ClaimrConfig): Record<string, string | undefined> {
  return {
    'data-organization': config.organization,
    'data-campaign': config.campaign,
    'data-container': config.container,
    // The loader treats any non-empty value as "on", including "false", so omit it to disable.
    'data-autoresize': config.autoresize === false ? undefined : 'true',
    'data-language': config.language,
    'data-theme': config.theme,
    'data-platform': config.platform,
    'data-user-token': config.userToken,
    'data-show-tags': config.showTags,
    'data-hide-tags': config.hideTags,
    'data-groups': config.groups,
    'data-ref': config.ref,
    'data-debug': config.debug ? 'true' : undefined,
  };
}

/**
 * Loads claimr.min.js once per page session. Safe to call many times.
 * `setup` runs on every fresh SDK instance: assign your callbacks there.
 */
export function loadClaimr(config: ClaimrConfig, setup?: Setup): Promise<Claimr> {
  if (typeof window === 'undefined') {
    return Promise.reject(new Error('Claimr can only be loaded in the browser'));
  }
  if (setup) setupFn = setup;
  if (loading) return loading;

  loading = new Promise<Claimr>((resolve, reject) => {
    const done = () => {
      const claimr = window.claimr;
      if (!claimr) return reject(new Error('claimr.min.js loaded but window.claimr is missing'));
      setupFn?.(claimr);
      resolve(claimr);
    };

    const existing = document.getElementById(CLAIMR_SCRIPT_ID) as HTMLScriptElement | null;
    if (existing) {
      // Already on the page, for example after hot module reload.
      if (window.claimr) return done();
      existing.addEventListener('load', done, { once: true });
      existing.addEventListener('error', () => reject(new Error('Failed to load claimr.min.js')), { once: true });
      return;
    }

    const script = document.createElement('script');
    script.id = CLAIMR_SCRIPT_ID;
    script.src = CLAIMR_SCRIPT_SRC;
    script.async = true;
    for (const [name, value] of Object.entries(toAttributes(config))) {
      if (value) script.setAttribute(name, value);
    }
    script.addEventListener('load', done, { once: true });
    script.addEventListener(
      'error',
      () => {
        loading = null;
        script.remove();
        reject(new Error('Failed to load claimr.min.js'));
      },
      { once: true },
    );
    document.body.appendChild(script);
  });

  return loading;
}

/**
 * Replaces the running widget with a new configuration, for example another campaign.
 * The stored wallet session is cleared, so call connect_wallet or set_user_token again afterwards.
 */
export function reloadClaimr(config: ClaimrConfig): Promise<Claimr> {
  getClaimr()?.destroy();
  document.getElementById(CLAIMR_SCRIPT_ID)?.remove();
  loading = null;
  return loadClaimr(config);
}

/** Resolves when the widget iframe is loaded and accepts commands. */
export function whenWidgetReady(): Promise<Claimr> {
  return new Promise((resolve) => {
    const current = getClaimr();
    if (current?.is_claimr_ready) return resolve(current);
    const onMessage = (event: MessageEvent) => {
      if (event.source !== window || event.data?.event !== 'widget::ready') return;
      window.removeEventListener('message', onMessage);
      resolve(window.claimr!);
    };
    window.addEventListener('message', onMessage);
  });
}

/** Runs `fn` once the widget is ready. Use it for set_language, complete_task, and similar methods. */
export async function withWidget(fn: (claimr: Claimr) => void): Promise<void> {
  fn(await whenWidgetReady());
}

Configuration and environment variables

The organization and campaign IDs are public values, so it is fine to expose them through your bundler’s public environment variables. The API token is secret and must only be read on the server.

Framework	Public (browser)	Server only
Vite (React, Vue)	`VITE_CLAIMR_ORGANIZATION`, `VITE_CLAIMR_CAMPAIGN`	Your backend’s own environment
Next.js	`NEXT_PUBLIC_CLAIMR_ORGANIZATION`, `NEXT_PUBLIC_CLAIMR_CAMPAIGN`	`CLAIMR_API_TOKEN`, `CLAIMR_PLATFORM`
Nuxt	`NUXT_PUBLIC_CLAIMR_ORGANIZATION`, `NUXT_PUBLIC_CLAIMR_CAMPAIGN`	`NUXT_CLAIMR_API_TOKEN`, `NUXT_CLAIMR_PLATFORM`

Script attributes are read once, when the script runs. Changing them later has no effect. To change settings at runtime, use the SDK method instead:

To change	Use
Language	`set_language(code)`
Theme	`set_theme(name)`, or `data-theme-key` to follow a `localStorage` key
Signed-in user	`set_user_token(token)`, and `logout()` when the user signs out
Wallet	`connect_wallet(...)` or `select_wallet(address)`
Campaign, organization, tags, groups, platform	`reloadClaimr(newConfig)` from the shared module

See Widget attributes for every data-* attribute and the SDK guide for every method and callback.

Identify your users

Pick one of these sign-in models. They are configured per campaign in Settings > Sign-in options.

Model	When to use it	What your app does
Widget sign-in	Users sign in inside the widget with X, Discord, email, and so on.	Nothing. Optionally call `login()` from your own button.
User token	Users already have an account in your app.	Generate a token on your server with `GET https://prod.claimr.io/api/v1/token`, then pass it with `data-user-token` or `set_user_token()`. Call `logout()` when the user signs out of your app. See User token.
Wallet (dApp)	Your app already connects a wallet (wagmi, RainbowKit, Reown, and so on).	Set `platform: 'dapp'` and implement `on_wallet_request`. See Integrate Claimr widget into your dApp.
Telegram	The app runs as a Telegram Mini App.	Set `platform: 'telegram'`. See Telegram Mini App.

The user token endpoint returns { "success": true, "data": { "token": "..." } }. The token does not expire, so you can store it with the user record instead of requesting it on every page load.

Common mistakes

Symptom	Cause	Fix
Nothing renders, no errors	The script tag’s ID is not `claimr-script`.	Set `id="claimr-script"`.
Nothing renders on one route	The container ID does not match `data-container`, or the container is not in the DOM.	Use the same constant for both.
Two widgets, or the widget flickers on navigation	The script is injected from the widget component, so it reloads on every mount.	Load it once from the app root. Only render the container in the widget component.
Widget does not come back after navigating away and back	The component calls `destroy()` on unmount.	Remove the `destroy()` call. The loader detaches and re-attaches on its own.
Callbacks stop firing	The script was reloaded and the callbacks were assigned to the old `window.claimr`.	Assign callbacks in the `setup` function passed to `loadClaimr`.
`set_language` or `complete_task` does nothing	Called before the widget loaded.	Wrap the call in `withWidget(...)`.
`ReferenceError: window is not defined`	Claimr code ran during server-side rendering.	Load from an effect, `onMounted`, or a `.client` plugin.
Page cannot scroll after navigating away from an open quest	The quest popup sets `overflow: hidden` on `<body>`.	Reset `document.body.style.overflow` when the widget component unmounts, as the framework guides do.
Autoresize cannot be turned off	`data-autoresize="false"` still enables it.	Omit the attribute.
Widget height fights your layout	The container has a framework-bound inline `height`.	Style the container with a class and let autoresize set the height.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Integrate Claimr into a JavaScript framework

React

Next.js

Vue and Nuxt

Before you start

How the loader works

Integration rules

Method readiness

The shared loader module

Configuration and environment variables

Identify your users

Common mistakes

React

Next.js

Vue and Nuxt

​Before you start

​How the loader works

​Integration rules

​Method readiness

​The shared loader module

​Configuration and environment variables

​Identify your users

​Common mistakes

Before you start

How the loader works

Integration rules

Method readiness

The shared loader module

Configuration and environment variables

Identify your users

Common mistakes