🎨Customization

WheelX Widget supports both functional configuration and visual customization.

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

WheelX Widget Demowidget.wheelx.fi

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:

WheelX Affiliate — Mutual benefits, shared enjoymentaffiliate.wheelx.fi

---

🌐 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'
    }
  }
}