Table of contents

Widget SDKs / Quick Search / Search Quick Widget (JS)

Quick Search Widget (JS)

A Vanilla JS widget that enables users to perform real-time product searches with instant results, enhancing product discoverability and conversion.

Use this library when you want to display a widget without using a transpiler like Babel and without using JSX. This library exports a htm HTML factory to assemble custom elements of the widget.

This widget library is version 0.0.12 and the API can change. Please specify exact version when installing.

Installation

Install @recombee/quick-search-widget-js@0.0.12 and recombee-js-api-client packages using your preferred NPM package manager. This example is using pnpm.

pnpm add @recombee/quick-search-widget-js@0.0.12 recombee-js-api-client

Copy

Client Initialization

The widget loads recommendation data using Recombee API Client. Here is how to initialize the client with necessary configuration for a specific database:

TypeScript JavaScript

import { class ApiClientClient for sending requests to Recombee and getting repliesApiClient } from "recombee-js-api-client";

const const DATABASE_ID: "[database-id]"DATABASE_ID = "[database-id]";
const const PUBLIC_TOKEN: "[database-public-token]"PUBLIC_TOKEN = "[database-public-token]";
const const REGION: "[database-region]"REGION = "[database-region]";

export const const apiClient: ApiClientapiClient = new new ApiClient(databaseId: string, publicToken: string, options?: ApiClientOptions): ApiClient@paramdatabaseId - ID of your database.@parampublicToken - Corresponding public token.@paramoptions - Other custom options.ApiClient(const DATABASE_ID: "[database-id]"DATABASE_ID, const PUBLIC_TOKEN: "[database-public-token]"PUBLIC_TOKEN, {
  region?: string | undefinedregion: const REGION: "[database-region]"REGION,
});

Copy

The Database Public Token can be found in the Admin UI Database Settings Page.

The widget also needs to be provided a createRequest function, which instantiates a client request class to define which data to pull from the database. Use Scenario ID which can be found on Admin GUI Database Scenarios Page.

TypeScript JavaScript

import { type type CreateRequestFunction = (options: FetchContentOptions) => RequestFactory for creating Recombee API Request to load data into a Widget.
@publicCreateRequestFunction } from "@recombee/carousel-widget-react";
import { class RecommendItemsToUserBased on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.
The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.
The returned items are sorted by relevance (the first item being the most relevant).
Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:
- Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui.html#reported-metrics).
- Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api.html#recommend-next-items).
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.RecommendItemsToUser } from "recombee-js-api-client";

