For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Embedded Wallets SDK for React

Overview​

MetaMask Embedded Wallets SDK (formerly Web3Auth Plug and Play) provides a seamless authentication experience for React applications with social logins, external wallets, and more. React hooks simplify how you connect users to their preferred wallets and manage authentication state.

For a complete working project, see the React quick start example on GitHub.

Requirements​

  • This is a frontend SDK and must be used in a browser environment.
  • Node.js 20+ and npm (or yarn).
  • Basic knowledge of JavaScript and React.

Prerequisites​

tip

See the dashboard setup guide to learn more.

Installation​

Install the Web3Auth Modal SDK and Wagmi dependencies:

npm install --save @web3auth/modal wagmi@3 @tanstack/react-query

1. Configuration​

Create a configuration file with your Client ID and Sapphire network from the Embedded Wallets dashboard.

Use Sapphire Devnet for local development (http://localhost). Sapphire Mainnet does not allow localhost origins.

web3authContext.tsx
import { type Web3AuthContextConfig } from '@web3auth/modal/react'
import { WEB3AUTH_NETWORK } from '@web3auth/modal'

const clientId = import.meta.env.VITE_WEB3AUTH_CLIENT_ID // or your env prefix

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId,
    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET, // use SAPPHIRE_MAINNET in production
    authBuildEnv: 'production',
  },
}

export default web3AuthContextConfig

2. Set up providers​

In your main entry file (main.tsx or index.tsx), wrap your app with Web3AuthProvider, QueryClientProvider, and the Embedded Wallets WagmiProvider:

main.tsx
import './index.css'

import ReactDOM from 'react-dom/client'
import { Web3AuthProvider } from '@web3auth/modal/react'
import { WagmiProvider } from '@web3auth/modal/react/wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import web3AuthContextConfig from './web3authContext'
import App from './App'

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <Web3AuthProvider config={web3AuthContextConfig}>
    <QueryClientProvider client={queryClient}>
      <WagmiProvider>
        <App />
      </WagmiProvider>
    </QueryClientProvider>
  </Web3AuthProvider>
)

3. Connect users​

Use useWeb3AuthConnect to open the pre-built modal or connect to a specific login method:

App.tsx
import { useWeb3AuthConnect, useWeb3AuthDisconnect } from '@web3auth/modal/react'
import { useAccount } from 'wagmi'

function App() {
  const { connect, loading, isConnected, error } = useWeb3AuthConnect()
  const { disconnect } = useWeb3AuthDisconnect()
  const { address } = useAccount()

  if (!isConnected) {
    return (
      <button onClick={() => connect()} disabled={loading}>
        {loading ? 'Connecting...' : 'Login'}
      </button>
    )
  }

  return (
    <div>
      <p>{address}</p>
      <button onClick={() => disconnect()}>Log out</button>
    </div>
  )
}

Advanced configuration​

The Web3Auth Modal SDK offers a rich set of advanced configuration options:

tip

See the advanced configuration section to learn more about each configuration option.

import { type Web3AuthContextConfig } from '@web3auth/modal/react'
import { WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId: import.meta.env.VITE_WEB3AUTH_CLIENT_ID,
    web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET,
    authBuildEnv: 'production',
  },
}

Blockchain integration​

Web3Auth is blockchain agnostic, enabling integration with any blockchain network. Out of the box, Web3Auth offers robust support for both Solana and Ethereum, each with dedicated React hooks.

Solana integration​

Solana hooks are included natively within the @web3auth/modal package. Install @solana/kit and use hooks from @web3auth/modal/react/solana.

For detailed usage and examples, see the Solana hooks section.

Ethereum integration​

Ethereum wallet operations use Wagmi hooks after the provider setup above. Configure EVM chains in the Embedded Wallets dashboard; no in-app chain list is required for standard integrations.

For implementation details and examples, refer to the Ethereum hooks section.

Troubleshooting​

JWT errors​

When using custom authentication, you may encounter JWT errors:

On this page