Migration Guide

This guide helps you upgrade from @metalayer/widget v0.x to v1.x, which introduces a cleaner API, improved naming conventions, and a powerful new theme system.

Breaking Changes

1. External WagmiProvider Required (disableWagmi removed)

The widget no longer ships an internal WagmiProvider. The disableWagmi prop has been removed — you must provide your own WagmiProvider in your application. If you were already using disableWagmi={true}, simply remove the prop:

  <WagmiProvider config={wagmiConfig}>
    <WidgetProvider
-     disableWagmi
      sdkConfig={sdkConfig}
      onSupportedChainsLoad={handleSupportedChainsLoad}
    >

If you were relying on the widget’s internal WagmiProvider (the old default), wrap your app with your own:

+ <WagmiProvider config={wagmiConfig}>
    <WidgetProvider
      sdkConfig={sdkConfig}
+     onSupportedChainsLoad={(chains) => {
+       // Update wagmi config with supported chains
+     }}
    >
      <Widget onConnectClick={openModal} />
    </WidgetProvider>
+ </WagmiProvider>

Use onSupportedChainsLoad to update your wagmi config with the chains the widget supports. The widget no longer uses a nested config object. Props are now passed directly to the component.

<Widget
  config={{
    onOpenConnectModal: openModal,
    onDisconnectWallet: disconnect,
    onSubmitTransaction: handleSubmit,
    onSelectToken: handleTokenSelect,
    className: 'custom-class',
    source: sourceConfig,
    destination: destinationConfig,
  }}
/>

3. Callback Naming Changes

All callbacks have been renamed for clarity and consistency with React conventions:

Old Name (v0.x)	New Name (v1.x)	Description
`onOpenConnectModal`	`onConnectClick`	Handler when user clicks connect
`onDisconnectWallet`	`onDisconnectClick`	Handler when user clicks disconnect
`onSubmitTransaction`	`onTransactionSubmitted`	Fired after transaction submission
`onSelectToken`	`onTokenSelected`	Fired after token selection

4. Theme System

The brandColor prop has been removed in favor of the new comprehensive theme system.

<WidgetProvider
  sdkConfig={{ apiKey: 'key', environment: 'mainnet' }}
  brandColor="#6750A4"
>

Note: brandColor has been completely removed in v1.x. You must use the new theme prop. See the New Theme System Features section below for comprehensive theming options.

5. WidgetProvider Props Update

The chains prop has been renamed to enabledChains for clarity:

<WidgetProvider
  sdkConfig={{ apiKey: 'key', environment: 'mainnet' }}
  chains={supportedChains}
>

6. RPC / wagmi transports (Metalayer RPC helpers)

v1.x expects you to own WagmiProvider and therefore your transports. Using plain viem http() (or other defaults that ignore Metalayer metadata) does not use Metalayer’s ordered RPCs or alternativeRpcs as viem fallback endpoints, which can lead to rate limits or mismatches with the chains the widget loads. Prefer:

createWidgetClient with wagmi createConfig using a client({ chain }) { return createWidgetClient(chain) } callback, typically multiInjectedProviderDiscovery: false, after converting onSupportedChainsLoad chains with chainsToViemChains / chainToViemChain (see Components), or
createWidgetTransportsRecord(viemChains) with createConfig({ chains, transports }) or RainbowKit getDefaultConfig({ transports }).

- transports: { [chain.id]: http() },
+ transports: createWidgetTransportsRecord(viemChains),

Step-by-Step Migration

Step 1: Update Package Version

pnpm update @metalayer/widget@^1.0.0

Find all <Widget> components and update the props:

- <Widget
-   config={{
-     onOpenConnectModal: openConnectModal,
-     onDisconnectWallet: () => disconnect(),
-     onSubmitTransaction: (source, dest, amount) => {
-       console.log('Transaction submitted', { source, dest, amount });
-     },
-     className: 'rounded-xl',
-   }}
- />
+ <Widget
+   onConnectClick={openConnectModal}
+   onDisconnectClick={() => disconnect()}
+   onTransactionSubmitted={(source, dest, amount) => {
+     console.log('Transaction submitted', { source, dest, amount });
+   }}
+   className="rounded-xl"
+ />

Step 3: Update WidgetProvider Theme

Replace brandColor with the new theme configuration:

  <WidgetProvider
    sdkConfig={{ apiKey: 'your-key', environment: 'mainnet' }}