const const createRequest: CreateRequestFunctioncreateRequest: type CreateRequestFunction = (options: FetchContentOptions) => RequestFactory for creating Recombee API Request to load data into a Widget.
@publicCreateRequestFunction = ({ count: numberNumber of items to fetch for the widget. Pass it to the appropriate
Request constructor.count }) => {
  const const SCENARIO_ID: "recommend-items-to-user"SCENARIO_ID = "recommend-items-to-user";
  return new new RecommendItemsToUser(userId: string, count: number, optional?: {
    scenario?: string;
    cascadeCreate?: boolean;
    returnProperties?: boolean;
    includedProperties?: string[];
    filter?: string;
    booster?: string;
    logic?: string | object;
    diversity?: number;
    minRelevance?: string;
    rotationRate?: number;
    rotationTime?: number;
    expertSettings?: {
        [key: string]: unknown;
    };
    returnAbGroup?: boolean;
}): RecommendItemsToUser@paramuserId - ID of the user for whom personalized recommendations are to be generated.@paramcount - Number of items to be recommended (N for the top-N recommendation).@paramoptional - Optional parameters given as an object.RecommendItemsToUser(userId, count: numberNumber of items to fetch for the widget. Pass it to the appropriate
Request constructor.count, {
    scenario?: string | undefinedScenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".scenario: const SCENARIO_ID: "recommend-items-to-user"SCENARIO_ID,
    cascadeCreate?: boolean | undefinedIf the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.cascadeCreate: true,
    returnProperties?: boolean | undefinedWith `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.returnProperties: true,
  });
};

Copy

Please ensure that you provide the user ID (typically obtained from your existing user tracking system), along with other relevant parameters - such as an item ID or Item Segment ID - depending on the specific type of recommendation request.

Basic Example

The widget in this example uses the DefaultItem component to render each recommendation in a consistent layout.

The resulting widget is inserted into the element specified by the container field.

Values of the recommended items - such as title, image URL, or link URL - are obtained from the API response and accessed via props.result?.values.

Ensure that returnProperties: true is set in the request, and optionally use includedProperties to control which item properties are returned.

TypeScript + ESM JavaScript + ESM JavaScript + Browser

import {
  const QuickSearchWidget: ({ container, ...props }: QuickSearchWidgetOptions) => null | undefinedQuick Search widget
@publicQuickSearchWidget,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
  const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  function SearchIcon(): React.JSX.ElementSearchIcon,
  function CloseIcon(): React.JSX.ElementCloseIcon,
  const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml,
} from "@recombee/quick-search-widget-js";

import "@recombee/quick-search-widget-js/dist/styles.css";

function QuickSearchWidget({ container, ...props }: QuickSearchWidgetOptions): null | undefinedQuick Search widget
@publicQuickSearchWidget({
  container: stringCSS Selector to target the element where the widget should be inserted.
@publiccontainer: "#widget-root",
  WidgetConfigurationBase<CR extends (...args: any[]) => Request = CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient: const apiClient: ApiClientapiClient,
  WidgetConfigurationBase<CR extends (...args: any[]) => Request = CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest: const createRequest: CreateRequestFunctioncreateRequest,
  minSearchCharactersCount: numberminSearchCharactersCount: 3,
  desktopMediaQuery: stringdesktopMediaQuery: "(min-width: 1000px)",
  type InputComponent: React.FC<InputProps>InputComponent: (props: InputPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<form className="flex w-[400px] text-[#374040]">
      <${const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput} state=${props: InputPropsprops.state: QuickSearchWidgetStatestate} />
    </form>`,
  type TriggerComponent: React.FC<TriggerProps>TriggerComponent: (props: TriggerPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<button
      ...${props: TriggerPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.triggerProps: {
    ref: (element: HTMLElement | null) => void;
    onClick: () => void;
}triggerProps}
      className="flex size-[38px] items-center justify-center rounded-sm bg-[#3bc4a1] text-white"
    >
      <${function SearchIcon(): React.JSX.ElementSearchIcon} />
    </button>`,

  type DropdownComponent: React.FC<DropdownProps>DropdownComponent: (props: DropdownPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<div
      className="mt-1 flex h-full max-h-full min-h-0 flex-col rounded-sm bg-white text-[#374040] shadow-2xl lg:h-auto lg:max-w-[900px] lg:min-w-[600px]"
    >
      ${!props: DropdownPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.isDesktop: booleanisDesktop &&
      const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<form className="flex items-center gap-2 p-2">
        <div className="flex-grow">
          <${const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput} state=${props: DropdownPropsprops.state: QuickSearchWidgetStatestate} />
        </div>
        <button
          ...${props: DropdownPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.closeButtonProps: {
    type: "button";
    onClick: () => void;
    onTouchEnd: () => void;
}closeButtonProps}
          className="flex size-[38px] items-center justify-center"
        >
          <${function CloseIcon(): React.JSX.ElementCloseIcon} />
        </button>
      </form>`}
      <div className="flex min-h-0 flex-grow flex-col">
        <div className="px-4 py-4 pb-2 text-sm font-semibold text-[#3bc4a1]">
          Results
        </div>
        <div className="overflow-auto p-2">
          ${props: DropdownPropsprops.state: QuickSearchWidgetStatestate
            .QuickSearchWidgetState.items: (index: number) => {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]items(0)
            .Array<{ key: string; id: string; recommId: string; values: { [key: string]: any; }; itemProps: { onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void; "data-search-result-id": string; tabIndex: number; }; }>.map<React.ReactElement<unknown, string | React.JSXElementConstructor<any>>>(callbackfn: (value: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}, index: number, array: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]) => React.ReactElement<...>, thisArg?: any): React.ReactElement<...>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.map(
              (item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item) =>
                const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<${const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem}
                  key=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.key: stringkey}
                  href=${function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
                    `${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anylink}`,
                    item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.recommId: stringrecommId,
                  )}
                  primaryContent=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anyproduct_title}
                  secondaryContent=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anycategory}
                  ...${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.itemProps: {
    onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
    "data-search-result-id": string;
    tabIndex: number;
}itemProps}
                />`,
            )}
        </div>
      </div>
    </div>`,
});

Copy

Batch request

To fetch results from multiple Scenarios, such as segments in addition to items, use Batch request.

