Skip to main content

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.

React UI

This page provides instructions for using the standard @metamask/sdk-react package. Alternatively, you can use the @metamask/sdk-react-ui package to easily use wagmi hooks and a pre-styled UI button component for connecting to MetaMask.

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:

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

3. Wrap your project with MetaMaskProvider​

Wrap your root component in a MetaMaskProvider. For example:

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>
);

When initializing MetaMaskProvider, set debug to true to activate debug mode. For the full list of options you can set for sdkOptions, see the JavaScript SDK options reference. Important options include:

4. Use the SDK​

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

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:

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>
);

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