This is the complete reference. For installing the widget in the first place, see Ask AI Widget; for the per-platform guides, start at Install on your platform.

​
How options are set

Every option has two spellings — a data-* attribute on the script tag, and a camelCase key passed to init(). They are the same option:
Three rules govern every attribute in the tables below:
  • Booleans are true unless the value is exactly "false" or "0". A bare data-search-mode-enabled with no value is true.
  • An absent attribute is not false. It leaves the documented default in place, which matters for the options that default to on.
  • An empty string means “leave the default”, so a template that renders data-product-name="" when it has no name does no harm.

​
Required

Both are in the dashboard under Knowledge Base → Integration. Without them the script loads and does nothing.

​
Identity and endpoint

data-language changes the widget’s own buttons and labels. It does not steer the answer — the model replies in the language the question was asked in.

​
Layout

​
Launcher

​
In your own header

An “Ask AI” button beside the search box, where a reader who has just failed to find something is already looking. Give the widget a selector for something already in your header and it mounts the launcher next to it:
The launcher becomes a 36px labelled button with no drop shadow and no animations, sized and shaped to sit in a row of header controls. It keeps its own shadow root, so your header’s button styles cannot reach it. Every match gets a button, not just the first. Most docs themes render a desktop header and a mobile header as separate markup, both always in the DOM, each hidden at the other’s breakpoint — anchoring only the first would leave phones with no way into the widget. The example above is Mintlify’s two search entries. Anchors are watched for as long as the page lives, so a header that renders after hydration, or is replaced on every client-side navigation, still gets its button back. If the selector matches nothing within data-launcher-button-anchor-wait-ms, the launcher falls back to the corner and says so in the console — a button in the wrong place beats no button at all.

​
Two placements at once

An anchor replaces the floating button, on the grounds that two ways into one panel is one too many. data-launcher-button-floating overrides that and you get both:
They answer different moments. The anchored one sits where the reader’s attention already is; the floating one is on every page at every scroll position, and it survives the breakpoint where a theme hides its header controls — which is exactly where an anchored launcher would otherwise disappear on a phone. Both drive the same panel and share its open state, so whichever is clicked, both render as open. Because they are two placements rather than two widgets, each one takes its own shape, size and label size:
A corner button stands alone on the page and can carry the larger type; an anchored one has the header’s own controls setting its scale. One number was never going to be right for both.
This is the inverse of an open trigger: a trigger binds a button you render, this renders the button for you. Use a trigger when you control the header markup and want your own styling; use an anchor when you do not — a hosted docs theme, someone else’s template.

​
The expand button

The panel header has a ⤢ button. The reader presses it to make the panel bigger, and ⤡ to put it back. What “bigger” means depends on the view mode:
  • modal — the panel grows from modalSize (760px) to modalExpandedSize (1500px), and to the full height of the window.
  • sidebar — the panel leaves the right edge and becomes that same large centred panel. Pressing ⤡ docks it back to the edge.
The reader’s choice is saved in their browser, per knowledge base. If they expand the panel on one page, it is already expanded on the next one. The button is hidden where there is nothing to gain: in the search view mode, when fullScreen is on, and on screens under 600px wide (there the panel already fills the screen). If a reader expands on a laptop and then makes the window narrow, their choice is kept for when it is wide again. To turn it off, or to change how big “expanded” is:
Your page can also do it itself, with expand() and collapse().

​
Opening

​
Open triggers

Use your own “Ask AI” button instead of the launcher. Each trigger accepts a selector, a class list, or an id list — three spellings of the same thing: The camelCase equivalents are openSelector, openSelectorAsk and openSelectorSearch, each taking one selector. Triggers are bound by delegation on document, so a button your framework re-renders on every route change keeps working without re-initialising. data-open-query-from is what stops the reader typing the question twice: they typed it into the search box, then pressed the button beside it.

​
Conversation and content

​
Search tab

A second tab that lists matching pages and generates no answer — cheap, fast, and often what the reader actually wanted. It searches on Enter, not on every keystroke, and Enter never sends the query to the chat: a reader typing into a box labelled Search gets a list of pages. Arrow keys walk that list and Enter opens the highlighted row. The AI is one click away on the “Ask AI: …” row above the results — the row hideSearchAskCta removes.

​
Retrieval scoping

Always intersected server-side with the client key’s own allowed_groups, so this can narrow what a reader reaches but never widen it. setSourceGroupIds() changes it at runtime — for a docs site that scopes the assistant to the section being read.

​
MCP menu

Left unset, the menu stays hidden unless the server reports mcp_available — a client key with an origin allowlist needs mcp_enabled before MCP clients can use it, and printing install commands that would 403 helps nobody. Setting data-mcp-enabled="true" overrides that check, for self-hosted or local runs. See MCP server.

​
Hand-off to a human

​
Call to action

​
Surveys

hideBranding and brandingText are Enterprise-plan only and verified server-side through widget-config (hide_branding_allowed). On every other plan the footer stays visible whatever the attribute says.data-privacy-links is JSON because the entries are pairs — every flat encoding of [{title,url}] in an attribute breaks on the first title containing a comma. Invalid JSON logs a warning and is ignored.

​
Analytics identity

The stored id is random — it identifies a browser, not a person.The fingerprint is deliberately low-entropy: user agent, language, timezone and screen size, and nothing else. No canvas, no font probing, no audio. It is still a fingerprint, which is why it is opt-in and named plainly — turning it on is a decision about your own privacy policy. See PII and data retention.

​
Bot protection

Only meaningful where captcha is configured server-side; the widget reads that from widget-config.

​
Theme tokens

Every color has a …Dark twin, used when the panel is in dark mode. The light value is deliberately not reused there: a brand surface chosen against white is usually unreadable against black. Append -dark to the attribute (data-surface-color-dark) or Dark to the option (surfaceColorDark).

​
Type and sizing

Theme values land inside a stylesheet, so they are validated before use: anything containing ;, {, } or url( is dropped. Styles are otherwise isolated in a Shadow DOM, so nothing here leaks into your page and your CSS does not leak in.

​
Form deflector

The same script tag can arm a support form deflector. data-deflector-id alone is enough — the wiring is fetched at runtime, so a form whose markup changes is a dashboard edit rather than a redeploy of your support page. Anything set on the tag overrides the stored value, which is what makes a one-page exception possible. The full reference, including the fields stored on the deflector itself, is in Behaviour and Styling.

​
Migrating from kapa.ai

Where an option has two attribute spellings, the second is the one an existing kapa embed already carries. Both work, so a migrated tag can be pasted across unchanged and edited later: The event names and payloads match as well, and there is a callable BeforeQuery("onModalOpen", handler) form alongside BeforeQueryWidget.on(), so existing analytics wiring needs no rewriting.