Skip to main content
For react integrations, we support 2 paths:
  • Widget: A plug-and-play widget that handles UI/State management for you. Find an example here
  • Session API: A react hook that gives you total control of the user journey and UI/State management. Find an example here.

​
Install

npm i @worldcoin/idkit

​
IDKitWidget

First, add the IDKitWidget component to your site. The values for the app_id and action props were obtained from the Developer Portal in Getting Started. We’ll define the handleVerify and onSuccess callbacks next.
/verify.tsx
"use client"; // for Next.js app router
import {
  IDKitWidget,
  VerificationLevel,
  ISuccessResult,
} from "@worldcoin/idkit";

// ...
<IDKitWidget
  app_id="your app id" // obtained from the Developer Portal
  action="your action id" // obtained from the Developer Portal
  onSuccess={onSuccess} // callback when the modal is closed
  handleVerify={handleVerify} // callback when the proof is received
  verification_level={VerificationLevel.Orb}
>
  {({ open }) => (
    // This is the button that will open the IDKit modal
    <button onClick={open}>Verify with World ID</button>
  )}
</IDKitWidget>;

​
handleVerify

The handleVerify callback is called when the user’s proof is received. This will send the proof to your backend for verification:
/verify.tsx
const handleVerify = async (proof: ISuccessResult) => {
  const res = await fetch("/api/verify", {
    // route to your backend will depend on implementation
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(proof),
  });
  if (!res.ok) {
    throw new Error("Verification failed."); // IDKit will display the error message to the user in the modal
  }
};

​
Verifying the proof

The handleVerify callback sends the proof to your backend for verification. In the backend handler should verify the proof with the Developer Portal API:
The call to the Developer Portal API must be made server-side to avoid man in the middle attacks.
/api/verify.ts
import { type IVerifyResponse, verifyCloudProof } from "@worldcoin/idkit-core";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const proof = req.body;
  const app_id = process.env.APP_ID;
  const action = process.env.ACTION_ID;
  const verifyRes = (await verifyCloudProof(
    proof,
    app_id,
    action
  )) as IVerifyResponse;

  if (verifyRes.success) {
    // This is where you should perform backend actions if the verification succeeds
    // Such as, setting a user as "verified" in a database
    res.status(200).send(verifyRes);
  } else {
    // This is where you should handle errors from the World ID /verify endpoint.
    // Usually these errors are due to a user having already verified.
    res.status(400).send(verifyRes);
  }
}
If you want to verify the proof onchain read more about it here.

​
onSuccess

The onSuccess callback is called when the user closes the modal. This is where you can perform any necessary actions, such as redirecting the user to a new page.
/verify.tsx
const onSuccess = () => {
  // This is where you should perform any actions after the modal is closed
  // Such as redirecting the user to a new page
  window.location.href = "/success";
};

​
Session Hook

First, setup the session hook with your configuration:
/verify.tsx
const { status, sessionURI, result, errorCode } = useSession({
  app_id: "your app id",
  action: "your action id",
});
After that you need to handle the following possible statuses:
  • WaitingForConnection: Display the sessionURI to the user eg. with a QR code
  • Confirmed: Session ended successfully, now you must verify the result proof in your backend.
  • Failed: Session failed, check errorCode