THIS IS ARCHIVED DOCUMENTATION

CategoryFieldSuggestions (Deprecated)

Example Implementation

category-suggestions.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {CategoryFieldSuggestions as HeadlessCategoryFieldSuggestions} from '@coveo/headless';
 
interface CategoryFieldSuggestionsProps {
  controller: HeadlessCategoryFieldSuggestions;
}
 
export const CategoryFieldSuggestions: FunctionComponent<
  CategoryFieldSuggestionsProps
> = (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.path, facetSearchValue.rawValue].join(
              '>'
            )}
            onClick={() => controller.select(facetSearchValue)}
          >
            {[...facetSearchValue.path, facetSearchValue.displayValue].join(
              ' > '
            )}{' '}
            ({facetSearchValue.count} results)
          </li>
        ))}
      </ul>
    </div>
  );
};
 
// usage
 
/**
 * ```tsx
 * const options: CategoryFieldSuggestionsOptions = {field: 'geographicalhierarchy'};
 * const controller = buildCategoryFieldSuggestions(engine, {options});
 *
 * <CategoryFieldSuggestions controller={controller} />;
 * ```
 */

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

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

This controller is a wrapper around the basic category 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.

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 facet search query.

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

buildCategoryFieldSuggestions

Creates a CategoryFieldSuggestions controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: CategoryFieldSuggestionsProps

    The configurable CategoryFieldSuggestions controller properties.

Returns CategoryFieldSuggestions

CategoryFieldSuggestionsProps

The configurable CategoryFieldSuggestions controller properties.

Properties

CategoryFieldSuggestionsOptions

The options for the CategoryFieldSuggestions controller.

Properties

  • field: string

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

  • basePath?: string[]

    The base path shared by all values for the facet.

    Default: []

  • delimitingCharacter?: string

    The character that specifies the hierarchical dependency.

    Default: ;

  • facetId?: string

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

  • facetSearch?: CategoryFacetSearchOptions

    Facet search options.

  • filterByBasePath?: boolean

    Whether to filter the results using basePath.

    Default: true

  • filterFacetCount?: boolean

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

    Default: true

  • injectionDepth?: number

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

    Note: A high injectionDepth may reduce facet request performance.

    Minimum: 0

    Default: 1000

  • numberOfValues?: number

    The number of values to request for this facet. This option also determines the number of additional values to request each time this facet is expanded, as well as the number of values to display when this facet is collapsed.

    Minimum: 1

    Default: 5

  • sortCriteria?: 'alphanumeric' | 'occurrences'

    The criterion to use for sorting returned facet values.

    Default: occurrences

CategoryFacetSearchOptions

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 string to match.

CategoryFacetSearchResult

Properties

  • count: number

    An estimate of the number of result items that match both the current query and the filter expression which would be 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.

  • path: string[]

    The hierarchical path to the facet value.

  • rawValue: string

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

Unsubscribe

Call signatures

  • (): void