-   brandColor="#6750A4"
+   theme={{
+     colors: { primary: '#6750A4' }
+   }}
  >

Step 4: Update Token Selection Callbacks

If you’re using token selection callbacks, update the naming:

  <Widget
-   config={{
-     onSelectToken: (direction, chainId, tokenAddress) => {
-       console.log('Token selected', { direction, chainId, tokenAddress });
-     }
-   }}
+   onTokenSelected={(direction, chainId, tokenAddress) => {
+     console.log('Token selected', { direction, chainId, tokenAddress });
+   }}
  />

Step 5: Update Controlled Token Selection

If using controlled source/destination props:

  <Widget
-   config={{
-     source: { chainId: 1, tokenAddress: '0x...' },
-     destination: { chainId: 42161, tokenAddress: '0x...' },
-     onOpenConnectModal: openModal,
-   }}
+   source={{ chainId: 1, tokenAddress: '0x...' }}
+   destination={{ chainId: 42161, tokenAddress: '0x...' }}
+   onConnectClick={openModal}
  />

New Theme System Features

Take advantage of the new theming capabilities:

Predefined Themes

<WidgetProvider
  sdkConfig={sdkConfig}
  theme={{ predefined: 'modern' }} // 'comfy' | 'modern'
>

Custom Color Palette

<WidgetProvider
  sdkConfig={sdkConfig}
  theme={{
    mode: 'light',       // 'light' | 'dark'
    colors: {
      primary: '#6750A4',
      neutral: '#5E5E5E',
      success: '#00C853',
      warning: '#FFB300',
      info: '#2196F3',
      failure: '#F44336',
    },
    corners: 'rounded',  // 'none' | 'minimal' | 'soft' | 'medium' | 'rounded'
    shadow: 'light',     // 'none' | 'sharp' | 'light' | 'heavy'
  }}
>

Feature Toggles

<WidgetProvider
  sdkConfig={sdkConfig}
  theme={{
    colors: { primary: '#6750A4' },
    features: {
      headerIcons: true,
      headerBackground: false,
      background: true,
      outlineComponents: false,
    }
  }}
>

Advanced Overrides

<WidgetProvider
  sdkConfig={sdkConfig}
  theme={{
    colors: { primary: '#6750A4' },
    overrides: {
      background: {
        main: '#FFFFFF',
        layer1: '#F5F5F5',
        layer2: '#EEEEEE',
        layer3: '#E0E0E0',
      },
      text: {
        primary: '#1A1A1A',
        secondary: '#666666',
        disabled: '#9E9E9E',
      }
    }
  }}
>

Common Integration Updates

RainbowKit

  function BridgePage() {
    const { openConnectModal } = useConnectModal();
    const { disconnect } = useDisconnect();

    return (
      <Widget
-       config={{
-         onOpenConnectModal: openConnectModal,
-         onDisconnectWallet: disconnect,
-       }}
+       onConnectClick={openConnectModal}
+       onDisconnectClick={disconnect}
      />
    );
  }

Dynamic.xyz

  function BridgePage() {
    const { setShowAuthFlow } = useDynamicContext();

    return (
      <Widget
-       config={{
-         onOpenConnectModal: () => setShowAuthFlow(true),
-       }}
+       onConnectClick={() => setShowAuthFlow(true)}
      />
    );
  }

ConnectKit

  function BridgePage() {
    const { openConnectModal } = useModal();
    const { disconnect } = useDisconnect();

    return (
      <Widget
-       config={{
-         onOpenConnectModal: openConnectModal,
-         onDisconnectWallet: disconnect,
-       }}
+       onConnectClick={openConnectModal}
+       onDisconnectClick={disconnect}
      />
    );
  }

TypeScript Updates

The type definitions have changed significantly:

// Old types (v0.x)
import type { WidgetProps, WidgetConfig } from '@metalayer/widget';

// v0.x used nested config object
const props: WidgetProps = {
  config: {
    onOpenConnectModal: () => void,
    onDisconnectWallet?: () => void,
    onSubmitTransaction?: (sourceChainId?: number, destChainId?: number, amount?: string) => void,
    onSelectToken?: (direction: 'source' | 'destination', chainId: number, tokenAddress: string) => void,
    className?: string,
    source?: { chainId: number; tokenAddress?: string },
    destination?: { chainId: number; tokenAddress?: string },
  }
};

