Widget API Reference

Properties and types of the LiFiWidget component configuration.

import { LiFiWidget, WidgetConfig } from '@lifi/widget'

const config: WidgetConfig = {
  integrator: 'your-dapp-name',
  // ... other options
}

<LiFiWidget integrator="your-dapp-name" config={config} />

Core Configuration

Name	Type	Default	Description
`integrator`	`string`	Required	Identifier of the integrator (dApp/company name)
`apiKey`	`string`	–	API authentication key
`referrer`	`string`	–	Identifier of the referrer
`feeConfig`	`WidgetFeeConfig`	–	Fee configuration
`providers`	`WidgetProvider[]`	–	Array of blockchain provider components

Form Values (Swap Details)

Name	Type	Default	Description
`fromChain`	`number`	–	Source chain ID
`toChain`	`number`	–	Destination chain ID
`fromToken`	`string`	–	Source token contract address
`toToken`	`string`	–	Destination token contract address
`fromAmount`	`number \| string`	–	Amount to swap
`toAmount`	`number \| string`	–	Expected destination amount
`toAddress`	`ToAddress`	–	Single destination wallet address
`toAddresses`	`ToAddress[]`	–	Curated list of destination addresses
`minFromAmountUSD`	`number`	–	Minimum USD value for fromAmount
`formUpdateKey`	`string`	–	Unique key to force form updates

ToAddress Type

interface ToAddress {
  name?: string        // Display name
  address: string      // Wallet address (required)
  chainType: ChainType // EVM, SVM, UTXO, etc. (required)
  logoURI?: string     // Optional logo
}

Route Configuration

Name	Type	Default	Description
`routePriority`	`Order`	`'RECOMMENDED'`	Route selection priority (`'RECOMMENDED'`, `'CHEAPEST'`, `'FASTEST'`, `'SAFEST'`)
`slippage`	`number`	`0.005`	Default slippage (0.005 = 0.5%)
`showSingleRoute`	`boolean`	`false`	Show only recommended route and hide route selector
`useRelayerRoutes`	`boolean`	`false`	Enable gasless/relayer routes

Filtering Options

Chains

Name	Type	Description
`chains.allow`	`number[]`	Only allow these chain IDs
`chains.deny`	`number[]`	Deny these chain IDs
`chains.from.allow`	`number[]`	Allow only for source chain
`chains.from.deny`	`number[]`	Deny for source chain
`chains.to.allow`	`number[]`	Allow only for destination chain
`chains.to.deny`	`number[]`	Deny for destination chain
`chains.types.allow`	`ChainType[]`	Allow chain types (EVM, SVM, etc.)
`chains.types.deny`	`ChainType[]`	Deny chain types

interface WidgetChains {
  types?: AllowDeny<ChainType>
  allow?: number[]
  deny?: number[]
  from?: AllowDeny<number>
  to?: AllowDeny<number>
}

Tokens

Name	Type	Description
`tokens.allow`	`BaseToken[]`	Only allow these tokens
`tokens.deny`	`BaseToken[]`	Deny these tokens
`tokens.from.allow`	`BaseToken[]`	Allow only for source tokens
`tokens.from.deny`	`BaseToken[]`	Deny for source tokens
`tokens.to.allow`	`BaseToken[]`	Allow only for destination tokens
`tokens.to.deny`	`BaseToken[]`	Deny for destination tokens
`tokens.featured`	`StaticToken[]`	Featured tokens (shown at top)
`tokens.include`	`Token[]`	Additional tokens to include
`tokens.popular`	`StaticToken[]`	Popular tokens section

interface WidgetTokens {
  featured?: StaticToken[]
  include?: Token[]
  popular?: StaticToken[]
  allow?: BaseToken[]
  deny?: BaseToken[]
  from?: AllowDeny<BaseToken>
  to?: AllowDeny<BaseToken>
}

Bridges & Exchanges

Name	Type	Description
`bridges.allow`	`string[]`	Only allow these bridges
`bridges.deny`	`string[]`	Deny these bridges
`exchanges.allow`	`string[]`	Only allow these exchanges
`exchanges.deny`	`string[]`	Deny these exchanges

