Skip to main content

Initializing PnP Web Modal SDK

After Installation, the next step to use Web3Auth is to Initialize the SDK. However, the Initialization is a two-step process, with an additional two steps for customizations, i.e.

Please note that these are the most critical steps where you need to pass on different parameters according to the preference of your project. Additionally, If you wish to customize your Web3Auth Instance, Whitelabeling and Custom Authentication have to be configured within this step.

Instantiating Web3Auth​

Import the Web3Auth class from @web3auth/modal​

import { Web3Auth } from "@web3auth/modal";

Assign the Web3Auth class to a variable​

const web3auth = new Web3Auth(Web3AuthOptions);

This Web3Auth constructor takes an object with Web3AuthOptions as input.

Arguments​

Web3AuthOptions​

ParameterTypeDescriptionMandatoryDefault
chainConfigPartial <CustomChainConfig> & Pick <CustomChainConfig, "chainNamespace">Custom configuration for your preferred blockchain. Read more about it here.Yes
clientIdstringClient ID for web3auth. Obtain your clientId from the Web3Auth Developer Dashboard.Yes
web3AuthNetwork?OPENLOGIN_NETWORK_TYPEWeb3Auth Network to use for the session & the issued idTokenNomainnet
authMode?enum - (DAPP, WALLET)Web3Auth instance provides different adapters for different type of usages. If you are a dApp and want to use external wallets like metamask, then you can use the DAPP authMode. If you are a wallet and only want to use you own wallet implementations, then you should use WALLET authMode.NoDAPP
uiConfig?UIConfigConfiguration for whitelabeling the Modal UI display properties. Read more about it hereNoPredefined UIConfig used
enableLogging?booleanSetting to true will enable logsNofalse
storageKey?enum - (session, local)Setting to "local" will persist social login session across browser tabs.Nolocal
sessionTime?numbersessionTime (in seconds) for idToken issued by Web3Auth for server side verification. Note: max value can be 7 days (86400 * 7) and min can be 1 day (86400)No86400
useCoreKitKey?booleanUse useCoreKitKey as true, if you're using this SDK with the Single Factor Auth Web SDKNofalse

Adding a Custom Chain Configuration​

chainConfig​

ParameterTypeDescriptionOptional
chainNamespace
  • string - (Choose between eip155, solana & other)
    • or
  • ChainNamespaceType - (Choose between CHAIN_NAMESPACES.EIP155, CHAIN_NAMESPACES.SOLANA & CHAIN_NAMESPACES.OTHER)
The namespace of your preferred chain. Checkout Providers SDK Reference for understanding RPC Calls.No
chainIdstringThe chain id of the selected blockchain in hexNo
rpcTargetstring
  • RPC Target URL for the selected chainNamespace & chainId.
  • We provide a default RPC Target for certain blockchains, but due to congestion it might be slow hence it is recommended to provide your own RPC Target URL.
No
wsTargetstringWeb socket target URL for the chainYes
displayNamestringDisplay Name for the chainNo
blockExplorerstringBlockchain's explorer URL. (eg: https://etherscan.io)No
tickerstringDefault currency ticker of the network (e.g: ETH)No
tickerNamestringName for currency ticker (e.g: Ethereum)No
decimalsnumberNumber of decimals for the currency ticker (e.g: 18)Yes

Whitelabeling​

Within the uiConfig parameter, you can configure the Web3Auth Modal according to your application's requirements.

tip

This is just one of the aspects of whitelabeling you can achieve with Web3Auth. To know more in-depth about how you can Whitelabel your application with Web3Auth Plug and Play Modal SDK, have a look at our Whitelabeling SDK Reference.

uiConfig​

ParameterTypeDescriptionMandatoryDefault
loginMethodsOrder?string[]The list of login methods can be reordered with this parameter. Those methods specified will be first on the list.No["google", "facebook", "twitter", "reddit", "discord", "twitch", "apple", "line", "github", "kakao", "linkedin", "weibo", "wechat", "email_passwordless"]
modalZIndex?stringZ-index of the modal and iframeNo"99998"
displayErrorsOnModal?booleanWhether to show errors on Web3Auth modal.Notrue
loginGridCol?2 or 3Number of columns to display the Social Login buttons.No3
primaryButton?enum - (externalLogin, socialLogin or emailLogin)Decides which button will be displayed as primary button in modal. Only one button will be primary and other buttons in modal will be secondary.NosocialLogin