// New types (v1.x)
import type { WidgetProps } from '@metalayer/widget';

const props: WidgetProps = {
  // REQUIRED callback
  onConnectClick: () => void,

  // Optional callbacks
  onDisconnectClick?: () => void,
  onTransactionSubmitted?: (
    sourceChainId?: number,
    destChainId?: number,
    amount?: string
  ) => void,
  onTokenSelected?: (
    direction: 'source' | 'destination',
    chainId: number,
    tokenAddress: string
  ) => void,

  // Optional configuration
  source?: { chainId: number; tokenAddress?: string },
  destination?: { chainId: number; tokenAddress?: string },
  className?: string,
  isConnecting?: boolean,
};

Additional Exported Types

v1.x exports comprehensive TypeScript types for all configuration:

import type {
  // Widget types
  WidgetProps,

  // Provider types
  WidgetProviderProps,

  // Theme types
  ThemeConfig,
  Theme,
  ThemeMode,
  PredefinedTheme,
  ThemeFeatures,
  CornerRadiusStyle,
  ShadowStyle,
  FontFamilyConfig,
  GoogleFontsConfig,
  CustomFontConfig,

  // Solana types (if using Solana support)
  WidgetSolanaSigner,
  WidgetSolanaProps,
} from '@metalayer/widget';

Troubleshooting

Property 'config' does not exist

Remove the config wrapper and pass props directly to <Widget>.

brandColor is deprecated

Use theme={{ colors: { primary: 'your-color' } }} instead.

onOpenConnectModal is not a valid prop

Rename to onConnectClick.

onSelectToken callback not firing

Rename to onTokenSelected.

Best Practices

Use the new theme system - It provides better customization and consistency
Leverage TypeScript - The new types provide better autocomplete and type safety
Optional disconnect - Only provide onDisconnectClick if your wallet library supports it
Test callbacks - Ensure all renamed callbacks are working correctly after migration

Breaking Changes

1. External WagmiProvider Required (disableWagmi removed)

2. Widget Props Structure

3. Callback Naming Changes

4. Theme System

5. WidgetProvider Props Update

6. RPC / wagmi transports (Metalayer RPC helpers)

Step-by-Step Migration

Step 1: Update Package Version

Step 2: Update Widget Component Usage

Step 3: Update WidgetProvider Theme

Step 4: Update Token Selection Callbacks

Step 5: Update Controlled Token Selection

New Theme System Features

Predefined Themes

Custom Color Palette

Feature Toggles

Advanced Overrides

Common Integration Updates

RainbowKit

Dynamic.xyz

ConnectKit

TypeScript Updates

Additional Exported Types

Troubleshooting

Best Practices

Documentation Index

​Breaking Changes

​1. External WagmiProvider Required (disableWagmi removed)

​2. Widget Props Structure

​3. Callback Naming Changes

​4. Theme System

​5. WidgetProvider Props Update

​6. RPC / wagmi transports (Metalayer RPC helpers)

​Step-by-Step Migration

​Step 1: Update Package Version

​Step 2: Update Widget Component Usage

​Step 3: Update WidgetProvider Theme

​Step 4: Update Token Selection Callbacks

​Step 5: Update Controlled Token Selection

​New Theme System Features

​Predefined Themes

​Custom Color Palette

​Feature Toggles

​Advanced Overrides

​Common Integration Updates

​RainbowKit

​Dynamic.xyz

​ConnectKit

​TypeScript Updates

​Additional Exported Types

​Troubleshooting

​Best Practices

Breaking Changes

1. External WagmiProvider Required (disableWagmi removed)

2. Widget Props Structure

3. Callback Naming Changes

4. Theme System

5. WidgetProvider Props Update

6. RPC / wagmi transports (Metalayer RPC helpers)

Step-by-Step Migration

Step 1: Update Package Version

Step 2: Update Widget Component Usage

Step 3: Update WidgetProvider Theme

Step 4: Update Token Selection Callbacks

Step 5: Update Controlled Token Selection

New Theme System Features

Predefined Themes

Custom Color Palette

Feature Toggles

Advanced Overrides

Common Integration Updates

RainbowKit

Dynamic.xyz

ConnectKit

TypeScript Updates

Additional Exported Types

Troubleshooting

Best Practices