HTML

caution

This documentation is for Web3Modal v3 which is currently in Beta. You can find Web3Modal v2 documentation here

With Web3Modal HTML we work with the @wagmi/core library which contains everything you need to start working with Ethereum. 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 started

Installation

Yo can install Web3Modal SDK by using a package manager like npm or with CDN imports.

Choose your preferred package manager

npm
Yarn
Bun
pnpm

npm install @web3modal/wagmi@beta @wagmi/core viem

yarn add @web3modal/wagmi@beta @wagmi/core viem

bun install @web3modal/wagmi@beta @wagmi/core viem

pnpm add @web3modal/wagmi@beta @wagmi/core viem

In order to use CDN replace the imports from the implementation example with the following ones

import { createWeb3Modal, defaultWagmiConfig } from 'https://esm.sh/@web3modal/wagmi?bundle'
import { mainnet, arbitrum } from 'https://esm.sh/@wagmi/core/chains?bundle'

Implementation

You can start Web3Modal configuration using either default or custom mode.

Default mode will implement WalletConnect, Browser Wallets (injected) and Coinbase options in addition to Wagmi's public provider and WalletConnect's provider.

Default
Custom

Start by importing Web3Modal, defaultWagmiConfig and wagmi packages, then create wagmiConfig using defaultWagmiConfig function as shown below. Finally, pass wagmiConfig to the Web3Modal class.

import { createWeb3Modal, defaultWagmiConfig } from '@web3modal/wagmi'

import { mainnet, arbitrum } from '@wagmi/core/chains'

// 1. Define constants
const projectId = 'YOUR_PROJECT_ID'

// 2. Create wagmiConfig
const chains = [mainnet, arbitrum]
const wagmiConfig = defaultWagmiConfig({ chains, projectId, appName: 'Web3Modal' })

// 3. Create modal
const modal = createWeb3Modal({ wagmiConfig, projectId, chains })

Start by importing createWeb3Modal, walletConnectProvider and wagmi packages, then create wagmiConfig using your own settings. Finally, pass wagmi config to createWeb3Modal.

import { createWeb3Modal, walletConnectProvider } from '@web3modal/wagmi'

import { configureChains, createConfig } from '@wagmi/core'
import { mainnet } from '@wagmi/core/chains'
import { InjectedConnector } from '@wagmi/core'
import { CoinbaseWalletConnector } from '@wagmi/core/connectors/coinbaseWallet'
import { WalletConnectConnector } from '@wagmi/core/connectors/walletConnect'

// 1. Define constants
const projectId = 'YOUR_PROJECT_ID'

// 2. Configure wagmi client
const { chains, publicClient } = configureChains([mainnet], [walletConnectProvider({ projectId })])
const wagmiConfig = createConfig({
  autoConnect: true,
  connectors: [
    new WalletConnectConnector({ chains, options: { projectId, showQrModal: false } }),
    new InjectedConnector({ chains, options: { shimDisconnect: true } }),
    new CoinbaseWalletConnector({ chains, options: { appName: 'Web3Modal' } })
  ],
  publicClient
})

// 3. Create modal
const modal = createWeb3Modal({ wagmiConfig, projectId, chains })

To open Web3Modal you can use our web components or build your own logic with Web3Modal actions

Components
Actions

You can use default web components to open the modal

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>HTML Example</title>
  </head>
  <body>
    <w3m-button />
    <script type="module" src="main.js"></script>
  </body>
</html>

Learn more about the Web3Modal web components here

note

Web components are global html elements that don't require importing.

You can trigger the modal by calling the open function from a modal instance returned by createWeb3Modal.

Let's first add two html elements to display information to the user:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>HTML Example</title>
  </head>
  <body>
    <button id="btn">Connect</button>
    <span id="user"></span>
    <script type="module" src="main.js"></script>
  </body>
</html>

Following with our main.js file, we can now add the needed logic to open the modal and display information in the DOM:

//main.js
import { watchAccount, disconnect, getAccount } from '@wagmi/core'

function connect() {
  if (getAccount().isConnected) {
    disconnect()
  } else {
    modal.open()
  }
}

const btnEl = document.getElementById('btn')
const userEl = document.getElementById('user')

btnEl.addEventListener('click', connect)

// listening for account changes
watchAccount(account => {
  userEl.innerText = account.address ?? ''
  if (account.isConnected) {
    btnEl.innerText = 'Disconnect'
  } else {
    btnEl.innerText = 'Connect'
  }
})

Learn more about the Web3Modal actions here

Use wagmi Actions

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

import { getAccount, writeContract, disconnect, watchAccount } from '@wagmi/core'

Was this helpful?

HTML

Don't have a project ID?

Installation​

Implementation​

Trigger the modal​

Use wagmi Actions​

Installation

Implementation

Trigger the modal

Use wagmi Actions