React

Reference for @worldcoin/idkit React widgets and hooks, including request flows and presets.

Use @worldcoin/idkit when you want React-native ergonomics on top of @worldcoin/idkit-core.

Install

npm

npm i @worldcoin/idkit

Choose your API

• Widgets: quickest integration, built-in modal and state handling
• Hooks: headless control for custom UI and flow orchestration

Controlled widgets

Request widget

import { IDKitRequestWidget, orbLegacy, type RpContext } from "@worldcoin/idkit";

const rpContext: RpContext = {
  rp_id: "rp_xxxxx",
  nonce: "0x...",
  created_at: 1735689600,
  expires_at: 1735689900,
  signature: "0x...",
};

<IDKitRequestWidget
  open={open}
  onOpenChange={setOpen}
  app_id="app_xxxxx"
  action="my-action"
  rp_context={rpContext}
  allow_legacy_proofs={true}
  preset={orbLegacy({ signal: "user-123" })}
  environment="production"
  handleVerify={async (result) => {
    const response = await fetch("/api/verify-proof", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ rp_id: rpContext.rp_id, idkitResponse: result }),
    });

    if (!response.ok) {
      throw new Error("Backend verification failed");
    }
  }}
  onSuccess={() => {
    // Called after `handleVerify` resolves (or immediately if omitted).
    // Update your app state/UI here.
  }}
  onError={(errorCode) => {
    console.error("IDKit error", errorCode);
  }}
/>;

Widget callbacks

• onSuccess is required for IDKitRequestWidget and IDKitSessionWidget.
• handleVerify is optional and only available on widgets. Use it to verify the proof in your backend before success is emitted.
• If handleVerify throws/rejects, the widget enters an error state, emits onError("failed_by_host_app"), and does not call onSuccess.
• onError is optional.

Headless hooks

useIDKitRequest

import { useIDKitRequest, orbLegacy } from "@worldcoin/idkit";

const flow = useIDKitRequest({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
  preset: orbLegacy({ signal: "user-123" }),
  polling: {
    interval: 2_000,
    timeout: 120_000,
  },
});

<button onClick={flow.open} disabled={flow.isAwaitingUserConfirmation}>
  Verify
</button>;

Hook result fields:

• open()
• reset()
• isAwaitingUserConnection
• isAwaitingUserConfirmation
• isSuccess
• isError
• connectorURI
• result
• errorCode

Invite-code mode

For invite-code flows, use IDKitInviteCodeRequestWidget (controlled) or useIDKitInviteCodeRequest (headless). Config matches IDKitRequestWidget / useIDKitRequest — invite-code mode adds no new required fields. See Invite-code mode for when to use it.

import { IDKitInviteCodeRequestWidget, selfieCheckLegacy } from "@worldcoin/idkit";

<IDKitInviteCodeRequestWidget
  open={open}
  onOpenChange={setOpen}
  app_id="app_xxxxx"
  action="my-action"
  rp_context={rpContext}
  allow_legacy_proofs={true}
  preset={selfieCheckLegacy({ signal: "user-123" })}
  handleVerify={async (result) => { /* ... */ }}
  onSuccess={() => { /* ... */ }}
/>;

useIDKitInviteCodeRequest result fields (sibling of useIDKitRequest’s):

• open()
• reset()
• isAwaitingUserConnection
• isAwaitingUserConfirmation
• isSuccess
• isError
• connectorURI
• codeExpiresAt
• result
• errorCode

Migrating from QR / connect-URL

// Before — QR / connect-URL widget
import { IDKitRequestWidget, orbLegacy } from "@worldcoin/idkit";

<IDKitRequestWidget
  open={open}
  onOpenChange={setOpen}
  app_id="app_xxxxx"
  action="my-action"
  rp_context={rpContext}
  allow_legacy_proofs={true}
  preset={orbLegacy({ signal: "user-123" })}
  handleVerify={handleVerify}
  onSuccess={onSuccess}
/>;

// After — invite-code widget
import { IDKitInviteCodeRequestWidget, selfieCheckLegacy } from "@worldcoin/idkit";

<IDKitInviteCodeRequestWidget
  open={open}
  onOpenChange={setOpen}
  app_id="app_xxxxx"
  action="my-action"
  rp_context={rpContext}
  allow_legacy_proofs={true}
  preset={selfieCheckLegacy({ signal: "user-123" })}
  handleVerify={handleVerify}
  onSuccess={onSuccess}
/>;

Swap the component and preset. Props, callbacks, and backend verification stay the same. The headless equivalent is useIDKitInviteCodeRequest in place of useIDKitRequest.

Presets

React hooks/widgets take preset directly in config.

Localization and UX notes

• Widgets support language="en" | "es" | "th"
• Widgets default to autoClose={true} after success

Backend utilities

For RP signature generation in React/Next.js apps, use the pure JS subpath:

import { signRequest } from "@worldcoin/idkit/signing";

See RP Signatures for the full algorithm and test vectors.