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.

Widget Light (@lifi/widget-light) lets you embed the full LI.FI cross-chain swap and bridge widget into your application via an iframe, while keeping wallet connections on your side. Users sign transactions with their existing wallet ā€” the widget never touches browser extensions or private keys directly.

ā€‹
When to Use Widget Light vs the Full Widget

Widget Light (@lifi/widget-light)Full Widget (@lifi/widget)
RenderingRuns inside an iframe hosted at widget.li.fiRenders directly in your React tree
DependenciesZero core dependencies beyond ReactMUI, Zustand, TanStack Router, i18next, and more
Bundle sizeMinimal ā€” only the postMessage bridge ships in your bundleFull widget code is included in your bundle
Wallet ownershipYour app owns all wallet connectionsWidget manages wallets via provider packages
IsolationSandboxed iframe ā€” widget cannot access your DOM or stateShares your React context and DOM
ConfigurationJSON-serializable config only (no React nodes, no MUI themes)Full WidgetConfig with React nodes, callbacks, and MUI theming
Framework supportAny framework that can render an iframeReact 18+ only
Choose Widget Light when you want strong isolation between the widget and your app, when you already manage wallets and want to keep that control, or when you want to minimize your bundle size. Choose the full widget when you need deep UI customization with MUI theming, React node injection, or callback-based configuration.

ā€‹
Architecture

+----------------------------------+       +----------------------------------+
|         YOUR APPLICATION         |       |      IFRAME (widget.li.fi)       |
|                                  |       |                                  |
|  LiFiWidgetLight component       | <---> |  Full LI.FI Widget               |
|  + Ecosystem handlers (wagmi...) | post  |  Receives config, sends RPC      |
|  + Event subscriptions           | Msg   |  requests back to your wallets   |
+----------------------------------+       +----------------------------------+
The communication flow works as follows:
  1. Your app renders <LiFiWidgetLight> which loads the hosted widget URL in an iframe
  2. The iframe sends a READY signal; your app responds with configuration and wallet state
  3. When the widget needs a signature or chain switch, it sends an RPC request via postMessage
  4. Your ecosystem handler (e.g. wagmi for EVM) executes the request and returns the result
  5. Wallet state changes (account switch, network change) are pushed to the iframe automatically
All communication is restricted to the expected origin (https://widget.li.fi by default) for security.

ā€‹
Key Benefits

  • Iframe isolation ā€” the widget runs in a sandboxed iframe; your page stays in full control
  • Zero core dependencies ā€” @lifi/widget-light ships nothing beyond React as a peer dependency; chain-specific handlers are tree-shakeable subpath imports
  • Your wallet, your UX ā€” transactions are signed by wallets you already manage (wagmi, wallet-standard, bigmi, dapp-kit)
  • Reactive configuration ā€” update config at any time without reloading the iframe
  • Typed event system ā€” subscribe to route execution, wallet, and UI events with full TypeScript support

ā€‹
Supported Ecosystems

Widget Light supports five blockchain ecosystems, each through a dedicated handler hook:
EcosystemChain TypeHandlerImport Path
Ethereum (EVM)EVMuseEthereumIframeHandler()@lifi/widget-light/ethereum
SolanaSVMuseSolanaIframeHandler()@lifi/widget-light/solana
BitcoinUTXOuseBitcoinIframeHandler()@lifi/widget-light/bitcoin
SuiMVMuseSuiIframeHandler()@lifi/widget-light/sui
TronTVMuseTronIframeHandler()@lifi/widget-light/tron
You only need to install and use handlers for the ecosystems you support. Unused ecosystem packages are fully tree-shaken from your bundle.

ā€‹
Hosted Widget

The widget iframe loads from https://widget.li.fi by default. You do not need to host or deploy any widget code yourself ā€” the <LiFiWidgetLight> component points to this URL automatically. For testing against a specific version or a self-hosted deployment, pass your custom URL as the src prop.

ā€‹
Next Steps