---
url: https://docs.comnto.com/reference/widget-api.md
description: >-
  Methods, properties, and events of the handle returned by window.comnto():
  setLocale, setTheme, setColors, update, reload, on, destroy, with examples.
---

# Widget API

`window.comnto(options)` mounts a widget and returns an API object. Each call creates one iframe and one API handle.

> Every widget needs a site id. Set `data-site="your-site-id"` on the container or include `site: 'your-site-id'` in each `window.comnto()` call. The examples below assume the container already carries a `data-site`.

```js
const widget = window.comnto({ el: '#comments', site: 'my-blog', topic: 'article-123' });
```

## Methods

| Method | Description |
| --- | --- |
| `setLocale(locale)` | Switch the UI language without reloading the iframe. Accepts language codes (`'en'`, `'fr'`, `'ar'`). |
| `setSorting(sort)` | Change the active sort to `'popular'`, `'latest'`, or `'oldest'`. The widget persists the choice until the page reloads. |
| `setConfig(config)` | Send configuration overrides to the iframe. |
| `setTheme(mode)` | Apply `'auto'`, `'light'`, or `'dark'`. Automatically re-computes contrast and background. |
| `setColors(colors)` | Override colour tokens. Accepts an object, array of pairs, or array of `{ key, value }`. |
| `setDirection(direction)` | Force RTL/LTR layout (`'rtl'`, `'ltr'`, or `'auto'`). |
| `setLocalization(locales)` | Merge translation overrides. Accepts a map of locale codes to message objects. |
| `update(options)` | Convenience method to set multiple keys at once (`{ theme, colors, locale, localization, direction, login_button_visible, css }`). |
| `reload(params = {})` | Rebuild the iframe URL with extra query parameters (`{ topic, locale, sso, sort, comment }`). Use this to switch threads or refresh the SSO token. |
| `on(event, callback)` | Subscribe to widget events. |
| `destroy()` | Remove the iframe and event listeners. Call this when the host component unmounts.

> When you pass `css` to `update`, the snippet is sanitised (no HTML tags or `javascript:` URLs) and truncated to 16 KB before being injected. Provide an empty string to clear the override.

## Properties

* `widget.el` – container element you supplied or the element resolved from the selector.
* `widget.iframe` – underlying iframe element. Avoid manipulating it directly; use the API whenever possible.

## Example: handle the login request

```js
const widget = window.comnto({ el: '#comments', site: 'my-blog', sso: '' });

const offLogin = widget.on('comnto:login', (payload) => {
  openMySignInDialog();
});
```

## Example: respond to height changes

```js
const widget = window.comnto({ el: '#comments', site: 'my-blog' });

widget.on('comnto:height', ({ height }) => {
  document.querySelector('#comments-frame').style.height = `${height}px`;
});
```

The loader already resizes the iframe automatically. Use this hook only when you implement custom scrolling or analytics.

## Example: switch topics without remounting

```js
const widget = window.comnto({ el: '#comments', site: 'my-blog', topic: 'article-123' });

function showTopic(newId) {
  widget.reload({ topic: newId });
}
```

Reloading preserves the iframe element, so the transition feels instant while the widget fetches the new thread.