Widget configuration

Configure the widget with data-* attributes on the script tag.

You configure the widget with data-* attributes on the script tag. Here’s the full set.

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_test_..."
  data-position="bottom-left"
  data-env="development"
  data-chat-size="large"
  data-locale="fr"
  data-config-load="eager"
></script>

A worked example: development key, bottom-left launcher, large panel, French UI, config fetched eagerly.

Core attributes

data-key — your publishable key (pk_test_… or pk_live_…). Required.
data-enabled — set to false to load the script but not mount the widget (true by default).
data-position — launcher corner: bottom-right (default), bottom-left, top-right, or top-left.
data-locale — pin the language and direction for this page (for example ar or en-US). Leave it off and the widget follows your page's own language automatically.
data-chat-size — small (default), medium, large, fullscreen, or embedded.
data-chat-mode — normal (default) or split (a two-pane layout).
data-env — development or production (otherwise inferred from the key prefix).
data-theme — a JSON string of theme token overrides.

The widget follows your page's language on its own — no attribute needed. It reads your <html lang> and, when your page renders a different script than it declares, it trusts what is on the screen. Click your own language switcher and the chat follows, client-side, with no reload and without losing the conversation. Set data-locale only when you want to override that for one page.

Your visitor's first message sets the conversation's language, and it stays there even if they switch your site's language afterwards — a conversation started in Hebrew keeps answering in Hebrew. The widget's own labels and the AI notice still follow your page, so the notice is always readable in the language they are browsing in. A visitor who wants to change languages just says so in the chat.

Advanced attributes

data-origin — the Syncanix API origin (defaults to the production API).
data-theme-name — select a named design from your library; auto follows the host’s light/dark setting.
data-prompt-profile — run a specific prompt profile on this page, by the name you published it under. Only published profiles can be named; anything else falls back to your live profile.
data-mount-target — a CSS selector for where to mount an embedded widget.
data-split-page — the URL of the page to show beside the chat in split mode.
data-config-load — lazy (fetch settings on first open, default) or eager (at mount).
data-executor — the name of a global function that runs browser/host actions.
data-token-provider — the name of a global function returning the end user’s token.
data-step-up-provider — the name of a global function that triggers step-up re-authentication.
data-headers-provider — the name of a global function returning extra request headers.
data-client-witness — opt in to passive, shape-only API-traffic observation (off by default).
data-act-on-behalf-consent — require a one-time 'act on your behalf' consent (off by default).

Next steps

Runtime APIControl the widget from JavaScript.ThemingHow the widget matches your brand.