CategoryFacet (Search Engine)
CategoryFacet (Search Engine)
|
|
Note
This component was introduced in version |
Example implementation
category-facet.fn.tsx
import {
CategoryFacet as HeadlessCategoryFacet,
CategoryFacetValue,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
import {CategoryFacetSearch} from './category-facet-search';
interface CategoryFacetProps {
controller: HeadlessCategoryFacet;
}
export const CategoryFacet: FunctionComponent<CategoryFacetProps> = (props) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
function getUniqueKeyForValue(value: CategoryFacetValue) {
return value.path.join('>');
}
function renderSearch() {
return (
<CategoryFacetSearch
controller={controller.facetSearch}
searchState={state.facetSearch}
/>
);
}
function renderClearButton() {
return (
<button onClick={() => controller.deselectAll()}>All categories</button>
);
}
function renderParents() {
return (
state.hasActiveValues && (
<div>
Filtering by: {renderClearButton()}
{state.parents.map((parentValue, i) => {
const isSelectedValue = i === state.parents.length - 1;
return (
<span key={getUniqueKeyForValue(parentValue)}>
→
{!isSelectedValue ? (
<button onClick={() => controller.toggleSelect(parentValue)}>
{parentValue.value}
</button>
) : (
<span>{parentValue.value}</span>
)}
</span>
);
})}
</div>
)
);
}
function renderActiveValues() {
return (
<ul>
{state.values.map((value) => (
<li key={getUniqueKeyForValue(value)}>
<button onClick={() => controller.toggleSelect(value)}>
{value.value} ({value.numberOfResults}{' '}
{value.numberOfResults === 1 ? 'result' : 'results'})
</button>
</li>
))}
</ul>
);
}
function renderCanShowMoreLess() {
return (
<div>
{state.canShowLessValues && (
<button onClick={() => controller.showLessValues()}>Show less</button>
)}
{state.canShowMoreValues && (
<button onClick={() => controller.showMoreValues()}>Show more</button>
)}
</div>
);
}
if (!state.hasActiveValues && state.values.length === 0) {
return <div>No facet values</div>;
}
return (
<ul>
<li>{renderSearch()}</li>
<li>
{renderParents()}
{renderActiveValues()}
{renderCanShowMoreLess()}
</li>
</ul>
);
};
// usage
/**
* ```tsx
* const options: CategoryFacetOptions = {field: 'geographicalhierarchy'};
* const controller = buildCategoryFacet(engine, {options});
*
* <CategoryFacet controller={controller} />;
* ```
*/
category-facet-search.tsx
import {
CategoryFacetSearch as HeadlessCategoryFacetSearch,
CategoryFacetSearchState,
} from '@coveo/headless';
import {FunctionComponent} from 'react';
export interface CategoryFacetSearchProps {
controller: HeadlessCategoryFacetSearch;
searchState: CategoryFacetSearchState;
}
export const CategoryFacetSearch: FunctionComponent<
CategoryFacetSearchProps
> = (props) => {
const onInput = (text: string) => {
props.controller.updateText(text);
props.controller.search();
};
return (
<div>
<input onInput={(e) => onInput(e.currentTarget.value)} />
<ul>
{props.searchState.values.map((value) => (
<li key={[...value.path, value.rawValue].join('>')}>
<button onClick={() => props.controller.select(value)}>
{value.displayValue} ({value.count} results)
</button>
</li>
))}
</ul>
</div>
);
};
The CategoryFacet headless controller offers a high-level interface for designing a facet UI controller that renders values hierarchically.
Methods
deselectAll
Deselects all facet values.
disable
Disables the facet. That is, prevents it from filtering results.
enable
Enables the facet. That is, undoes the effects of disable.
isSortedBy
Checks whether the facet values are sorted according to the specified criterion.
Parameters
-
criterion:
'alphanumeric' | 'occurrences'The criterion to compare.
Returns boolean: Whether the facet values are sorted according to the specified criterion.
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:
'alphanumeric' | 'occurrences'The criterion by which to sort values.
toggleSelect
Toggles the specified facet value.
Parameters
-
selection:
CategoryFacetValueThe facet value to toggle.
subscribe
Adds a callback that’s invoked on state change.
Parameters
-
listener:
() => voidA 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.
search
Performs a facet search.
select
Selects a facet search result.
Parameters
-
value:
CategoryFacetSearchResultThe search result to select.
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:
stringThe facet search query.
state
The state of the Facet controller.
Properties
-
facetSearch:
CategoryFacetSearchStateThe state of the facet’s searchbox.
-
activeValue:
CategoryFacetValue | undefinedThe facet’s selected value if any, undefined otherwise.
-
canShowLessValues:
booleanReturns
trueif fewer values can be displayed, andfalseif not. -
canShowMoreValues:
booleanReturns
trueif there are more values to display and,falseif not. -
enabled:
booleanWhether the facet is enabled and its values are used to filter search results.
-
facetId:
stringThe facet ID.
-
hasActiveValues:
booleanReturns
trueif there’s at least one non-idle value, andfalseif not. -
isHierarchical:
booleanWhether
valuesAsTreecontains hierarchical values (that is, facet values with children), or only 'flat' values (that is, facet values without children). -
isLoading:
booleanReturns
trueif a search is in progress, andfalseif not. -
parents:
CategoryFacetValue[]The facet’s parent values.
-
selectedValueAncestry:
CategoryFacetValue[]The selected facet values ancestry. The first element is the "root" of the selected value ancestry tree. The last element is the selected value itself.
-
sortCriteria:
'alphanumeric' | 'occurrences'The facet’s active
sortCriterion. -
values:
CategoryFacetValue[]The facet’s values.
-
valuesAsTrees:
CategoryFacetValue[]The root facet values. Child values might be available in
valuesAsTrees[i].children[j]
Initialize
buildCategoryFacet
Creates a CategoryFacet controller instance.
Parameters
-
engine:
SearchEngineThe headless engine.
-
props:
CategoryFacetPropsThe configurable
CategoryFacetproperties.
Returns CategoryFacet
CategoryFacetProps
The configurable CategoryFacet properties.
Properties
-
options:
CategoryFacetOptionsThe options for the
CategoryFacetcontroller.
CategoryFacetOptions
The options for the CategoryFacet controller.
Properties
-
field:
stringThe field whose values you want to display in the facet.
-
basePath?:
string[]The base path shared by all values for the facet.
Default:
[] -
delimitingCharacter?:
stringThe character that specifies the hierarchical dependency.
Default:
; -
facetId?:
stringA unique identifier for the controller. By default, a random unique ID is generated.
-
facetSearch?:
CategoryFacetSearchOptionsFacet search options.
-
filterByBasePath?:
booleanWhether to filter the results using
basePath.Default:
true -
filterFacetCount?:
booleanWhether to exclude the parents of folded results when estimating the result count for each facet value.
Default:
true -
injectionDepth?:
numberThe maximum number of results to scan in the index to ensure that the facet lists all of the potential facet values.
Note: A high
injectionDepthmay reduce facet request performance.Minimum:
0Default:
1000 -
numberOfValues?:
numberThe 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:
1Default:
5 -
sortCriteria?:
'alphanumeric' | 'occurrences'The criterion to use for sorting returned facet values.
Default:
occurrences
Related types
CategoryFacetSearchOptions
Properties
-
captions?:
Record<string, string>A dictionary that maps index field values to facet value display names.
-
numberOfValues?:
numberThe maximum number of values to fetch.
Default:
10 -
query?:
stringThe string to match.
CategoryFacetSearchResult
Properties
-
count:
numberAn 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:
stringThe custom facet value display name, as specified in the
captionsargument of the facet request. -
path:
string[]The hierarchical path to the selected facet value.
-
rawValue:
stringThe original facet value, as retrieved from the field in the index.
CategoryFacetSearchState
Properties
-
isLoading:
booleanReturns
trueif the facet search is in progress, andfalseif not. -
moreValuesAvailable:
booleanWhether more values are available.
-
query:
stringThe current query in the facet search box.
-
values:
CategoryFacetSearchResult[]The facet search results.
CategoryFacetValue
Properties
-
children:
CategoryFacetValue[]The children of this facet value.
-
isLeafValue:
booleanWhen the hierarchical value has no children, this property is true.
-
moreValuesAvailable:
booleanWhether more facet values are available.
-
numberOfResults:
numberThe number of results that match the facet value.
-
path:
string[]The hierarchical path to the facet value.
-
state:
'idle' | 'selected' | 'excluded'Whether a facet value is filtering results (
selected) or not (idle). -
value:
stringThe facet value.
Unsubscribe
Call signatures
-
(): void;