WhiteLabelData​

whiteLabel?: WhiteLabelData;​

The whitelabel parameter takes WhitelabelData as input. The WhitelabelData object takes the following parameters:

WhiteLabelData

ParameterTypeDescriptionDefaultMandatory
appName?stringApp name to be displayed in the User Flow Screens.dApp's Website URLNo
appUrl?stringApp URL to be displayed in the User Flow Screens.dApp's Website URLNo
logoLight?stringApp logo to be shown on the dark background (dark theme)web3auth-logo.svgNo
logoDark?stringApp logo to be shown on the light background (light theme)web3auth-logo.svgNo
defaultLanguage?stringDefault Language to use.
Choose from:
  • en - English
  • de - German
  • ja - Japanese
  • ko - Korean
  • zh - Mandarin
  • es - Spanish
  • fr - French
  • pt - Portuguese
  • nl - Dutch
en - EnglishNo
mode?stringChoose between auto, light or dark modes.autoNo
theme?{ [P in string]: string; }Used to customize the theme of the login modal with the following options
'primary' - To customize the primary color of the modal's content		#0364FFNo
tncLink?Partial<Record<LANGUAGE_TYPE, string>>Language specific link for terms and conditions on torus-website. See (examples/vue-app) to configure e.g. tncLink: {en: "http://example.com/tnc/en", ja: "http://example.com/tnc/ja"}noneNo
privacyPolicy?Partial<Record<LANGUAGE_TYPE, string>>Language specific link for privacy policy on torus-website. See (examples/vue-app) to configure e.g. privacyPolicy: { en: "http://example.com/tnc/en", ja: "http://example.com/tnc/ja", }noneNo

Returns​

  • Object: The web3auth instance with all its methods and events.

Example​

const web3auth = new Web3Auth({
  clientId: "", // Get your Client ID from the Web3Auth Dashboard
  web3AuthNetwork: "sapphire_mainnet",
  chainConfig: {
    chainNamespace: CHAIN_NAMESPACES.EIP155,
    chainId: "0x1",
    rpcTarget: "https://rpc.ankr.com/eth", // This is the mainnet RPC we have added, please pass on your own endpoint while creating an app
  },
  uiConfig: {
    theme: "dark",
    loginMethodsOrder: ["facebook", "google"],
    appLogo: "https://web3auth.io/images/w3a-L-Favicon-1.svg", // Your App Logo Here
  },
  defaultLanguage: "en",
  modalZIndex: "99998",
});

Configuring Adapters​

An adapter is a pluggable package that implements IAdapter interface for a wallet within Web3Auth. An adapter can be plugged in and out of web3auth modal. Each adapter exposes the provider on successful user login which can be used to invoke RPC calls on the wallet and on the connected blockchain. Web3Auth's modal UI supports a set of default adapters depending on the authMode being used.

info

This step is generally optional. You don't have to configure any default adapter unless you want to override default configs for the adapter.

Only those adapters that are marked are nondefault in this table on the Adapters Documentation are required to be configured always based on the authMode you are using.

Configuring Openlogin Adapter​

The default adapter of Web3Auth is the openlogin-adapter. This adapter is a wrapper around the openlogin library from Web3Auth and enables the social login features. For customising features of the main Web3Auth flow, like Whitelabel, Custom Authentication, etc. you need to customise the Openlogin Adapter.

tip

Checkout the openlogin-adapter SDK Reference for more details on different configurations you can pass for customisations.

Whitelabeling​

whiteLabel​

For customising the redirect screens while logging in and constructing the key, you need to pass on whiteLabel configurations to the adapterSettings property of the openlogin-adapter.

tip

This is just one of the aspects of whitelabeling you can achieve with Web3Auth. To know more in depth about how you can Whitelabel your application with Web3Auth, have a look at our Whitelabeling SDK Reference.

Example​
import OpenloginAdapter from "@web3auth/openlogin-adapter";

