Widget configuration
Configure the widget with data-* attributes on the script tag.
You configure the widget with data-* attributes on the script tag. Everything the widget reads from that tag is below, grouped by what it does: the core settings, the advanced ones, and the attributes that switch a whole behavior on.
<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>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-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-api-base-url — where your own API lives, if it is on a different host from the page. Without it, actions are sent to the page’s own host, which is right for a single-host site and wrong for the common app./api. split.
- data-api-origins — a comma-separated list of extra origins that are also your API. Only traffic to your own origins is ever observed, so an API on a separate host has to be named here or it is deliberately ignored.
- data-theme-vars — map the widget’s color roles onto your own CSS variable names, as JSON. Resolved live, so it follows your light/dark switch on its own; pair it with data-theme-source to name the element your variables are declared on.
- 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).
Opting in to a behavior
These do not configure how the widget looks or where it points — they turn a whole behavior on. Each is off unless you add it.
- data-trigger — a CSS selector for buttons on your own page that should open the chat. A nav item, a footer link, an empty-state button. Clicking one toggles the panel, and the widget keeps the button’s expanded state announced correctly to screen readers.
- data-ask-about — let a visitor select something on your page and ask the assistant about it. Off by default; it also has to be switched on for the workspace.
- data-haptics — set to false to stop the widget vibrating a phone when a visitor approves an action. On by default, and always suppressed for a visitor whose device asks for reduced motion.
- data-frame-mode — how a widget inside an iframe behaves: auto (default), agent, or standalone. Only relevant if your app embeds parts of itself in frames.
- data-frame-origins — a comma-separated list of exact origins whose framed pages your top-level widget may work with. Empty or absent means it works with none, which is the default.
- data-capture-closed-roots — set to true if parts of your page are built with a third-party component library the assistant otherwise cannot see into. Off by default, and only worth reaching for when a control it should be able to operate is invisible to it.
Keeping data off the assistant
The assistant reads your page to know what is on it. These three decide what it may see, so a value on screen never has to reach it — and common personal-data shapes are held back by default.
- data-block-selectors — a comma-separated list of CSS selectors for regions the assistant must never see. A matching element, and everything inside it, is excluded at capture — provably absent, not removed after it was read. Mark the container, not each control.
- data-mask-selectors — a comma-separated list of CSS selectors whose VALUES are withheld while the field itself stays visible. The assistant knows the field exists but never reads what is in it — the same treatment built-in password and card redaction gets.
- data-mask-pii — on by default. A value that looks like an email address, a US Social Security number, or a card number is withheld even if no selector names it. It hides only the value; the field stays visible. Set it to false only where you accept those values reaching the assistant and the stored transcript.