Use MetaMask SDK with React

Import MetaMask SDK into your React dapp to enable your users to easily connect to the MetaMask browser extension and MetaMask Mobile. The SDK for React has the same prerequisites as for standard JavaScript.

MetaMask SDK + Wagmi

This page provides instructions for using the standard @metamask/sdk-react package. Alternatively, you can use wagmi hooks and follow our tutorial on setting up MetaMask SDK using Create Wagmi or our Consensys Create Web3 CLI to scaffold a project that comes configured with Viem, Wagmi and MetaMask SDK.

Steps

1. Install the SDK

In your project directory, install the SDK using Yarn or npm:

yarn add @metamask/sdk-react

or

npm i @metamask/sdk-react

2. Import the SDK

In your project script, add the following to import the SDK:

index.tsx

import { MetaMaskProvider } from "@metamask/sdk-react"

3. Wrap your project with MetaMaskProvider

Wrap your root component in a MetaMaskProvider. For example:

index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { MetaMaskProvider } from "@metamask/sdk-react";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <MetaMaskProvider
      sdkOptions={{
        dappMetadata: {
          name: "Example React Dapp",
          url: window.location.href,
        },
        infuraAPIKey: process.env.INFURA_API_KEY,
        // Other options.
      }}
    >
      <App />
    </MetaMaskProvider>
  </React.StrictMode>
);

For the full list of options you can set for sdkOptions, see the JavaScript SDK options reference. Important options include:

• dappMetadata - Use this to display information about your dapp in the MetaMask connection modal.
• infuraAPIKey - Use this to make read-only RPC requests from your dapp.
• Use headless to customize the logic and UI of the displayed modals.

4. Use the SDK

Use the SDK by using the useSDK hook in your React components. For example:

App.tsx

import { useSDK } from "@metamask/sdk-react";
import React, { useState } from "react";

export const App = () => {
  const [account, setAccount] = useState<string>();
  const { sdk, connected, connecting, provider, chainId } = useSDK();

  const connect = async () => {
    try {
      const accounts = await sdk?.connect();
      setAccount(accounts?.[0]);
    } catch (err) {
      console.warn("failed to connect..", err);
    }
  };

  return (
    <div className="App">
      <button style={{ padding: 10, margin: 10 }} onClick={connect}>
        Connect
      </button>
      {connected && (
        <div>
          <>
            {chainId && `Connected chain: ${chainId}`}
            <p></p>
            {account && `Connected account: ${account}`}
          </>
        </div>
      )}
    </div>
  );
};

useSDK return values

• sdk: Main SDK object that facilitates connection and actions related to MetaMask.
• connected: Boolean value indicating if the dapp is connected to MetaMask.
• connecting: Boolean value indicating if a connection is in process.
• provider: The provider object which can be used for lower-level interactions with the Ethereum blockchain.
• chainId: Currently connected blockchain's chain ID.

The connect method initiates a connection to MetaMask and returns an array of connected accounts.

You can also use the connectAndSign method to connect to MetaMask and sign data in a single interaction:

const connectAndSign = async () => {
  try {
    const signResult = await sdk?.connectAndSign({
      msg: "Connect + Sign message",
    })
    setResponse(signResult)
  } catch (err) {
    console.warn("failed to connect..", err)
  }
}

You can also batch multiple JSON-RPC requests using the metamask_batch method.

Example

You can copy the full React example to get started:

Root component

index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { MetaMaskProvider } from "@metamask/sdk-react";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <MetaMaskProvider
      debug={false}
      sdkOptions={{
        dappMetadata: {
          name: "Example React Dapp",
          url: window.location.href,
        },
        infuraAPIKey: process.env.INFURA_API_KEY,
        // Other options
      }}
    >
      <App />
    </MetaMaskProvider>
  </React.StrictMode>
);

React component

App.tsx

import { useSDK } from "@metamask/sdk-react";
import React from "react";

export const App = () => {
  const [account, setAccount] = useState<string>();
  const { sdk, connected, connecting, provider, chainId } = useSDK();

  const connect = async () => {
    try {
      const accounts = await sdk?.connect();
      setAccount(accounts?.[0]);
    } catch (err) {
      console.warn("failed to connect..", err);
    }
  };

  return (
    <div className="App">
      <button style={{ padding: 10, margin: 10 }} onClick={connect}>
        Connect
      </button>
      {connected && (
        <div>
          <>
            {chainId && "Connected chain: ${chainId}"}
            <p></p>
            {account && "Connected account: ${account}"}
          </>
        </div>
      )}
    </div>
  );
};

See the example React dapp in the JavaScript SDK GitHub repository for more information.