Skip to content

Search API

Feature name: h-storefront-search

Api name: SearchApi

API used to perform search actions in the shop.

classDiagram
direction LR
    SearchAPI --> getSuggestions
    SearchAPI --> search
    SearchAPI --> searchForProducts
    SearchAPI --> searchForProducers
    SearchAPI --> searchForCategories

    class SearchAPI {
        getSuggestions(query: string) Promise~string[]|null~
        search(suggestion: string, query?: string) Promise~TSearchResponse|null~
        searchForProducts(query: string, page: number) Promise~TSearchProductsResponse|null~
        searchForProducers(query: string, page: number) Promise~TSearchProducersResponse|null~
        searchForCategories(query: string, page: number) Promise~TSearchCategoriesResponse|null~
    }

    link getSuggestions "../methods/get-suggestions/"
    link search "../methods/search/"
    link searchForProducts "../methods/search-for-products/"
    link searchForProducers "../methods/search-for-producers/"
    link searchForCategories "../methods/search-for-categories/"

Get API

To get the Search API use its name SearchApi with the getApi method.

useStorefront(async (storefront) => {
    const searchApi = await storefront.getApi('SearchApi');
});

This API is initialized only after h-storefront-search webcomponent has been added to the page. Unless you add the webcomponent, you won't be able to fetch the API. If you wish to use the API alone without the webcomponent you can use the registerDynamic method from the Feature System API. Here is an example on how to do it:

useStorefront(async (storefront) => {
    const featureSystemApi = this.getApiSync('FeatureSystemApi');
    await featureSystemApi.registerDynamic('h-storefront-search');

    const searchApi = storefront.getApiSync('SearchApi');
});

Methods

Event Bus events

Methods of this API dispatch the following events with the Event Bus:

Example

In this example we make a SearchApi call to search for products.

useStorefront(async (storefront) => {
    const searchApi = await storefront.getApi('SearchApi');

    const products = searchApi.search('black shirt');
});

Example

In this example we make a SearchApi call to get search results based on a given query and suggestion.

    useStorefront(async (storefront) => {
        const searchApi = await storefront.getApi('SearchApi');

        const $searchElement = document.querySelector('input[type="search"]');

        $searchElement.addEventListener('keydown', (ev) => {
            if (ev.key.length !== 1) return;

            const searchPhrase = ev.target.value;

            const suggestions = await searchApi.getSuggestions(searchPhrase);

            const searchResultsWithSuggestions = await searchApi.search(suggestions[0], searchPhrase);

            console.log('search results with suggestions', searchResultsWithSuggestions);
        });
    });

Example

In this example we listen to loadMoreProducts event and load more products whenever it's emitted.

useStorefront(async (storefront) => {
    const searchApi = await storefront.getApi('SearchApi');

    const $exampleElement = document.querySelector('my-element');

    handleLoadMoreProducts($exampleElement);

    document.addEventListener('loadMoreProducts', (event) => {
        if (!event.detail) return;

        const { searchPhrase, page, moduleInstanceId } = event.detail;

        const moreProducts = await searchApi.searchForProducts(searchPhrase, page);

        console.log('more products have been loaded', moreProducts);

        // Assuming this component has a method for handling more products.
        // We could also write the method globally if needed.
        $element.exampleHandleMoreProducts(moreProducts);
    });
});

Models Reference

Objects Reference

Webcomponents reference

APIs reference