Skip to main content

Web3Auth v10 whitelabeling migration guide

This guide focuses specifically on migrating whitelabeling and UI customization configurations from Web3Auth v8 to v10. This is a supplementary guide to the main v8 to v10 migration guide.

Overview​

Whitelabeling and UI customization have been significantly streamlined in v10, focusing on dashboard configurations and a more direct approach to modal customization.

Migration steps​

1. Branding (v8 uiConfig): Moves to dashboard​

  • Most general branding settings previously in the client-side uiConfig (for example, appName, logoLight, logoDark, theme colors) are now primarily configured on the Embedded Wallets dashboard. Branding customizations on Web3Auth Dashboard/Embedded Wallets dashboard
  • Action: Transfer v8 uiConfig branding to the dashboard. Client-side uiConfig in v10 Web3AuthOptions is minimal, for overrides not covered by the dashboard.

2. Modal login method display (v8 modalConfig in initModal()): New structure in Web3AuthOptions​

  • Previously (v8): Customizing which login methods appear in the modal (and their appearance/order) was done via modalConfig in initModal() in v8.
  • Now (v10): This moves to modalConfig within Web3AuthOptions (at SDK instantiation). The structure is new, utilizing connectors (for example, WALLET_CONNECTORS.AUTH for social/email, WALLET_CONNECTORS.WALLET for external wallets) and a loginMethods object within each connector.
  • Each login method (for example, google, email_passwordless, metamask) is an object conforming to LoginMethodConfig, allowing you to set name, showOnModal, `authConnectionId (for custom auth), for example. 
    // v10: modalConfig in Web3AuthOptions
    const web3AuthOptions: Web3AuthOptions = {
      // ... other options
      modalConfig: {
        connectors: {
          [WALLET_CONNECTORS.AUTH]: {
            /* ... config for social/email ... */
          },
          [WALLET_CONNECTORS.WALLET]: {
            /* ... config for external wallets ... */
          },
        },
      },
    }
  • Action: Rebuild your modal display logic using the new modalConfig structure in Web3AuthOptions. Refer to the v10 LoginMethodConfig type definition for all properties. Deprecated v8 WALLET_ADAPTERS enum is replaced by WALLET_CONNECTORS and specific login method keys.

3. Auth adapter whitelabeling in v8: no longer supported​

  • In v8, whiteLabel settings in an @web3auth/openlogin-adapter instance could customize intermediate auth screens (for example, social login pop-ups).
  • In v10, passing this whiteLabel configuration is no longer supported since there is no way to configure auth adapter settings.
  • Action: Remove v8 OpenloginAdapter whiteLabel configurations. Ensure your dashboard branding is comprehensive.

Summary​

This shift centralizes UI control on the dashboard and simplifies client-side SDK configuration for whitelabeling. The new approach provides better consistency across applications and easier maintenance of branding configurations.

Next steps​

Return to the main v8 to v10 migration guide to continue with other migration aspects like Smart Account functionality, custom authentication, and MFA configurations.

On this page