Customization

WheelX Widget supports both functional configuration and visual customization.

If you want the fastest workflow, start from the hosted theme page:

Recommended workflow:

1. Open the theme page
2. Adjust colors and typography
3. Copy the generated config
4. Paste it into your host app
5. Add functional restrictions such as networks or tokens

🧩 Configuration Overview

The main config type is:

import type { WheelxWidgetConfig } from '@wheelx/widget'

Example:

const widgetConfig: WheelxWidgetConfig = {
  mode: 'bridge-and-swap',
  referralCode: 'your-affiliate-code',
  networks: {
    from: [1, 8453],
    to: [8453, 137]
  },
  defaultTokens: {
    from: {
      chainId: 8453,
      address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
      symbol: 'USDT'
    },
    to: {
      chainId: 8453,
      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
      symbol: 'USDC'
    }
  },
  allowedTokens: {
    from: [
      {
        chainId: 8453,
        tokens: ['0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2']
      }
    ]
  },
  styles: {
    formContainer: {
      backgroundColor: '#0f172a'
    }
  }
}

🔀 mode

Controls the widget flow.

Supported values:

• bridge-and-swap Enables swap, bridge, and cross-chain routing.
• swap Restricts the widget to same-chain swap flows.

Example:

const widgetConfig: WheelxWidgetConfig = {
  mode: 'swap'
}

Use swap when:

• your product only supports a single chain
• you want a simpler UI
• you do not want users switching into bridge routes

💸 referralCode

Adds your affiliate code to widget quote requests.

const widgetConfig: WheelxWidgetConfig = {
  referralCode: 'your-affiliate-code'
}

Good to know:

• the value is trimmed before use
• the widget does not need a separate UI change for referral tracking
• the same config can be combined with theme and token restrictions

You can get your code here:

🌐 networks

Restricts which chains users can choose.

const widgetConfig: WheelxWidgetConfig = {
  networks: {
    from: [1, 8453],
    to: [8453, 137]
  }
}

Supported forms:

• 'all'
• a single chain ID
• an array of chain IDs

Examples:

Allow only Base:

const widgetConfig: WheelxWidgetConfig = {
  networks: {
    from: 8453,
    to: 8453
  }
}

Allow bridge from Ethereum or Base into Base or Polygon:

const widgetConfig: WheelxWidgetConfig = {
  networks: {
    from: [1, 8453],
    to: [8453, 137]
  }
}

Use this when:

• your app only supports a known list of chains
• you want to avoid irrelevant routes
• you want a smaller, more guided selection flow

🪙 defaultTokens

Sets the initial token selection shown in the widget.

const widgetConfig: WheelxWidgetConfig = {
  defaultTokens: {
    from: {
      chainId: 8453,
      address: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
      symbol: 'USDT'
    },
    to: {
      chainId: 8453,
      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
      symbol: 'USDC'
    }
  }
}

Recommended usage:

• prefill the most common trading pair
• match the primary network of your product
• reduce the number of clicks before the user gets a quote

Notes:

• chainId and address are the real identifiers
• symbol is optional, but helpful for readability
• if a default token is not valid under the current restrictions, the widget falls back to the nearest valid option

🔐 allowedTokens

Restricts the selectable tokens on a per-chain basis.

const widgetConfig: WheelxWidgetConfig = {
  allowedTokens: {
    from: [
      {
        chainId: 8453,
        tokens: [
          '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
          '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        ]
      }
    ],
    to: [
      {
        chainId: 8453,
        tokens: [
          '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        ]
      }
    ]
  }
}

This is especially useful when:

• your product should only expose approved assets
• you want to guide users into a narrow route set
• you are embedding the widget for a single token onboarding path

Behavior notes:

• restrictions are chain-scoped
• addresses are normalized internally
• chains not listed remain unrestricted

🎛️ styles

Use styles to override the widget appearance with slot-based style objects.

const widgetConfig: WheelxWidgetConfig = {
  styles: {
    formContainer: {
      backgroundColor: '#081121',
      borderColor: '#24324c'
    },
    formTitleText: {
      color: '#f8fafc'
    },
    primaryButton: {
      background: 'linear-gradient(135deg, #38bdf8 0%, #7c3aed 100%)'
    }
  }
}

Style Areas

The widget supports a broad set of visual slots. In practice, the most useful groups are:

• Form shell formContainer, formTitleText, formFooterText
• Token and input area sectionContainer, tokenSelector, amountInputContainer, amountInputText
• Buttons primaryButton, primaryButtonText, quickHalfButton, quickMaxButton
• Token modal tokenModalContent, tokenModalSearchInput, tokenModalChainPanel, tokenModalTokenPanel
• Slippage controls slippageSettingsTrigger, slippagePopoverContent, slippageAutoButton, slippageCustomInput
• Quote and transaction status quoteInfoContainer, quoteInfoCard, txStateCard, txStatePrimaryButton

Example: Branded Dark Theme

const widgetConfig: WheelxWidgetConfig = {
  referralCode: 'your-affiliate-code',
  styles: {
    formContainer: {
      backgroundColor: '#0b1220',
      borderColor: '#1e293b'
    },
    sectionContainer: {
      backgroundColor: '#111c30',
      borderColor: '#334155'
    },
    formTitleText: {
      color: '#f8fafc'
    },
    tokenPrimaryText: {
      color: '#e2e8f0'
    },
    tokenSecondaryText: {
      color: '#94a3b8'
    },
    primaryButton: {
      background: 'linear-gradient(135deg, #38bdf8 0%, #7c3aed 100%)'
    },
    primaryButtonText: {
      color: '#ffffff'
    }
  }
}