FieldSuggestions

This is for:

Developer

In this article

Example implementation
Methods
Attributes
Initialize
Related types

Note

This component was introduced in version 1.54.0.

Example implementation

field-suggestions.fn.tsx

import {FieldSuggestions as HeadlessFieldSuggestions} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
 
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 facetOptions: FacetOptions = {field: 'author'};
 * const options: FieldSuggestionsOptions = {facet: facetOptions};
 * 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 suggestions.

`search`

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

value: FieldSuggestionsValue

The field suggestion for which to select the matching facet value.

`showMoreResults`

Shows more field suggestions for the current query.

`singleSelect`

Filters the search using the specified value, deselecting others.

If a facet exists with the configured facetId, selects the corresponding facet value while deselecting other facet values.

Parameters

value: FieldSuggestionsValue

The field suggestion for which to select the matching facet value.

`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 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.

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: FieldSuggestionsValue[]

The field suggestions.

Initialize

`buildFieldSuggestions`

Creates a FieldSuggestions controller instance.

This controller initializes a facet under the hood, but exposes state and methods that are relevant for suggesting field values based on a query. It’s important not to initialize a facet with the same facetId but different options, because only the options of the controller which is built first will be taken into account.

Parameters

engine: SearchEngine

The headless engine.
props: FieldSuggestionsProps

The configurable FieldSuggestions controller properties.

Returns FieldSuggestions