> ## 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.
# Migrate from v2 to v3
> Migration guide for upgrading LI.FI Widget v2 to v3
Looking for the latest migration guide? See [Migrate from v3 to v4](/widget/migrate-from-v3-to-v4) for upgrading to the current version.
## Overview
**LI.FI Widget v3** introduces a comprehensive overhaul of its core, enhancing compatibility with popular account management libraries like [Wagmi](https://wagmi.sh/) and [RainbowKit](https://www.rainbowkit.com/) and incorporating many new features, including multi-ecosystem support starting with [Solana](https://github.com/anza-xyz/wallet-adapter). Therefore, there are some breaking changes and deprecations to be aware of, as outlined in this guide. Additionally, we encourage you to read the updated documentation, which includes new features that are not mentioned here.
To get started, install the latest version of Widget.
```typescript yarn theme={"system"}
yarn add @lifi/widget
```
```typescript pnpm theme={"system"}
pnpm add @lifi/widget
```
```typescript bun theme={"system"}
bun add @lifi/widget
```
```typescript npm theme={"system"}
npm install @lifi/widget
```
## Configuration
### Renamed variants
The following widget variants were renamed to better reflect their functionality:
`default` is now `compact`
`expandable` is now `wide`
See [Select Widget Variants](/widget/select-widget-layout#variant) for more details.
### Updated toAddress type
In Widget v3 we updated destination wallet functionality to have wallet bookmarks, recently used addresses and more. Previously, the `toAddress` option had a type `string`. To extend the feature in v3 we added a specific type for this field.
```typescript theme={"system"}
// Widget v2
interface WidgetConfig {
// ...
toAddress?: string;
// ...
}
// Widget v3
interface ToAddress {
name?: string;
address: string;
chainType: ChainType;
logoURI?: string;
}
interface WidgetConfig {
// ...
toAddress?: ToAddress;
// ...
}
```
### Updated subvariantOptions type
In Widget v3 we extended the functionality of subvariants and `subvariantOptions` required type update. Previously, `subvariantOptions` supported only `split` subvariant and had `SplitSubvariantOptions` type and now we added support for `custom` subvariant with possibly more subvariant options coming in the future.
```typescript theme={"system"}
// Widget v2
type SplitSubvariantOptions = 'bridge' | 'swap';
interface WidgetConfig {
// ...
subvariantOptions?: SplitSubvariantOptions;
// ...
}
// Widget v3
type SplitSubvariant = 'bridge' | 'swap';
type CustomSubvariant = 'checkout' | 'deposit';
interface SubvariantOptions {
split?: SplitSubvariant;
custom?: CustomSubvariant;
}
interface WidgetConfig {
// ...
subvariantOptions?: SubvariantOptions;
// ...
}
```
### SDK configuration
Following the release of LI.FI SDK v3 there are some changes to SDK configuration in the widget.
`SDKConfig` type is now `WidgetSDKConfig`.
`defaultRouteOptions` renamed to `routeOptions`.
### Removed pre-built drawer button
Previously in Widget v2 there were two ways of controlling the drawer. The first one was pre-built button which came with drawer variant to open and close it. The second one was hiding the button via `hiddenUI` option and controlling the drawer by attaches the ref. Since the title and positioning often required some adjustments we decided to remove pre-built drawer button in favor of controlling the drawer with external button.
Here is the example of controlling the drawer with ref and you can customize the button as you like.
```typescript theme={"system"}
export const WidgetPage = () => {
const drawerRef = useRef(null);
const toggleWidget = () => {
drawerRef.current?.toggleDrawer();
};
return (
);
}
```
We also removed `HiddenUI.DrawerButton` option since there is no default button anymore. However, we added a new option `HiddenUI.DrawerCloseButton` to hide the close button inside the drawer.
### Theming
In Widget v3, we revamped customization and theming possibilities and did a small cleanup.
The top-level `containerStyle` option is moved under the umbrella of the `theme` option and was renamed to `container`.
```typescript theme={"system"}
// Widget v2
export const WidgetPage = () => {
return (
);
};
// Widget v3
export const WidgetPage = () => {
return (
);
};
```
Also, `theme` option type was renamed from `ThemeConfig` to `WidgetTheme`.
Please check out more in [Customize Widget](/widget/customize-widget) section.
### Miscellaneous
`disableLanguageDetector` configuration option was removed. Language detection should now be inherited from the integration dApp.
## Wallet Management
### Moved from Ethers.js to Wagmi
We dropped support for Ethers.js. Instead, Widget now has a first-class Wagmi and all Wagmi-based libraries support like RainbowKit. You can still use Ethers.js in your project and convert Signer/Provider object to use Wagmi's [injected](https://wagmi.sh/react/api/connectors/injected) connector before wrapping the Widget with [WagmiProvider](https://wagmi.sh/react/api/WagmiProvider). However, we suggest moving your dApp's wallet management to use Wagmi as a more future proof solution.
#### Widget v2 setup with Ethers.js
```typescript theme={"system"}
import { LiFiWidget, WidgetConfig } from '@lifi/widget';
export const WidgetPage = () => {
const { account, connect, disconnect, switchChain } = useWallet();
const widgetConfig = useMemo((): WidgetConfig => {
return {
walletManagement: {
signer: account.signer,
connect: async () => {
const signer = await connect();
return signer;
},
disconnect: async () => {
await disconnect();
},
switchChain: async (chainId: number) => {
await switchChain(chainId);
if (account.signer) {
return account.signer;
} else {
throw Error('No signer object is found after the chain switch.');
}
},
},
};
}, [account.signer, connect, disconnect, switchChain]);
return (
);
}
```
#### Widget v3 setup with Wagmi
No more complicated callbacks, just wrap the Widget in `WagmiProvider` and you are set. If you already have one in your dApp, just make sure to keep the Wagmi chains configuration in sync with the Widget chain list, so all functionality like switching chains can keep working.
See [Wallet Management](/widget/wallet-management) for more details.
```typescript theme={"system"}
import { LiFiWidget } from '@lifi/widget';
import { createClient } from 'viem';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { mainnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';
const wagmiConfig = createConfig({
// Make sure to provide the full list of chains
// you would like to support in the Widget
// and keep them in sync, so all functionality
// like switching chains can work correctly.
chains: [mainnet],
connectors: [injected()],
client({ chain }) {
return createClient({ chain, transport: http() });
},
});
export const WidgetPage = () => {
return (
);
};
```
### Updated wallet management configuration
Since we don't need to provide callbacks and signers to widget configuration, `walletManagement` option was renamed to `walletConfig` and now has the following interface:
```typescript theme={"system"}
interface WidgetWalletConfig {
// Can be used to open the external wallet menu,
// if the user is not connected and dApp uses external wallet management
onConnect(): void;
// Provide your projectId and other WalletConnect properties
// when using Widget's internal wallet management
walletConnect?: WalletConnectParameters;
// Provide your app name and other Coinbase properties
// when using Widget's internal wallet management
coinbase?: CoinbaseWalletParameters;
}
```
## Dependencies
### Wagmi is a new peer dependency
Since we moved from `ethers.js` to `Wagmi` we added it to our peer dependencies.
### Dropped CommonJS support
LI.FI Widget v3 no longer publishes a separate CommonJS build since most of the modern front-end tooling supports ESM and ESM is the future. See [Sindre Sorhus' guide](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) for more info about switching to ESM.