FAQs

This page answers common questions about the New Autosuggest SDK, including setup, configuration, behavior, and troubleshooting. For step-by-step integration, see Getting Started. For all configuration options, see Configuration.

FAQs

General queries

What is the New Autosuggest SDK?

The New Autosuggest SDK is a lightweight JavaScript library that enables real-time search suggestions as users type into a search input. It helps guide users toward relevant queries and products by dynamically presenting suggestions based on partial input—reducing typing effort, minimizing zero-result searches, and improving overall search efficiency.

The SDK is designed to be easy to integrate and flexible to configure. It can be used with any web application, regardless of framework, and does not require build tools or additional dependencies. Once initialized, the new Autosuggest SDK listens to user input events and fetches relevant suggestions from Unbxd in real time. By surfacing meaningful suggestions early in the search journey, it results in faster discovery, higher engagement, and a more intuitive search experience for end users.

Do I need a framework to use the New Autosuggest SDK?

No. The SDK is framework-agnostic and works with:

Vanilla JavaScript — With a bundler (e.g. Webpack, Vite), you can use the SDK in plain JS.
React, Vue, Angular, or other frameworks — You can initialize the SDK in a lifecycle hook (e.g. useEffect, mounted) and pass the search input element or selector. Ensure the DOM element exists at the time of initialization.

The library is distributed as an npm package that attaches to a search input and manages suggestions via the Unbxd API. Your application only needs to install the package, import it, provide configuration (including siteKey, apiKey, and inputBoxConfigs.searchInput), and optionally customize templates and callbacks.

What types of suggestions does the SDK support?

The New Autosuggest SDK supports multiple suggestion types, each configurable via apiConfigs:

Suggestion type	Description	Configuration
In-field suggestions	Keyword suggestions matched against specific indexed fields (e.g. product name, category, brand).	`apiConfigs.inFields.count`
Popular products	Frequently viewed or searched products relevant to the user’s input.	`apiConfigs.popularProducts.count`
Keyword suggestions	Commonly searched or relevant keywords based on the user’s input.	`apiConfigs.keywordSuggestions.count`
Top queries	Most frequently searched queries across the site.	`apiConfigs.topQueries.count`
Promoted suggestions	Keywords or results boosted by merchandising rules in the Unbxd Console.	`apiConfigs.promotedSuggestions.count`

You can enable or disable categories and set how many results to fetch per category. Adjust these counts based on your UI space and performance needs; see Best Practices for guidance on suggestion counts.

How do I get an API key and Site key to use with the SDK?

To use the New Autosuggest SDK, you need a valid siteKey and apiKey from your Unbxd account.

Sign up or log in at Unbxd.
Complete the self-serve FTU (First Time User) flow — This includes account setup, site creation, feed upload, and relevancy configuration. Detailed guidance is available in the Self Serve Dashboard Documentation.
Obtain your keys — Once your project and site are set up, locate the API key and Site key in the project dashboard (often displayed as long strings). Copy these and use them in your SDK configuration.
Keep keys secure — Treat these keys like any other sensitive credentials. Do not share them publicly or commit them in a way that violates your agreement. Use environment variables or secure config in production where appropriate.

The exact steps may vary depending on your plan and Unbxd’s current offerings. If you need help, refer to the Unbxd dashboard or contact Unbxd support. For integration steps using these keys, see Getting Started.

How do I configure the SDK on my website?

Configuring the New Autosuggest SDK involves installing the npm package, importing the SDK, and initializing it with the required and optional settings.

1. Install the package

Install the New Autosuggest SDK from npm (or Yarn), as described in Getting Started:

npm install @unbxd-ui/autosuggest-js-sdk

or with Yarn:

yarn add @unbxd-ui/autosuggest-js-sdk

2. Import and initialize with at least the required fields

Import the Autosuggest class and create an instance. You must provide:

siteKey — Your Unbxd site key.
apiKey — Your Unbxd API key.
inputBoxConfigs.searchInput — A valid CSS selector (e.g. ".search-input") or DOM element for the search input to which the SDK will attach.

Example minimal configuration:

import { Autosuggest } from "@unbxd-ui/autosuggest-js-sdk";

const autosuggest = new Autosuggest({
  siteKey: "<<site key>>",
  apiKey: "<<api key>>",
  inputBoxConfigs: {
    searchInput: ".search-input"
  }
});

3. Add optional configuration

You can then customize behavior, API, DOM, and callbacks. For example:

Behavior — debounceDelay, minChars (see Configuration).
API — Suggestion types and counts (see Configuration).
DOM — containerTag, attributes (see Configuration).
Events — onEvent for lifecycle hooks (see Configuration).
Templates — Custom UI (see Configuration).

A full example is available in Getting Started. For a complete list of options, see Configuration.

How can I test the SDK before deploying to production?

You can test the New Autosuggest SDK safely by using a sandbox or test environment that is isolated from production.

Use separate credentials — Create or use a test project in the Unbxd dashboard with its own API key, site key, and index. This keeps test traffic and configuration separate from your live site.
Use a test feed — Upload and index a test feed (or a subset of data) so you can verify suggestion behavior without affecting production data.
Verify prerequisites — Ensure your test site has completed the FTU flow and that required fields (e.g. title, imageUrl, price, categoryPath) are mapped correctly for the test feed.
Test on a staging URL — Deploy the integration to a staging or development URL and verify initialization, suggestion display, and callbacks (e.g. onSelect, onError) before going live.

