JS Reference

Here you will find information about all the methods and parameters that the JS package exposes.

Methods

.init()

The .init() method is the main initialization method. It should be called to start the World ID package and render the World ID verification widget.

Render of World ID widget

Caution

The .init() method should only be called once in the lifecycle of your app. To update properties, please use .update() instead.

.init(elementNodeOrID, parameters) => void

Attribute	Description	Example
elementNodeOrID	HTML ID of the element on where to mount the World ID widget or HTML node of where to mount the element.	`world-id-container` `document.getElementsByClassName('world-id')[0]`
parameters	List of additional parameters. Please see for details. `action_id` is always required.	See below for example.

Example:

worldID.init(
  'world-id-container', // this can be the HTML ID of an element or any HTML node. Please be sure the node is mounted in your DOM before you call `.init()`
  {
    enable_telemetry: true,
    debug: true, // to aid with debugging, remove in production
    action_id: 'wid_lshSNnaJfdt6Sohu6YAA',
    signal: 'my-user-id-1',
    app_name: 'My App',
    signal_description: 'Receive a super cool airdrop!',
  }
)

.update()

The .update() method works similarly to .init() except it's used only to update the relevant parameters to run the World ID widget. The DOM element (elementNodeOrID) where World ID is mounted cannot be changed.

Tip

One common use case for .update() is if you want to render the World ID widget even if the user hasn't logged in to your dapp with their wallet. This will keep your UI consistent. Once the user logs in, you can use .update() to pass the wallet's address as signal.

.update(parameters?) => void

When calling .update() you only need to include the parameters you wish to update. No need to include all original init parameters again.

Example:

worldID.update({
  signal: 'my_new_signal',
})

.getProps()

Returns all the props for the widget.

.getProps() => WidgetProps

Example:

console.log(worldID.getProps().signal)

Parameters

The following parameters can be passed to both .init() and .update().

Parameter	Type	Required	Description
`action_id`	`string`	Yes	Unique identifier for the action being verified. This should be the action ID obtained from the . Read more about the .
`signal`	`string`	Not required, but widget won't be enabled until passed	Read more about the . For web3 dApps, you will usually want to use your user's wallet address.
`on_success`	`function`	Yes	Function to trigger when verification is successful. Sends a single parameter of type `VerificationResponse` which contains the proof details.
`on_error`	`function`	No	Triggered when verification fails and user did not retried. Sends a single parameter of type `VerificationErrorResponse` containing error details.
`enable_telemetry`	`boolean`	No	Whether telemetry is enabled. We send very few events, with no PII to help us improve the product. Read more in the section.
`theme`	`light` or `dark`	No	The theme to apply to the widget's UI.
`debug`	`boolean`	No	Will log verbose details to JS console to aid with debugging.
`on_init_success`	`function`	No	Triggered after the widget has been successfully initialized and mounted and all passed props are valid. Useful for debugging.
`on_init_error`	`function`	No	Triggered if widget could not be initialized, usually due to incorrect parameters. Sends a `string` containing the error description.
`disable_remote_fonts`	`boolean`	No	Disables loading remote fonts (from Google Fonts) for the widget and uses the system's font instead (e.g. Roboto, San Francisco).
`advanced_use_raw_signal`	`string`	No	Advanced! Use this to hash and encode your own signal. Read more on .
`advanced_use_raw_action_id`	`string`	No	Advanced! Use this to hash and encode your own Action ID. Read more on .
`app_name`	`string`	No	⚠️ Deprecated! Use Dev Portal instead. The name of your app/project/company (shown to users in Worldcoin app).
`signal_description`	`string`	No	⚠️ Deprecated! Use Dev Portal instead. The description of the specific action (shown to users in Worldcoin app).

Response

Upon successful completion of the World ID verification request, you will receive a response object in the respective Promise you subscribed to in the .init() method. The response object will contain the following attributes. Normally, you will pass all these parameters to the transaction to be executed on-chain with your smart contract.

Attribute	Type	Description
`merkle_root`	`string` (ABI-encoded)	This is the hash pointer to the root of the Merkle tree that proves membership of the user's identity in the list of identities verified by the Orb. Read more about the .
`nullifier_hash`	`string` (ABI-encoded)	The hash that proves uniqueness between a single person and an action. Read more about the .
`proof`	`string` (ABI-encoded)	The Zero-knowledge proof of the verification.