@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
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 app renders
<LiFiWidgetLight>which loads the hosted widget URL in an iframe - The iframe sends a
READYsignal; your app responds with configuration and wallet state - When the widget needs a signature or chain switch, it sends an RPC request via
postMessage - Your ecosystem handler (e.g. wagmi for EVM) executes the request and returns the result
- Wallet state changes (account switch, network change) are pushed to the iframe automatically
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-lightships 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:
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 fromhttps://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
- Install Widget Light ā set up the package and dependencies
- Configure Widget Light ā learn about all configuration options
- Widget Light Events ā subscribe to widget events
- Widget Light Wallet Management ā understand ecosystem handlers
- Widget Light API Reference ā full component and hook reference