Configuration - Trails

Focused components

Shared props

All focused components accept these optional props in addition to their mode-specific props.

Appearance

Prop	Type	Default	Description
`theme`	`"light" \| "dark" \| "auto"`	`"auto"`	Color theme; `auto` follows system preference
`customCss`	`string \| Record<string, string>`	—	Custom CSS to inject into the widget
`disableCss`	`boolean`	`false`	Disable default CSS injection
`renderInline`	`boolean`	`false`	Render inline instead of as a modal
`buttonText`	`string`	—	Custom CTA button text

App metadata

Used in wallet connection dialogs (WalletConnect, etc.):

appMetadata={{
  name: "My App",
  url: "https://myapp.com",
  imageUrl: "https://myapp.com/logo.png",
  description: "Short description",
}}

Wallet options

Prop	Type	Description
`walletConnectProjectId`	`string`	WalletConnect project ID
`walletOptions`	`string[]`	Wallet connector IDs to show (e.g. `["metamask", "walletconnect"]`)
`adapters`	`TrailsAdapterEntry[]`	Explicit wallet runtime adapters. Use `wagmiAdapter` from `@0xtrails/adapter-wagmi` to share an existing wagmi session, or build your own with `evmAdapter`. See Adapters.
`hideAddWallet`	`boolean`	Hide “Add wallet” option
`isSmartWallet`	`boolean`	Signal that the connected wallet is a smart wallet

The wagmiConnectors and decoupleWagmi props were removed in 0xtrails@0.16.0. Wagmi is no longer required by default — pass adapters on the widget’s adapters prop instead. See Adapters.

Route options

Prop	Type	Description
`slippageTolerance`	`number \| string`	Slippage tolerance (e.g. `0.005` for 0.5%)
`swapProvider`	`RouteProvider`	Preferred same-chain swap provider
`swapProviderFallback`	`boolean`	Fall back if preferred swap provider is unavailable
`bridgeProvider`	`RouteProvider`	Preferred bridge provider
`bridgeProviderFallback`	`boolean`	Fall back if preferred bridge provider is unavailable
`priceImpactWarningThresholdBps`	`number`	Basis points before showing a price impact warning
`priceImpactWarningMessage`	`string`	Custom price impact warning message
`priceImpactFallbackBridgeUrl`	`string`	URL to redirect when price impact is too high
`intentProtocolVersion`	`IntentProtocolVersion`	Force a specific intent protocol version

Debug / dev

dev={{
  debug: true,
  sequenceIndexerUrl: "https://...",
  trailsApiUrl: "https://...",
}}

General callbacks

These callbacks are available on all focused components (in addition to mode-specific lifecycle callbacks):

Callback	When it fires
`onOpen`	Widget modal opens
`onClose`	Widget modal closes
`onOriginConfirmation`	Origin-chain transaction confirmed
`onDestinationConfirmation`	Destination-chain transaction confirmed
`onQuote`	Quote is received
`onSignRequest`	Wallet signature requested
`onSign`	Wallet signature obtained
`onSignReject`	User rejected the signature
`onApproveRequest`	ERC-20 approval requested
`onApprove`	ERC-20 approval confirmed
`onApproveReject`	User rejected the approval
`onStatus`	Transaction status update

ChainIdentifier

All chain fields accept a ChainIdentifier, which can be:

A chain name string: "base", "ethereum", "polygon", "arbitrum", "optimism", "avalanche", "bsc", "katana", etc.
A numeric chain ID: 8453, 1, 137, etc.
A viem Chain object

PaymentMethod

The paymentMethod prop on focused components accepts:

Value	Method
`"CONNECTED_WALLET"`	Connected wallet (default when omitted)
`"CRYPTO_TRANSFER"`	QR code / address deposit
`"CREDIT_DEBIT_CARD"`	Fiat on-ramp (credit/debit card)
`"EXCHANGE"`	CEX transfer (Coinbase, Binance, etc.)

Mode-specific props

See the individual mode pages for full prop details:

Pay — to.recipient, to.currency, to.chain, to.amount, payMessage, onPaymentStart/Success/Error
Fund — to, fundMethodsList, hideUnlistedFundMethods, hideSwap, onFundingStart/Success/Error
Swap — from, to, onSwapStart/Success/Error
Withdraw — from, to, onWithdrawStart/Success/Error
Earn — to with calldata, onEarnStart/Success/Error

​Focused components

​Shared props

​Appearance

​App metadata

​Wallet options

​Route options

​Debug / dev

​General callbacks

​ChainIdentifier

​PaymentMethod

​Mode-specific props

Focused components

Shared props

Appearance

App metadata

Wallet options

Route options

Debug / dev

General callbacks

ChainIdentifier

PaymentMethod

Mode-specific props