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 Coveo. For example, the Coveo Atomic library relies on Headless to handle application state and Coveo interactions.

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 those features, Headless provides a collection of controllers. For example, to implement a search box UI component, one would use the Headless search box controller, which exposes various methods (updateText, submit, showSuggestion, etc.).

Under the hood, Headless relies on the Coveo Usage Analytics Write API and Coveo Search API for interacting with Coveo.

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.