AutomaticFacet

This is for:

Developer

Example Implementation

automatic-facet.fn.tsx

import {AutomaticFacet as HeadlessAutomaticFacet} from '@coveo/headless';
import {FunctionComponent, useEffect, useState} from 'react';
 
interface AutomaticFacetProps {
  controller: HeadlessAutomaticFacet;
}
 
export const AutomaticFacet: FunctionComponent<AutomaticFacetProps> = (
  props
) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  return (
    <ul>
      {state.values.map((value) => (
        <li key={value.value}>
          <input
            type="checkbox"
            checked={value.state === 'selected'}
            onChange={() => controller.toggleSelect(value)}
          />
          {value.value} ({value.numberOfResults} results)
        </li>
      ))}
    </ul>
  );
};

automatic-facet-generator.fn.tsx

import {AutomaticFacetGenerator as HeadlessAutomaticFacetGenerator} from '@coveo/headless';
import {FunctionComponent, useEffect, useState} from 'react';
import {AutomaticFacet as AutomaticFacetFn} from '../automatic-facet/automatic-facet.fn';
 
interface AutomaticFacetGeneratorProps {
  controller: HeadlessAutomaticFacetGenerator;
}
 
export const AutomaticFacetGenerator: FunctionComponent<
  AutomaticFacetGeneratorProps
> = (props) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  const automaticFacets = state.automaticFacets.map((facet) => {
    return (
      <AutomaticFacetFn
        key={facet.state.field}
        controller={facet}
      ></AutomaticFacetFn>
    );
  });
  return <div>{automaticFacets}</div>;
};
 
// usage
 
/**
 * ```tsx
 * const options: AutomaticFacetGeneratorOptions = {desiredCount: 5, numberOfValues: 6}
 * const controller = buildAutomaticFacetGenerator(engine, {options});
 *
 * <AutomaticFacetGenerator controller={controller} />;
 * ```
 */

The AutomaticFacet 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). Unlike traditional facets that need to be explicitly defined and requested in the query, automatic facets are dynamically generated by the index in response to the query.

It’s important to note that this controller is not typically used directly. It is internally used by the AutomaticFacetGenerator controller to automatically render updated facets.

To read more about the automatic facet generator feature, see: https://docs.coveo.com/en/n9sd0159/

Methods

deselectAll

Deselects all automatic facet values.

toggleSelect

Toggles the specified automatic facet value.

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

state

The state of the AutomaticFacet controller.

Properties

  • field: string

    The automatic facet field.

  • label: string

    The automatic facet label.

  • values: FacetValue[]

    The automatic facet values.

Initialize

buildAutomaticFacet

Creates a AutomaticFacet controller instance.

Parameters

  • engine: SearchEngine

    The headless engine.

  • props: AutomaticFacetProps

    The configurable AutomaticFacet properties.

Returns AutomaticFacet

AutomaticFacetProps

The configurable AutomaticFacet properties.

Properties

  • field: string

    The field whose values you want to display in the facet.

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.

Unsubscribe

Call signatures

  • (): void