Facet (Product Listing Engine)
Facet (Product Listing Engine)
Example Implementation
facet.fn.tsx
import {Facet as HeadlessFacet} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
import {FacetSearch} from './facet-search';
interface FacetProps {
controller: HeadlessFacet;
}
export const Facet: FunctionComponent<FacetProps> = (props) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
if (!state.values.length) {
return <div>No facet values</div>;
}
return (
<ul>
<li>
<FacetSearch
controller={controller.facetSearch}
facetState={state.facetSearch}
isValueSelected={(facetSearchValue) =>
!!state.values.find(
(facetValue) =>
facetValue.value === facetSearchValue.displayValue &&
controller.isValueSelected(facetValue)
)
}
/>
</li>
<li>
<ul>
{state.values.map((value) => (
<li key={value.value}>
<input
type="checkbox"
checked={controller.isValueSelected(value)}
onChange={() => controller.toggleSelect(value)}
disabled={state.isLoading}
/>
{value.value} ({value.numberOfResults} results)
</li>
))}
</ul>
</li>
</ul>
);
};
// usage
/**
* ```tsx
* const options: FacetOptions = {field: 'objecttype'};
* const controller = buildFacet(engine, {options});
*
* <Facet controller={controller} />;
* ```
*/
facet-search.tsx
import {
FacetSearch as HeadlessFacetSearch,
FacetSearchState,
SpecificFacetSearchResult,
} from '@coveo/headless';
import {FunctionComponent} from 'react';
export interface FacetSearchProps {
controller: HeadlessFacetSearch;
facetState: FacetSearchState;
isValueSelected: (facetSearchValue: SpecificFacetSearchResult) => boolean;
}
export const FacetSearch: FunctionComponent<FacetSearchProps> = (props) => {
const onInput = (text: string) => {
props.controller.updateText(text);
props.controller.search();
};
return (
<div>
<input onInput={(e) => onInput(e.currentTarget.value)} />
<ul>
{props.facetState.values.map((facetSearchValue) => (
<li key={facetSearchValue.rawValue}>
<button
onClick={() => props.controller.select(facetSearchValue)}
disabled={props.isValueSelected(facetSearchValue)}
>
{facetSearchValue.displayValue} ({facetSearchValue.count} results)
</button>
</li>
))}
</ul>
</div>
);
};
The Facet
controller allows you to create a search interface component that the end user can use to refine a query by selecting filters based on item metadata (that is, field values). If you have enabled a Dynamic Navigation Experience (DNE) model, the Facet
controller automatically reorders facet values according to the user query.
Methods
deselectAll
Deselects all facet values.
disable
Disables the facet. In other words, prevents it from filtering results.
enable
Enables the facet. In other words, undoes the effects of disable
.
isSortedBy
Checks whether the facet values are sorted according to the specified criterion.
Parameters
-
criterion:
FacetSortCriterion
The criterion to compare.
Returns boolean
: Whether the facet values are sorted according to the specified criterion.
isValueExcluded
Checks whether the specified facet value is excluded.
Parameters
-
value:
FacetValue
The facet value to check.
Returns boolean
: Whether the specified facet value is excluded.
isValueSelected
Checks whether the specified facet value is selected.
Parameters
-
value:
FacetValue
The facet value to check.
Returns boolean
: Whether the specified facet value is selected.
showLessValues
Sets the number of values displayed in the facet to the originally configured value.
showMoreValues
Increases the number of values displayed in the facet to the next multiple of the originally configured value.
sortBy
Sorts the facet values according to the specified criterion.
Parameters
-
criterion:
FacetSortCriterion
The criterion to use for sorting values.
toggleExclude
Toggles exclusion of the specified facet value.
Parameters
-
selection:
FacetValue
The facet value to toggle exclusion.
toggleSelect
Toggles the specified facet value.
Parameters
-
selection:
FacetValue
The facet value to toggle.
toggleSingleExclude
Excludes the specified facet value, deselecting others.
Parameters
-
selection:
FacetValue
The facet value to toggle exclusion.
toggleSingleSelect
Toggles the specified facet value, deselecting others.
Parameters
-
selection:
FacetValue
The facet value to toggle.
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
facetSearch
Provides methods to search the facet’s values.
clear
Resets the query and empties the values.
exclude
Excludes a facet search result.
Parameters
-
value:
SpecificFacetSearchResult
The search result to exclude.
search
Performs a facet search.
select
Selects a facet search result.
Parameters
-
value:
SpecificFacetSearchResult
The search result to select.
showMoreResults
Shows more facet search results.
singleExclude
Excludes a search result while including facet values.
Parameters
-
value:
SpecificFacetSearchResult
The search result to exclude.
singleSelect
Selects a search result while deselecting facet values.
Parameters
-
value:
SpecificFacetSearchResult
The search result to select.
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.
state
The state of the Facet
controller.
Properties
-
facetSearch:
FacetSearchState
The state of the facet’s searchbox.
-
canShowLessValues:
boolean
true
if fewer values can be displayed andfalse
otherwise. -
canShowMoreValues:
boolean
true
if there are more values to display andfalse
otherwise. -
enabled:
boolean
Whether the facet is enabled and its values are used to filter search results.
-
facetId:
string
The facet ID.
-
hasActiveValues:
boolean
true
if there is at least one non-idle value andfalse
otherwise. -
isLoading:
boolean
true
if a search is in progress andfalse
otherwise. -
sortCriterion:
FacetSortCriterion
The active sortCriterion of the facet.
-
values:
FacetValue[]
The values of the facet.
Initialize
buildFacet
Creates a Facet
controller instance for the product listing.
Parameters
-
engine:
ProductListingEngine
The headless engine.
-
props:
FacetProps
The configurable
Facet
properties.
Returns Facet
FacetProps
The configurable Facet
properties.
Properties
-
options:
FacetOptions
The options for the
Facet
controller.
FacetOptions
The options for the Facet
controller.
Properties
-
field:
string
The field whose values you want to display in the facet.
-
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
-
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?:
FacetResultsMustMatch
The criterion to use for specifying how results must match the selected facet values.
Default:
atLeastOneValue
-
sortCriteria?:
FacetSortCriterion
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
Related Types
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.
FacetSearchState
Properties
-
isLoading:
boolean
true
if the facet search is in progress andfalse
otherwise. -
moreValuesAvailable:
boolean
Whether more values are available.
-
query:
string
The current query in the facet search box.
-
values:
SpecificFacetSearchResult[]
The facet search results.
FacetValue
Properties
-
numberOfResults:
number
The number of results that have the facet value.
-
state:
'idle' | 'selected' | 'excluded'
Whether a facet value is filtering results (
selected
) or not (idle
). -
value:
string
The facet value.
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