Configurations

Overview
Usage
Configuration Properties

Overview

The Autosuggest JS SDK provides a flexible configuration model that allows developers to control behavior, API response types, UI rendering, and event handling.

Configurations are passed during SDK initialization and are grouped into logical sections such as:

inputBoxConfigs — Controls search input behavior.
apiConfigs — Defines API parameters and enabled suggestion types.
suggestionBoxConfigs — Manages the suggestion container and rendering behavior.
onEvent — Handles lifecycle and interaction events.

These configuration options enable fine-grained control over how autosuggest behaves and appears within your application.

Usage

All configurations are provided when instantiating the Autosuggest class.

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

const autosuggest = new Autosuggest({
    siteKey: "ss-unbxd-aus-demo-fashion831421736321881",
    apiKey: "1ccbb7fcb0faf770d1c228be80ba16d9",

    inputBoxConfigs: {
        searchInput: ".search-input",
        debounceDelay: 500,
        minChars: 3,
    },

    suggestionBoxConfigs: {
        containerTag: "div",
        attributes: {
            class: ["search-input", "unbxd-autosuggest-box"],
            "data-testid": "search-input",
            id: "search-id"
        },
        template: null, // or a custom template function
    },

    apiConfigs: {
        apiEndpoint: "https://search.unbxd.io",
        initialRequest: false,
        inFields: { count: 2 },
        popularProducts: { count: 3, fields: [] },
        keywordSuggestions: { count: 2 },
        topQueries: { count: 2 },
        promotedSuggestions: { count: 2 },
        trendingSearches: { count: 5 },
        search: { prefetch: false, filterField: "" },
    },

    onEvent: ({ eventType }) => {
        console.log("Autosuggest event:", eventType);
    }
});

Each configuration section is documented below with detailed options, accepted values, and examples.

Configuration Properties

siteKey

String

Required

A unique identifier assigned by Unbxd to each site created in the Unbxd Console dashboard. It is required to associate new Autosuggest SDK API requests with the correct site. Refer to the Unbxd documentation for steps to retrieve the Site Key for your account.

Default

siteKey: ""

apiKey

String

Required

A unique API Key assigned to each site created in the Unbxd Console dashboard. Refer to the Unbxd documentation for steps to retrieve the API Key for your account.

Default

apiKey: ""

inputBoxConfigs

Object

Optional

Behavior and performance options that control when new Autosuggest SDK API calls are triggered and how frequently they are made. These settings help balance responsiveness with performance by reducing unnecessary network requests while maintaining a smooth user experience.

Option	Type	Required	Default	Description
`searchInput`	String \| null	Yes	`null`	CSS selector for the input element where the SDK should be enabled. The SDK queries the DOM with this selector and attaches autosuggest behavior to the matched element (e.g. `".input-search"`, `"#search-box"`).
`debounceDelay`	Number	No	`0`	Delay in milliseconds after the user stops typing before triggering an Autosuggest API call. Reduces requests during rapid typing. A value of `0` disables debouncing (API is called on every input change once `minChars` is met).
`minChars`	Number	No	`3`	Minimum number of characters in the input before triggering an Autosuggest API call. Prevents fetching suggestions too early. The API is only called when input length is greater than or equal to this value.

Default

inputBoxConfigs: {
  searchInput: null,
  debounceDelay: 0,
  minChars: 3,
}

suggestionBoxConfigs

Object

Optional

Container and DOM configuration options allow you to control how and where the new Autosuggest SDK container is rendered in the DOM. These settings help align the new Autosuggest SDK with your application’s markup structure, styling conventions, and testing requirements. You can also provide a custom template to fully override the default UI and render suggestions according to your design and layout requirements.

Option	Type	Required	Default	Description
`containerTag`	String	No	`"div"`	HTML tag used for the autosuggestion container element (e.g. `"div"`, `"section"`). Choose a tag that fits your layout or accessibility needs.
`attributes`	Object	No	`{ class: "unx-autosuggest-box" }`	HTML attributes applied to the container (e.g. `class`, `id`, `data-testid`). Useful for CSS classes, test IDs, or custom data attributes. Array values (e.g. for `class`) are joined with a space and applied as a single attribute string.
`template`	Function	null	No	`null`	Custom template function to fully override the default suggestion UI. See details below.