const openloginAdapter = new OpenloginAdapter({
  adapterSettings: {
    clientId, //Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    network: "sapphire_mainnet", // Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    uxMode: "popup",
    whiteLabel: {
      appName: "W3A Heroes",
      appUrl: "https://web3auth.io",
      logoLight: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoDark: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
      defaultLanguage: "en", // en, de, ja, ko, zh, es, fr, pt, nl
      mode: "dark", // whether to enable dark mode. defaultValue: auto
      theme: {
        primary: "#00D1B2",
      },
      useLogoLoader: true,
    },
  },
  privateKeyProvider,
});
web3auth.configureAdapter(openloginAdapter);

Custom Authentication​

loginConfig​

With Web3Auth, you have the option to configure logins using your own authentication services. For adding your own authentication, you have to first configure your verifiers in the Web3Auth Dashboard. Have a look at our Custom Authentication Documentation for configuring that first.

Custom Authentication in Web3Auth is supported by the Openlogin Adapter, which is the default adapter for the Web3Auth SDK. For this, you need to configure the loginConfig parameter in the adapterSettings of the openlogin-adapter package.

tip

Refer to the Custom Authentication Documentation for more information.

Example​

Since we're using the @web3auth/modal, ie. the Plug and Play Modal SDK, the loginConfig should correspond to the socials mentioned in the modal. Here, we're customizing Google and Facebook to be custom verified, rest all other socials will be default. You can customize other social logins or remove them using the whitelabeling option.

import OpenloginAdapter from "@web3auth/openlogin-adapter";

const openloginAdapter = new OpenloginAdapter({
  adapterSettings: {
    clientId, //Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    uxMode: "popup",
    loginConfig: {
      // Google login
      google: {
        verifier: "YOUR_GOOGLE_VERIFIER_NAME", // Please create a verifier on the developer dashboard and pass the name here
        typeOfLogin: "google", // Pass on the login provider of the verifier you've created
        clientId: "GOOGLE_CLIENT_ID.apps.googleusercontent.com", // Pass on the clientId of the login provider here - Please note this differs from the Web3Auth ClientID. This is the JWT Client ID
      },
    },
  },
  privateKeyProvider,
});
web3auth.configureAdapter(openloginAdapter);

Configuring External Wallet Adapters​

configureAdapter(ADAPTER)​

To configure an adapter, create the instance of adapter by using its corresponding package and pass the returned adapter instance in configureAdapter function.

tip

Refer to the Adapters documentation to know more deeply about what adapters are available and how to configure them.

Example​

If you want to configure the Torus EVM Wallet Adapter

  • Import the TorusWalletAdapter from @web3auth/torus-evm-adapter package
  • Create an instance of the adapter along with the configuration
  • Pass the returned instance in to web3auth.configureAdapter
import { TorusWalletAdapter } from "@web3auth/torus-evm-adapter";

const torusAdapter = new TorusWalletAdapter({
  adapterSettings: {
    clientId, //Optional - Provide only if you haven't provided it in the Web3Auth Instantiation Code
    buttonPosition: "bottom-left",
  },
  loginSettings: {
    verifier: "google",
  },
  initParams: {
    buildEnv: "testing",
  },
  chainConfig: {
    chainNamespace: CHAIN_NAMESPACES.EIP155,
    chainId: "0x1",
    rpcTarget: "https://rpc.ankr.com/eth", // This is the mainnet RPC we have added, please pass on your own endpoint while creating an app
    displayName: "Ethereum Mainnet",
    blockExplorer: "https://etherscan.io/",
    ticker: "ETH",
    tickerName: "Ethereum",
  },
});

web3auth.configureAdapter(torusAdapter);

Subscribing the Lifecycle Events​

Subscribing to events help you trigger responses based on the status of the connection of the user. An adapter emits certain events like CONNECTED, CONNECTING and DISCONNECTED etc during login lifecycle of a user. For example, you can use this to show an error message, if the user is not connected to the network. Generally, this is not a required step and should be done only if needed in particular cases.

info

This step is totally optional. If you don't want to use any plugins, feel free to skip this section.

tip

If you're using the uxMode: "redirect" option within your openlogin-adapter configuration, you need to subscribe to the event to handle the logging in implicitly. This is because, when redirected to a different application, the app state is not updated as per the login status. Using a lifecycle method to check this, one can easily handle the login status within the constructor function.

