CategoryFieldSuggestions (Deprecated)

This is for:

Developer
Warning

Headless v1 has been deprecated. We recommend using the latest version of the Coveo Headless library.

Example implementation

category-suggestions.fn.tsx

import {CategoryFieldSuggestions as HeadlessCategoryFieldSuggestions} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';

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 facetOptions: CategoryFacetOptions = {field: 'geographicalhierarchy'}
 * const options: CategoryFieldSuggestionsOptions = {facet: facetOptions};
 * 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 suggestions.

Requests field suggestions based on a query.

select

Filters the search using the specified value.

If a facet exists with the configured facetId, selects the corresponding facet value.

Parameters

showMoreResults

Shows more field suggestions for the current query.

updateCaptions

Updates the captions of field suggestions.

Parameters

  • captions: Record<string, string>

    A dictionary that maps field values to field suggestion display names.

updateText

Requests field suggestions based on a query.

Parameters

  • text: string

    The query with which to request field suggestions.

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

Properties

  • isLoading: boolean

    Whether the request for field suggestions is in progress.

  • moreValuesAvailable: boolean

    Whether more field suggestions are available.

  • query: string

    The query used to request field suggestions.

  • values: CategoryFieldSuggestionsValue[]

    The field suggestions.

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 for which you wish to get field suggestions.

  • basePath?: string[]

    The base path shared by all values for the field suggestions.

    Default: []

  • delimitingCharacter?: string

    The character that specifies the hierarchical dependency.

    Default: ;

  • facetId?: string

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

    If a facet shares the same id, then its values are going to be selectable with select and singleSelect. However, you must make sure to build the field suggestion controller after the facet controller.

  • facetSearch?: CategoryFieldSuggestionsFacetSearchOptions

    The options related to search.

  • 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 field suggestion.

    Default: true

  • injectionDepth?: number

  • numberOfValues?: number

    This option has no effect.

  • sortCriteria?: 'alphanumeric' | 'occurrences'

    The criterion to use to sort returned field suggestions. Learn more about sortCriteria values and the default behavior of specific facets in the Search API documentation.

    Default: automatic

CategoryFieldSuggestionsFacetSearchOptions

Properties

  • captions?: Record<string, string>

    A dictionary that maps field values to field suggestion display names.

  • numberOfValues?: number

    The maximum number of suggestions to request.

    Default: 10

  • query?: string

    The query with which to request field suggestions.

CategoryFieldSuggestionsValue

Properties

  • count: number

    An estimated number of result items matching both the current query and the filter expression that would get generated if this field suggestion was selected.

  • displayValue: string

    The custom field suggestion display name, as specified in the captions argument of the FieldSuggestion controller.

  • path: string[]

    The hierarchical path to the value.

  • rawValue: string

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

Unsubscribe

Call signatures

  • (): void