Default

suggestionBoxConfigs: {
  containerTag: "div",
  attributes: { class: "unx-autosuggest-box" },
  template: null,
}

Custom `template` function

When provided, the template function replaces the entire default suggestion box rendering. It is called with the current state object and must return an HTML string.

The function is bound to the TemplateService instance, so this.getTemplate(name) is available inside to invoke any of the built-in sub-templates.

Function signature:

template: function (state) {
  // `this` provides access to this.getTemplate()
  // Return an HTML string
}

state object shape:

{
  query: "",                    // Current search input value
  response: {
    products: [],               // All raw products from the autosuggest API
    popularProducts: [],        // Popular product suggestions
    inFields: [],               // In-field suggestions
    keywordSuggestions: [],     // Keyword suggestions
    promotedSuggestions: [],    // Promoted suggestions
    topSearchQueries: [],       // Top search queries
    trendingSearches: [],       // Trending searches (fetched on load separately)
    initialRequestProducts: [], // Products from the initial wildcard request (query=*)
    prefetchedSearchResults: {} // Prefetched hover search results, keyed by query string
  }
}

Available sub-templates via this.getTemplate(name):

Name	Input object key	Description
`"popularProducts"`	`{ POPULAR_PRODUCTS: [] }`	Renders popular product cards.
`"inFields"`	`{ IN_FIELD: [] }`	Renders in-field suggestion items.
`"keywordSuggestions"`	`{ KEYWORD_SUGGESTION: [] }`	Renders keyword suggestion items.
`"promotedSuggestions"`	`{ PROMOTED_SUGGESTIONS: [] }`	Renders promoted suggestion items.
`"topSearchQueries"`	`{ TOP_SEARCHES: [] }`	Renders top search query items.
`"trendingSearches"`	`{ TRENDING_SEARCHES: [] }`	Renders trending search pills.

Example:

suggestionBoxConfigs: {
  template: function (state) {
    const { query, response: { trendingSearches = [], popularProducts = [] } = {} } = state;

    if (!query || query.trim().length === 0) {
      return this.getTemplate("trendingSearches").call(this, { TRENDING_SEARCHES: trendingSearches });
    }

    return this.getTemplate("popularProducts").call(this, { POPULAR_PRODUCTS: popularProducts });
  }
}

apiConfigs

Object

Optional

The API configuration controls how the new Autosuggest SDK communicates with the Unbxd backend. It allows you to define the API endpoint and fine-tune the types and number of suggestions fetched for each request. These settings help tailor the new Autosuggest SDK experience to match business priorities and user behavior.

apiConfigs options

Option	Type	Default	Description
`apiEndpoint`	String	`"https://search.unbxd.io"`	Base URL for the Unbxd Search API used to fetch autosuggestion data. In most cases use the default; useful for private cloud or custom routing.
`initialRequest`	Boolean	`false`	When `true`, an autosuggest API call with `query=*` is fired on SDK initialization. The results are stored as `initialRequestProducts` in state and can be used in custom templates to display products before the user types anything.
`inFields`	Object	`{ count: 2 }`	In-field suggestions — keyword suggestions matched against specific indexed fields (e.g. product name, category, brand). `count`: number of suggestions to fetch.
`popularProducts`	Object	`{ count: 3, fields: [] }`	Popular product suggestions — frequently viewed or searched products. `count`: number to retrieve for autosuggest; also used as `rows` for search API calls (prefetch and hover). `fields`: optional array of product field names (e.g. `["title", "price", "imageUrl"]`). Used for autosuggest response and as `fields` for search API calls; when empty, the API returns default fields.
`keywordSuggestions`	Object	`{ count: 2 }`	Keyword-based suggestions — commonly searched or relevant keywords. `count`: number of keyword suggestions to fetch.
`topQueries`	Object	`{ count: 2 }`	Top search queries — most frequently searched queries across the site. `count`: number to include in results.
`promotedSuggestions`	Object	`{ count: 2 }`	Promoted suggestions — keywords or results boosted by merchandising rules in the Unbxd Console. `count`: number to fetch.
`trendingSearches`	Object	`{ count: 5 }`	Trending search suggestions. `count`: number of trending searches to fetch. Set to `0` to disable trending search; use a value greater than `0` to enable it.
`search`	Object	`{ prefetch: false, filterField: "" }`	Search prefetch options — controls prefetching of search results when hovering over suggestions. `prefetch`: when `true`, search results for each suggestion (in-field, keyword, promoted, top queries) are prefetched after the autosuggest API returns, enabling instant product display on hover. When `false`, search is triggered on hover. `filterField`: field name used for filtering prefetched search results (e.g. `"brand"`, `"category"`). Required when suggestions include filters; used to build filter queries like `brand:"value"`. Search API calls (both prefetch and hover) use `rows` and `fields` from the `popularProducts` config.