interface AllowDeny<T> {
  allow?: T[]
  deny?: T[]
}

UI Variants

Name	Type	Default	Description
`variant`	`'compact' \| 'wide' \| 'drawer'`	`'compact'`	Widget layout style
`mode`	`'default' \| 'split' \| 'custom' \| 'refuel'`	`'default'`	Widget mode
`modeOptions`	`ModeOptions`	–	Mode-specific options

ModeOptions

type SplitMode = 'bridge' | 'swap'
type SplitModeOptions = { defaultTab: SplitMode }
type CustomMode = 'checkout' | 'deposit'

interface ModeOptions {
  split?: SplitMode | SplitModeOptions       // For split mode
  custom?: { type: CustomMode }              // For custom mode
}

Appearance & Theme

Name	Type	Default	Description
`appearance`	`'light' \| 'dark' \| 'system'`	`'system'`	Theme mode
`theme`	`WidgetTheme`	–	Theme customization

WidgetTheme

interface WidgetTheme {
  colorSchemes?: {
    light?: { palette: PaletteOptions }
    dark?: { palette: PaletteOptions }
  }
  shape?: Partial<Shape>
  typography?: TypographyVariantsOptions
  components?: WidgetThemeComponents
  container?: CSSProperties
  routesContainer?: CSSProperties
  chainSidebarContainer?: CSSProperties
  header?: CSSProperties
  navigation?: {
    edge?: boolean  // @default true
  }
}

Theme Components

type WidgetThemeComponents = Partial<Pick<Components<Theme>,
  | 'MuiAppBar'
  | 'MuiAvatar'
  | 'MuiButton'
  | 'MuiCard'
  | 'MuiDrawer'
  | 'MuiIconButton'
  | 'MuiInputCard'
  | 'MuiNavigationTabs'
  | 'MuiNavigationTab'
  | 'MuiTabs'
  | 'MuiCheckbox'
>>

UI Control

UI control options use object configs where each key is a UI element and the value is a boolean.

DisabledUIConfig

Disable specific UI elements (still visible but not interactive):

interface DisabledUIConfig {
  fromAmount?: boolean
  fromToken?: boolean
  toAddress?: boolean
  toToken?: boolean
}

HiddenUIConfig

Hide specific UI elements completely:

interface HiddenUIConfig {
  addressBookConnectedWallets?: boolean
  allNetworks?: boolean
  appearance?: boolean
  bridgesSettings?: boolean
  chainSelect?: boolean
  chainSidebar?: boolean    // Hide chain sidebar in wide variant
  contactSupport?: boolean
  drawerCloseButton?: boolean
  fromToken?: boolean
  gasRefuelMessage?: boolean
  hideSmallBalances?: boolean
  history?: boolean
  insufficientGasMessage?: boolean
  integratorStepDetails?: boolean
  language?: boolean
  lowAddressActivityConfirmation?: boolean
  poweredBy?: boolean
  reverseTokensButton?: boolean
  routeCardPriceImpact?: boolean
  routeTokenDescription?: boolean
  searchTokenInput?: boolean
  toAddress?: boolean
  toToken?: boolean
  walletMenu?: boolean
}

RequiredUIConfig

Make specific UI elements required:

interface RequiredUIConfig {
  accountDeployedMessage?: boolean
  toAddress?: boolean
}

DefaultUI

Configure default UI states:

interface DefaultUI {
  transactionDetailsExpanded?: boolean
  navigationHeaderTitleNoWrap?: boolean
}

Internationalization

Name	Type	Description
`languages.default`	`LanguageKey`	Default language
`languages.allow`	`LanguageKey[]`	Only show these languages
`languages.deny`	`LanguageKey[]`	Hide these languages
`languageResources`	`LanguageResources`	Custom translations

type LanguageKey = 
  | 'bn' | 'de' | 'en' | 'es' | 'fr' | 'hi' | 'id' 
  | 'it' | 'ja' | 'ko' | 'pl' | 'pt' | 'th' | 'tr' 
  | 'uk' | 'vi' | 'zh'

Wallet Configuration

