Ask AI Widget

The BeforeQuery widget is a single script tag that adds instant search and streaming RAG chat with source citations to any page. Styles are isolated in a Shadow DOM — zero CSS leakage. Installing on a docs platform or CMS? See the per-platform guides: Mintlify, Docusaurus, GitBook, ReadMe, VitePress, MkDocs, Sphinx, Next.js, WordPress, Webflow, Shopify, plain HTML.

Quick start

<script
  async
  src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx"
  data-client-key="bq_pk_..."
></script>

Configuration

Every option can be set as a data-* attribute on the script tag, or as the equivalent camelCase key passed to init(). These are the ones most sites set:

Attribute / Option	Type	Default	Description
`data-knowledge-base-id` / `knowledgeBaseId`	`string`	required	The knowledge base to answer from
`data-client-key` / `clientKey`	`string`	required	Public client key (`bq_pk_...`)
`data-product-name` / `productName`	`string`	knowledge base name → `"Ask AI"`	Name in the header, placeholder and welcome copy
`data-product-logo` / `productLogo`	URL	—	Header logo and assistant avatar
`data-brand-color` / `brandColor`	CSS color	`#343CED`	Accent for header, launcher, send button and links
`data-view-mode` / `viewMode`	`"modal" \| "search" \| "sidebar"`	`"modal"`	How the panel presents
`data-color-scheme` / `colorScheme`	`"light" \| "dark" \| "auto"`	`"light"`	`"auto"` follows the visitor’s OS — deliberately not the default, since a dark widget on a light docs site reads as broken
`data-color-scheme-selector` / `colorSchemeSelector`	CSS selector	—	Follow the site’s own dark-mode toggle, e.g. `html.dark`. Wins over `data-color-scheme`
`data-hotkey` / `hotkey`	`string`	`"k"`	Cmd/Ctrl + this key opens the widget; `"none"` disables
`data-position` / `position`	`"bottom-right" \| "bottom-left"`	`"bottom-right"`	Launcher corner
`data-language` / `language`	`string`	`en`	UI language. It does not steer the answer — the model replies in the language asked
`data-search-mode-enabled` / `searchModeEnabled`	`boolean`	`false`	Add a Search tab beside the chat, listing pages with no answer generated
`data-source-group-ids` / `sourceGroupIds`	comma-separated / `string[]`	—	Confine retrieval to these source groups
`data-hide-branding` / `hideBranding`	`boolean`	`false`	Hide the “Powered by BeforeQuery” footer. Enterprise only, verified server-side

Full configuration reference

All 160-odd options — launcher, modal chrome, open triggers, consent, hand-off, surveys, analytics identity, theme tokens, and the kapa.ai attribute spellings the widget also answers to.

Booleans are true unless the value is exactly "false" or "0", and an absent attribute leaves the default rather than meaning false — which matters for the options that default to on, like data-instant-search and data-exit-feedback-enabled.

View modes

modal (default)
search
sidebar

A centered overlay triggered by the floating launcher. Closes on backdrop click or Esc.

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-view-mode="modal"></script>

An answer panel anchored below the viewport top — perfect for docs-site search boxes. No launcher button. Optionally attach to your existing input:

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-view-mode="search"
  data-search-input="#docs-search-input"></script>

A panel that slides in from the right edge; full viewport width on mobile.

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-view-mode="sidebar"></script>

Making the panel bigger

The panel header has a ⤢ button, so a reader with a long answer in front of them can give it more room. ⤡ puts it back.

View mode	⤢ does this
`modal`	The panel grows to 1500px wide and the full height of the window
`sidebar`	The panel leaves the right edge and becomes that same large centred panel
`search`	No button — the search panel is anchored to the top of the page

Their choice is saved in the browser, per knowledge base: expand it on one page and it is already expanded on the next. On phones there is no button, because the panel already fills the screen. Two attributes change it, both optional. data-modal-expanded-size sets how big “expanded” is, and data-modal-expand-button-hidden removes the button:

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-modal-expanded-size="1280px"></script>

Beside your search bar

The arrangement most docs sites want: an Ask AI button in the header, next to the search box, where a reader who has just failed to find something is looking. There are two ways round it, and which one you need depends on one thing — can you edit your header’s markup? No (a hosted docs theme — Mintlify, GitBook, ReadMe). Name an element that is already there, and the widget puts its own button beside it:

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-launcher-button-anchor-selector="#search-bar-entry, #search-bar-entry-mobile"
></script>

