JS Widget
JS Introduction
The World ID Javascript integration is the simplest way to start using World ID. The JS package currently supports web applications and requires only a few lines of code.
Installation
The JS package can be included in your project either as a module (which supports tree shaking to reduce bundle size) or you can add the script directly to your website.
npm install @worldcoin/id
# or
yarn add @worldcoin/id
Alternatively, to add the script directly in your HTML, just add this tag to your <head>
.
<script
type="text/javascript"
src="//unpkg.com/@worldcoin/id/dist/world-id.js"
></script>
Usage in React apps
If your app is built on React, using the React widget is by far the easiest approach.
import { WorldIDWidget } from '@worldcoin/id'
<WorldIDWidget
actionId="wid_BPZsRJANxct2cZxVRyh80SFG" // obtain this from developer.worldcoin.org
signal="my_signal"
enableTelemetry
onSuccess={(verificationResponse) => console.log(verificationResponse)} // pass the proof to the API or your smart contract
onError={(error) => console.error(error)}
debug={true} // to aid with debugging, remove in production
/>
Tip
A fully functional React example can be found .
Usage in Next.js apps
If your app is built on Next.js, you should use the React widget, but it's critical to disable SSR.
import { WidgetProps } from '@worldcoin/id'
const WorldIDWidget = dynamic<WidgetProps>(
() => import('@worldcoin/id').then((mod) => mod.WorldIDWidget),
{ ssr: false }
)
<WorldIDWidget
actionId="wid_BPZsRJANxct2cZxVRyh80SFG" // obtain this from developer.worldcoin.org
signal="my_signal"
enableTelemetry
onSuccess={(verificationResponse) => console.log(verificationResponse)}
onError={(error) => console.error(error)}
debug={true} // to aid with debugging, remove in production
/>
Tip
A fully functional Next.js example can be found .
Usage in vanilla JS apps
-
Add a
div
to mount World ID, and later initialize. You'll want to do this on the screen where the user executes the protected action (e.g. before they click "Claim airdrop" or "Create account").<div id="world-id-container"></div>
-
Initialize the widget.
import * as worldID from '@worldcoin/id' // If you installed the JS package as a module worldID.init('world-id-container', { debug: true, // to aid with debugging, remove in production enable_telemetry: true, action_id: 'wid_BPZsRJANxct2cZxVRyh80SFG', // obtain this from developer.worldcoin.org signal: 'your_signal', on_success: (proof) => console.log(proof), on_error: (error) => console.error(error), })
Note
The widget will remain disabled until you pass a non-empty signal.
Check out the for full details on how to use the JS package.
Info
The JS package is open source and accepts contributions! Head over to and submit a pull request.
Hosted version
To make it easier to use World ID, we have a hosted version of the frontend side of World ID (basically just mounting the World ID widget). This page can be particularly helpful for off-chain use cases as you can receive the World ID verification without needing to add the widget to your own page. The hosted World ID widget can be found at: https://id.worldcoin.org/use
.
The way it works is:
- You send the required parameters for the World ID verification and a return URL via query string.
- After the user completes the verification process, you receive the proof results via query string to the return URL you specified.
Input parameters
Here's an example of your request could look like. Remember to URL encode all parameters!
https://id.worldcoin.org/use?action_id=0x32D59776E91fdb3F377755e12cEC05d9067c2B4F&signal=0x0000000000000000000000000000000000000000&return_to=https%3A%2F%2Fmyapp.worldcoin.org
Parameter | Required | Description |
---|---|---|
return_to |
Yes | The URL to where the user will be redirected upon successful completion. All the response attributes will be included as query string parameters. Please make sure your URL:
|
action_id |
Yes | Unique identifier for the action being verified. Read more about the . |
signal |
Yes | Read more about the . You will usually want to use your user's wallet address as the signal if you're using a crypto app. |
app_name |
No | Highly recommended! The name of your app/project/company. This will be shown to the users in the WLD app, unless you have a . |
signal_description |
No | Highly recommended! The description of the specific action the user is verifying. This will be shown to the users in the WLD app, unless you have a . |
Response
The ZKP and related parameters which the World ID verification outputs will be sent to you via query string parameters to your return URL. The parameters that will be sent are the same which the World ID widget sends (). Below is an example of a response to the return URL https://myapp.worldcoin.org
https://myapp.worldcoin.org/?merkle_root=0x2a92313324532131530395d13b8a0e230149fa9bf8feb677ecea7749937083f6&nullifier_hash=0x2de0cf609355bb58ca267bc495a9603bd2e00ef2afda676b2927c4be533a5923&proof=0x2a2d8fdf047570e92dc37816849dadd87827e3b555828cdc84c2d42c8e4f6bb6102328fa1936b1ababde362faa03d23654a3b0187ba4f0fed55abd0d11cf1b8a0bdf6b8c683f8b610f93014e40aa245c1578f1e558db3ff99ec78f19c6493fb22dd14ae3b30cff03e5ccddf8f390739cb3e9dc7fd5a09115f26671b7d42dfd981e2c63484361883100b35c1f0b3f405bc4134284c2a7fdfb0b338e8554c5c7ca034a903497cea8e5c1e325ecd801e006be2de521112a39cbab6f389e3eecee37056d3e46bca9e704f8faaa52dba47c83e5cd7d4b9b6ca6b8d6fa03939bb0483c2065d6bd6502bea669daaee2ebf46d70170800a834e571661f87ef01512fabe0