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

# Widget Overview

> Drop-in swap widget you embed into any website with a single iframe

## What is the Houdini Widget?

The Houdini Widget is a pre-built, hosted swap interface that you embed into any website or web application with a single `<iframe>`. It renders the full Houdini swap experience — no backend and no API key required for a basic embed.

You control which features appear and preselect the swap pair through URL parameters on the iframe `src`.

<Card title="Try the Widget Playground" icon="play" href="https://widget-playground.houdiniswap.com/">
  Configure the widget visually, preview it live, and copy a ready-to-paste embed snippet.
</Card>

## Key Features

<CardGroup cols={2}>
  <Card title="Drop-in Integration" icon="puzzle-piece">
    Add a full-featured swap interface in minutes with a single iframe
  </Card>

  <Card title="Configurable via URL" icon="sliders">
    Preselect tokens and show or hide tabs with simple query parameters
  </Card>

  <Card title="All Route Types" icon="route">
    Supports private, semi-private, and DEX swaps out of the box
  </Card>

  <Card title="Responsive Design" icon="mobile">
    Works on desktop, tablet, and mobile devices
  </Card>

  <Card title="Auto-Updated" icon="arrows-rotate">
    Maintained and updated by Houdini - always current
  </Card>

  <Card title="No Backend Required" icon="server">
    The widget handles all swap logic - no server or API key needed to embed
  </Card>
</CardGroup>

## Quick Start

### Embed with an iframe

Add the widget to your page in 2 steps:

<Steps>
  <Step title="Copy the iframe">
    ```html theme={null}
    <iframe
      src="https://app.houdiniswap.com/widget"
      width="480"
      height="640"
      title="Houdini Exchange Widget"
      allow="clipboard-write"
    />
    ```
  </Step>

  <Step title="Paste it into your page">
    Drop the snippet anywhere in your HTML. Adjust `width` and `height` to fit
    your layout. That's it — the widget is live.
  </Step>
</Steps>

## Configuration (URL parameters)

Append query parameters to the iframe `src` to preselect tokens and control which tabs are visible. You can build and preview these combinations in the [Widget Playground](https://widget-playground.houdiniswap.com/).

| Parameter       | Values                    | Default | Effect                                                                                                                                                        |
| --------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `widgetMode`    | `true` / `1`              | off     | Enables widget mode (hides the "Powered By" and "New" badges). The `/widget` route is always in widget mode; use this flag only when embedding another route. |
| `tokenIn`       | Token symbol (e.g. `ETH`) | —       | Preselects the input ("from") token                                                                                                                           |
| `tokenOut`      | Token symbol (e.g. `SOL`) | —       | Preselects the output ("to") token                                                                                                                            |
| `hideSwap`      | `true`                    | Visible | Hides the **Swap** tab                                                                                                                                        |
| `hideMultiswap` | `true`                    | Visible | Hides the **Multiswap** tab                                                                                                                                   |
| `hideSend`      | `true`                    | Visible | Hides the **Send** tab                                                                                                                                        |

<Note>
  Tab parameters are **opt-out**: every tab is shown by default, and you set
  `=true` to hide the ones you don't want. There is no "include" parameter.
</Note>

### Examples

Preselect an ETH → SOL swap:

```html theme={null}
<iframe
  src="https://app.houdiniswap.com/widget?tokenIn=ETH&tokenOut=SOL"
  width="480"
  height="640"
  title="Houdini Exchange Widget"
  allow="clipboard-write"
/>
```

Show only the Swap tab (hide Multiswap and Send):

```html theme={null}
<iframe
  src="https://app.houdiniswap.com/widget?hideMultiswap=true&hideSend=true"
  width="480"
  height="640"
  title="Houdini Exchange Widget"
  allow="clipboard-write"
/>
```

Everything combined — widget mode, ETH → SOL preselected, Swap tab only:

```html theme={null}
<iframe
  src="https://app.houdiniswap.com/widget?widgetMode=true&tokenIn=ETH&tokenOut=SOL&hideMultiswap=true&hideSend=true"
  width="480"
  height="640"
  title="Houdini Exchange Widget"
  allow="clipboard-write"
/>
```

## Theming

<Note>
  Deeper visual customization (custom colors, fonts, and styling) is coming with
  the **Widget SDK**. It is not yet available via URL parameters.
</Note>

## Notes & gotchas

* **Opt-out, not opt-in.** The `hide*` parameters remove tabs; there is no parameter to add tabs. All tabs are visible unless you hide them.
* **Don't hide all three tabs.** Setting `hideSwap`, `hideMultiswap`, and `hideSend` all to `true` leaves an empty tab header. Always keep at least one tab visible.
* **`widgetMode` is independent of the `hide*` flags.** It only controls the badge chrome ("Powered By" / "New"); it does not change which tabs appear.
* **The `/widget` route is always in widget mode**, so you only need `widgetMode=true` when embedding a different route.

## Widget vs API Integration

| Feature                 | Widget                                       | Direct API                       |
| ----------------------- | -------------------------------------------- | -------------------------------- |
| **Implementation Time** | Minutes                                      | Days/Weeks                       |
| **Maintenance**         | Auto-updated by Houdini                      | You maintain                     |
| **Customization**       | Preselect tokens, toggle tabs (theming soon) | Full control                     |
| **UI/UX**               | Pre-built, tested                            | Build from scratch               |
| **Backend Required**    | No                                           | Yes (for security)               |
| **Best For**            | Quick integration, standard flows            | Custom experiences, full control |