Widget Placement
The IntentFlow widget is a lightweight JavaScript file that can be added to most storefront themes.
Basic snippet
<script
src="https://app.example.com/widget.js"
data-store-id="STORE_UUID"
data-api-key="if_PLACEHOLDER_KEY">
</script>By default, the widget binds to:
input[type="search"], [data-intentflow-search]Recommended placement
Place the script after the search input exists on the page. For most themes, that means near the end of the layout body or inside the theme section that renders search.
<form action="/search" method="get">
<input type="search" name="q" data-intentflow-search>
</form>
<script
src="https://app.example.com/widget.js"
data-api-key="if_PLACEHOLDER_KEY"
data-target="[data-intentflow-search]">
</script>Script options
| Attribute | Required | Default | Description |
|---|---|---|---|
data-api-key | Yes | None | Store API key sent as X-Api-Key. |
data-store-id | No | None | Store UUID for display or debugging. |
data-endpoint | No | Script origin + /api/v1/autocomplete | Override API endpoint. |
data-target | No | input[type="search"], [data-intentflow-search] | CSS selector for inputs to bind. |
data-min-chars | No | 2 | Minimum query length before requests are sent. |
data-debounce | No | 150 | Delay in milliseconds after typing. |
data-limit | No | 5 | Maximum suggestions and products per response group. |
data-theme | No | rounded | Dropdown appearance: rounded, sharp, or compact. See the Widget API theming guide. |
data-product-display | No | line | Product result display: line or card; card mode shows three cards per row with horizontal scroll for the rest. |
Platform notes
| Platform | Placement guidance | Status |
|---|---|---|
| Plain HTML | Add the snippet after the search input or at the end of <body>. | Supported |
| Shopify-style themes | Add the script in theme.liquid before </body> or inside the search section, and set data-target to the theme search input selector. | Supported |
| WooCommerce | Enqueue the script through the active child theme or a snippet plugin on storefront pages, then target the product search field. | Supported |
| Magento | Add through layout XML or theme template. | PLACEHOLDER |
| BigCommerce | Add through Script Manager or theme template. | PLACEHOLDER |
| PrestaShop | Add through a module or theme template. | PLACEHOLDER |
| Drupal Commerce | Add through a library or theme attachment. | PLACEHOLDER |
Integration examples
Plain HTML:
<form action="/search" method="get">
<input type="search" name="q" data-intentflow-search>
</form>
<script src="https://app.example.com/widget.js" data-api-key="if_PLACEHOLDER_KEY"></script>WooCommerce child theme:
add_action('wp_footer', function () {
?>
<script
src="https://app.example.com/widget.js"
data-api-key="if_PLACEHOLDER_KEY"
data-target=".woocommerce-product-search input[type=search]"
data-product-display="line"></script>
<?php
});Shopify-style theme:
<script
src="https://app.example.com/widget.js"
data-api-key="{{ shop.metafields.intentflow.widget_key }}"
data-target="input[name=q]"
data-product-display="card"></script>Styling and isolation
The widget renders its dropdown in Shadow DOM so host page styles should not leak into the result UI. Merchants can choose the supported data-theme and data-product-display values, while arbitrary JavaScript and raw style injection are not accepted as widget configuration.
The widget does not render additional input fields, intent chips, comparison trays, search branch timelines, visual search controls, voice search controls, or commerce action buttons. Product results are plain links to your product pages; the only shopper input is the storefront search bar it binds to.
Accessibility checklist
The widget result panel is a Shadow DOM listbox. Shoppers can move through suggestions and categories with ArrowDown and ArrowUp, select the active suggestion/category with Enter, and close the panel with Escape. Product rows are links to the product page. Result updates are announced through a polite live region. The panel is scrollable and mobile friendly.