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.

Examples

See the example JavaScript dapps in the JavaScript SDK GitHub repository for advanced use cases.

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={{
      checkInstallationImmediately: false,
      dappMetadata: {
        name: "Demo React App",
        url: window.location.host,
      }
    }}>
      <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 SDK options

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 sdk.connect() method initiates a connection to MetaMask and returns an array of connected accounts:

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

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

Refer to the MetaMask JavaScript SDK examples for advanced use cases.