InstantResults

This is for:

Developer

Example Implementation

instant-results.fn.tsx

import {
  SearchBox as HeadlessSearchBox,
  InstantResults as HeadlessInstantResults,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
 
interface InstantResultsProps {
  controllerSearchbox: HeadlessSearchBox;
  controllerInstantResults: HeadlessInstantResults;
}
 
export const InstantResults: FunctionComponent<InstantResultsProps> = (
  props
) => {
  const {controllerSearchbox, controllerInstantResults} = props;
  const isEnterKey = (e: React.KeyboardEvent<HTMLInputElement>) =>
    e.key === 'Enter';
  const [searchboxState, setStateSearchbox] = useState(
    controllerSearchbox.state
  );
  const [instantResultsState, setStateInstantResults] = useState(
    controllerInstantResults.state
  );
 
  useEffect(
    () =>
      controllerSearchbox.subscribe(() =>
        setStateSearchbox(controllerSearchbox.state)
      ),
    []
  );
  useEffect(
    () =>
      controllerInstantResults.subscribe(() =>
        setStateInstantResults(controllerInstantResults.state)
      ),
    []
  );
 
  return (
    <div>
      <p>
        Type in the searchbox and hover a query suggestion to preview associated
        results
      </p>
 
      <input
        value={searchboxState.value}
        onChange={(e) => controllerSearchbox.updateText(e.target.value)}
        onKeyDown={(e) => isEnterKey(e) && controllerSearchbox.submit()}
      />
 
      <div style={{display: 'flex'}}>
        <ul>
          {searchboxState.suggestions.map((suggestion) => {
            const value = suggestion.rawValue;
            return (
              <li
                key={value}
                onMouseEnter={() => controllerInstantResults.updateQuery(value)}
                onClick={() => controllerSearchbox.selectSuggestion(value)}
              >
                {value}
              </li>
            );
          })}
        </ul>
        <ul>
          {instantResultsState.results.map((result) => {
            return (
              <li>
                <div>
                  {result.title}: {result.raw.source}
                </div>
                <pre>{result.excerpt}</pre>
              </li>
            );
          })}
        </ul>
      </div>
    </div>
  );
};
 
// usage
 
/**
 * ```tsx
 * const controllerSearchbox = buildSearchBox(engine, {options: {id: 'foo'}});
 * const controllerInstantResults = buildInstantResults(engine, {options: {maxResultsPerQuery: 5, searchBoxId: 'foo'}});
 *
 * <InstantResults controllerSearchbox={controllerSearchbox} controllerInstantResults={controllerInstantResults}  />;
 * ```
 */

The InstantResults controller allows the end user to manage instant results queries.

Example: instant-results.fn.tsx

Methods

clearExpired

Clears all expired instant results queries.

updateQuery

Updates the specified query and shows instant results for it.

Parameters

  • q: string

    The query to get instant results for. For more precise instant results, query suggestions are recommended.

subscribe

Adds a callback that’s invoked on state change.

Parameters

  • listener: () => void

    A callback that’s invoked on state change.

Returns Unsubscribe: A function to remove the listener.

Attributes

state

The state of the InstantResults controller.

Properties

  • error: SearchAPIErrorWithStatusCode | SerializedError | null

    An error returned when executing an instant results request, if any. This is null otherwise.

  • isLoading: boolean

    Determines if a search is in progress for the current query.

  • q: string

    The current query for instant results.

  • results: Result[]

    The instant results for the current query.

Initialize

buildInstantResults

Creates an InstantResults controller instance.

Parameters

  • engine: SearchEngine

    The Headless engine.

  • props: InstantResultProps

    The configurable InstantResults properties.

Returns InstantResults

InstantResultProps

The configurable InstantResults properties.

Properties

InstantResultOptions

Properties

  • maxResultsPerQuery: number

    The maximum items to be stored in the instant result list for each query.

  • cacheTimeout?: number

    Number in milliseconds that cached results will be valid for. Defaults to 1 minute. Set to 0 so that results never expire.

  • searchBoxId?: string

    A unique identifier for the search box.

HighlightKeyword

Properties

  • length: number

    The length of the offset.

  • offset: number

    The 0 based offset inside the string where the highlight should start.

Raw

Properties

  • [key: string]: unknown

    Custom keys that depend on the documents in the index.

Result

Properties

  • absentTerms: string[]

    The basic query expression terms which this query result item does not match. Note: This property is populated by terms from the query pipeline-processed q value (not from the original q value).

  • clickUri: string

    The hyperlinkable item URI. Notes: Use the clickUri value when you want to create hyperlinks to the item, rather than the uri or printableUri value.

  • excerpt: string

    The contextual excerpt generated for the item (see the excerptLength query parameter).

  • excerptHighlights: HighlightKeyword[]

    The length and offset of each word to highlight in the item excerpt string.

  • firstSentences: string

    The first sentences retrieved from the item (see the retrieveFirstSentences query parameter).

  • firstSentencesHighlights: HighlightKeyword[]

    The length and offset of each word to highlight in the item firstSentences string.

  • flags: string

    The flags that are set on the item by the index. Distinct values are separated by semicolons.

  • hasHtmlVersion: boolean

    Whether the index contains an HTML version of this item.

  • isRecommendation: boolean

    Whether the item score was boosted as a Coveo ML recommendation.

  • isTopResult: boolean

    Whether the item score was boosted by a featured result rule in the query pipeline.

  • isUserActionView: boolean

    Whether the result item has been previously viewed by one of the users specified in the canSeeUserProfileOf section of the search token generated to perform the search request.

  • percentScore: number

    The item ranking score expressed as a percentage (see the sortCriteria and rankingFunctions query parameters).

  • printableUri: string

    The human readable item URI. Note: Avoid using the printableUri value to create hyperlinks to the item. Use the clickUri value instead.

  • printableUriHighlights: HighlightKeyword[]

    The length and offset of each word to highlight in the item printableUri string.

  • rankingInfo: string | null

    The raw debug information generated by the index to detail how the item was ranked. This property is null unless the debug query parameter is set to true.

  • raw: Raw

    The values of the fields which were retrieved for this item (see the fieldsToInclude and fieldsToExclude query parameters).

  • score: number

    The total ranking score computed for the item (see the sortCriteria and rankingFunctions query parameters).

  • searchUid: string

    The unique identifier of the search that returned this result.

  • summary: null

    The item summary (see the summaryLength query parameter).

  • summaryHighlights: HighlightKeyword[]

    The length and offset of each word to highlight in the item summary string.

  • title: string

    Contains the title of the item.

  • titleHighlights: HighlightKeyword[]

    The length and offset of each word to highlight in the item title string.

  • uniqueId: string

    The unique item identifier. You should consider the uniqueId value as an opaque string.

  • uri: string

    The item URI. Notes: Avoid using the uri value to create hyperlinks to the item. Use the clickUri value instead.

  • rankingModifier?: string

    If applicable, represents the type of ranking modification that was applied to this result.

Unsubscribe

Call signatures

  • (): void;