usePreviewSearch

The usePreviewSearch hook returns the data and functionality to provides a way to perform preview search.

Parameters

This hook accepts a single optional object parameter:

type PVSInitialState = {
    keyphrase?: string;
    suggestionsList?: Array<{
      suggestion: string;
      max?: number;
    }>;
    itemsPerPage?: number;
  }
Copy

{
  query?: (query: Query<Request>) => void, // method to init query request customized
  state?: PVSInitialState | () => PVSInitialState;
}
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: {
        onSuggestionAdded: ({ suggestion: string, max?: number }) => void,
        onSuggestionRemoved: ({ suggestion: string, max?: number }) => void,
        onKeyphraseChange: ({ keyphrase: string }) => void,
        onItemClick: ({ id: string, index: number, sourceId?: string }) => void // Track item click event
        onSuggestionClick: ({ name: string, title?: string, value?: string, displayName?: string, uri?: string }) => void // Track suggestion click event
    },
    // the following are default values
    state: {
        keyphrase: string,
        suggestionsList: [{
            suggestion: string; // suggestion name configured in CEC suggestions blocks i.e. content_name_context_aware, content_trending_category
            max?: number; // max count of suggestion to return
        }];
        itemsPerPage: number;
    },
    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: {
            suggestion: {
                [key: string]: [{
                    freq: number,
                    text: string
                }]
            } = {},
            content: items = [] ,
        } = {},
    }
}
Copy

Importing

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

Usage: Example for content entity

import React from 'react';

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

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

type ArticleModel = {
  id: string;
  name: string;
  image_url: string;
  url: string;
};
type InitialState = PreviewSearchInitialState<'itemsPerPage' | 'suggestionsList'>;

const PreviewSearchWidget = ({ defaultItemsPerPage = 6 }) => {
  const {
    widgetRef,
    state: { itemsPerPage, keyphrase },
    actions: { onItemClick, onKeyphraseChange },
    queryResult: {
      isFetching,
      isLoading,
      data: {
        content: items = [],
        suggestion: {
          content_name_context_aware: articleSuggestions = [],
          content_trending_category: trendingCategorySuggestions = [],
        } = {},
      } = {},
    },
  } = usePreviewSearch<ArticleModel, InitialState>({
      state: {
        suggestionsList: [
          { suggestion: 'content_name_context_aware', max: 10 },
          { suggestion: 'content_trending_category', max: 10 },
        ],
        itemsPerPage: defaultItemsPerPage
      }
    });

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

const MyPreviewSearchWidget = widget(PreviewSearchWidget, WidgetDataType.PREVIEW_SEARCH, '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.PREVIEW_SEARCH.