TypeScript + ESM JavaScript + ESM JavaScript + Browser

import {
  const QuickSearchWidget: ({ container, ...props }: QuickSearchWidgetOptions) => null | undefinedQuick Search widget
@publicQuickSearchWidget,
  function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam,
  const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput,
  const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem,
  function SearchIcon(): React.JSX.ElementSearchIcon,
  function CloseIcon(): React.JSX.ElementCloseIcon,
  const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml,
} from "@recombee/quick-search-widget-js";

import "@recombee/quick-search-widget-js/dist/styles.css";

const const createRequest: CreateRequestFunctioncreateRequest: type CreateRequestFunction = (options: {
    searchQuery: string;
    isFullScreen?: boolean;
}) => RequestCreateRequestFunction = ({ searchQuery: stringsearchQuery }) => {
  return new new Batch(requests: Request[], optional?: {
    distinctRecomms?: boolean;
}): Batch@paramrequests - Array containing the requests.@paramoptional - Optional parameters given as an object (allowed parameters: distinctRecomms).Batch(
    [
      new new SearchItems(userId: string, searchQuery: string, count: number, optional?: {
    scenario?: string;
    cascadeCreate?: boolean;
    returnProperties?: boolean;
    includedProperties?: string[];
    filter?: string;
    booster?: string;
    logic?: string | object;
    expertSettings?: {
        [key: string]: unknown;
    };
    returnAbGroup?: boolean;
}): SearchItems@paramuserId - ID of the user for whom personalized search will be performed.@paramsearchQuery - Search query provided by the user. It is used for the full-text search.@paramcount - Number of items to be returned (N for the top-N results).@paramoptional - Optional parameters given as an object.SearchItems("userId", searchQuery: stringsearchQuery, 5, {
        scenario?: string | undefinedScenario defines a particular search field in your user interface.scenario: "search",
        cascadeCreate?: boolean | undefinedIf the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.cascadeCreate: true,
        returnProperties?: boolean | undefinedWith `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.returnProperties: true,
      }),
      new new SearchItemSegments(userId: string, searchQuery: string, count: number, optional?: {
    scenario?: string;
    cascadeCreate?: boolean;
    filter?: string;
    booster?: string;
    logic?: string | object;
    expertSettings?: {
        [key: string]: unknown;
    };
    returnAbGroup?: boolean;
}): SearchItemSegments@paramuserId - ID of the user for whom personalized search will be performed.@paramsearchQuery - Search query provided by the user. It is used for the full-text search.@paramcount - Number of segments to be returned (N for the top-N results).@paramoptional - Optional parameters given as an object.SearchItemSegments("userId", searchQuery: stringsearchQuery, 5, {
        scenario?: string | undefinedScenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".scenario: "search-brands",
        cascadeCreate?: boolean | undefinedIf the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.cascadeCreate: true,
      }),
    ],
    {
      distinctRecomms?: boolean | undefineddistinctRecomms: true,
    },
  );
};

function QuickSearchWidget({ container, ...props }: QuickSearchWidgetOptions): null | undefinedQuick Search widget
@publicQuickSearchWidget({
  container: stringCSS Selector to target the element where the widget should be inserted.
@publiccontainer: "#widget-root",
  WidgetConfigurationBase<CR extends (...args: any[]) => Request = CreateRequestFunction>.apiClient: ApiClientInstance of Recombee JS API Client. See

{@link 
file://./#client-initialization Example
}
.
@publicapiClient: const apiClient: ApiClientapiClient,
  WidgetConfigurationBase<CR extends (...args: any[]) => Request = CreateRequestFunction>.createRequest: CreateRequestFunctionRequest factory function. See

{@link 
file://./#client-initialization Quick Example
}
 or visit

{@link 
file:///api API Reference
}
 for overview of available requests.
@publiccreateRequest: const createRequest: CreateRequestFunctioncreateRequest,
  minSearchCharactersCount: numberminSearchCharactersCount: 3,
  desktopMediaQuery: stringdesktopMediaQuery: "(min-width: 1000px)",
  type InputComponent: React.FC<InputProps>InputComponent: (props: InputPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<form className="flex w-[400px] text-[#374040]">
      <${const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput} state=${props: InputPropsprops.state: QuickSearchWidgetStatestate} />
    </form>`,
  type TriggerComponent: React.FC<TriggerProps>TriggerComponent: (props: TriggerPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<button
      ...${props: TriggerPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.triggerProps: {
    ref: (element: HTMLElement | null) => void;
    onClick: () => void;
}triggerProps}
      className="flex size-[38px] items-center justify-center rounded-sm bg-[#3bc4a1] text-white"
    >
      <${function SearchIcon(): React.JSX.ElementSearchIcon} />
    </button>`,

  type DropdownComponent: React.FC<DropdownProps>DropdownComponent: (props: DropdownPropsprops) =>
    const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<div
      className="mt-1 flex h-full max-h-full min-h-0 flex-col rounded-sm bg-white text-[#374040] shadow-2xl lg:h-auto lg:max-w-[900px] lg:min-w-[600px]"
    >
      ${!props: DropdownPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.isDesktop: booleanisDesktop &&
      const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<form className="flex items-center gap-2 p-2">
        <div className="flex-grow">
          <${const DefaultInput: ((props: {
    state: QuickSearchWidgetState;
}) => React.JSX.Element) & {
    displayName: string;
}DefaultInput} state=${props: DropdownPropsprops.state: QuickSearchWidgetStatestate} />
        </div>
        <button
          ...${props: DropdownPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.closeButtonProps: {
    type: "button";
    onClick: () => void;
    onTouchEnd: () => void;
}closeButtonProps}
          className="flex size-[38px] items-center justify-center"
        >
          <${function CloseIcon(): React.JSX.ElementCloseIcon} />
        </button>
      </form>`}
      <div className="flex">
        <div className="flex min-h-0 flex-col">
          <div className="px-4 py-4 pb-2 text-sm font-semibold text-[#3bc4a1]">
            Segments
          </div>
          <div className="overflow-auto p-2">
            ${props: DropdownPropsprops.state: QuickSearchWidgetStatestate.QuickSearchWidgetState.items: (index: number) => {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]items(1).Array<{ key: string; id: string; recommId: string; values: { [key: string]: any; }; itemProps: { onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void; "data-search-result-id": string; tabIndex: number; }; }>.map<React.ReactElement<unknown, string | React.JSXElementConstructor<any>>>(callbackfn: (value: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}, index: number, array: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]) => React.ReactElement<...>, thisArg?: any): React.ReactElement<...>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.map(
              (item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item) =>
                const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<a
                  key=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.key: stringkey}
                  href=${function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
                    `${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anylink}`,
                    item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.recommId: stringrecommId,
                  )}
                  ...${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.itemProps: {
    onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
    "data-search-result-id": string;
    tabIndex: number;
}itemProps}
                  className="flex items-center gap-2 rounded-sm p-2 outline-hidden hover:bg-[#f7f7f7] focus:bg-[#f7f7f7]"
                  ><div className="flex-grow">
                    <div className="font-semibold">${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.id: stringid}</div>
                  </div></a
                >`,
            )}
          </div>
        </div>
        <div className="flex min-h-0 flex-grow flex-col">
          <div className="px-4 py-4 pb-2 text-sm font-semibold text-[#3bc4a1]">
            Results
          </div>
          <div className="overflow-auto p-2">
            ${props: DropdownPropsprops.state: QuickSearchWidgetStatestate
              .QuickSearchWidgetState.items: (index: number) => {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]items(0)
              .Array<{ key: string; id: string; recommId: string; values: { [key: string]: any; }; itemProps: { onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void; "data-search-result-id": string; tabIndex: number; }; }>.map<React.ReactElement<unknown, string | React.JSXElementConstructor<any>>>(callbackfn: (value: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}, index: number, array: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}[]) => React.ReactElement<...>, thisArg?: any): React.ReactElement<...>[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.map(
                (item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item) =>
                  const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElementhtml`<${const DefaultItem: ((props: DefaultItemProps) => React.JSX.Element) & {
    displayName: string;
}Default Item component provided for basic usage.
@publicDefaultItem}
                    key=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.key: stringkey}
                    href=${function addRecommIdQueryParam(url: string, recommId: string | undefined): stringUtility function to append `recombee_recomm_id` parameter to an url string.
For usage in widget template to construct item link URL.
@publicaddRecommIdQueryParam(
                      `${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anylink}`,
                      item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.recommId: stringrecommId,
                    )}
                    primaryContent=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anyproduct_title}
                    secondaryContent=${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.values: {
    [key: string]: any;
}values?.__type[string]: anycategory}
                    ...${item: {
    key: string;
    id: string;
    recommId: string;
    values: {
        [key: string]: any;
    };
    itemProps: {
        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
        "data-search-result-id": string;
        tabIndex: number;
    };
}item.itemProps: {
    onKeyDown: (event: React.KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void;
    "data-search-result-id": string;
    tabIndex: number;
}itemProps}
                  />`,
              )}
          </div>
        </div>
      </div>
    </div>`,
});

