The Coveo Headless library acts as a middle-layer for applications, opening a line of communication between the UI elements and Coveo.

A project built on top of Headless will typically involve two main building-blocks: the engine, which manages the state of the search interface and communicates with Coveo, and the controllers, which dispatch actions to the engine based on user interactions.

This article provides an overview of the core Headless concepts.

Install Headless

Use npm to install the Headless library.

npm install @coveo/headless

Headless requires Node.js version 12 or above.

Configure a Headless Engine

Use Headless Controllers

A Headless controller is an abstraction that simplifies the implementation of a specific Coveo-powered UI feature or component. In other words, controllers provide intuitive programming interfaces for interacting with the Headless engine’s state.

For most use cases, we recommend that you use controllers to interact with the state.


To implement a search box UI component, you decide to use the SearchBox controller.

This controller exposes various public methods such as updateText and submit. You write code to ensure that when the end user types in the search box, the Searchbox controller’s updateText method is called. Under the hood, calling this method dispatches some actions. The Headless engine’s reducers react to those actions by updating the state as needed.

In this case, the query property of the state is updated. Then, the controller fetches new query suggestions from the Search API, and updates the querySuggestState property.

For detailed information on the various Headless controllers, see the reference documentation.

Initialize a Controller Instance

You can initialize a Headless Controller instance by calling its builder function.

A controller’s builder function always requires a Headless engine instance as a first argument.

// src/Components/MySearchBox.ts
import { SearchBox, buildSearchBox } from '@coveo/headless';
import { engine } from '../Engine';
const mySearchBox: SearchBox = buildSearchBox(engine);

Many builder functions also accept, and sometimes require, an options object as a second argument.

// src/Components/MyStandaloneSearchBox.ts
import { SearchBox, SearchBoxOptions, buildSearchBox } from '@coveo/headless';
import { engine } from '../Engine';
const options: SearchBoxOptions = { 1
  numberOfSuggestions: 3,
  isStandalone: true
const myStandaloneSearchBox: SearchBox = buildSearchBox(engine, { options });
1 None of the SearchBox controller options are required, but you can use them to tailor the controller instance to your needs.
// src/Components/MyAuthorFacet.ts
import { Facet, FacetOptions, buildFacet } from '@coveo/headless';
import { engine } from '../Engine';
const options: FacetOptions = { field: "author" }; 1
const myAuthorFacet: Facet = buildFacet(engine, { options });
1 Specifying a field value in the options object is required to initialize a Facet controller instance.

The options that are available on each controller are detailed in the reference documentation.

Interact With a Controller

Every controller exposes a public interface which you can use to interact with the Headless engine’s state.

When you call a method on a controller instance, one or more actions are dispatched. The Headless engine’s reducers listen to those actions, and react to them by altering the state as necessary.

Calling some of the SearchBox controller’s methods.

import { SearchBox, buildSearchBox } from '@coveo/headless';
import { engine } from '../Engine';

const mySearchBox: SearchBox = buildSearchBox(engine);
mySearchBox.updateText('hello'); 1
mySearchBox.selectSuggestion(mySearchBox.state.suggestions[0].value) 2
1 Dispatches actions to update the query to hello, and fetch new query suggestions.
2 Dispatches actions to set the query to the value of the first query suggestion (e.g., hello world), and execute that query.

The methods that are available on each controller are detailed in the reference documentation.

Subscribe to State Changes

You can use the subscribe method on a controller instance to listen to its state changes.

The listener function you pass when calling the subscribe method will be executed every time an action is dispatched.

import { SearchBox, buildSearchBox } from '@coveo/headless';
import { engine } from '../Engine';

const mySearchBox: SearchBox = buildSearchBox(engine);
// ...
function onSearchBoxUpdate() {
  const state = mySearchBox.state;
  // ...Do something with the updated SearchBox state...
const unsubscribe = mySearchBox.subscribe(onSearchBoxUpdate); 1
mySearchBox.updateText('hello'); 2
// ...
unsubscribe(); 3
1 Every time the portion of the state that’s relevant for the SearchBox controller changes, the onSearchBoxUpdate function will be called.
2 This will trigger a SearchBox state change.
3 The subscribe method returns a function for unregistering the listener, so you can call unsubscribe to stop listening to state updates (e.g., when the controller is deleted).

You can also call the subscribe method from your Headless engine instance to listen to all state changes.

import { engine } from '../Engine';
function onStateUpdate() {
  const state = engine.state;
  // ...Do something with the updated state...
const unsubscribe = engine.subscribe(onStateUpdate);
// ...

Dispatch Actions

You will often use controller methods to interact with the state. However, you may sometimes want to dispatch actions on your own. To do so, you can use the can Headless engine’s dispatch method.

import { engine } from './engine';
import { SearchActions, AnalyticsActions } from "@coveo/headless";
const action = SearchActions.executeSearch(AnalyticsActions.logInterfaceLoad());

Every action dispatch triggers the corresponding listener function. Consequently, you should only perform costly operations, such as rendering a UI component, when the state they depend on has changed.

For more information on the various actions you can dispatch, see the reference documentation.

What's next for me?