Migrating from Wallet Widget

This comprehensive guide will help you migrate from the legacy @initia/react-wallet-widget to the new and improved @initia/interwovenkit-react. InterwovenKit v2 offers better performance, improved TypeScript support, and a more intuitive API.

Migration Benefits - No more SSR configuration required - Better TypeScript support - Improved performance and bundle size - Simplified API with consistent naming - Enhanced error handling

Step-by-Step Migration

Update Package Installation

Replace the legacy wallet widget package with InterwovenKit.

# Remove old package
npm uninstall @initia/react-wallet-widget

# Install new package
npm install @initia/interwovenkit-react

# Remove old package
yarn remove @initia/react-wallet-widget

# Install new package
yarn add @initia/interwovenkit-react

# Remove old package
pnpm remove @initia/react-wallet-widget

# Install new package
pnpm add @initia/interwovenkit-react

# Remove old package
bun remove @initia/react-wallet-widget

# Install new package
bun add @initia/interwovenkit-react

Update all imports from @initia/react-wallet-widget to @initia/interwovenkit-react throughout your codebase.

Clean Up Legacy Configuration

Remove SSR-related imports and configuration that are no longer needed.

Remove SSR Imports

- import { ... } from "@initia/react-wallet-widget/ssr"

Remove Build Configuration

// next.config.js
module.exports = {
- swcMinify: false,
}

Remove CDN Scripts

<!-- Remove any CDN script tags for the wallet widget -->
- <script src="...wallet-widget.js"></script>

Install Required Peer Dependencies

InterwovenKit requires specific peer dependencies for proper functionality.

npm install wagmi viem @tanstack/react-query

yarn add wagmi viem @tanstack/react-query

pnpm add wagmi viem @tanstack/react-query

bun add wagmi viem @tanstack/react-query

These dependencies enable advanced wallet functionality and improved chain interaction capabilities.

Update Provider Configuration

Replace the legacy provider setup with the new InterwovenKit configuration.

providers.tsx

"use client"

import { PropsWithChildren, useEffect } from "react"
import { createConfig, http, WagmiProvider } from "wagmi"
import { mainnet } from "wagmi/chains"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import {
  initiaPrivyWalletConnector,
  injectStyles,
  InterwovenKitProvider
} from "@initia/interwovenkit-react"
import interwovenKitStyles from "@initia/interwovenkit-react/styles.js"

// Configure Wagmi for wallet connections
const wagmiConfig = createConfig({
  connectors: [initiaPrivyWalletConnector],
  chains: [mainnet],
  transports: { [mainnet.id]: http() },
})

const queryClient = new QueryClient()

export default function Providers({ children }: PropsWithChildren) {
  useEffect(() => {
    // Inject styles into the shadow DOM used by Initia Wallet
    injectStyles(interwovenKitStyles)
  }, [])

  return (
    <QueryClientProvider client={queryClient}>
      <WagmiProvider config={wagmiConfig}>
        <InterwovenKitProvider defaultChainId="YOUR_CHAIN_ID">
          {children}
        </InterwovenKitProvider>
      </WagmiProvider>
    </QueryClientProvider>
  )
}

The new provider structure separates concerns better and provides more flexibility for wallet configuration.

API Migration Guide

Provider Configuration Changes

<WalletWidgetProvider chainId="YOUR_CHAIN_ID" />

<InterwovenKitProvider defaultChainId="YOUR_CHAIN_ID" />

<WalletWidgetProvider customLayer={YOUR_CHAIN} />

<InterwovenKitProvider customChain={YOUR_CHAIN} />

Bridge Configuration Migration

export default function Providers() {
  return (
    <WalletWidgetProvider
      bridgeOptions={{
        defaultDstChainId: "YOUR_CHAIN_ID",
        defaultDstAssetDenom: "YOUR_DENOM"
      }}
    />
  )
}

import { useInterwovenKit } from '@initia/interwovenkit-react'

export default function Home() {
  const { openBridge } = useInterwovenKit()

  return (
    <button
      onClick={() =>
        openBridge({
          dstChainId: 'YOUR_CHAIN_ID',
          dstDenom: 'YOUR_DENOM',
        })
      }
    >
      Bridge
    </button>
  )
}

Bridge configuration has moved from the provider level to individual method calls, providing more flexibility and better user experience.

Removed Provider Props

The following props are no longer supported:

- <WalletWidgetProvider additionalWallets={...} />
- <WalletWidgetProvider filterWallet={...} />

To customize wallet options, use wagmi connectors in your wagmi configuration instead.

Hook and Method Changes

Wallet Connection Interface

import { truncate } from "@initia/utils"
import { useWallet } from "@initia/react-wallet-widget"

export default function WalletButton() {
  const { address, onboard, view, bridge, isLoading } = useWallet()

if (!address) { return ( <button onClick={onboard} disabled={isLoading}>
{isLoading ? "Loading..." : "Connect Wallet"} </button> ) }

return ( <div> <button onClick={bridge}>Open Bridge</button>

<button onClick={view}>{truncate(address)}</button> </div> ) }

