FieldSuggestions
FieldSuggestions
This is for:
DeveloperExample 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
FieldSuggestionsProps
The configurable FieldSuggestions
controller properties.
Properties
-
options:
FieldSuggestionsOptions
The options for the
FieldSuggestions
controller.
FieldSuggestionsOptions
The options for the FieldSuggestions
controller.
Properties
-
facet:
FacetOptions
The options used to register the facet used by the field suggestions controller.
Related Types
FacetOptions
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 itsfield
in the current result set. -
customSort?:
string[]
Identifies the facet values that must appear at the top, in this order. This parameter can be used in conjunction with the
sortCriteria
parameter.Facet values not part of the
customSort
list will be sorted according to thesortCriteria
.The maximum amount of custom sort values is 25.
The default value is
undefined
, and the facet values will be sorted using only thesortCriteria
. -
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
-
resultsMustMatch?:
'allValues' | 'atLeastOneValue'
The criterion to use for specifying how results must match the selected facet values.
Default:
atLeastOneValue
-
sortCriteria?:
'score' | 'alphanumeric' | 'alphanumericDescending' | 'occurrences' | 'automatic'
The criterion to use for sorting returned facet values.
The
sortCriteria
option does not apply when making a facet search request. It is only used for sorting returned facet values during a regular Coveo search request.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.
FieldSuggestionsValue
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 theFieldSuggestion
controller. -
rawValue:
string
The original field value, as retrieved from the field in the index.
Unsubscribe
Call signatures
-
(): void;