on(EVENT, CALLBACK)​

Web3Auth provides the following lifecycle event to check the login status:

Adapter Events​

EventTrigger with @web3auth/base packageTrigger without packageDescription
ADAPTER_DATA_UPDATEDADAPTER_EVENTS.ADAPTER_DATA_UPDATED"adapter_data_updated"Adapter data is updated within the dApp
NOT_READYADAPTER_EVENTS.NOT_READY"not_ready"Adapter is not yet ready for login
READYADAPTER_EVENTS.READY"ready"Adapter is ready for login
CONNECTINGADAPTER_EVENTS.CONNECTING"connecting"User is connecting to the dApp/ login process is in progress
CONNECTEDADAPTER_EVENTS.CONNECTED"connected"User is logged in and connected with the dApp
DISCONNECTEDADAPTER_EVENTS.DISCONNECTED"disconnected"User is logged out and disconnected from the dApp
ERROREDADAPTER_EVENTS.ERRORED"errored"There has been some error in connecting the user to the dApp
Example​
import { ADAPTER_EVENTS } from "@web3auth/base";

// subscribe to lifecycle events emitted by web3auth
const subscribeAuthEvents = (web3auth: Web3Auth) => {
  web3auth.on(ADAPTER_EVENTS.CONNECTED, (data: CONNECTED_EVENT_DATA) => {
    console.log("connected to wallet", data);
    // web3auth.provider will be available here after user is connected
  });
  web3auth.on(ADAPTER_EVENTS.CONNECTING, () => {
    console.log("connecting");
  });
  web3auth.on(ADAPTER_EVENTS.DISCONNECTED, () => {
    console.log("disconnected");
  });
  web3auth.on(ADAPTER_EVENTS.ERRORED, (error) => {
    console.log("error", error);
  });
  web3auth.on(ADAPTER_EVENTS.ERRORED, (error) => {
    console.log("error", error);
  });
};

Login Modal Events​

EventTrigger with @web3auth/ui packageTrigger without packageDescription
INIT_EXTERNAL_WALLETSLOGIN_MODAL_EVENTS.INIT_EXTERNAL_WALLETS"INIT_EXTERNAL_WALLETS"External Wallet are initialised
LOGINLOGIN_MODAL_EVENTS.LOGIN"LOGIN"Login is triggered
DISCONNECTLOGIN_MODAL_EVENTS.DISCONNECT"DISCONNECT"Disconnection is triggered
MODAL_VISIBILITYLOGIN_MODAL_EVENTS.MODAL_VISIBILITY"MODAL_VISIBILITY"Indicates whether the modal is visible or not
Example​
import { LOGIN_MODAL_EVENTS } from "@web3auth/ui";

// subscribe to lifecycle events emitted by web3auth
const subscribeAuthEvents = (web3auth: Web3Auth) => {
  // emitted when modal visibility changes.
  web3auth.on(LOGIN_MODAL_EVENTS.MODAL_VISIBILITY, (isVisible) => {
    console.log("is modal visible", isVisible);
  });
};

Configuring Plugins​

Plugins are essentially extensions to the core functionality of Web3Auth, allowing you to add additional features to your dApp. These features can be used to extend the UI functionalities, making your integration more interoperable, and a lot more, even having the functionality to be customised extremely and to your liking.

info

This step is totally optional. If you don't want to use any plugins, feel free to skip this section.

Currently Web3Auth supports the following two plugins:

tip

Learn about adding plugins to your Web3Auth instance here.

showWalletConnectScanner()​

Shows the Wallet Connect Scanner to connect with dApps having Wallet Connect login option.

Example​

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
  torusWalletOpts: {},
  walletInitOptions: {
    whiteLabel: {
      theme: { isDark: true, colors: { primary: "#00a8ff" } },
      logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
    },
    useWalletConnect: true, // make sure this is enabled before using the showWalletConnectScanner function
    enableLogging: true,
  },
});

await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance

await torusPlugin.showWalletConnectScanner();

initiateTopup()​

Initiates the Top Up flow with selected provider.

Arguments​

ParameterTypeDescriptionMandatory
providerPAYMENT_PROVIDER_TYPE ["moonpay", "wyre", "rampnetwork", "xanpool", "mercuryo", "transak", "banxa"]Payment Provider nameYes
paramsPaymentParamsPayment Params objectYes