import { truncate } from "@initia/utils"
import { useInterwovenKit } from "@initia/interwovenkit-react"

export default function WalletButton() {
  const { address, openConnect, openWallet, openBridge } = useInterwovenKit()

  if (!address) {
    return <button onClick={openConnect}>Connect Wallet</button>
  }

  return (
    <div>
      <button onClick={openBridge}>Open Bridge</button>
      <button onClick={openWallet}>{truncate(address)}</button>
    </div>
  )
}

Ensure your entire application is wrapped with <InterwovenKitProvider> at the root level for the hooks to function properly.

Transaction Handling

import { useWallet } from "@initia/react-wallet-widget"

export default function TransactionComponent() {
  const { requestTx } = useWallet()

const handleSubmit = async () => { try { const transactionHash = await
requestTx( { messages: [] }, { chainId: "YOUR_CHAIN_ID" } )
console.log("Transaction submitted:", transactionHash) } catch (error) {
console.error("Transaction failed:", error) } }

return <button onClick={handleSubmit}>Submit Transaction</button> }

import { useInterwovenKit } from "@initia/interwovenkit-react"

export default function TransactionComponent() {
  const { requestTxBlock } = useInterwovenKit()

  const handleSubmit = async () => {
    try {
      const { transactionHash } = await requestTxBlock({
        messages: [],
        chainId: "YOUR_CHAIN_ID" // optional, default to InterwovenKit's `defaultChainId`
      })
      console.log("Transaction confirmed:", transactionHash)
    } catch (error) {
      console.error("Transaction failed:", error)
    }
  }

  return <button onClick={handleSubmit}>Submit Transaction</button>
}

For more granular control over transaction states, use requestTxSync() to get the transaction hash immediately, then waitForTxConfirmation() to wait for blockchain confirmation. See the useInterwovenKit reference for details.

Advanced Integration

Working with @initia/initia.js

For complex transaction building, InterwovenKit seamlessly integrates with @initia/initia.js:

example-usage.tsx

import { MsgSend, Msg } from '@initia/initia.js'
import { useInterwovenKit } from '@initia/interwovenkit-react'

// Helper function to convert Initia.js messages to InterwovenKit format
function toEncodeObject(msg: Msg) {
  const data = msg.toData()
  return {
    typeUrl: data['@type'],
    value: msg.toProto(),
  }
}

export default function SendTransaction() {
  const { initiaAddress, requestTxBlock } = useInterwovenKit()

  const handleSend = async () => {
    // Build messages using initia.js
    const msgs = [
      MsgSend.fromPartial({
        fromAddress: initiaAddress,
        toAddress: 'recipient_address_here',
        amount: [{ amount: '1000000', denom: 'uinit' }],
      }),
    ]

    // Convert to InterwovenKit format
    const messages = msgs.map(toEncodeObject)

    try {
      const { transactionHash } = await requestTxBlock({
        messages,
        chainId: 'YOUR_CHAIN_ID',
      })
      console.log('Transfer successful:', transactionHash)
    } catch (error) {
      console.error('Transfer failed:', error)
    }
  }

  return (
    <button onClick={handleSend} disabled={!initiaAddress}>
      Send INIT
    </button>
  )
}

Migration Checklist

✅ Package & Dependencies

Uninstalled @initia/react-wallet-widget
Installed @initia/interwovenkit-react
Installed peer dependencies (wagmi, viem, @tanstack/react-query)
Updated all import statements

✅ Configuration Cleanup

Removed SSR-related imports - [ ] Removed build configuration changes - [ ] Removed CDN scripts - [ ] Updated provider configuration

✅ API Updates

Replaced WalletWidgetProvider with InterwovenKitProvider - [ ] Updated useWallet to useInterwovenKit - [ ] Migrated method calls (onboard → openConnect, etc.) - [ ] Updated transaction handling (requestTx → requestTxBlock)

✅ Testing

Wallet connection works correctly
Bridge functionality works
Transaction submission works
No console errors or warnings

Need help with migration? Check out the Getting Started guide for complete implementation examples, or refer to the API Reference for detailed method documentation.

Getting Started Changelog

⌘I

InterwovenKit

Integrations

Features

API Reference

Migrating from Wallet Widget

Step-by-Step Migration

API Migration Guide

Provider Configuration Changes

Bridge Configuration Migration

Removed Provider Props

Hook and Method Changes

Wallet Connection Interface

Transaction Handling

Advanced Integration

Working with @initia/initia.js

Migration Checklist

​Step-by-Step Migration

​API Migration Guide

​Provider Configuration Changes

​Bridge Configuration Migration

​Removed Provider Props

​Hook and Method Changes

​Wallet Connection Interface

​Transaction Handling

​Advanced Integration

​Working with @initia/initia.js

​Migration Checklist

Step-by-Step Migration

API Migration Guide

Provider Configuration Changes

Bridge Configuration Migration

Removed Provider Props

Hook and Method Changes

Wallet Connection Interface

Transaction Handling

Advanced Integration

Working with @initia/initia.js

Migration Checklist