THIS IS ARCHIVED DOCUMENTATION

FieldSuggestions (Deprecated)

Example Implementation

field-suggestions.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {FieldSuggestions as HeadlessFieldSuggestions} from '@coveo/headless';
 
interface FieldSuggestionsProps {
  controller: HeadlessFieldSuggestions;
}
 
export const FieldSuggestions: FunctionComponent<FieldSuggestionsProps> = (
  props
) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  const onInput = (text: string) => {
    if (text === '') {
      controller.clear();
      return;
    }
    controller.updateText(text);
  };
 
  return (
    <div>
      <input onInput={(e) => onInput(e.currentTarget.value)} />
      <ul>
        {state.values.map((facetSearchValue) => (
          <li
            key={facetSearchValue.rawValue}
            onClick={() => controller.select(facetSearchValue)}
          >
            {facetSearchValue.displayValue} ({facetSearchValue.count} results)
          </li>
        ))}
      </ul>
    </div>
  );
};
 
// usage
 
/**
 * ```tsx
 * const options: FieldSuggestionsOptions = {field: 'author'};
 * const controller = buildFieldSuggestions(engine, {options});
 *
 * <FieldSuggestions controller={controller} />;
 * ```
 */

The FieldSuggestions controller provides query suggestions based on a particular facet field.

For example, you could use this controller to provide auto-completion suggestions while the end user is typing an item title.

This controller is a wrapper around the basic facet controller search functionality, and thus exposes similar options and properties.

Methods

clear

Resets the query and empties the values.

Performs a facet search.

select

Selects a facet search result.

Parameters

showMoreResults

Shows more facet search results.

singleSelect

Selects a search result while deselecting facet values.

Parameters

updateCaptions

Updates the facet value captions.

Parameters

  • captions: Record<string, string>

    A dictionary that maps index field values to facet value display names.

updateText

Updates the facet search query.

Parameters

  • text: string

    The query to search.

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.

Initialize

buildFieldSuggestions

Creates a FieldSuggestions controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: FieldSuggestionsProps

    The configurable FieldSuggestions controller properties.

Returns FieldSuggestions

FieldSuggestionsProps

The configurable FieldSuggestions controller properties.

Properties

FieldSuggestionsOptions

The options for the FieldSuggestions controller.

Properties

  • field: string

    The field whose values you want to display in the facet.

  • allowedValues?: string[]

    Specifies an explicit list of allowedValues in the Search API request.

    If you specify a list of values for this option, the facet uses only these values (if they are available in the current result set).

    The maximum amount of allowed values is 25.

    Default value is undefined, and the facet uses all available values for its field in the current result set.

  • delimitingCharacter?: string

  • facetId?: string

    A unique identifier for the controller. By default, a random unique identifier is generated.

  • facetSearch?: FacetSearchOptions

    Facet search options.

  • filterFacetCount?: boolean

    Whether to exclude the parents of folded results when estimating the result count for each facet value.

    Default: true

  • hasBreadcrumbs?: boolean

    Specifies whether breadcrumbs appear for the facet

    Default: true

  • injectionDepth?: number

    The maximum number of results to scan in the index to ensure that the facet lists all potential facet values.

    Note: A high injectionDepth may negatively impact the facet request performance.

    Minimum: 0

    Default: 1000

  • numberOfValues?: number

    The number of values to request for this facet. Also determines the number of additional values to request each time this facet is expanded, and the number of values to display when this facet is collapsed.

    Minimum: 1

    Default: 8

  • sortCriteria?: 'score' | 'alphanumeric' | 'occurrences' | 'automatic'

    The criterion to use for sorting returned facet values. Learn more about sortCriteria values and the default behavior of specific facets in the Search API documentation.

    Default: automatic

FacetSearchOptions

Properties

  • captions?: Record<string, string>

    A dictionary that maps index field values to facet value display names.

  • numberOfValues?: number

    The maximum number of values to fetch.

    Default: 10

  • query?: string

    The query to search the facet values with.

SpecificFacetSearchResult

Properties

  • count: number

    An estimate of the number of result items matching both the current query and the filter expression that would get generated if the facet value were selected.

  • displayValue: string

    The custom facet value display name, as specified in the captions argument of the facet request.

  • rawValue: string

    The original facet value, as retrieved from the field in the index.

Unsubscribe

Call signatures

  • (): void