Facet (Search Engine)

This is for:

Developer

In this article

Example implementation
Methods
Attributes
Initialize
Related types

Note

This component was introduced in version 1.41.7.

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. 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: 'score' | 'alphanumeric' | 'alphanumericDescending' | 'occurrences' | 'automatic'

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: 'score' | 'alphanumeric' | 'alphanumericDescending' | 'occurrences' | 'automatic'

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 and false otherwise.
canShowMoreValues: boolean

true if there are more values to display and false 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 and false otherwise.
isLoading: boolean

true if a search is in progress and false otherwise.
sortCriterion: 'score' | 'alphanumeric' | 'alphanumericDescending' | 'occurrences' | 'automatic'

The active sortCriterion of the facet.
values: FacetValue[]

The values of the facet.
label?: string

The name to display if this field is used by the Facet Generator in your interface. See Change Facet Generator options.

Initialize

`buildFacet`

Creates a Facet controller instance.

Parameters

engine: SearchEngine

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.
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 its field 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 the sortCriteria.

The maximum amount of custom sort values is 25.

The default value is undefined, and the facet values will be sorted using only the sortCriteria.
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.

`FacetSearchState`

Properties

isLoading: boolean

true if the facet search is in progress and false 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;