Copy

API Reference

const

DefaultItem

Default Item component provided for basic usage.

interface

DefaultItemProps

Properties

className

string | undefined

Custom classes of item wrapper element. See Custom CSS.

classNameDisableBase

boolean | undefined

Disables default classes of item wrapper element.

There are some default class names with essential styles applied to the item wrapper element. This setting disables them as an escape hatch for customization. See Custom CSS.

imageWrapperClassName

string | undefined

Custom classes of item image wrapper element. See Custom CSS.

imageWrapperClassNameDisableBase

boolean | undefined

Disables default classes of item image wrapper element.

There are some default class names with essential styles applied to the item image wrapper element. This setting disables them as an escape hatch for customization. See Custom CSS.

contentWrapperClassName

string | undefined

Custom classes of item content element. See Custom CSS.

result

Recommendation | undefined

A single item recommedation.

href

string | null | undefined

Item link URL.

image

ReactNode

Item Image element.

labelContent

ReactNode

Item content above title. Sets the entire content of an item aside from an image.

labelContentWrapperClassName

string | undefined

Custom classes of label content wrapper element. See Custom CSS.

labelContentWrapperClassNameDisableBase

boolean | undefined

Disables default classes of label content wrapper element.

There are some default class names with essential styles applied to the label content wrapper element. This setting disables them as an escape hatch for customization. See Custom CSS.

