# Customization

WheelX Widget supports both functional configuration and visual customization.

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

{% embed url="<https://widget.wheelx.fi/theme>" %}

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:

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

Example:

```tsx
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:

```tsx
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.

```tsx
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:

{% embed url="<https://affiliate.wheelx.fi/>" %}

***

## 🌐 `networks`

Restricts which chains users can choose.

```tsx
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:

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

Allow bridge from Ethereum or Base into Base or Polygon:

```tsx
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.

```tsx
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.

```tsx
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.

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

```tsx
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'
    }
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wheelx.fi/widget/customization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.