Name	Type	Description
`walletConfig.onConnect`	`(args?: WalletMenuOpenArgs) => void`	Callback for connect button
`walletConfig.walletEcosystemsOrder`	`Record<string, ChainType[]>`	Ecosystem order per wallet
`walletConfig.usePartialWalletManagement`	`boolean`	Enable hybrid wallet management
`walletConfig.forceInternalWalletManagement`	`boolean`	Force internal wallet management

interface WidgetWalletConfig {
  onConnect?(args?: WalletMenuOpenArgs): void
  walletEcosystemsOrder?: Record<string, ChainType[]>
  usePartialWalletManagement?: boolean  // @default false
  forceInternalWalletManagement?: boolean  // @default false
}

SDK Configuration

Name	Type	Description
`sdkConfig.rpcUrls`	`Record<number, string[]>`	Custom RPC URLs per chain
`sdkConfig.routeOptions`	`RouteOptions`	Route fetching options
`sdkConfig.executionOptions`	`ExecutionOptions`	Route execution options

interface WidgetSDKConfig {
  rpcUrls?: Record<number, string[]>
  routeOptions?: Omit<RouteOptions, 'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'>
  executionOptions?: {
    updateTransactionRequestHook?: (request: TransactionRequest) => Promise<TransactionRequest>
  }
}

In Widget v4, disableMessageSigning has moved from sdkConfig.executionOptions to the EthereumProvider configuration. See Wallet Management for details.

Fee Configuration

Name	Type	Description
`feeConfig.name`	`string`	Display name for fee
`feeConfig.logoURI`	`string`	Logo URL
`feeConfig.fee`	`number`	Static fee (0-1)
`feeConfig.showFeePercentage`	`boolean`	Show fee percentage in UI
`feeConfig.showFeeTooltip`	`boolean`	Show fee tooltip
`feeConfig.feeTooltipComponent`	`ReactNode`	Custom tooltip component
`feeConfig.calculateFee`	`(params) => Promise<number>`	Dynamic fee calculation

interface WidgetFeeConfig {
  name?: string
  logoURI?: string
  fee?: number
  showFeePercentage?: boolean  // @default false
  showFeeTooltip?: boolean     // @default false
  feeTooltipComponent?: ReactNode
  calculateFee?(params: CalculateFeeParams): Promise<number | undefined>
}

interface CalculateFeeParams {
  fromChain: ExtendedChain
  toChain: ExtendedChain
  fromToken: Token
  toToken: Token
  fromAddress?: string
  toAddress?: string
  fromAmount?: bigint
  toAmount?: bigint
  slippage?: number
}

Explorer URLs

Name	Type	Description
`explorerUrls[chainId]`	`ExplorerUrl[]`	Custom explorer URLs per chain
`explorerUrls.internal`	`ExplorerUrl[]`	Override internal explorer

type ExplorerUrl = string | {
  url: string
  txPath?: string      // Default: '/tx/'
  addressPath?: string // Default: '/address/'
}

Route Labels

Add custom labels to routes:

interface RouteLabelRule {
  label: RouteLabel
  bridges?: AllowDeny<string>
  exchanges?: AllowDeny<string>
  fromChainId?: number[]
  toChainId?: number[]
  fromTokenAddress?: string[]
  toTokenAddress?: string[]
  match?: (route: Route) => boolean
}

interface RouteLabel {
  text: string
  sx?: SxProps<Theme>  // MUI style object
}

Contract Integration

For custom checkout/deposit flows:

Name	Type	Description
`contractCalls`	`ContractCall[]`	Contract calls to execute
`contractComponent`	`ReactNode`	Main custom component
`contractSecondaryComponent`	`ReactNode`	Secondary component
`contractCompactComponent`	`ReactNode`	Compact view component
`contractTool`	`WidgetContractTool`	Tool display info

interface WidgetContractTool {
  name: string
  logoURI: string
}

Form & URL State

Name	Type	Default	Description
`buildUrl`	`boolean`	`false`	Sync widget state to URL
`keyPrefix`	`string`	–	Prefix for multiple widget instances
`formRef`	`RefObject<FormState>`	–	Ref for programmatic form control

FormState

