Upgrade from Web3Modal to Reown AppKit for React Native

This document outlines the steps to migrate from the old @web3modal packages to the new multichain @reown/appkit packages in your React Native project.

Overview of Changes

The new AppKit architecture introduces a core library with pluggable chain adapters, providing better support for multiple blockchains (EVM, Solana, Bitcoin) in a single integration. Key Changes:

Core Library: Use @reown/appkit-react-native as the main package
Chain Adapters: Install specific adapters for each blockchain you want to support
Unified API: All hooks and components are imported from the core package
Multichain Support: Native support for EVM, Solana, and Bitcoin chains

Wagmi
Ethers

Step 1. Replace the dependencies using package manager commandsFor Yarn users:Remove the old Web3Modal packages:

yarn remove @web3modal/wagmi-react-native @web3modal/email-wagmi-react-native @web3modal/coinbase-wagmi-react-native @web3modal/siwe-react-native

Add the new Reown AppKit packages:

AppKit is only compatible with wagmi 2.x. Ensure you are using a compatible version.

# Core AppKit library and dependencies
yarn add @reown/appkit-react-native @react-native-async-storage/async-storage react-native-get-random-values react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

# Wagmi adapter and its dependencies
yarn add @reown/appkit-wagmi-react-native wagmi viem@2.x @tanstack/react-query

# Optional: Additional adapters for other chains
yarn add @reown/appkit-solana-react-native @reown/appkit-bitcoin-react-native

Step 2. Update your AppKit configurationCreate a new AppKitConfig.ts file with the multichain setup:

// src/AppKitConfig.ts
import "@walletconnect/react-native-compat"; // MUST BE THE FIRST IMPORT

import { createAppKit } from "@reown/appkit-react-native";
import { WagmiAdapter } from "@reown/appkit-wagmi-react-native";
import { mainnet, sepolia } from "wagmi/chains";

const projectId = "YOUR_PROJECT_ID"; // Obtain from https://dashboard.reown.com/

const metadata = {
  name: "My Awesome dApp",
  description: "My dApp description",
  url: "https://myapp.com",
  icons: ["https://myapp.com/icon.png"],
  redirect: {
    native: "YOUR_APP_SCHEME://",
    universal: "YOUR_APP_UNIVERSAL_LINK.com",
  },
};

// Initialize Wagmi adapter
const wagmiAdapter = new WagmiAdapter({
  projectId,
  networks: [mainnet, sepolia], // Add all chains you want to support
});

export const appKit = createAppKit({
  projectId,
  metadata,
  networks: [mainnet, sepolia], // Must match the networks in wagmiAdapter
  adapters: [wagmiAdapter],
  // ... other AppKit options
});

// Export the wagmi config for provider setup
export const wagmiConfig = wagmiAdapter.wagmiConfig;

Step 3. Update your App.tsx with providers

// App.tsx
import React from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { AppKitProvider } from '@reown/appkit-react-native';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { appKit, wagmiConfig } from './AppKitConfig';
import YourAppRootComponent from './YourAppRootComponent';

const queryClient = new QueryClient();

function App() {
  return (
    <SafeAreaProvider>
      <AppKitProvider instance={appKit}>
        <WagmiProvider config={wagmiConfig}>
          <QueryClientProvider client={queryClient}>
            <YourAppRootComponent />
          </QueryClientProvider>
        </WagmiProvider>
      </AppKitProvider>
    </SafeAreaProvider>
  );
}

export default App;

Step 4. Update your component with AppKit UI

// YourAppRootComponent.tsx
import React from 'react';
import { AppKit } from '@reown/appkit-react-native';
// ... other imports

function YourAppRootComponent() {
  return (
    <>
      {/* Your application's content */}
      <AppKit /> {/* This renders the modal and other AppKit UI */}
    </>
  );
}

export default YourAppRootComponent;

Step 5. Update your Hooks usageUpdate your hook imports as follows:

