---
url: https://docs.comnto.com/integration/data-attributes.md
description: >-
  Every data-* attribute the embed script reads from a data-comnto container,
  including per-colour attributes, multiple widgets, and when to switch to the
  JavaScript API.
---

# Using Data Attributes

Mark your container with `data-comnto` and place configuration attributes directly on that element. The embed script scans the document, finds these containers, and initialises a widget in each one.

```html
<div
  data-comnto
  data-site="my-blog"
  data-topic="article-123"
  data-locale="en"
></div>
<script src="https://comnto.com/embed.js" defer></script>
```

## Available Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-site` | string | **Required.** Site id that owns the comments. |
| `data-topic` | string | Explicit topic/thread id. If missing, the loader derives one from the canonical URL (stable across visits). |
| `data-locale` | string | Language code such as `en`, `fr`, `ar`. Accepts region tags (`pt-BR`). |
| `data-theme` | string | `auto`, `light`, or `dark`. Auto adjusts to background changes. |
| `data-sort` | string | Initial sorting: `popular`, `latest`, or `oldest`. Falls back to the site default. |
| `data-colors` | JSON | Inline JSON object with colour overrides (see [Appearance](/customization/appearance)). |
| `data-localization` | JSON | Custom translation overrides (see [Localization](/customization/localization)). |
| `data-direction` | string | Optional text direction hint: `ltr`, `rtl`, or `auto`. |
| `data-sso` | string | Optional SSO token to authenticate the viewer immediately. Refresh it via the API when the token changes. |
| `data-login-button-visible` | boolean | Set to `true` (or leave the attribute empty) to force a login button even when the site runs in SSO-only mode. |
| `data-css` | string | Optional CSS override injected into the widget. The snippet is sanitised (no HTML/`javascript:`) and limited to 16 KB. |

> The comment box’s formatting tools, image limit, and mention limit have no attribute here. They are applied when a comment is saved rather than in the browser, so an embed cannot override them — set them in the dashboard instead, under [Editor Tools](/customization/editor-tools).

### Passing colour overrides as separate attributes

If serialising JSON is inconvenient you can pass individual colours. The loader merges them into a colour object.

Available keys: `data-primary`, `data-primary-hover`, `data-on-primary`, `data-link`, `data-link-hover`, `data-success`, `data-success-hover`, `data-on-success`, `data-danger`, `data-danger-hover`, `data-on-danger`, `data-warning`, `data-warning-hover`, `data-on-warning`, `data-surface`, `data-surface-alt`, `data-text`.

```html
<div
  data-comnto
  data-site="my-blog"
  data-theme="light"
  data-primary="#1d4ed8"
  data-on-primary="#ffffff"
  data-surface="#ffffff"
  data-text="#111827"
></div>
<script src="https://comnto.com/embed.js" defer></script>
```

### Multiple widgets

Add a `data-comnto` container for each location where comments should appear. The single embed script initialises all of them, so no extra `<script>` tags are needed. For pages with many widgets consider the programmatic API to keep tighter control over data fetching.

### When to avoid auto-init

Choose the manual API instead when:

* Your topic id is only known after an async call.
* You need to re-render the widget inside a client-side router without reloading the page.
* You want to update locale, theme, or SSO token without rebuilding the iframe.

In those cases, keep the container but omit extra attributes and call `window.comnto()` explicitly.