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.

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

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

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

Example: respond to height changes

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

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.