> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/widget.md).

# Widget

Embed Omniston-powered TON swaps with minimal configuration, collect integrator fees, and customize the experience.

The STON.fi Widget adds a swap interface for the TON blockchain to your application or website with minimal configuration. Powered by [Omniston](/developer-section/omniston.md), it handles wallet connection, quotes, and swap execution. You can collect integrator fees, choose available assets and the initial trading pair, and customize the appearance to match your product.

<figure><img src="https://1159777691-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJ1ZKietYw2GrKAuOqA8%2Fuploads%2Fgit-blob-0ac5824eb51d99c2021b1fb24980838eb9306f28%2FSTON.fi%20widget.png?alt=media" alt="STON.fi swap widget"><figcaption></figcaption></figure>

The widget provides:

* **Complete swap flow**: wallet balances, quotes, transaction signing, and trade-status tracking in a ready-made interface.
* **Flexible wallet integration**: manage TON Connect automatically or share your application's existing wallet connection.
* **Optional fee collection**: collect integrator fees on trades through your widget.
* **Optional asset configuration**: use STON.fi's curated asset selection, extend it with custom assets, or offer a specific trading pair.
* **Visual customization**: adapt themes, colors, component styles, and layout to match your product.

## Start integrating

Follow [Installation](/developer-section/widget/installation.md) to load the widget through the CDN script or npm loader and mount it in your application. The guide also covers lifecycle events and cleanup when you remove the widget.

## Integration examples

The public [Omniston Widget repository](https://github.com/ston-fi/omniston-widget) contains open-source integration examples you can use as a reference:

* [Vanilla JavaScript](https://github.com/ston-fi/omniston-widget/tree/main/examples/vanilla): integrate the widget without a UI framework.
* [React](https://github.com/ston-fi/omniston-widget/tree/main/examples/react): integrate the widget into a React application.

## Visual constructor

Use the [visual constructor](https://widget.ston.fi/constructor) as a playground to try the widget or as a configuration UI for your integration. Preview your changes as you configure the widget.

<figure><img src="https://1159777691-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJ1ZKietYw2GrKAuOqA8%2Fuploads%2Fgit-blob-3dcb833dbe9b1811a146ba8f582c97a4f1b65f7b%2Fwidget_dark.png?alt=media" alt="STON.fi Widget visual constructor"><figcaption></figcaption></figure>

The constructor provides:

* **Theme customization**: configure light and dark themes, colors, spacing, borders, and widths.
* **Asset selection**: use the default assets, add custom assets, or define your own list and initial trading pair.
* **Integrator fees**: set the fee recipient and rate.
* **Code export**: copy the generated CSS and JavaScript configuration or a complete HTML example into your project.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/widget.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.