> 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/installation.md).

# Installation

Load the STON.fi Widget directly from the CDN or on demand through the npm loader.

You can load the STON.fi Widget from a content delivery network (CDN) using a script tag or the npm loader. A script tag downloads the widget as the browser parses your HTML, without a package installation or bundler. The npm loader downloads the same script when your application calls `load()`, so you control when the download starts.

The widget implementation is distributed exclusively through the CDN. Only the loader is published as an npm package. Your integration receives updates without requiring you to update dependencies, rebuild your application, or redeploy it.

Both options use a CDN URL with a major version prefix, currently `/v0/`. Updates within that major version do not introduce breaking changes and take effect on subsequent page loads. Breaking changes use a new prefix, such as `/v1/`, so you choose when to upgrade.

## Ways to install

### CDN script

Load the widget from this CDN URL:

```
https://widget.ston.fi/v0/index.js
```

The script exposes the widget constructor as `window.OmnistonWidget`. It also includes the widget styles, so you do not need a separate CSS import.

In this minimal example, the `DOMContentLoaded` handler creates a widget instance and mounts it into a container. Give your container an `id` and pass that ID to `document.getElementById()`:

```html
<html>
  <head>
    <script src="https://widget.ston.fi/v0/index.js"></script>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        const widget = new window.OmnistonWidget({
          tonconnect: {
            type: 'standalone',
            options: {
              manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
            },
          },
        });

        widget.mount(document.getElementById('omniston-widget-container'));
      });
    </script>
  </head>
  <body>
    <div id="omniston-widget-container"></div>
  </body>
</html>
```

### loader package

Use [@ston-fi/omniston-widget-loader](https://www.npmjs.com/package/@ston-fi/omniston-widget-loader) to control when your application downloads the widget. For example, start the download when a swap screen opens.

Install the loader:

```sh
npm install @ston-fi/omniston-widget-loader
```

Importing the loader does not download the widget. **Call `load()` explicitly** to download the widget for the corresponding major version from the CDN. The returned promise resolves to the widget constructor. The following example creates an instance and mounts it into the same container as the CDN example:

```js
import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: { manifestUrl: 'https://your-app.com/tonconnect-manifest.json' },
  },
});

widget.mount(document.getElementById('omniston-widget-container'));
```

The npm package also includes TypeScript types for the widget API.

## Lifecycle

Creating a widget instance prepares its configuration. Call `widget.mount()` to render it into an existing container, and `widget.unmount()` to remove the rendered interface.

### Mount and unmount

Mount the widget after the container exists in the DOM. Call `unmount()` before removing the container, such as during component cleanup or a route change. You can reuse the same widget instance by mounting it again after unmounting:

```js
const container = document.getElementById('omniston-widget-container');

widget.mount(container);

// Clean up when the widget is no longer displayed.
widget.unmount();

// Mount the same instance again when needed.
widget.mount(container);
```

Call `unmount()` before mounting an instance into another container. Unmounting leaves the container element in the DOM.

### Events

Use `widget.on(event, callback)` to observe lifecycle events. Register a handler before the operation you want to observe:

| Event     | Callback argument                 | When it fires                                                                                       |
| --------- | --------------------------------- | --------------------------------------------------------------------------------------------------- |
| `mount`   | Container element (`HTMLElement`) | After the widget interface is mounted. Wallet connection and asset loading continue asynchronously. |
| `unmount` | None                              | When `widget.unmount()` is called.                                                                  |

The `mount` callback receives the container element directly:

```js
const unsubscribe = widget.on('mount', (container) => {
  console.info('Widget mounted', container);
});

widget.mount(document.getElementById('omniston-widget-container'));
```

Event subscriptions remain active across remounts. The function returned by `on()` removes that handler. Call it when you no longer need the subscription:

```js
unsubscribe();
```

## Next step

See [Configuration](https://docs.ston.fi/developer-section/widget/configuration.md) for TON Connect, asset, and integrator fee options. See [Customization](https://docs.ston.fi/developer-section/widget/customization.md) for appearance settings.


---

# 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/installation.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.
