> For the complete documentation index, see [llms.txt](/llms.txt).

# Embedded Wallets SDK for React

## Overview[​](#overview "Direct link to 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](https://github.com/Web3Auth/web3auth-examples/tree/main/quick-starts/react-quick-start)on GitHub.

## Requirements[​](#requirements "Direct link to Requirements")

- This is a frontend SDK and must be used in a browser environment
- Node.js 22+ and npm 10+
- Basic knowledge of JavaScript and React

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- Set up your project on the [Embedded Wallets dashboard](https://developer.metamask.io/)

tip

See the [dashboard setup](/embedded-wallets/dashboard/) guide to learn more.

## Installation[​](#installation "Direct link to Installation")

Install the Web3Auth Modal SDK and Wagmi dependencies:

- npm
- Yarn
- pnpm
- Bun

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

```

```
yarn add @web3auth/modal wagmi@3 @tanstack/react-query

```

```
pnpm add @web3auth/modal wagmi@3 @tanstack/react-query

```

```
bun add @web3auth/modal wagmi@3 @tanstack/react-query

```

### 1. Configuration[​](#1-configuration "Direct link to 1. Configuration")

Create a configuration file with your Client ID and Sapphire network from the [Embedded Wallets dashboard](https://developer.metamask.io/).

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[​](#2-set-up-providers "Direct link to 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[​](#3-connect-users "Direct link to 3. Connect users")

Use [useWeb3AuthConnect](/embedded-wallets/sdk/react/hooks/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[​](#advanced-configuration "Direct link to Advanced configuration")

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

- **[Smart accounts](/embedded-wallets/sdk/react/advanced/smart-accounts/):** Configure account abstraction parameters.
- **[Custom authentication](/embedded-wallets/sdk/react/advanced/custom-authentication/):** Define authentication methods.
- **[Whitelabeling and UI customization](/embedded-wallets/sdk/react/advanced/whitelabel/):** Personalize the modal's appearance.
- **[Multi-Factor Authentication (MFA)](/embedded-wallets/sdk/react/advanced/mfa/):** Set up and manage MFA.
- **[Wallet Services](/embedded-wallets/sdk/react/advanced/wallet-services/):** Integrate additional Wallet Services.

tip

See the [advanced configuration](/embedded-wallets/sdk/react/advanced/) section to learn more about each configuration option.

- Basic Configuration
- Advanced Configuration

```
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',
  },
}

```

```
import { type Web3AuthContextConfig } from '@web3auth/modal/react'
import {
  WALLET_CONNECTORS,
  WEB3AUTH_NETWORK,
  MFA_LEVELS,
  type Web3AuthOptions,
} from '@web3auth/modal'

const web3AuthOptions: Web3AuthOptions = {
  clientId: import.meta.env.VITE_WEB3AUTH_CLIENT_ID,
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  authBuildEnv: 'production',
  modalConfig: {
    connectors: {
      [WALLET_CONNECTORS.AUTH]: {
        label: 'auth',
        loginMethods: {
          google: {
            name: 'google login',
            // logoDark: "url to your custom logo which will shown in dark mode",
          },
          facebook: {
            name: 'facebook login',
            showOnModal: false, // hides the facebook option
          },
          email_passwordless: {
            name: 'email passwordless login',
            showOnModal: true,
            authConnectionId: 'w3a-email_passwordless-demo',
          },
          sms_passwordless: {
            name: 'sms passwordless login',
            showOnModal: true,
            authConnectionId: 'w3a-sms_passwordless-demo',
          },
        },
        showOnModal: true, // set to false to hide all social login methods
      },
    },
    hideWalletDiscovery: true, // set to true to hide external wallets discovery
  },
  mfaLevel: MFA_LEVELS.MANDATORY,
}

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions,
}

```

## Blockchain integration[​](#blockchain-integration "Direct link to 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-integration "Direct link to Solana integration")

Solana hooks are included natively within the `@web3auth/modal` package. Install [@solana/kit](https://www.npmjs.com/package/@solana/kit) and use hooks from `@web3auth/modal/react/solana`.

For detailed usage and examples, see the [**Solana hooks**](/embedded-wallets/sdk/react/solana-hooks/) section.

### Ethereum integration[​](#ethereum-integration "Direct link to Ethereum integration")

Ethereum wallet operations use [Wagmi](https://wagmi.sh/) hooks after the provider setup above. Configure EVM chains in the [Embedded Wallets dashboard](/embedded-wallets/dashboard/chains-and-networks/); no in-app chain list is required for standard integrations.

For implementation details and examples, refer to the [**Ethereum hooks**](/embedded-wallets/sdk/react/ethereum-hooks/) section.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### JWT errors[​](#jwt-errors "Direct link to JWT errors")

When using custom authentication, you may encounter JWT errors:

- [**Invalid JWT verifiers ID field**](/embedded-wallets/troubleshooting/jwt-errors/#invalid-jwt-verifiers-id-field)
- [**Failed to verify JWS signature**](/embedded-wallets/troubleshooting/jwt-errors/#failed-to-verify-jws-signature)
- [**Duplicate token**](/embedded-wallets/troubleshooting/jwt-errors/#duplicate-token)
- [**Expired token**](/embedded-wallets/troubleshooting/jwt-errors/#expired-token)
- [**Mismatch JWT validation field**](/embedded-wallets/troubleshooting/jwt-errors/#mismatch-jwt-validation-field)