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