interface FormState {
  setFieldValue: <K extends FieldNames>(
    key: K,
    value: FieldValues[K],
    options?: { setUrlSearchParam: boolean }
  ) => void
}

type FieldNames = 
  | 'fromChain' | 'toChain' 
  | 'fromToken' | 'toToken'
  | 'fromAmount' | 'toAmount' 
  | 'toAddress'

Drawer Props

For variant: 'drawer':

Name	Type	Description
`open`	`boolean`	Controlled open state
`onClose`	`() => void`	Close callback
`elementRef`	`RefObject<HTMLDivElement>`	Ref to drawer element

WidgetDrawer Ref

interface WidgetDrawer {
  isOpen(): boolean
  toggleDrawer(): void
  openDrawer(): void
  closeDrawer(): void
}

Exported Hooks

Hook	Description
`useWidgetEvents`	Subscribe to widget events (returns event emitter)
`useWidgetChains(config)`	Fetch available chains from LI.FI API using a `WidgetConfig`
`useFieldActions`	Access form field actions
`useFieldValues`	Access current form field values

Hook	Description
`useEthereumContext`	Access Ethereum wallet context
`useSolanaContext`	Access Solana wallet context
`useBitcoinContext`	Access Bitcoin wallet context
`useSuiContext`	Access Sui wallet context
`useTronContext`	Access Tron wallet context
`isWalletInstalled`	Check if a specific wallet is installed

Export	Description
`EthereumProvider`	Factory function returning an Ethereum provider component
`createDefaultWagmiConfig`	Create a default Wagmi config with common connectors
`useSyncWagmiConfig`	Hook to sync Wagmi config with LI.FI chains

Export	Description
`SolanaProvider`	Factory function returning a Solana provider component
`useWalletAccount`	Hook to access Solana wallet account

Export	Description
`BitcoinProvider`	Factory function returning a Bitcoin provider component
`createDefaultBigmiConfig`	Create a default Bigmi config

Export	Description
`SuiProvider`	Factory function returning a Sui provider component

Export	Description
`TronProvider`	Factory function returning a Tron provider component
`createTronAdapters`	Create default Tron wallet adapters

Other Options

Name	Type	Default	Description
`poweredBy`	`'default' \| 'jumper'`	`'default'`	Powered by branding style
`routeLabels`	`RouteLabelRule[]`	–	Custom route labels/badges

​Widget Component

​Core Configuration

​Form Values (Swap Details)

​ToAddress Type

​Route Configuration

​Filtering Options

​Chains

​Tokens

​Bridges & Exchanges

​UI Variants

​ModeOptions

​Appearance & Theme

​WidgetTheme

​Theme Components

​UI Control

​DisabledUIConfig

​HiddenUIConfig

​RequiredUIConfig

​DefaultUI

​Internationalization

​Wallet Configuration

​SDK Configuration

​Fee Configuration

​Explorer URLs

​Route Labels

​Contract Integration

​Form & URL State

​FormState

​Drawer Props

​WidgetDrawer Ref

​Exported Hooks

​From @lifi/widget

​From @lifi/widget-provider

​From @lifi/widget-provider-ethereum

​From @lifi/widget-provider-solana

​From @lifi/widget-provider-bitcoin

​From @lifi/widget-provider-sui

​From @lifi/widget-provider-tron

​Other Options

Widget Component

Core Configuration

Form Values (Swap Details)

ToAddress Type

Route Configuration

Filtering Options

Chains

Tokens

Bridges & Exchanges

UI Variants

ModeOptions

Appearance & Theme

WidgetTheme

Theme Components

UI Control

DisabledUIConfig

HiddenUIConfig

RequiredUIConfig

DefaultUI

Internationalization

Wallet Configuration

SDK Configuration

Fee Configuration

Explorer URLs

Route Labels

Contract Integration

Form & URL State

FormState

Drawer Props

WidgetDrawer Ref

Exported Hooks

From `@lifi/widget`

From `@lifi/widget-provider`

From `@lifi/widget-provider-ethereum`

From `@lifi/widget-provider-solana`

From `@lifi/widget-provider-bitcoin`

From `@lifi/widget-provider-sui`

From `@lifi/widget-provider-tron`

Other Options