> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Full reference for all widget configuration options

## Display Options

| Option          | Type                        | Default           | Description                                                                |
| --------------- | --------------------------- | ----------------- | -------------------------------------------------------------------------- |
| `containerId`   | `string`                    | **required**      | DOM element ID to mount into                                               |
| `apiKey`        | `string`                    | —                 | Your API key. Optional — attributes swaps to your account for fee tracking |
| `theme`         | `"dark" \| "light"`         | `"dark"`          | Widget color theme                                                         |
| `mode`          | `"swap" \| "gas" \| "fund"` | `"swap"`          | Initial active mode                                                        |
| `modes`         | `string`                    | `"swap,gas,fund"` | Comma-separated list of enabled modes                                      |
| `width`         | `string`                    | `"420px"`         | Widget width                                                               |
| `height`        | `string`                    | `"700px"`         | Widget height                                                              |
| `hideOnramp`    | `boolean`                   | `false`           | Hide the mode toggle (swap/gas/fund)                                       |
| `hidePoweredBy` | `boolean`                   | `false`           | Hide "Powered by Hypermid"                                                 |

### Mode Control

You can control which modes are available in the widget using the `modes` parameter:

```javascript theme={"system"}
// Show only Swap and Buy Crypto (hide Gas)
HypermidWidget.init({
  containerId: "hypermid-widget",
  modes: "swap,fund",
  mode: "swap",
});
```

```javascript theme={"system"}
// Show only Swap (no mode toggle shown)
HypermidWidget.init({
  containerId: "hypermid-widget",
  modes: "swap",
});
```

When only one mode is enabled, the mode toggle is automatically hidden.

## Chain & Token Presets

| Option              | Type               | Default | Description                                                         |
| ------------------- | ------------------ | ------- | ------------------------------------------------------------------- |
| `defaultFromChain`  | `number \| string` | `1`     | Default source chain — numeric ID or slug                           |
| `defaultToChain`    | `number \| string` | —       | Default destination chain — numeric ID or slug                      |
| `defaultFromToken`  | `string`           | —       | Default source token address                                        |
| `defaultToToken`    | `string`           | —       | Default destination token address                                   |
| `defaultFromAmount` | `string`           | —       | Default input amount                                                |
| `destAddress`       | `string`           | —       | Pre-fill destination/recipient address (overrides connected wallet) |
| `walletAddress`     | `string`           | —       | Pre-fill wallet address                                             |
| `lockFromChain`     | `boolean`          | `false` | Lock source chain selector                                          |
| `lockToChain`       | `boolean`          | `false` | Lock destination chain selector                                     |

<Info>
  The `destAddress` parameter is useful when the destination address differs from the connected wallet — for example, when building a payment flow where users send tokens to a merchant address, or when the recipient is a smart contract.
</Info>

### Chain Identifiers

Hypermid uses a **unified chain ID system**. You can reference chains by either their **numeric ID** or a **human-readable slug**:

| Chain      | Slug         | Chain ID           |
| ---------- | ------------ | ------------------ |
| Ethereum   | `ethereum`   | `1`                |
| Arbitrum   | `arbitrum`   | `42161`            |
| Base       | `base`       | `8453`             |
| Polygon    | `polygon`    | `137`              |
| Optimism   | `optimism`   | `10`               |
| PulseChain | `pulsechain` | `369`              |
| BNB Chain  | `bsc`        | `56`               |
| Avalanche  | `avalanche`  | `43114`            |
| Berachain  | `berachain`  | `80094`            |
| Solana     | `solana`     | `1151111081099710` |
| Bitcoin    | `bitcoin`    | `20000000000001`   |
| Sui        | `sui`        | `9270000000000000` |
| NEAR       | `near`       | `900000001`        |
| TON        | `ton`        | `900000002`        |
| Tron       | `tron`       | `900000003`        |
| XRP        | `xrp`        | `900000004`        |
| Dogecoin   | `doge`       | `900000005`        |
| Aptos      | `aptos`      | `900000010`        |
| zkSync Era | `zksync`     | `324`              |
| Linea      | `linea`      | `59144`            |
| Scroll     | `scroll`     | `534352`           |
| Sonic      | `sonic`      | `146`              |
| Mantle     | `mantle`     | `5000`             |
| Blast      | `blast`      | `81457`            |

