Usage

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

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 the Coveo Platform, 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

To start building an application on top of the Headless library, you must first initialize and export a HeadlessEngine instance.

You will specify your search endpoint configuration through this instance (i.e., where to send Coveo search requests, and how to authenticate them). You will also pass a set of reducers, which will determine what state attributes are available within your application (typically, you’ll import and use the standard searchPageReducers from the Headless library).

For testing purposes, you can use our sample configuration:

// app/Engine.ts
 
import { HeadlessEngine, searchPageReducers } from '@coveo/headless';
 
export const engine = new HeadlessEngine({
  configuration: HeadlessEngine.getSampleConfiguration(),
  reducers: searchPageReducers
});

However, most of the time, your HeadlessEngine initialization and export will look like this:

// app/Engine.ts
import { HeadlessEngine, searchPageReducers } from '@coveo/headless';
 
export const engine = new HeadlessEngine({
  configuration: {
    organizationId: '<ORGANIZATION_ID>',
    accessToken: '<ACCESS_TOKEN>',
  },
  reducers: searchPageReducers
});

where:

  • <ORGANIZATION_ID> (string) is the unique identifier of your Coveo organization (e.g., mycoveoorganizationa1b23c).

  • <ACCESS_TOKEN> (string) is an API key or search token that grants the Allowed access level on the Execute Queries domain, as well as the Push access level on the Analytics Data domain in the target organization.

The HeadlessEngine also lets you do some more advanced things such as passing your own reducers, using a preloaded state, or extending the Headless library with custom middlewares. The Customization section of this guide (coming soon!) will cover those use cases.

For more information on the HeadlessEngine see the reference documentation.

Use Headless Controllers

A Headless controller is an abstraction that simplifies the implementation of a specific 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.

EXAMPLE

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);
 
searchBox.updateText('hello'); (1)
 
searchBox.selectSuggestion(searchBox.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)
 
searchBox.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);
 
// ...
 
unsubscribe();

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 { configurationActions } from '@coveo/headless';
import { engine } from './engine';
 
const action = configurationActions.updateSearchConfiguration({
  endpoint: 'https://platform.cloud.coveo.com/',
});
 
engine.dispatch(action);

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.

Recommended Articles