Use the Headless library

This is for:

Developer

What’s Coveo Headless?

Coveo Headless is a library for developing Coveo-powered UI components. It works as a middle layer for applications, opening a line of communication between the UI elements and the Coveo Platform.

For example, the Coveo Atomic library relies on Headless to handle interactions between the application state and Coveo. Platform.

At its core, Headless consists of an engine whose main property is its state (that is, a Redux store). The engine’s state depends on a set of features (that is, reducers). To interact with these features, Headless provides a collection of controllers.

For example, to implement a search box UI component, you would use the Headless search box controller. This exposes various methods, such as updateText, submit, and showSuggestion.

Under the hood, Headless relies on different Coveo APIs depending on your solution:

  • For sending analytics data, Headless uses the Coveo Event API.

  • For non-commerce solutions, Headless interacts with the Coveo Platform using the Coveo Search API.

    For Coveo for Commerce solutions, Headless interacts with the Coveo Platform using the Coveo Commerce API. For more details, see the documentation on the commerce engine.

Diagram showing where Headless fits with Atomic and the APIs

When Should I Use Headless?

The Headless library wraps the complexity of the Coveo APIs without sacrificing flexibility. It’s usable with any web development framework and it manages the state of your search page for you. Rather than prebuilt UI components, it provides an extendable set of reducers and controllers that allow you to connect your own search UI components to the Coveo APIs.

If you want to use Coveo to power your own UI component library, then you should definitely consider using Headless. It’s the easiest and least error-prone approach to developing and maintaining your Coveo-powered UI component library.

The following interactive code sample uses Coveo Headless alongside the Material-UI React framework to create a simple search page.

Tip
Leading practice

Unless you need full control over the appearance of your page, Headless is most likely not for you. Rather, to quickly assemble a feature-rich search interface, consider using Coveo Atomic, our prebuilt, modern component library.

Additionally, in rare cases you may need to develop directly against the Coveo APIs, such as when you want to integrate Coveo search features inside a non-web-based application.

Where Do I Start?

To learn the basics of the Headless library, see the Usage section.

To create a starter Angular, React, or Vue.js project with a Coveo Headless-powered search page, check out the Coveo CLI.

You may also want to check out the Reference section.