title

ReactNode

Item title.

titleWrapperClassName

string | undefined

Custom classes of title wrapper element. See Custom CSS.

titleWrapperClassNameDisableBase

boolean | undefined

Disables default classes of title wrapper element.

There are some default class names with essential styles applied to the title wrapper element. This setting disables them as an escape hatch for customization. See Custom CSS.

highlightedContent

ReactNode

Item content under title. Sets the entire content of an item aside from an image.

highlightedContentWrapperClassName

string | undefined

Custom classes of highlighted content wrapper element. See Custom CSS.

highlightedContentWrapperClassNameDisableBase

boolean | undefined

Disables default classes of highlighted content wrapper element.

There are some default class names with essential styles applied to the highlighted content wrapper element. This setting disables them as an escape hatch for customization. See Custom CSS.

bottomContent

ReactNode

Any custom content to display at the bottom of the item.

const

QuickSearchWidget

Quick Search widget

type

QuickSearchWidgetOptions

Quick Search widget options

Properties

container

string

CSS Selector to target the element where the widget should be inserted.

apiClient

ApiClient

Instance of Recombee JS API Client. See Example.

createRequest

QuickSearchCreateRequestFunction

Request factory function. See Quick Example or visit API Reference for overview of available requests.

onRecommResponse

WidgetRecommResponseCallback | undefined

Callback function allowing to intercept and inspect recommendation request+response made by widget.

TypeScript JavaScript

import React from "react";
import { const CarouselWidget: ({ container, ...props }: CarouselWidgetOptions) => CarouselWidgetState | null | undefinedCarousel Widget initialization function
@publicCarouselWidget } from "@recombee/carousel-widget-js";

function CarouselWidget({ container, ...props }: CarouselWidgetOptions): CarouselWidgetState | null | undefinedCarousel Widget initialization function
@publicCarouselWidget({
  // ...ommited code...
  WidgetConfigurationBase<CreateRequestFunction>.onRecommResponse?: WidgetRecommResponseCallback | undefinedCallback function allowing to intercept and inspect recommendation
request+response made by widget.

```tsx|-react
import React from "react";
import { CarouselWidget } from "@recombee/carousel-widget-react";

//
@noErrors: 2739 2345
<CarouselWidget
// ...ommited code...
onRecommResponse={({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget } from "@recombee/carousel-widget-js";

//@noErrors: 2739 2345
CarouselWidget({
// ...ommited code...
onRecommResponse: ({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
},
});
```@publiconRecommResponse: ({ recombeeRequest: RequestrecombeeRequest, recombeeResponse: anyrecombeeResponse }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  },
});

Copy

initialQuery

string | undefined

minSearchCharactersCount

number

primaryResultsIndex