This approach lets you experiment with configuration, templates, and styling without impacting real users or production analytics.

Can I use my own styles instead of the default SDK styles?

Yes. The default styles are optional. You can fully style the suggestion UI with your own CSS.

You can use the attributes configuration (e.g. suggestionBoxConfigs.attributes: { class: ["my-autosuggest-box"] }) to attach your own classes to the container for targeting with CSS.
For full control over structure and markup, use a custom template (see Configuration). The template function receives suggestion data and returns an HTML string, which you can style entirely with your own classes and design system.

This makes it possible to align the autosuggest experience with your brand and layout without relying on the default theme.

Behavior and usage

When do suggestions appear, and how often are API calls made?

Suggestions are requested based on two main settings: minChars and debounceDelay.

minChars — The minimum number of characters the user must type before a new Autosuggest SDK API call is triggered. The default is 3. For example, with minChars: 3, typing “sh” will not trigger a request; “sho” will. This prevents too many requests for very short queries and can be set to 2 or 3 for a balanced experience (see Best Practices).
debounceDelay — The delay in milliseconds after the user stops typing before the API call is sent. For example, with debounceDelay: 500, rapid typing of “shoes” will result in one request 500 ms after the last keystroke, rather than a request on every character. This reduces the number of API calls and improves performance. A value of 0 disables debouncing (not recommended in production).

Both options are documented in Configuration. Tuning them helps balance responsiveness with server load and rate limits.

Trending searches are controlled by apiConfigs.trendingSearches.count. Set count to 0 to disable trending search. Use a value greater than 0 to enable it and specify how many trending searches to fetch (e.g. trendingSearches: { count: 5 }). See Configuration for details.

How do I handle suggestion clicks (when the user selects a suggestion)?

You can handle suggestion selection by using the appropriate callback provided by the SDK (e.g. onSelect, or the equivalent in your version). When the user clicks or selects a suggestion, this callback is invoked so you can run custom logic.

Common use cases include:

Navigating to a search results page — Use the selected suggestion text (or associated data) to build the URL and redirect the user (e.g. /search?q=selected-query).
Updating the search input — Set the input value to the selected suggestion and optionally submit the form or trigger a search.
Analytics and tracking — Record the suggestion click for conversion or engagement analytics.

The exact callback name and parameters may vary by SDK version; refer to Configuration (onEvent) and the SDK reference for the current API. Implement this callback during initialization so that every selection is handled consistently.

Does the New Autosuggest SDK work on mobile and touch devices?

Yes. The SDK works on mobile and touch devices. It does not rely on mouse-only events; suggestions can be opened, scrolled, and selected via touch.

You can further optimize for small screens by:

Adjusting suggestion counts — Request fewer suggestions per category on mobile to keep the dropdown compact and fast (see Configuration).
Using responsive CSS — Style the suggestion container and items with media queries so layout, font size, and spacing work well on narrow viewports.
Tuning behavior — Consider slightly higher minChars or debounceDelay on mobile if you observe performance or UX issues, though the same configuration often works across devices.

No separate “mobile build” is required; a single integration works across desktop and mobile.

Troubleshooting

Suggestions are not showing. What should I check?

If suggestions do not appear, work through the following:

Required configuration
Ensure siteKey, apiKey, and searchInput are set correctly. Missing or wrong values can prevent the SDK from authenticating or attaching to the input. See Getting Started and Best Practices.
Search input element
The element matching searchInput (selector or DOM reference) must exist in the DOM when the SDK is initialized. If you use a framework, initialize after the component has mounted and the input is rendered.
Feed and index
Your Unbxd feed must be uploaded and indexed, and the FTU flow completed. Required fields (e.g. title, imageUrl, price, categoryPath) should be mapped. Configuration attributes in the docs are based on sample feeds; your schema may differ.
Browser console and network
Open the browser’s developer tools:
- Console — Look for JavaScript errors (e.g. invalid config, missing element).
- Network — Check whether new Autosuggest SDK API requests are sent, and whether they return 200 with valid JSON. Failed or blocked requests (e.g. CORS, wrong endpoint) will prevent suggestions from appearing.
Error callback
Configure the onEvent callback (see Configuration) to log or report errors. This helps capture API failures, network issues, or invalid responses in production.

Addressing these areas usually resolves missing suggestions. If the issue persists, verify your Unbxd dashboard and account status and contact Unbxd support if needed.

I am seeing too many API requests. How do I reduce them?

Too many requests are usually due to no or low debouncing or low minChars. Use the following to reduce load:

Enable debouncing — Set debounceDelay to a value such as 300–500 ms. This waits until the user pauses typing before sending a request, so rapid typing generates fewer calls. A value of 0 disables debouncing and is not recommended in production (see Best Practices).
Increase minChars — Use at least 2 or 3 characters (e.g. minChars: 3) so that very short partial queries do not trigger requests.
Review suggestion counts — Lower count for each suggestion type in Configuration if you do not need many results; this can also reduce response size and processing time.

These settings are documented in Configuration. Balancing debounceDelay and minChars will significantly reduce the number of API calls while keeping the experience responsive.

For more detail, see Getting Started, Configuration, and Best Practices.