Extend controllers

This is for:

Developer

Headless controllers provide methods that trigger different high-level behaviors. When you call a method, Headless dispatches one or more low-level actions. For example, calling the submit method on the SearchBox controller dispatches actions to:

update the query
clear active facet values
reset the result page to the first page
perform a query
log the appropriate usage analytics event

Controllers embed user experience decisions that we believe are best-practices for creating great search experiences. For example, submitting a query from a search box resets selected facet values to reduce the odds of seeing no results. However, it’s possible to change the default behaviors by overriding or adding new methods that dispatch a different set of actions. The following sample shows how to add a new method to the search box controller to perform a search request without resetting active facet values:

import {
  buildSearchBox,
  loadQueryActions,
  loadPaginationActions,
  loadSearchActions,
  loadSearchAnalyticsActions,
} from '@coveo/headless'
 
function buildCustomSearchBox(engine: SearchEngine, id: string) {
  const baseSearchBox = buildSearchBox(engine, {options: {id}});
  const {updateQuery} = loadQueryActions(engine);
  const {updatePage} = loadPaginationActions(engine);
  const {executeSearch} = loadSearchActions(engine);
  const {logSearchboxSubmit} = loadSearchAnalyticsActions(engine);
 
  return {
    ...baseSearchBox,
 
    submitWithoutFacetReset() {
      const query = engine.state.querySet![id];
 
      updateQuery({q: query});
      updatePage(1);
      executeSearch(logSearchboxSubmit());
    }
  }
}

You can extend any Headless controller this way. It is possible to override existing methods, or add new ones that dispatch different sets of actions.