> ## 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 API Reference

> API documentation for the widget components and hooks.

## Widget Component

Properties and types of the `LiFiWidget` component configuration.

```typescript theme={"system"}
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

```typescript theme={"system"}
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                   |

```typescript theme={"system"}
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            |

```typescript theme={"system"}
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       |

```typescript theme={"system"}
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

```typescript theme={"system"}
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

```typescript theme={"system"}
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

```typescript theme={"system"}
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):

```typescript theme={"system"}
interface DisabledUIConfig {
  fromAmount?: boolean
  fromToken?: boolean
  toAddress?: boolean
  toToken?: boolean
}
```

### HiddenUIConfig

Hide specific UI elements completely:

```typescript theme={"system"}
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:

```typescript theme={"system"}
interface RequiredUIConfig {
  accountDeployedMessage?: boolean
  toAddress?: boolean
}
```

### DefaultUI

Configure default UI states:

```typescript theme={"system"}
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       |

```typescript theme={"system"}
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 |

```typescript theme={"system"}
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   |

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

<Note>
  In Widget v4, `disableMessageSigning` has moved from `sdkConfig.executionOptions` to the `EthereumProvider` configuration. See [Wallet Management](/widget/wallet-management) for details.
</Note>

***

## 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   |

```typescript theme={"system"}
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     |

```typescript theme={"system"}
type ExplorerUrl = string | {
  url: string
  txPath?: string      // Default: '/tx/'
  addressPath?: string // Default: '/address/'
}
```

***

## Route Labels

Add custom labels to routes:

```typescript theme={"system"}
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         |

```typescript theme={"system"}
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

```typescript theme={"system"}
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

```typescript theme={"system"}
interface WidgetDrawer {
  isOpen(): boolean
  toggleDrawer(): void
  openDrawer(): void
  closeDrawer(): void
}
```

***

## Exported Hooks

### From `@lifi/widget`

| 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                             |

### From `@lifi/widget-provider`

| 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 |

### From `@lifi/widget-provider-ethereum`

| 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               |

### From `@lifi/widget-provider-solana`

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

### From `@lifi/widget-provider-bitcoin`

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

### From `@lifi/widget-provider-sui`

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

### From `@lifi/widget-provider-tron`

| 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 |