<Tip>
  **Use slugs for non-EVM chains** — `"solana"` is much easier to work with than `1151111081099710`. EVM chains can use either format: `defaultFromChain: 1` or `defaultFromChain: "ethereum"`.
</Tip>

For the complete list of all 90+ supported chains, use the [Chains API endpoint](/api-reference/chains) or the [Preset Builder](/widget/preset-builder).

**Example — ETH to USDC on Arbitrum (using slugs):**

```javascript theme={"system"}
HypermidWidget.init({
  containerId: "hypermid-widget",
  defaultFromChain: "ethereum",
  defaultToChain: "arbitrum",
  defaultFromToken: "0x0000000000000000000000000000000000000000", // ETH
  defaultToToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",  // USDC
  lockFromChain: true,
  lockToChain: true,
});
```

**Example — Solana to Bitcoin (non-EVM slugs):**

```javascript theme={"system"}
HypermidWidget.init({
  containerId: "hypermid-widget",
  defaultFromChain: "solana",
  defaultToChain: "bitcoin",
});
```

## Theme Customization

Override any visual aspect of the widget to match your brand:

| Option             | Type     | Default     | Description                                               |
| ------------------ | -------- | ----------- | --------------------------------------------------------- |
| `accentColor`      | `string` | `"#44E1AA"` | Accent & highlight color                                  |
| `buttonColor`      | `string` | —           | CTA button color (overrides gradient)                     |
| `accentHoverColor` | `string` | —           | Accent hover state color                                  |
| `bgCard`           | `string` | `"#0C1022"` | Card background color                                     |
| `bgCardInner`      | `string` | `"#0E1428"` | Inner card / token area background                        |
| `bgInput`          | `string` | `"#111832"` | Input field background                                    |
| `textPrimary`      | `string` | `"#E2E8F0"` | Primary text color                                        |
| `textSecondary`    | `string` | `"#8A9AB4"` | Secondary text color                                      |
| `borderColor`      | `string` | —           | Border color (format: `"hex:opacity"` e.g. `"6C63FF:15"`) |
| `borderRadius`     | `number` | `16`        | Card corner radius in px                                  |
| `buttonRadius`     | `number` | `12`        | Button corner radius in px                                |
| `fontFamily`       | `string` | `"Sora"`    | Google Font family name                                   |

### Border Color Format

The `borderColor` option uses a special `hex:opacity` format where opacity is a percentage (0–100):

```javascript theme={"system"}
// Blue border at 10% opacity
borderColor: "416EF2:10"

// Purple border at 15% opacity
borderColor: "6C63FF:15"

// Simple solid hex (100% opacity)
borderColor: "333333"
```

### Font Family

Any [Google Font](https://fonts.google.com/) is supported. The widget dynamically loads the font when specified. Popular choices:

`Sora` (default), `Inter`, `Poppins`, `Space Grotesk`, `DM Sans`, `Roboto`, `Manrope`, `Outfit`, `Plus Jakarta Sans`, `Nunito Sans`, `Work Sans`, `Montserrat`, `Rubik`, `Figtree`, `Lexend`

### Full Branding Example

```javascript theme={"system"}
HypermidWidget.init({
  containerId: "swap",
  apiKey: "sk_live_your_key",
  theme: "dark",
  defaultFromChain: 1,
  defaultToChain: 42161,
  // Brand customization
  accentColor: "#FF6B35",
  buttonColor: "#FF6B35",
  bgCard: "#252540",
  bgCardInner: "#2D2D55",
  bgInput: "#35356A",
  textPrimary: "#FFFFFF",
  textSecondary: "#A0A0C0",
  borderColor: "FF6B35:12",
  borderRadius: 20,
  buttonRadius: 8,
  fontFamily: "Inter",
});
```

### Direct Iframe URL Parameters

When using the direct iframe embed, pass theme options as URL query parameters (hex values without `#`):

```
https://app.hypermid.io/widget?embed=1
  &theme=dark
  &accent=FF6B35
  &buttonColor=FF6B35
  &bgCard=252540
  &borderRadius=20
  &buttonRadius=8
  &fontFamily=Inter
  &destAddress=0x1234...abcd
```

<Tip>
  Use the **[Widget Playground](/widget/playground)** to visually configure all these options and generate the embed code automatically.
</Tip>