Configure Widget
Flexibility at your fingertips
Last updated
Was this helpful?
Flexibility at your fingertips
Last updated
Was this helpful?
The LI.FI Widget supports a range of configuration options, allowing you to:
Allow or deny specific chains, tokens, bridges, and exchanges.
Preselect default source and destination chains.
Choose default tokens for both source and destination.
Set the amount of the destination token.
Specify a destination address.
Customize various settings through the sdkConfig
configuration.
These options enable precise control over the widget's behavior and improve the user experience by adjusting it to specific needs and preferences.
The LI.FI Widget is built on top of the LI.FI SDK, leveraging its robust functionality for cross-chain swaps and bridging. The sdkConfig
option allows you to configure various aspects of the SDK directly within the widget.
Let's look at the example of configuring private RPC endpoints using the sdkConfig
option.
Please see other SDK configuration options in the Configure SDK section.
The LI.FI Widget uses a number of form values that are used to fetch and execute routes.
These values are fromAmount, fromChain, fromToken, toChain, toToken and toAddress.
They are most often set by using the Widget UI but they can also be initialized and updated programmatically.
By configuring these options, you can streamline the user experience, ensuring that the widget is preloaded with the desired chains, tokens, amount and address for a swap or bridge. This reduces the need for manual input and helps guide users through the intended flow.
You can initialize these values by either:
Widget config - by adding fromAmount, fromChain, fromToken, toChain, toToken or toAddress values to the widget config.
URL search params - when buildUrl
in the widget config is set to true
, by adding them to the URL search params in the url of the page the widget is featured on.
When setting form values via config or URL search params you will see any corresponding form field UI updated to reflect those values.
The LI.FI Widget allows you to preconfigure default chains and tokens, making it easy to set up your desired swap or bridging parameters right from the start. Below is an example of how to configure the widget with specific default chains, tokens, amount, and send to address values.
To initialize form values in the widget using URL search params you will need to ensure that buildUrl
is set to true
in the widget config.
You can then feature the URL search params in the URL when navigating to the page that features the widget.
Its important to understand this will only work for the widgets initialization - dynamically changing the search params in the URL without a page load will not cause an update of the form values in the widget.
After the widget has initialized there are two ways you can update the form values in the widget
Using the widget config - this uses reactive values in the config and requires some management of those values for updates
Using the formRef - this provides an function call that you can use to update values in the widgets form store.
Once the widget has initialized you can update the form values in the widget by updating the widget config.
To perform an update you should only include the form values in the config that you want to change and ensure these changes are passed to the Widget.
For example, if you want to change the fromChain and fromToken and nothing else you should include only include those values
In addition to the form values you want to change you should also set a formUpdateKey. This needs to be a unique, randomly generated string and is used to ensure that the form values are updated in the widget - essentially forcing an update. This can avoid some edge case issues that might arise when setting values in the widget via a mix of config and user actions via the widgets UI.
Here is an example of what your config would look like.
You can also reset the form values and their fields to an empty state using undefined
. This example resets only the fromChain and fromToken form values.
Here undefined
used to reset a the widgets form value to an empty state. The absence of a property from the widget config object means that property will remain unchanged.
When using config to update widgets form values it is often a good choice to consider using an application state management library to store your widget config. There are many options to choose from such as Zustand, MobX, Redux or even React context.
For example, if you were to use Zustand as your state management tool you could use Zustand’s API to access and set values on your config from any part of your application. In addition you would also be able to use Zustand’s equality functionality, such as the built-in shallow
function, to ensure that your widget config is only used to update the instance of the LiFi Widget when necessary. This should be beneficial for optimizing re-renders.
This method provides developers a way to set the form values directly in the widget without making changes to the widget config. By passing a ref object to the widget you can access a function to set values directly on the widgets form state. See the example below.
Notice the use of setFieldValue
function.
Once initialized the setFieldValue
function can be called to set the form value, note that setUrlSearchParam
will ensure the url is updated if you have buildUrl
set to true
in your widget config.
Here are some examples of usage.
fromChain and fromToken can be set independently but you might also find that you want to set them at the same time
To reset fromChain and fromToken
We provide allow
and deny
configuration options to control which chains, tokens, bridges, and exchanges can be used within your application. Here’s how you can set up and use these options:
Apart from the allow
and deny
options, the tokens
option can be configured to include other tokens or featured tokens that will appear at the top of the corresponding list of tokens.
There are use cases where users need to have a different destination address. Usually, they can enter the destination address independently.
Still, the widget also has configuration options to pre-configure the destination address or create a curated list of wallet addresses to choose from.
Developers can use the toAddress
option to configure a single destination address. The address
and chainType
properties are required, while the name
and logoURI
properties are optional.
Developers can use toAddresses
option to configure a curated list of wallet addresses.
Using this configuration, when users click on the Send to wallet
button, they will open a pre-configured list of addresses from which to choose, skipping the step where they can manually enter the address.
We have default behaviors in relation to opening explorers and we can also use widget config to override and change these behaviors.
Often when trying to direct a user to an explorer the widget will know which chain relates to a transaction or address and it will present an explorer that matches that chain.
For example, after the user has executed a transaction, on the transaction details page they can click on the "Token allowance approved" explorer button to see more detail about that approval. If the approval was done using the Optimism chain then a new tab would open taking the user to optimistic.etherscan.io to show them more information about that approval.
If no explorer can be found in relation to a chain then the user will be directed to LiFi’s explorer.
An internal explorer is an explorer that is the preferred choice of an organization that is building an app using the widget. In some parts of the widget we use an internal explorer rather than attempting to find an explorer for a specific chain.
It's possible to override the explorer URLs that widget uses via the widget config. We can do this for specific chains and for the internal explorer. You can use your own explorer urls for multiple chains and at the same time state your own alternative for the internal explorer.
In the widget config you can override chains by adding an entry to the explorerUrls object: you provide the chain id as a key and the base url of the explorer as the value.
The explorer specified above will be used only for that chain, in the above example this would be Arbitrum. For other chains that aren’t specified in the explorerUrls object the widget will still present the default behavior (as stated above).
In the widget config you can override the internal explorer by adding an entry to the explorerUrls object: you provide internal
as a key and the base url of the explorer as the value.
Any places within the widget that use the internal explorer will now use the url stated in the config rather than the default.
The widget assumes that the explorer will provide pages for addresses at/address/:address
and for transactions at /tx/:hash
and will attempt to navigate the user to those pages when the users clicks the related buttons.
A link to a wallet address would look like:
And a link to a transaction would look like:
The widget assumes that any explorer used with the widget will follow this convention.
You can find an example that uses in the widget repository.
Together with configuring the wallet list, developers can make the destination address required to be filled out. Please see for more details.
In the widget there are numerous points where a user can click to open an explorer in a separate browser tab in order to find out more information about a transaction or an address. Any buttons or links in the widget that present this icon will direct the user to an explorer.
For example, once the user has completed a transaction and is on the transaction details page they are presented with a transfer ID (see below). This is accompanied by a link which allows the user to open an explorer in order to find more information about that transaction. There is no attempt to find a chain specific explorer. The default explorer used is LI.FI own internal explorer and users will be directed to