// Remove the following code lines
import {
  useWeb3Modal,
  useWeb3ModalState,
  useWeb3ModalEvents,
  useWalletInfo,
} from "@web3modal/wagmi-react-native";

// Add the following code lines
import {
  useAppKit,
  useAppKitState,
  useAppKitEventSubscription,
  useWalletInfo,
} from "@reown/appkit-react-native";

Step 6. Update your Components usageUpdate your component imports as follows:

// Remove the following code lines
import {
  W3mAccountButton,
  W3mButton,
  W3mConnectButton,
  W3mNetworkButton,
  Web3Modal,
} from "@web3modal/wagmi-react-native";

// Add the following code lines
import {
  AccountButton,
  AppKitButton,
  ConnectButton,
  NetworkButton,
  AppKit,
} from "@reown/appkit-react-native";

Step 7. Update your config for Universal WalletsRemove email wallet specific imports as follows:

// Remove the following code lines
import { emailConnector } from "@web3modal/email-wagmi-react-native";

Step 8. Update your import to support Coinbase WalletUpdate coinbase connector import as follows:

// Remove the following code lines
import { coinbaseConnector } from "@web3modal/coinbase-wagmi-react-native";

// Add the following code lines
import { MMKV } from 'react-native-mmkv';
import { CoinbaseConnector } from '@reown/appkit-coinbase-react-native';

export const appKit = createAppKit({
  // ...
  extraConnectors: [
    new CoinbaseConnector({ storage: new MMKV() })
  ],
  // ...
});

If you are using ethers v5, follow the same steps but replacing ethers with ethers5

Step 1. Replace the dependencies using package manager commandsFor Yarn users:Remove the old Web3Modal packages:

yarn remove @web3modal/ethers-react-native @web3modal/ethers5-react-native @web3modal/email-ethers-react-native @web3modal/coinbase-ethers-react-native @web3modal/siwe-react-native

Add the new Reown AppKit packages:

# Core AppKit library and dependencies
yarn add @reown/appkit-react-native @react-native-async-storage/async-storage react-native-get-random-values react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

# Ethers adapter
yarn add @reown/appkit-ethers-react-native

# Optional: Additional adapters for other chains
yarn add @reown/appkit-solana-react-native @reown/appkit-bitcoin-react-native

Step 2. Update your AppKit configurationCreate a new AppKitConfig.ts file with the multichain setup:

// src/AppKitConfig.ts
import "@walletconnect/react-native-compat"; // MUST BE THE FIRST IMPORT

import { createAppKit } from "@reown/appkit-react-native";
import { EthersAdapter } from "@reown/appkit-ethers-react-native";
import { mainnet, polygon } from "viem/chains";

const projectId = "YOUR_PROJECT_ID"; // Obtain from https://dashboard.reown.com/

const metadata = {
  name: "My Awesome dApp",
  description: "My dApp description",
  url: "https://myapp.com",
  icons: ["https://myapp.com/icon.png"],
  redirect: {
    native: "YOUR_APP_SCHEME://",
    universal: "YOUR_APP_UNIVERSAL_LINK.com",
  },
};

// Initialize Ethers adapter
const ethersAdapter = new EthersAdapter();

export const appKit = createAppKit({
  projectId,
  metadata,
  networks: [mainnet, polygon], // Add all chains you want to support
  adapters: [ethersAdapter],
  // ... other AppKit options
});

Step 3. Update your App.tsx with providers

// App.tsx
import React from 'react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { AppKitProvider } from '@reown/appkit-react-native';
import { appKit } from './AppKitConfig';
import YourAppRootComponent from './YourAppRootComponent';

function App() {
  return (
    <SafeAreaProvider>
      <AppKitProvider instance={appKit}>
        <YourAppRootComponent />
      </AppKitProvider>
    </SafeAreaProvider>
  );
}

export default App;

Step 4. Update your component with AppKit UI

// YourAppRootComponent.tsx
import React from 'react';
import { AppKit } from '@reown/appkit-react-native';
// ... other imports

