JS Widget

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
Render of World ID widget

Caution

.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

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