Functionality
Panel states, catalog search, offer results, measurement eligibility, and mobile behavior.
The panel has three content modes: pre-search, typeahead, and catalog results. Editing the query exits catalog results and returns to typeahead or pre-search.
Prerequisites
- Mount an authenticated widget using Quick start.
- Apply open-state requests and provide product selection behavior.
Pre-search
An open panel with a blank query loads recents and recommendations from one request. Each section can show loading, content, empty, or failure independently. Empty recents mean the API returned no recent searches for that member. Recommendations are API-provided products; their availability and ordering belong to the service.
Selecting a recent submits its search text through the selected results mode. A recent with an opaque ID also has a separate Remove action. Remove persists dismissal through the API, then refreshes the pre-search content. A successful dismissal survives reloads; it does not submit the query or launch chat. A failed dismissal shows recents recovery and can be retried. Older responses without IDs still provide selectable recents but cannot offer Remove.
Typeahead
Typing pauses for 250 milliseconds before the SDK requests suggestions. Only the latest query response renders; superseded requests are canceled or ignored. product-catalog suggestion requests trim the query and cap it at 256 characters. An offer-scope query is not trimmed into a different term. A trimmed offer-scope query outside 2–100 characters returns no suggestions and does not call a provider.
| Row or action | Behavior |
|---|---|
| Search suggestion, including a merchant term | Submit its API-provided keyword through ordinary search. Do not open a merchant or category wall |
| THEO prompt with a sparkle | Pass the prompt text to onAskAi and request closure |
| Typed-query fallback | Submit the entered query when no search suggestion matches |
| Ask AI about this | Pass the entered text to onAskAi and request closure |
Submitting whitespace does nothing.
Enter and Send submit the query through the same results ownership rules.
A selected suggestion executes its API keyword, not the typed prefix.
A recent selection executes that recent's text.
Each deliberate submit or selection gets a fresh execution id.
An identical query still gets a new id.
Ask AI emits a launcher activation even when onAskAi is absent.
The event includes a seed-presence flag; only the callback supplies the actual text.
Catalog results
Without onSearchSubmit, submission fetches catalog products and renders them in the panel.
The panel emits one performed event after those products or the empty state commit.
A failed, loading, or superseded catalog response emits nothing.
onCatalogComplete receives the current successful page, including a successful empty page.
It does not run for failed, superseded, closed, or destroyed requests.
Rendering does not depend on this callback.
That callback does not replace search measurement.
With onSearchSubmit, the host receives the executed query and an execution handle.
The panel requests closure and makes no catalog request.
It does not call onCatalogComplete.
The host fetches and renders its own results page.
Call presented only when that page's products or empty state commit.
Use the displayed item count, not the total match count.
Panel and host results share one completion path.
Closing the panel does not cancel a pending host execution.
Editing away from panel results abandons that panel execution.
Typing alone does not cancel a pending host execution.
| Interaction | Measurement |
|---|---|
| Keystrokes or unselected suggestions | No execution |
| Product activation or Ask AI | No search measurement |
| Pagination or rerender | No additional performed event |
| Agent or LLM request | No search-bar execution |
| Direct results-route visit | Existing route behavior, no synthesized execution |
Returned offer rows render in the order received.
They do not show points, a product cart action, a why line, or a save control when wallet status is unavailable.
A missing price, image, or optional field stays absent.
max_discount is not a percentage.
The item id is the offer id string, not a merchant, token, or location id.
Selecting an offer calls onCatalogItemSelect with that entry and its returned action.
The host navigates.
The panel does not build a provider route.
A product row still uses the product callbacks.
An offer is never passed to those callbacks.
If both handlers are present, navigate only once.
The SDK does not add phrase rows the response omitted.
A generated phrase, when chat presentation is off, still submits through ordinary search.
Product rows require onResultSelect for selection behavior.
The callback receives a normalized SearchProduct; the widget then requests closure.
Without it, product selection has no host action and does not close the panel.
Product rows do not implement checkout or member mutations.
Clear, dismiss, and presentation
The Clear control and Escape reset the query and catalog mode, returning the open panel to pre-search.
It does not erase stored recents or dismiss the panel.
Panel dismissal requests onOpenChange(false); the host applies that state.
The search field remains available after panel closure.
An Ask AI control sits beside the closed field.
It passes the trimmed query, which may be empty, to onAskAi and emits one launcher activation.
Automatic presentation uses a sheet at widths up to 767 pixels and an overlay at 768 pixels and above.
Resizing follows that breakpoint unless presentation is explicitly set.
Both presentations support the same search interactions and callbacks.
The overlay opens in place over the closed field, so it needs no page-level backdrop.
The sheet's Back control requests closure through onOpenChange(false).
The host owns the surrounding mount size and page layout.
Requests and failures
| Interaction | SDK request |
|---|---|
| Open with a blank query | GET /api/search-sdk/suggestions |
| Pause while typing | GET /api/catalog/search/suggestions?q=<query> |
| Submit for panel results | GET /api/search-sdk/catalog?query=<query> plus the captured context query |
| Explicit ordinary search | One POST /api/search-sdk/recents with { query, submission_id } |
| Remove an identified recent | DELETE /api/search-sdk/recents/<id> |
Catalog search encodes the original nonblank query, within 200 characters, and the captured catalogContext.
Context arrays are comma-separated wire names such as search_radius_unit and category_ids.
catalog is not a query parameter.
product-catalog suggestion requests still trim and cap at 256 characters.
A direct searchCatalog read uses the same authentication and cancellation rules.
It does not post history.
Focus, typing, prefetch, page changes, and Ask AI do not post history.
An auth retry reuses the same submission id and body.
recorded true or false is an acknowledgement, not a provider choice.
A history failure does not block navigation or ranking.
Dismissal does not submit.
A newer query, page, filter set, location, AbortSignal, destroy, or member or program change drops a stale page.
Do not replace visible results with that late response.
The SDK attaches the member bearer in the Authorization header.
It validates API responses before passing product data to callbacks.
Section recovery retries failed reads or dismissal writes.
An HTTP 200 response with unavailable: true represents an unavailable section, not a successful empty result.
The broader API also exposes recents listing and recently viewed products. Those endpoints are not additional public widget methods or a recently viewed widget section. Consult the platform API for direct service integrations.
Related links
- Route search and product actions: Host integration
- Event and privacy contract: Events
- Acceptance cases: Validation
- Empty and unavailable sections: Troubleshooting