useSearchResults

The useSearchResults hook returns the data and functionality to provides a way to perform a search results widget.

Parameters

This hook accepts a single optional object parameter with 3 properties, query, state and config.

Example of SearchResultInitialState:

type SearchResultInitialState = {
    page?: number;
    keyphrase?: string;
    selectedFacets?: Record<string, { facet: { name: string, label: string }, values: Array<id:string> }>;
    itemsPerPage?: number;
    sortType?: string;
  }
Copy

Examle for config:

// type definition

type FacetPayloadType = 'valueId' | 'text' | 'rage';

interface SearchResultsFacetConfigItem {
  type: FacetPayloadType;
}

export type SearchResultsConfig = {
  facets?: {
    [key: string]: SearchResultsFacetConfigItem;
  };
};

// Example
{
  config: {
    facets: {
      price: { type: 'range' }, // This tells the sdk to handle price as a range
      brand: { type: 'text' }, // This tells the sdk to allow match by text
      color: { type: 'valueId' } // This tells the sdk to match by facet id
    }
  }
}
Copy

{
  query?: (query: Query<Request>) => void, // method to init query request customized
  state?: SearchResultInitialState | () => SearchResultInitialState,
  config: SearchResultsConfig,
}
Copy

Return Value

{
    // rfkId of the widget.
    rfkId,
    // Access to the widget query. This will make the query available on the widget scope.
    query,
    // Widget dom reference.
    widgetRef,
    // Actions available for this widget.
    actions: {
        onKeyphraseChange: ({ keyphrase: string }) => void,
        onClearFilters: () => void,
        onResultsPerPageChange: ({ numItems: number }) => void,
        onPageNumberChange: ({ page: number }) => void,
        onItemClick: ({ id: string, index: number }) => void // Track click product event
        onFilterClick: ({ facetId: string, facetValueId: string, checked: boolean }) => void,
        onSortChange: ({ name: string }) => void,
        onFacetClick ({facetId: string, facetValueId: string, facetIndex: number, facetValueIndex: number, checked: boolean}) => void,
    },
    // the following are default values
    state: {
        page: number, // The current page.
        keyphrase: string,
        selectedFacets: Array<SearchResultsStoreSelectedFacet>, // The initial values for the selected facets
        itemsPerPage: number, // The number of results per page.
        sortType: string, // The value for sorting results.

    },
    queryResult: {
        isLoading, // The query has no data and is currently fetching
        isError,// The query encountered an error
        isSuccess, // The query was successful and data is available
        isFetching, // In any state, if the query is fetching at any time (including background refetching) isFetching will be true.
        data: {
            total_item: number, // The total count of results.
            limit: number,
            offset: number,
            related_questions: [{
                answer: string,
                context: string,
                document_id: string,
                extra_fields: Record<string, any>,
                highlight: string,
                question: string,
            }] = [],
            sort: { 
                choices: [
                    {
                        label: string,
                        name: string
                    }] = []
                } = {},
            facet: [
                {
                    name: string;
                    label: string;
                    value: [
                        count: number;
                        id: string;
                        max: number;
                        min: number;
                        text: string;
                    ];
                }] = [],
            content: items = [],
        } = {},
    }
}
Copy

Importing

import { useSearchResults } from '@sitecore-search/react';
Copy

Usage

import React from 'react';
import type { SearchResultsInitialState, SearchResultsStoreState } from '@sitecore-search/react';

import { WidgetDataType, WidgetsProvider, useSearchResults, widget } from '@sitecore-search/react';

const MyApp = () => {
    return (
        <WidgetsProvider
                env='<environment>'
                customerKey='<customer key>'
                apiKey='<API key provided in CEC>'
            >
            <MySearchResultsWidget />
        </WidgetsProvider>
)};

type ArticleSearchResultsProps = {
  defaultSortType?: SearchResultsStoreState['sortType'];
  defaultPage?: SearchResultsStoreState['page'];
  defaultItemsPerPage?: SearchResultsStoreState['itemsPerPage'];
  defaultKeyphrase?: SearchResultsStoreState['keyphrase'];
};

type InitialState = SearchResultsInitialState<'itemsPerPage' | 'keyphrase' | 'page' | 'sortType' | 'selectedFacets'>;

const MySearchResultsComponent = ({
  defaultSortType = 'featured_desc',
  defaultPage = 1,
  defaultKeyphrase = '',
  defaultItemsPerPage = 24,
}: ArticleSearchResultsProps) => {
    const {
        widgetRef,
        actions: {
            onResultsPerPageChange,
            onPageNumberChange,
            onItemClick,
            onFilterClick,
            onSortChange,
            onFacetClick,
            onClearFilters,
        },
        state: { sortType, page, itemsPerPage },
        queryResult: {
            isLoading,
            isFetching,
            data: {
                limit = 1,
                total_item: totalItems = 0,
                sort: { choices: sortChoices = [] } = {},
                facet: facets = [],
                content: articles = [],
            } = {},
        },
    } = useSearchResults<ArticleModel, InitialState>({
        state: {
            sortType: defaultSortType,
            page: defaultPage,
            itemsPerPage: defaultItemsPerPage,
            keyphrase: defaultKeyphrase,
            selectedFacets: [{
              facetId: 'price',
              min: 0,
              max: 10,
            }, {
              facetId: 'brand',
              facetValueText: 'Brand 1',
            }, {
              facetId: 'color',
              facetValueId: 'facetIdForColor'
            }]
        },
    });

    return (
      <div ref={widgetRef}>
        // Logic here. Refer to Widget templates to see a complete example 
      </div>
   );
}

const MySearchResultsWidget = widget(MySearchResultsComponent, WidgetDataType.SEARCH_RESULTS, 'content');
Copy

Note: To make the hook available, the SDK needs the component to be registered. This can be made using the widget function. Where the first parameter for widget is the component itself, the second one a constant that indicates the widget type and the last one is the entity type. In this case the widget type constant is getting from WidgetDataType.SEARCH_RESULTS.