Skip to main content



This documentation is for Web3Modal v2. You can find Web3Modal v3 docs here

With Web3Modal JavaScript, we work with the Wagmi library which is a collection of React Hooks to make your dapp development flow easier. You can sign messages, interact with smart contracts, and much more.

Don't have a project ID?

Head over to WalletConnect Cloud and create a new project now!

Get startedcloud illustration

Add packages (NPM)

npm install @web3modal/ethereum @web3modal/html @wagmi/core viem

Add packages (CDN)

Web3Modal uses unpkg as its official CDN provider. For a majority of use cases you simply need to swap npm imports to cdn ones, however due to some downstream package issues with cdn workflows, we recommend using pre-packaged version of wagmi core as shown below. (WagmiCore imports).

See full CDN example for more info.

<script type="module">
import {
} from ''

import { Web3Modal } from ''

// Equivalent to importing from @wagmi/core
const { configureChains, createConfig } = WagmiCore

// Equivalent to importing from viem/chains
const { mainnet, polygon, avalanche, arbitrum } = WagmiCoreChains

// Equivalent to importing from @wagmi/core/providers
const { CoinbaseWalletConnector } = WagmiCoreConnectors


Start by importing Web3Modal and wagmi packages, then create wagmi config using your own settings or our default presets as shown below. Finally, pass wagmi config to Web3Modal as ethereumClient.

import { EthereumClient, w3mConnectors, w3mProvider } from '@web3modal/ethereum'
import { Web3Modal } from '@web3modal/html'
import { configureChains, createConfig } from '@wagmi/core'
import { arbitrum, mainnet, polygon } from 'viem/chains'

const chains = [arbitrum, mainnet, polygon]
const projectId = 'YOUR_PROJECT_ID'

const { publicClient } = configureChains(chains, [w3mProvider({ projectId })])
const wagmiConfig = createConfig({
autoConnect: true,
connectors: w3mConnectors({ projectId, chains }),
const ethereumClient = new EthereumClient(wagmiConfig, chains)
const web3modal = new Web3Modal({ projectId }, ethereumClient)

Trigger the modal

Use pre-built w3m-core-button web component.


Alternatively, use your own button with openModal action.

document.getElementById('my-button').addEventListener('click', () => {

<button id="my-button">Connect Wallet</button>

Use wagmi actions

wagmi provides everything you'll need to start working with accounts, contracts, chains and much more.

import { getAccount, getContract } from '@wagmi/core'