> 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 authentication 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.

Migration from v9 or v10

Use the [Web SDK v11 migration guide](/embedded-wallets/migration-guides/web/). It includes an LLM agent prompt, a full v9/v10-to-v11 API map, and step-by-step changes for `@web3auth/modal/react`.

## 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
  },
}

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 { useConnection } from 'wagmi'

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

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

```

```
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,
  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), [@solana-program/system](https://www.npmjs.com/package/@solana-program/system), and [@solana/react-hooks](https://www.npmjs.com/package/@solana/react-hooks), then wrap your app with `SolanaProvider`:

main.tsx

```
import { SolanaProvider } from '@web3auth/modal/react/solana'

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

```

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)