PaymentParams​

ParameterTypeDescriptionMandatory
selectedAddress?stringAddress to send the funds toNo
selectedCurrency?stringDefault fiat currency for the user to make the payment inNo
fiatValue?numberAmount to buy in the selectedCurrencyNo
selectedCryptoCurrency?stringCryptocurrency to buyNo
chainNetwork?SUPPORTED_PAYMENT_NETWORK_TYPE ["mainnet", "matic", "bsc_mainnet", "avalanche_mainnet", "xdai"]Chain Network to useNo

Example​

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
  torusWalletOpts: {},
  walletInitOptions: {
    whiteLabel: {
      theme: { isDark: true, colors: { primary: "#00a8ff" } },
      logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
      logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
    },
    useWalletConnect: true,
    enableLogging: true,
  },
});

await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance

await torusPlugin.initiateTopup("moonpay", {
  selectedAddress: "wallet_address",
  selectedCurrency: "USD", // Fiat currency
  fiatValue: 100, // Fiat Value
  selectedCryptoCurrency: "ETH", // Cryptocurreny `SOL`, `MATIC` etc.
  chainNetwork: "mainnet", // Blockchain network
});

Initializing Modal​

initModal()​

The final step in the whole initialization process is the initialize the Modal from Web3Auth.

This is done by calling initModal function of the web3auth instance we created above.

await web3auth.initModal(params);

Arguments​

The web3auth.initModal takes an optional params config object as input.

params?: {
  modalConfig?: Record<WALLET_ADAPTER_TYPE, ModalConfig>;
}

This params object further takes a modalConfig object using which you can configure the visibility of each adapter within the modal. Each modal config has the following configurations:

modalConfig​

modalConfig: { ADAPTER : { params } }

ParameterTypeDescriptionDefaultMandatory
labelstringLabel of the adapter you want to configureNA - identifier for corresponding adapterYes
showOnModal?booleanWhether to show an adapter in modal or not.trueNo
showOnDesktop?booleanWhether to show an adapter in desktop or not.trueNo
showOnMobile?booleanWhether to show an adapter in mobile or not.trueNo

Additionally, to configure the Openlogin Adapter's each login method, we have the loginMethods? parameter.

ParameterTypeDescriptionDefaultMandatory
loginMethods?LoginMethodConfigTo configure visibility of each social login method for the openlogin adapter.Default LoginMethod for each social loginNo

loginMethods: { label: { params } }

In loginMethods, you can configure the visibility of each social login method for the openlogin adapter. The social login is corresponded by the label parameter. Below is the table indicating the different params available for customization.

For labels you can choose between these options: google, facebook, twitter, reddit, discord, twitch, apple, line, github, kakao, linkedin, weibo, wechat, email_passwordless

params

ParameterTypeDescriptionDefaultMandatory
namestringDisplay NameDefault for Openlogin AppNo
description?stringDescription for button. If provided, it renders as a full length button. else, icon buttonJust an icon renderedNo
logoHover?stringLogo to be shown on mouse hoverweb3auth-logo.svgNo
logoLight?stringLogo to be shown on dark background (dark theme)web3auth-logo.svgNo
logoDark?stringLogo to be shown on light background (light theme)web3auth-logo.svgNo
mainOption?booleanShow login button on the main listDefault for Openlogin AppNo
showOnModal?stringWhether to show the login button on modal or notDefault for Openlogin AppNo
showOnDesktop?stringWhether to show the login button on desktopDefault for Openlogin AppNo
showOnMobile?stringWhether to show the login button on mobileDefault for Openlogin AppNo

Example​

await web3auth.initModal({
  modalConfig: {
    [WALLET_ADAPTERS.OPENLOGIN]: {
      label: "openlogin",
      loginMethods: {
        google: {
          name: "google login",
          logoDark: "url to your custom logo which will shown in dark mode",
        },
        facebook: {
          // it will hide the facebook option from the Web3Auth modal.
          name: "facebook login",
          showOnModal: false,
        },
      },
      // setting it to false will hide all social login methods from modal.
      showOnModal: true,
    },
  },
});