Widget API

The widget API is the browser-facing integration layer for storefront autocomplete.

Script endpoint

GET /widget.js

Example for any website:

<input type="search" data-intentflow-search placeholder="Search products">

<script
    src="https://app.example.com/widget.js"
    data-api-key="if_PLACEHOLDER_KEY"
    data-target="[data-intentflow-search]">
</script>

Runtime behavior

1. The script finds matching search inputs.
2. When the shopper focuses an empty input, it requests discovery results and renders search suggestions, optional top categories, and trending products.
3. When the shopper types, it sends the current search query and renders autocomplete suggestions, category chips, and product results.
4. It versions each query, aborts superseded requests, and ignores stale responses from older query versions.
5. It announces result updates through a screen-reader live region and supports arrow-key navigation.
6. It closes silently on network, auth, or validation failures.

The widget never renders additional input fields. It does not include intent chips, search chips, comparison trays, branch timelines, visual/voice controls, or commerce action buttons. The storefront search bar is the only shopper input.

Configuration

Attribute	Required	Default	Description
data-api-key	Yes	None	Storefront API key.
data-target	No	input[type="search"], [data-intentflow-search]	CSS selector for search inputs to enhance.
data-endpoint	No	Same origin as the script + /api/v1/autocomplete	Autocomplete API URL.
data-min-chars	No	2	Minimum characters before typed search runs. Empty focus still loads discovery content.
data-debounce	No	150	Delay in milliseconds after typing before the request is sent.
data-limit	No	5	Maximum results per group.
data-theme	No	rounded	Dropdown appearance: rounded, sharp, or compact. Unknown values fall back to rounded.
data-product-display	No	line	Product result display: line or card. Unknown values fall back to line.
data-tracking	No	on	Set to off to disable anonymous click tracking (see Click tracking below).
data-events-endpoint	No	Same origin as the script + /api/v1/events	Journey events API URL, for CDN/proxy setups.

Rendering states

State	Trigger	API request	Visible groups
Empty input	Shopper focuses an empty bound search field.	/api/v1/autocomplete?q=&limit=5	Search suggestions, optional top categories, trending products.
Typed query	Shopper enters a search query.	/api/v1/autocomplete?q={term}&limit=5	Autocomplete suggestions, category chips, product results.

Selecting a suggestion or category writes its label into the input and dispatches a native input event so existing storefront search handlers can react. Product results render as plain links to the product URL from your catalog; the widget adds no other product action controls (no add-to-cart, quick view, or comparison buttons).

The runtime keeps a short-lived in-memory cache by normalized query and limit so returning to a previous query can repaint immediately while the latest request refreshes in the background.

Request headers

The widget sends the configured API key as:

X-Api-Key: if_PLACEHOLDER_KEY

CORS

The widget runs on merchant domains, so the autocomplete API must support cross-origin browser requests.

PLACEHOLDER: Document final allowed origins, headers, methods, and CDN behavior.

Custom endpoint

Use data-endpoint when the widget is served from a CDN or proxy but should call a different API host.

<script
    src="https://cdn.example.com/intentflow/widget.js"
    data-endpoint="https://app.example.com/api/v1/autocomplete"
    data-api-key="if_PLACEHOLDER_KEY">
</script>

Multiple search fields

The widget binds every element matching data-target, and each input receives its own isolated Shadow DOM dropdown.

<input data-intentflow-search type="search">
<input data-intentflow-search type="search">

<script
    src="https://app.example.com/widget.js"
    data-api-key="if_PLACEHOLDER_KEY"
    data-target="[data-intentflow-search]">
</script>

Click tracking

The widget reports two anonymous events to POST /api/v1/events so suggestion and product ranking can learn from real shopper behavior:

Event	When	Payload
suggestion_click	A suggestion or category chip is selected.	The selected phrase, the region (suggestions or categories), and the current query.
product_click	A product result is clicked.	The public product UUID, the region, and the current query.

Privacy properties:

• No cookies and no persistent identifiers. The session id is a random value kept in sessionStorage for the lifetime of the browser tab.
• No shopper PII is collected — only the phrase or product UUID that was clicked and the query that led there.
• Requests use fetch with keepalive, so a product click that navigates away still delivers, and failures are silent — tracking can never break the storefront.
• Set data-tracking="off" on the script tag to disable tracking entirely.

These events power the popularity ranking: clicked suggestions and frequently clicked or purchased products rank higher in autocomplete over time.

Events And Accessibility

The widget uses native DOM behavior. Suggestions and categories dispatch an input event after writing the selected label. Product results are links to the product URL.

The result panel is rendered as a listbox with option elements. ArrowDown, ArrowUp, Enter, and Escape are handled inside the input, and result count changes are announced through an aria-live="polite" region. On small screens the panel becomes fixed near the bottom of the viewport and remains scrollable.

Theming

The dropdown is rendered inside Shadow DOM to avoid collisions with host page CSS. Use data-theme to pick one of the built-in looks:

Theme	Description
rounded	Soft rounded corners with a small gap below the input. This is the default.
sharp	No corner rounding on the panel, category chips, or product thumbnails.
compact	Attaches the panel flush to the search bar as a single continuous element; the top corners are squared and the gap is removed.

Product display modes:

Display	Description
line	Current compact product display with thumbnail, title, category/price/stock detail line.
card	Large product image and title only, shown three cards per row with additional products available by horizontal scroll.

<script
    src="https://app.example.com/widget.js"
    data-api-key="if_PLACEHOLDER_KEY"
    data-theme="compact"
    data-product-display="card">
</script>

The Install Widget page in the merchant dashboard has an interactive builder that generates this snippet for you as you pick a theme and paste in an API key.