Facet

Methods

deselectAll

Deselects all facet values.

isSortedBy

Checks whether the facet values are sorted according to the specified criterion.

Parameters

  • criterion: 'score' | 'alphanumeric' | 'occurrences' | 'automatic'

    The criterion to compare.

Returns boolean: Whether the facet values are sorted according to the specified criterion.

isValueSelected

Checks whether the specified facet value is selected.

Parameters

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' | 'occurrences' | 'automatic'

    The criterion to use for sorting values.

toggleSelect

Toggles the specified facet value.

Parameters

  • selection: FacetValue

    The facet value to toggle.

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.

Performs a facet search.

select

Selects a facet search result.

Parameters

showMoreResults

Shows more facet search results.

singleSelect

Selects a search result while deselecting facet values.

Parameters

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.

  • 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' | 'occurrences' | 'automatic'

    The active sortCriterion of the facet.

  • values: FacetValue[]

    The values of the facet.

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.

  • delimitingCharacter?: string

  • 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

  • sortCriteria?: 'score' | 'alphanumeric' | 'occurrences' | 'automatic'

    The criterion to use for sorting returned facet values.

    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'

    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

Example Implementation

facet.fn.tsx

import {useEffect, useState, FunctionComponent} from 'react';
import {Facet as HeadlessFacet} from '@coveo/headless';
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>
  );
};

Associated Engines

The Facet controller is available in the following engines:

What's Next for Me?