Default

apiConfigs: {
  apiEndpoint: "https://search.unbxd.io",
  initialRequest: false,
  inFields: { count: 2 },
  popularProducts: { count: 3, fields: [] },
  keywordSuggestions: { count: 2 },
  topQueries: { count: 2 },
  promotedSuggestions: { count: 2 },
  trendingSearches: { count: 5 },
  search: { prefetch: false, filterField: "" }
}

Example

apiConfigs: {
  apiEndpoint: "https://search.unbxd.io",
  initialRequest: true,
  inFields: { count: 5 },
  popularProducts: { count: 5, fields: [] },
  keywordSuggestions: { count: 5 },
  topQueries: { count: 5 },
  promotedSuggestions: { count: 5 },
  trendingSearches: { count: 5 },
  search: { prefetch: true, filterField: "brand" }
}

onEvent

Function

Optional

Callback function triggered on Autosuggest lifecycle and interaction events.
Useful for logging, analytics integration, error handling, or debugging.

The function receives a single object with eventType and, depending on the event, additional fields like query or error.

onEvent: function ({ eventType, query, error }) { ... }

Supported Events

Event Name	Extra Fields	Description
`BEFORE_TRENDING_SEARCHES_API_CALL`	—	Triggered before the Trending Searches API request is made.
`AFTER_TRENDING_SEARCHES_API_CALL`	—	Triggered after receiving the Trending Searches API response.
`BEFORE_AUTOSUGGEST_API_CALL`	`query`	Triggered before the Autosuggest API request is made. Includes the current search query.
`AFTER_AUTOSUGGEST_API_CALL`	`query`	Triggered after receiving the Autosuggest API response. Includes the search query used.
`AUTOSUGGEST_QUERY_UPDATED`	`query`	Triggered whenever the search input value changes. Includes the updated query string.
`INPUT_FOCUS`	—	Triggered when the search input gains focus.
`INPUT_BLUR`	—	Triggered when the search input loses focus.
`ERROR`	`error`	Triggered when an error occurs during API execution or DOM processing. Includes the thrown `Error` object.

Default

onEvent: function ({ eventType }) {
  console.log(`Unbxd Running onEvent with ${eventType}`);
}

Example

const autosuggest = new Autosuggest({
  siteKey: "your-site-key",
  apiKey: "your-api-key",
  inputBoxConfigs: {
    searchInput: ".input-search",
    debounceDelay: 200,
    minChars: 2,
  },
  onEvent: function ({ eventType, query, error }) {
    if (eventType === "AUTOSUGGEST_QUERY_UPDATED") {
      console.log("User typed:", query);
    }

    if (eventType === "ERROR") {
      console.error("Autosuggest error:", error);
    }
  }
});

Configurations

Table of contents

Overview

Usage

Configuration Properties

siteKey

Default

apiKey

Default

inputBoxConfigs

Default

suggestionBoxConfigs

Default

Custom template function

apiConfigs

apiConfigs options

Default

Example

onEvent

Supported Events

Default

Example

Custom `template` function