Attribute / Option	Type	Default	Description
`data-launcher-button-anchor-selector` / `launcherAnchorSelector`	CSS selector	—	The element(s) to stand beside. Every match gets a button — most themes have a desktop search box and a mobile one, both always in the page, each hidden at the other’s breakpoint
`data-launcher-button-anchor-position` / `launcherAnchorPosition`	`beforebegin` \| `afterbegin` \| `beforeend` \| `afterend`	`afterend`	Which side. The two “inside” values are for anchoring to a container, like a nav
`data-launcher-button-anchor-wait-ms` / `launcherAnchorWaitMs`	number	`10000`	Your header is drawn after this script runs, so the element is watched for rather than looked for once. This is when it gives up and floats the launcher in the corner instead. `-1` never gives up
`data-launcher-button-anchor-overlay` / `launcherAnchorOverlay`	boolean	auto	Lay the button over the anchor rather than inserting it beside. A header that spreads its children shifts when anything is inserted into it, so that case is detected and overlaid automatically — set this only to force or forbid it

The button becomes a labelled toolbar control — 36px, no drop shadow, no animations — and keeps its own shadow root, so your header’s CSS cannot restyle it by accident. Anchors are re-checked for the life of the page, so a header your framework re-renders on every navigation gets its button back. Finding the selector: right-click your search box → Inspect → read the id="…" off the highlighted tag (#that-id), or one of its classes (.that-class). Check it in the console with document.querySelectorAll("…") before you ship it.

Your own “Ask AI” button

Yes, you can edit the header. Then keep the button in your own markup and point the widget at it — it inherits your styling and sits exactly where your layout puts it.

<!-- your page -->
<input id="docs-search" type="search" placeholder="Search the docs…" />
<button id="ask-ai">✦ Ask AI</button>

<script async src="https://widget.beforequery.com/beforequery-widget.js"
  data-knowledge-base-id="kb_xxx" data-client-key="bq_pk_..."
  data-modal-override-open-selector-ask-ai="#ask-ai"
  data-open-query-from="#docs-search"
  data-hide-launcher="true"></script>

Attribute / Option	Type	Default	Description
`data-modal-override-open-selector` / `openSelector`	CSS selector	—	Elements that open the panel on click, in whichever mode it is already in
`…-open-selector-ask-ai` / `openSelectorAsk`	CSS selector	—	Opens straight into chat
`…-open-selector-search` / `openSelectorSearch`	CSS selector	—	Opens straight into the Search tab
`data-open-query-from` / `openQueryFrom`	CSS selector	`searchInput`	Field the question is carried out of — your search box. Reads inputs and `contenteditable` alike
`data-open-submit` / `openSubmit`	`boolean`	`true`	Send the carried question immediately. `false` prefills it instead. An empty field sends nothing either way

Triggers are bound by delegation on document, so a button your framework re-renders on every route change keeps working without re-initialising the widget. data-open-query-from is what stops the reader typing the question twice: they typed it into the search box, then pressed the button next to it. Without it the panel opens with an empty composer. The same thing from code, if you would rather wire the click yourself:

BeforeQueryWidget.open({
  mode: "ai",
  query: document.querySelector("#docs-search").value,
  submit: true,
});

Programmatic API

For SPAs, initialize and control the widget from code. Everything hangs off window.BeforeQueryWidget:

window.BeforeQueryWidget.init({
  knowledgeBaseId: "kb_xxx",
  clientKey: "bq_pk_...",
  viewMode: "modal",
  hotkey: "k",
  colorScheme: "auto",
});

Methods

Method	Description
`init(config)`	Store the configuration and mount, unless `renderOnLoad: false`
`render()`	Mount a widget configured with `renderOnLoad: false`, or remount an unmounted one. No-op if already on the page
`unmount()`	Remove from the page, keeping the configuration for `render()`
`open(options?)`	Open the panel. `{ mode, query, submit }` — land on a tab, prefill the composer, and optionally send it straight away
`close()`	Close the panel
`toggle()`	Open if closed, close if open
`isOpen()`	Whether the panel is currently open
`expand()`	Make the panel big, as the header’s ⤢ button does. A sidebar pops out to the centre of the screen
`collapse()`	Back to the normal size, or back to the edge for a sidebar
`toggleExpand()`	Expand if normal, collapse if expanded
`isExpanded()`	Whether the panel is currently expanded
`ask(question)`	Open the panel and send `question` as the next turn
`reset()`	Clear the transcript and start a fresh thread
`getMode()` / `setMode(mode)`	Which tab is showing: `"ai"` or `"search"`
`setSourceGroupIds(ids)`	Narrow retrieval to these source groups from here on — for scoping the assistant to the section being read. `[]` clears it. Always intersected server-side with the client key’s own allowed groups, so this can narrow but never widen
`getSourceGroupIds()`	The groups currently in force
`setUser({ email, id })`	Attach the signed-in reader to the questions that follow
`on(event, handler)`	Subscribe. Returns an unsubscribe function
`off(event, handler)`	Unsubscribe
`destroy()`	Remove from the DOM and discard the configuration
`version` / `buildTime`	The loaded bundle’s identity

Events

Every widget interaction is reported to a callback, which is how a docs team gets “how many opened it, what did they ask, did the answer land” into the analytics tool they already use:

BeforeQueryWidget.on("onAskAIAnswerCompleted", ({ question, answer, citations }) => {
  analytics.track("docs_ai_answer", { question, sources: citations.length });
});

Event	Payload
`onModalOpen` / `onModalClose`	`{ mode }`
`onModeSwitch`	`{ mode }`
`onConsentAccept` / `onConsentReject`	—
`onAskAIQuerySubmit`	`{ threadId?, questionAnswerId, question }`
`onAskAIExampleQuerySubmit`	Same, fired instead of the above when a starter chip was clicked
`onAskAIAnswerCompleted`	`{ threadId?, questionAnswerId, question, answer, citations, conversation }`
`onAskAIGenerationStop`	`{ threadId?, question, conversation }`
`onAskAIConversationReset`	`{ threadId?, conversation }`
`onAskAIFeedbackSubmit`	`{ reaction: "up" \| "down" \| "withdrawn", threadId?, questionAnswerId, question, answer }`
`onAskAIAnswerCopy`	`{ threadId?, questionAnswerId, question, answer }`
`onAskAILinkClick` / `onAskAICtaClick`	`{ href, threadId?, questionAnswerId }`
`onAskAISourceClick`	`{ source, threadId?, questionAnswerId }`
`onAskAIHandoffOpen` / `onAskAIHandoffSubmit`	`{ threadId?, conversation, triggersMatched }`
`onAskAIHandoffCancel`	`{ threadId?, conversation }`
`onSearchResultsCompleted`	`{ query, searchResults }`
`onSearchResultClick`	`{ query, searchResult, rank }`
`onExitFeedbackSubmit`	`{ helpful, threadId? }` — the survey shown when the panel closes on an unrated conversation
`onUserSatisfactionSubmit`	`{ rating, comment?, threadId? }` — the CSAT prompt offered after a few answered questions

Handlers run inside a try/catch. A broken analytics snippet logs and is stepped over; it cannot take the chat down with it. Subscriptions outlive any one instance, so unmount() then render() keeps reporting, and registering before the bundle has finished loading is safe.

Migrating from another widget — there is a callable form of the same bus:

BeforeQuery("onAskAIAnswerCompleted", handler);          // subscribe
BeforeQuery("onAskAIAnswerCompleted", handler, "remove"); // unsubscribe

The event names and payload shapes match kapa.ai’s, so an existing analytics wiring can be pointed here without being rewritten. The same goes for the embed itself: where an attribute has two spellings, the second is the one a kapa script tag already carries.

Keyboard shortcut & dark mode

Cmd+K (Mac) / Ctrl+K (Windows/Linux) opens the widget by default. Change with data-hotkey="/" or disable with data-hotkey="none". Esc always closes.
The widget renders light unless told otherwise. Set data-color-scheme="auto" to follow the visitor’s OS preference, or "dark" to force it. Better still on a site with its own theme switch: point data-color-scheme-selector at the class that switch toggles (html.dark), which wins over both and is re-checked as the page changes, so the widget follows the toggle mid-session.

Features at a glance

Instant search results as you type (debounced 250 ms)
Optional Search tab — matching pages, no answer generated
Streaming RAG chat with numbered source citations
Follow-up questions continue the same thread
Thumbs up / down feedback, plus optional satisfaction and exit prompts
11 UI languages
Full theming with separate light and dark palettes, and a selector that follows your site’s own toggle
Consent screen and footer privacy links for GDPR-style flows
“Talk to a human” escalation on configurable triggers
“Connect to AI tools” menu offering the MCP server
reCAPTCHA v3 support (configured server-side via the widget-config API)
Mobile full-screen sheet layout
White-label branding: custom name, logo, accent color, and hideable footer (enterprise)

Local testing

<script
  src="http://localhost:5000/beforequery-widget.js"
  data-knowledge-base-id="…"
  data-client-key="bq_pk_…"
  data-base-url="http://localhost:8280"
  defer
></script>

Get Started

Knowledge Sources

Knowledge Connectors

Community Sources

Helpdesk Tickets

Deploy

Platform

Account Management

Quick start

Configuration

Full configuration reference

View modes

Making the panel bigger

Beside your search bar

Your own “Ask AI” button

Programmatic API

Methods

Events

Keyboard shortcut & dark mode

Features at a glance

Local testing

​Quick start

​Configuration

Full configuration reference

​View modes

​Making the panel bigger

​Beside your search bar

​Your own “Ask AI” button

​Programmatic API

​Methods

​Events

​Keyboard shortcut & dark mode

​Features at a glance

​Local testing

Quick start

Configuration

View modes

Making the panel bigger

Beside your search bar

Your own “Ask AI” button

Programmatic API

Methods

Events

Keyboard shortcut & dark mode

Features at a glance

Local testing