Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.li.fi/llms.txt

Use this file to discover all available pages before exploring further.

Get up and running with Widget Light in minutes. The core package has zero dependencies beyond React — you only add peer dependencies for the blockchain ecosystems you want to support.

​
Core Package

pnpm add @lifi/widget-light

​
Ecosystem Dependencies

Install the peer dependencies for each blockchain ecosystem you want to support. You only need the ecosystems your application uses.

​
EVM (Ethereum)

pnpm add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query

​
Solana

pnpm add @lifi/widget-light @wallet-standard/base

​
Bitcoin

pnpm add @lifi/widget-light @bigmi/client @bigmi/react

​
Sui

pnpm add @lifi/widget-light @mysten/dapp-kit-react

​
Tron

The Tron handler is library-agnostic — you pass wallet state explicitly. Only @lifi/widget-light is required for that API. If you follow the documented integration using @tronweb3/tronwallet-adapter-react-hooks, install it alongside the core package: 
pnpm add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks

​
All Ecosystems

To install everything at once: 
pnpm add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query @wallet-standard/base @bigmi/client @bigmi/react @mysten/dapp-kit-react @tronweb3/tronwallet-adapter-react-hooks

​
Quick Start — EVM Only (wagmi)

This is the minimal setup for EVM chains using wagmi. It assumes you already have a wagmi provider configured in your app.

​
1. Configure your wallet provider

Set up wagmi as you normally would. Widget Light reads wallet state from your existing wagmi context. 
// providers/WalletProvider.tsx
import type { FC, PropsWithChildren } from 'react'
import { createClient, http } from 'viem'
import { arbitrum, base, mainnet, optimism, polygon } from 'viem/chains'
import { createConfig, WagmiProvider } from 'wagmi'
import { injected } from 'wagmi/connectors'

const config = createConfig({
  chains: [mainnet, arbitrum, optimism, base, polygon],
  connectors: [injected()],
  client({ chain }) {
    return createClient({ chain, transport: http() })
  },
  multiInjectedProviderDiscovery: true,
  ssr: false,
})

export const WalletProvider: FC<PropsWithChildren> = ({ children }) => (
  <WagmiProvider config={config}>{children}</WagmiProvider>
)

​
2. Set up the provider tree

// main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import React from 'react'
import ReactDOM from 'react-dom/client'
import { App } from './App'
import { WalletProvider } from './providers/WalletProvider'

const queryClient = new QueryClient()

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <App />
      </WalletProvider>
    </QueryClientProvider>
  </React.StrictMode>
)

​
3. Render the widget

// App.tsx
import { LiFiWidgetLight } from '@lifi/widget-light'
import type { WidgetLightConfig } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useMemo } from 'react'

const widgetConfig: WidgetLightConfig = {
  integrator: 'your-project-name',
  variant: 'wide',
  theme: {
    container: {
      border: '1px solid rgb(234, 234, 234)',
      borderRadius: '16px',
    },
  },
}

export function App() {
  const ethHandler = useEthereumIframeHandler()
  const handlers = useMemo(() => [ethHandler], [ethHandler])

  return (
    <LiFiWidgetLight
      config={widgetConfig}
      handlers={handlers}
      autoResize
    />
  )
}
The widget renders inside an iframe and all EVM transactions are signed through your wagmi-managed wallet.

​
Full Multi-Ecosystem Setup

To support Solana, Bitcoin, Sui, and Tron alongside EVM, install the additional handler peer dependencies and pass all handlers to the widget. 
import { LiFiWidgetLight } from '@lifi/widget-light'
import type { WidgetLightConfig } from '@lifi/widget-light'
import { useEthereumIframeHandler } from '@lifi/widget-light/ethereum'
import { useSolanaIframeHandler } from '@lifi/widget-light/solana'
import { useBitcoinIframeHandler } from '@lifi/widget-light/bitcoin'
import { useSuiIframeHandler } from '@lifi/widget-light/sui'
import { useTronIframeHandler } from '@lifi/widget-light/tron'
import { useMemo } from 'react'

const widgetConfig: WidgetLightConfig = {
  integrator: 'your-project-name',
  variant: 'wide',
}

export function App() {
  // EVM -- reads wallet state from wagmi context automatically
  const ethHandler = useEthereumIframeHandler()

  // Solana -- pass wallet state explicitly (library-agnostic)
  const solHandler = useSolanaIframeHandler({
    address: solanaAddress,       // string | null
    connected: solanaConnected,   // boolean
    wallet: solanaWallet,         // Wallet from @wallet-standard/base | null
  })

  // Bitcoin -- reads from @bigmi/react context automatically
  const btcHandler = useBitcoinIframeHandler()

  // Sui -- reads from @mysten/dapp-kit-react context automatically
  const suiHandler = useSuiIframeHandler()

  // Tron -- pass wallet state explicitly (library-agnostic)
  const tronHandler = useTronIframeHandler({
    address: tronAddress,         // string | null
    connected: tronConnected,     // boolean
    adapter: tronAdapter,         // TronAdapter | null
  })

  const handlers = useMemo(
    () => [ethHandler, solHandler, btcHandler, suiHandler, tronHandler],
    [ethHandler, solHandler, btcHandler, suiHandler, tronHandler]
  )

  return (
    <LiFiWidgetLight
      config={widgetConfig}
      handlers={handlers}
      autoResize
    />
  )
}
Only include the handlers you need. If you only support EVM and Solana, pass [ethHandler, solHandler]. Unused ecosystem packages are fully tree-shaken from your bundle.

​
TypeScript Support

Widget Light is written in TypeScript and provides full type definitions. All configuration options, event payloads, and handler interfaces are fully typed: 
import type { WidgetLightConfig } from '@lifi/widget-light'

const config: WidgetLightConfig = {
  // TypeScript will provide autocomplete and type checking
  integrator: 'my-dapp',
  appearance: 'dark',
  variant: 'wide',
}