THIS IS ARCHIVED DOCUMENTATION

(Deprecated) Usage

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.

Note

To create a starter Angular, React, or Vue.js project with a Coveo Headless-powered search page, check out the Coveo CLI. The CLI can handle several steps for you.

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’ll specify your search endpoint configuration through this instance (that is, where to send Coveo search requests and how to authenticate them). You’ll 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 searchAppReducers from the Headless library.

For testing purposes, you can use the sample configuration:

// app/Engine.ts

import { HeadlessEngine, searchAppReducers } from '@coveo/headless';

export const engine = new HeadlessEngine({
  configuration: HeadlessEngine.getSampleConfiguration(),
  reducers: searchAppReducers
});

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

// app/Engine.ts

import { HeadlessEngine, searchAppReducers } from '@coveo/headless';

export const engine = new HeadlessEngine({
  configuration: {
    organizationId: '<ORGANIZATION_ID>', 1
    accessToken: '<ACCESS_TOKEN>', 2
  },
  reducers: searchAppReducers
});
1 <ORGANIZATION_ID> (string) is the unique identifier of your Coveo organization (for example, mycoveoorganizationa1b23c).
2 <ACCESS_TOKEN> (string) is a search token or an API key that grants the Allowed access level on the Execute Queries domain and 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 middleware.

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.

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);
 
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 (for example, 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 (for example, 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. You can create actions using action loaders and dispatch them using the Headless engine’s dispatch method.

import { engine } from './engine';
import { loadFieldActions } from '@coveo/headless';
 
const FieldActionCreators = loadFieldActions(engine); 1
const action = FieldActionCreators.registerFieldsToInclude(['field1', 'field2']); 2
 
engine.dispatch(action); 3
1 The action loader loadFieldActions allows you to use field actions. Calling this function will add the necessary reducers to the engine, if they haven’t been added already, and return an object holding the relevant action creator functions.
2 To create a dispatchable action, use the action creators that were loaded in the previous line. In this case, the registerFieldsToInclude method takes field names as parameters and returns an action that, when dispatched, will cause those fields to be returned as part of each search result.
3 Dispatch the action using the engine’s dispatch method.
Note

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.