The provider component that sets up the widget context and configuration.
Props Prop Type Description Default Required sdkConfigMetalayerConfig SDK configuration - ✅ themeWidgetTheme Theme configuration for customizing colors, corners, shadows, and more undefined❌ defaultSourceDefaultChainToken Default source chain and token undefined❌ defaultDestinationDefaultChainToken Default destination chain and token undefined❌ enabledChainsChain []Pre-loaded chains (bypasses fetching) undefined❌ onSupportedChainsLoad(chains: Chain[]) => voidCallback when chains are loaded undefined❌ onError(error: Error) => voidError handling callback undefined❌ debugEnabledbooleanEnable debug logging false❌ disableWagmibooleanDisable internal wagmi provider (use when parent provides wagmi) false❌
SDK Configuration Basic Configuration
With Custom Options
< WidgetProvider sdkConfig = { { apiKey: 'your-api-key' , environment: 'mainnet' , // or 'testnet' } } >
The defaultOptions configuration is optional. When not specified, the widget will display all supported chains and use default quote preference.
Default Source and Destination < WidgetProvider defaultSource = { { chainId: 1 , // Ethereum Mainnet tokenAddress: '0x0000000000000000000000000000000000000000' , // ETH } } defaultDestination = { { chainId: 33139 , // ApeChain tokenAddress: '0x0000000000000000000000000000000000000000' , // ETH } } >
Chain Loading Callback < WidgetProvider onSupportedChainsLoad = { ( chains ) => { // Use chains with your wallet provider const viemChains = chainsToViemChains ( chains ); updateWalletConfig ( viemChains ); } } >
📋 Note : The WidgetProvider automatically sets up a wagmi context internally with the supported chains. The onSupportedChainsLoad callback is provided for external wallet providers that need chain configuration (e.g., Dynamic.xyz). If using an external wagmi provider (e.g., Privy), set disableWagmi={true} to use the parent’s wagmi configuration.
Theme Configuration The widget supports extensive theming options including predefined themes, custom colors, fonts, and advanced overrides.
See the Theming
The main UI component that renders the bridge interface.
Props See WidgetProps
< Widget onConnectClick = { () => openWalletModal () } onDisconnectClick = { () => disconnect () } solanaSigner = { solanaSigner } />
Type Definitions SDK configuration object. See MetalayerConfig
Property Type Description Default Required onConnectClick() => voidCallback when user clicks connect - ✅ onDisconnectClick() => voidCallback when user clicks disconnect. When provided, widget manages wallet connection internally undefined❌ onTransactionSubmitted(sourceChainId?: number, destChainId?: number, amount?: string) => voidCallback when user submits a transaction undefined❌ onTokenSelected(direction: 'source' | 'destination', chainId: number, tokenAddress: string) => voidCallback when user selects a token undefined❌ source{ chainId: number; tokenAddress?: string }Controlled source chain and token undefined❌ destination{ chainId: number; tokenAddress?: string }Controlled destination chain and token undefined❌ isConnectingbooleanWhether a wallet is connecting false❌ solanaSignerWidgetSolanaSigner Solana wallet signer for Solana transactions undefined❌ classNamestringCSS class name for custom styling undefined❌
When onDisconnectClick is provided, the widget manages wallet connection state internally and displays wallet info in the settings tab. If your page already handles wallet connect/disconnect logic, you don’t need to set this prop; the widget will work with your existing wallet connection management.
import type { WidgetProps } from '@metalayer/widget' ;
Property Type Description Default Required addressstringSolana wallet address - ✅ isConnected() => booleanFunction that returns whether the wallet is connected - ✅ signTransaction(transaction: Transaction) => Promise<Transaction>Function to sign a Solana transaction - ✅
const solanaSigner = { address: wallet . publicKey . toString (), isConnected : () => wallet . connected , signTransaction : async ( transaction ) => await wallet . signTransaction ( transaction ), };
DefaultChainToken interface DefaultChainToken { chainId : number ; tokenAddress : string ; }
Property Type Description Default Required chainIdnumberChain ID of the default network - ✅ tokenAddressstringToken contract address - ✅
Utility Functions The widget provides utility functions for chain conversion. For detailed documentation and usage examples, see the SDK Utilities section:
CSS Styling The widget requires a CSS import for proper styling:
import '@metalayer/widget/styles.css' ;
Error Handling Error Callback Handle errors in the widget through the onError callback:
< WidgetProvider onError = { ( error ) => { console . error ( 'Widget error:' , error ); // Handle error (show toast, log to service, etc.) } } >
