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