> ## 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.

# Install Widget Light

> Installation and quick start guide for @lifi/widget-light

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

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light
  ```
</CodeGroup>

## Ecosystem Dependencies

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

### EVM (Ethereum)

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light wagmi viem @wagmi/core @tanstack/react-query
  ```
</CodeGroup>

### Solana

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @wallet-standard/base
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @wallet-standard/base
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @wallet-standard/base
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @wallet-standard/base
  ```
</CodeGroup>

### Bitcoin

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @bigmi/client @bigmi/react
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @bigmi/client @bigmi/react
  ```
</CodeGroup>

### Sui

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @mysten/dapp-kit-react
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @mysten/dapp-kit-react
  ```
</CodeGroup>

### 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`](https://www.npmjs.com/package/@tronweb3/tronwallet-adapter-react-hooks), install it alongside the core package:

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash yarn theme={"system"}
  yarn add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash npm theme={"system"}
  npm install @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```

  ```bash bun theme={"system"}
  bun add @lifi/widget-light @tronweb3/tronwallet-adapter-react-hooks
  ```
</CodeGroup>

### All Ecosystems

To install everything at once:

<CodeGroup>
  ```bash pnpm theme={"system"}
  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
  ```

  ```bash yarn theme={"system"}
  yarn 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
  ```

  ```bash npm theme={"system"}
  npm install @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
  ```

  ```bash bun theme={"system"}
  bun 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
  ```
</CodeGroup>

## 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.

```tsx theme={"system"}
// 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

```tsx theme={"system"}
// 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

```tsx theme={"system"}
// 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.

```tsx theme={"system"}
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
    />
  )
}
```

<Note>
  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.
</Note>

## TypeScript Support

Widget Light is written in TypeScript and provides full type definitions. All configuration options, event payloads, and handler interfaces are fully typed:

```tsx theme={"system"}
import type { WidgetLightConfig } from '@lifi/widget-light'

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