function YourAppRootComponent() {
  return (
    <>
      {/* Your application's content */}
      <AppKit /> {/* This renders the modal and other AppKit UI */}
    </>
  );
}

export default YourAppRootComponent;

Step 5. Update your Hooks usageUpdate your hook imports as follows:

// Remove the following code lines
import {
  useWeb3Modal,
  useWeb3ModalState,
  useWeb3ModalEvents,
  useWeb3ModalAccount,
  useWeb3ModalProvider,
  useWeb3ModalError,
  useWalletInfo,
} from "@web3modal/ethers-react-native";

// Add the following code lines
import {
  useAppKit,
  useAppKitState,
  useAppKitEventSubscription,
  useAccount,
  useProvider,
  useWalletInfo,
} from "@reown/appkit-react-native";

Step 6. Update your Components usageUpdate your component imports as follows:

// Remove the following code lines
import {
  W3mAccountButton,
  W3mButton,
  W3mConnectButton,
  W3mNetworkButton,
  Web3Modal,
} from "@web3modal/ethers-react-native";

// Add the following code lines
import {
  AccountButton,
  AppKitButton,
  ConnectButton,
  NetworkButton,
  AppKit,
} from "@reown/appkit-react-native";

Step 7. Remove email wallet specific imports as follows:

// Remove the following code lines
import { EmailProvider } from "@web3modal/email-ethers-react-native";

Step 8. Update your import to support Coinbase WalletUpdate coinbase connector import as follows:

// Remove the following code lines
import { CoinbaseProvider } from "@web3modal/coinbase-ethers-react-native";

// Add the following code lines
import { MMKV } from 'react-native-mmkv';
import { CoinbaseConnector } from '@reown/appkit-coinbase-react-native';

export const appKit = createAppKit({
  // ...
  extraConnectors: [
    new CoinbaseConnector({ storage: new MMKV() })
  ],
  // ...

Key Migration Notes

New Hook Structure

useWeb3Modal → useAppKit (includes open, close, disconnect, switchNetwork)
useWeb3ModalState → useAppKitState
useWeb3ModalEvents → useAppKitEventSubscription
useWeb3ModalAccount → useAccount
useWeb3ModalProvider → useProvider
useDisconnect → useAppKit

New Component Structure

Web3Modal → AppKit
W3mButton → AppKitButton
W3mConnectButton → ConnectButton
W3mAccountButton → AccountButton
W3mNetworkButton → NetworkButton

Multichain Support

The new AppKit supports multiple blockchains natively. You can add support for Solana and Bitcoin by installing their respective adapters:

# For Solana support
yarn add @reown/appkit-solana-react-native

# For Bitcoin support
yarn add @reown/appkit-bitcoin-react-native

Then add them to your AppKitConfig.ts:

import { SolanaAdapter } from "@reown/appkit-solana-react-native";
import { BitcoinAdapter } from "@reown/appkit-bitcoin-react-native";
import { solana, bitcoin } from "@reown/appkit-react-native";

const solanaAdapter = new SolanaAdapter();
const bitcoinAdapter = new BitcoinAdapter();

export const appKit = createAppKit({
  // ...
  networks: [mainnet, polygon, solana, bitcoin],
  adapters: [ethersAdapter, solanaAdapter, bitcoinAdapter],
  // ...
});

Final notes

Ensure that you have updated all relevant configurations and imports in your project to reflect the changes from Web3Modal to the new multichain AppKit.
Test your application thoroughly to ensure that the migration has been successful and that all functionality is working as expected.
Check our AppKit examples for React Native to compare with your implementation in case you are having issues
For detailed information about the new architecture, see the Migration to Multichain guide

Fundamentals

Features

Upgrade from Web3Modal to Reown AppKit for React Native

Overview of Changes

Key Migration Notes

New Hook Structure

New Component Structure

Multichain Support

Final notes

​Overview of Changes

​Key Migration Notes

​New Hook Structure

​New Component Structure

​Multichain Support

​Final notes

Overview of Changes

Key Migration Notes

New Hook Structure

New Component Structure

Multichain Support

Final notes