Skip to main content

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 here.

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 here.

Usage in vanilla JS apps

  1. 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>
  2. 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 JS Reference for full details on how to use the JS package.

info

The JS package is open source and accepts contributions! Head over to GitHub 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:

  1. You send the required parameters for the World ID verification and a return URL via query string.
  2. 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
ParameterRequiredDescription
return_toYesThe 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:
  • Does not contain any query string or hash parameters itself
  • Is served over HTTPs
  • Is from a domain the user can recognize and trust
  • Is URL encoded
action_idYesUnique identifier for the action being verified. Read more about the action ID.
signalYesRead more about the signal. You will usually want to use your user's wallet address as the signal if you're using a crypto app.
app_nameNoHighly recommended! The name of your app/project/company. This will be shown to the users in the WLD app, unless you have a Verified action.
signal_descriptionNoHighly 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 Verified action.

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 (docs here). 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