number | undefined

InputComponent

FC<InputProps>

TriggerComponent

FC<TriggerProps>

DropdownComponent

FC<DropdownProps>

desktopMediaQuery

string

QuickSearchComponent

FC<QuickSearchProps> | undefined

type

QuickSearchWidgetProps

Quick Search component configuration options

Properties

apiClient

ApiClient

Instance of Recombee JS API Client. See Example.

createRequest

QuickSearchCreateRequestFunction

Request factory function. See Quick Example or visit API Reference for overview of available requests.

onRecommResponse

WidgetRecommResponseCallback | undefined

Callback function allowing to intercept and inspect recommendation request+response made by widget.

TypeScript JavaScript

import React from "react";
import { const CarouselWidget: ({ container, ...props }: CarouselWidgetOptions) => CarouselWidgetState | null | undefinedCarousel Widget initialization function
@publicCarouselWidget } from "@recombee/carousel-widget-js";

function CarouselWidget({ container, ...props }: CarouselWidgetOptions): CarouselWidgetState | null | undefinedCarousel Widget initialization function
@publicCarouselWidget({
  // ...ommited code...
  WidgetConfigurationBase<CreateRequestFunction>.onRecommResponse?: WidgetRecommResponseCallback | undefinedCallback function allowing to intercept and inspect recommendation
request+response made by widget.

```tsx|-react
import React from "react";
import { CarouselWidget } from "@recombee/carousel-widget-react";

//
@noErrors: 2739 2345
<CarouselWidget
// ...ommited code...
onRecommResponse={({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
}}
/>;
```

```ts|-js
import React from "react";
import { CarouselWidget } from "@recombee/carousel-widget-js";

//@noErrors: 2739 2345
CarouselWidget({
// ...ommited code...
onRecommResponse: ({ recombeeRequest, recombeeResponse }) => {
// use data from request and response for any purpose, i.e. internal tracking
},
});
```@publiconRecommResponse: ({ recombeeRequest: RequestrecombeeRequest, recombeeResponse: anyrecombeeResponse }) => {
    // use data from request and response for any purpose, i.e. internal tracking
  },
});

Copy

initialQuery

string | undefined

minSearchCharactersCount

number

primaryResultsIndex

number | undefined

InputComponent

FC<InputProps>

TriggerComponent

FC<TriggerProps>

DropdownComponent

FC<DropdownProps>

desktopMediaQuery

string

QuickSearchComponent

FC<QuickSearchProps> | undefined

class

QuickSearchWidgetState

Class exposing quick search widget state for use in custom templates

Properties

isDesktop

boolean

inputRef

ObservableRef<HTMLElement>

triggerRef

ObservableRef<HTMLElement>

dropdownRef

ObservableRef<HTMLElement>

handleInputChange

(event: ChangeEvent<HTMLInputElement>) => void

handleInputClick

() => void

inputProps

{ value: string; onChange: (event: ChangeEvent<HTMLInputElement>) => void; onKeyDown: (event: KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void; onClick: () => void; ref: (element: HTMLElement | null) => void; }

triggerProps

{ ref: (element: HTMLElement | null) => void; onClick: () => void; }

closeButtonProps

{ type: "button"; onClick: () => void; onTouchEnd: () => void; }

handleInteractionKeyDown

(event: KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void

items

(index: number) => { key: string; id: string; recommId: string; values: { [key: string]: any; }; itemProps: { onKeyDown: (event: KeyboardEvent<HTMLInputElement | HTMLAnchorElement | HTMLDivElement>) => void; "data-search-result-id": string; tabIndex: number; }; }[]

isExpanded

boolean

isLoading

boolean

const

ItemImage

Item image component

type

ItemImageProps

Item Image properties

Properties

src

string | null | undefined

Image URL

missingImageSrc

string | undefined

URL of an image to display when the main image could not be loaded.

className

string | undefined

Image wrapper class name

imgClassName

string | undefined

Image class name

width

number | undefined

Image width in pixels

height

number | undefined

Image height in pixels

verticalAlignment

"top" | "center" | "bottom" | undefined

Image vertical alignment

horizontalAlignment

"center" | "left" | "right" | undefined

Image horizontal alignment

fittingAlgorithm

"cover" | "scale_down" | undefined

Image fitting algorithm

function

addRecommIdQueryParam

Utility function to append recombee_recomm_id parameter to an url string. For usage in widget template to construct item link URL.