Skip to main content

Whitelabel Plug n Play Modal

Web3Auth is fully whitelabel with application branding to have a consistent user experience. For Whitelabeling, there are three different aspects available for you. Web3Auth gives you the ability to define a custom UI, branding, and translations for your applications. All our SDKs support Whitelabeling, giving granular customization capability across all our offerings.

Within the Web3Auth Plug and Play Modal SDK, whitelabeling can happen in 3 different places,

  • Web3Auth Modal: You can whitelabel the Web3Auth Modal according to your needs, for this, you need to pass on the following parameters:
    • Within the uiConfig parameter while instantiating Web3Auth, you can configure the Web3Auth Modal according to your application's requirements.
    • Change the visibility and order of methods appearing in Web3Auth modal by passing the modalConfig in initModal function, while initializing the SDK.
  • Openlogin Adapter: The redirect screens while logging in and constructing the key, can be customised according to your common as well. For this, you need to pass on the whiteLabel configuration parameter to the openlogin-adapter.
  • Torus Wallet Plugin: The Torus Wallet Plugin can be customized according to your needs for helping you make wallet flows within your application. For this, you need to pass on the torusWalletOpts configuration.

Web3Auth Modal

Whitelabeling while Web3Auth Instantiation

tip

Read more about Instantiating Web3Auth in the Initialization SDK Reference

While instantiating Web3Auth, the constructor takes an object with Web3AuthOptions as input. The Web3AuthOptions object is further taken in the parameter of uiConfig which is the configuration for whitelabeling the Modal UI display properties.

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

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",
});

Whitelabeling while Modal Initialization

tip

Read more about Initializing Web3Auth Modal in the Initialization SDK Reference

While initializing the Web3Auth Modal, the initModal() function takes an object with modalConfig as input. This object helps you configure the different adapters available in the Web3Auth Modal. Further, the modalConfig object takes the parameter of loginMethods which helps you configure the social logins and their visibility in the modal.

initModal()

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,
},
},
});

Openlogin Adapter

Web3Auth's Social Logins and Email Login run using the OpenLogin Flow. The whole OpenLogin user experience can also be whitelabeled using OpenLogin Adapter settings. For this, you need to pass on the whiteLabel configuration parameter to the adapterSettings property of the openlogin-adapter.

tip

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

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

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);

Torus Wallet Plugin

The Torus Wallet Plugins help you get the functionalities of the Torus Wallets into your Web3Auth Instance. They help you get the UI of the Torus Wallet Embedded Interface into your dApp, giving your user an overview of their wallet.

tip

Read more about Initializing the Torus EVM Wallet Plugin in the Torus Wallet Connector Plugin SDK Reference

While initializing the plugin, you need to pass on the following parameters to the constructor:

ParameterTypeDescriptionMandatory
torusWalletOpts?TorusCtorArgsConfiguration options for Torus WalletNo
walletInitOptionsPartial<TorusParams> & Required<Pick<TorusParams, "whiteLabel">>Parameters to customise your Torus Wallet Embed UI within the applicationYes

torusWalletOpts

torusWalletOpts is an optional parameter that allows you to pass in the configuration options for Torus Wallet. It takes the TorusCtorArgs object as input which contains the following parameters:

TorusCtorArgs

ParameterTypeDescriptionDefault ValueMandatory
buttonPosition?enum - (bottom-left, top-left, bottom-right, top-right)Determines where the torus widget is visible on the page.bottom-leftNo
modalZIndex?numberZ-index of the modal and iframe99999No
buttonSizenumberSize of the widget button56No
apiKey?stringTorus Wallet API Key - Get it from Web3Auth DashboardNo

walletInitOptions

The walletInitOptions from Torus Wallet is a required parameter that allows you to customise your Torus Wallet Embed Modal UI within the application. It takes the objet TorusParams as input which contains multiple parameters mentioned in the Torus Wallet Documentation.

Out of those mentioned parameters, the following 3 parameters are important for whitelabeling the plugin:

TorusParams

ParameterTypeMandatoryDescriptionDefault
whiteLabelWhiteLabelParamsYesParams to enable whitelabelling of torus website and widget. Know more about whitelabeling options for Torus Wallet here.N/A
showTorusButtonbooleanNoDetermines whether to show/hide torus widget.true
useWalletConnectbooleanNoSetting useWalletConnect to true allows to display wallet connect qr scanner from torus-embed.false

While initializing the plugin, you need to pass on the following parameters to the constructor:

whiteLabel

As you can see, the whiteLabel parameter is a required parameter within the plugin. This is because this plugin needs you to incorporate basic whitelabel to avoid showing the Torus Wallet branding on your website.

The whiteLabel parameter takes WhiteLabelParams object as input which contains the following parameters:

ParameterTypeMandatoryDescriptionDefault
themeThemeParams
(contains two params, isDark: boolean &
colors: Record<string, string>)
YesParams to customise the theme for the wallet embed. You can enable darkMode and use the colours of your choice for the modal.N/A
logoDarkstringYesLogo to be shown on dark background (dark theme)N/A
logoLightstringYesLogo to be shown on light background (light theme)N/A
defaultLanguage?stringNoLanguage of whitelabelOrder of preference: Whitelabel language > user language (in torus-website) > browser language
topupHide?booleanNoShows/hides topup option in torus-website/widget.false
featuredBillboardHide?booleanNoShows/hides billboard in torus-website.false
disclaimerHide?booleanNoShows/hides disclaimers on login page. Only works if special logins are hiddenfalse
tncLink?stringNoLanguage specific link for terms and conditions on torus-website.
Choose between:
  • en - English
  • de - German
  • ja - Japanese
  • ko - Korean
  • zh - Mandarin
  • es - Spanish
  • fr - French
  • pt - Portuguese
  • nl - Dutch
en - English
privacyPolicy?stringNoLanguage specific link for privacy policy on torus-website.en - English
contactLink?stringNoLanguage specific link for contact links on torus-website.en - English
customTranslations?stringNoCustom translations.en - English

Example

In this example we're adding the TorusWalletConnectorPlugin with a very basic configuration.

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);